docs: add Secure EC overview - #40
Conversation
Document the project's goals, architecture, security direction, and key repositories in the mdBook. Link the overview from the README and fix existing Markdown lint issues. Assisted-by: GitHub Copilot:gpt-5.3-codex
| | Repository | Purpose | | ||
| | ---------- | ------- | | ||
| | [`odp-embedded-controller`](https://github.com/OpenDevicePartnership/odp-embedded-controller) | Reference EC firmware including hardware platforms and virtualized platforms. Refer to its README to get started. Secure EC top-level documentation is also included. | | ||
| | [`odp-platform-qemu-arm-virt`](https://github.com/OpenDevicePartnership/odp-platform-qemu-arm-virt) | End to End virtualized Secure EC testing platform using virtualized EC RISC-V platform <-> QEMU ARM virtual platform running Windows Validation OS. | |
There was a problem hiding this comment.
@philgweber @kurtjd Is there a document I can point to for getting started with the E2E on QEMU, that would probably be the best starting point for most people.
There was a problem hiding this comment.
Ideally it could point to: https://opendevicepartnership.github.io/odp-platform-qemu-arm-virt/
Which is where the mdbook should be published according to the README: https://github.com/OpenDevicePartnership/odp-platform-qemu-arm-virt/blob/main/README.md#documentation
But, the job that publishes is currently broken and so that link just forwards back to ODP homepage at the moment...
There was a problem hiding this comment.
The URL should now work since the job is fixed (thanks @philgweber).
There was a problem hiding this comment.
I double checked the settings and realized that gh pages publishing is not enabled on that repo, so I enabled it. I don't know if that fixed it or not. @philgweber did you do anything on your side as well? Just want to record down the right steps to public gh pages from github actions, we need to do the same for this repo.
There was a problem hiding this comment.
Pull request overview
Adds a Secure EC project overview to the mdBook and links it from the README.
Changes:
- Documents goals, architecture, security direction, current work, and repositories.
- Adds the overview to mdBook navigation.
- Updates README Markdown formatting.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description | Review comments |
|---|---|---|
README.md |
Links the Secure EC overview and fixes Markdown formatting. | Nit (3 votes): Qualify secure boot, device identity, and attestation as goals or planned capabilities. |
docs/src/SUMMARY.md |
Adds the overview to book navigation. | None. |
docs/src/secure-ec-overview.md |
Adds Secure EC project documentation. | Nits: Clarify subsystem interfaces (4 votes); make the RISC-V EC and ARM QEMU/Windows setup explicit (2 votes); hyphenate the compound modifier (2 votes). |
Suppressed comments (2)
docs/src/secure-ec-overview.md:7
- The
and focusingclause is grammatically attached to the platform (that is ... and focusing), which makes the platform—not device makers—the subject doing the focusing. Change it towhile focusingso the sentence expresses the intended benefit for device makers.
on a standardized platform that is secure by design and focusing on their unique value added.
docs/src/secure-ec-overview.md:51
- This sentence is missing the article “a” before “standardized HID communication protocol,” which makes the current-work item grammatically incomplete.
- Developing standardized HID communication protocol over eSPI and I3C transport with OS support.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| standardized host interfaces, and security capabilities including secure boot, | ||
| device identity, and attestation. See the |
|
|
||
| 1. **MCU HALs and board support** provide access to clocks, GPIO, I2C, eSPI, | ||
| I3C, and other peripherals. | ||
| 2. **Subsystem abstractions** connect hardware implementations to subsystem abstractions for battery, thermal, power, USB-C, HID, and other common EC subsystems. |
| | Repository | Purpose | | ||
| | ---------- | ------- | | ||
| | [`odp-embedded-controller`](https://github.com/OpenDevicePartnership/odp-embedded-controller) | Reference EC firmware including hardware platforms and virtualized platforms. Refer to its README to get started. Secure EC top-level documentation is also included. | | ||
| | [`odp-platform-qemu-arm-virt`](https://github.com/OpenDevicePartnership/odp-platform-qemu-arm-virt) | End to End virtualized Secure EC testing platform using virtualized EC RISC-V platform <-> QEMU ARM virtual platform running Windows Validation OS. | |
| - Starting with secure boot and working toward device identity + attestation. | ||
| - Using QEMU-based virtualized platforms for development, integration testing, and ecosystem | ||
| onboarding. | ||
| - Exploring how Rust based Secure EC components and APIs can interoperate with Zephyr-based |
| | [`odp-embedded-controller`](https://github.com/OpenDevicePartnership/odp-embedded-controller) | Reference EC firmware including hardware platforms and virtualized platforms. Refer to its README to get started. Secure EC top-level documentation is also included. | | ||
| | [`odp-platform-qemu-arm-virt`](https://github.com/OpenDevicePartnership/odp-platform-qemu-arm-virt) | End to End virtualized Secure EC testing platform using virtualized EC RISC-V platform <-> QEMU ARM virtual platform running Windows Validation OS. | | ||
| | [`embedded-services`](https://github.com/OpenDevicePartnership/embedded-services) | Reusable EC service implementations and interfaces, including battery, thermal, HID, time and alarms, and UART services. | | ||
|
|
There was a problem hiding this comment.
@philgweber @williampMSFT Is there a secure service repo I should highlight here? Or a EC HID spec?
| | Repository | Purpose | | ||
| | ---------- | ------- | | ||
| | [`odp-embedded-controller`](https://github.com/OpenDevicePartnership/odp-embedded-controller) | Reference EC firmware including hardware platforms and virtualized platforms. Refer to its README to get started. Secure EC top-level documentation is also included. | | ||
| | [`odp-platform-qemu-arm-virt`](https://github.com/OpenDevicePartnership/odp-platform-qemu-arm-virt) | End to End virtualized Secure EC testing platform using virtualized EC RISC-V platform <-> QEMU ARM virtual platform running Windows Validation OS. | |
There was a problem hiding this comment.
I double checked the settings and realized that gh pages publishing is not enabled on that repo, so I enabled it. I don't know if that fixed it or not. @philgweber did you do anything on your side as well? Just want to record down the right steps to public gh pages from github actions, we need to do the same for this repo.
A streamlined secure EC overview