From 3576c9050ee02aa3628a0f96f44e76d086afaf81 Mon Sep 17 00:00:00 2001 From: Jerry Xie Date: Mon, 24 Aug 2026 17:45:55 -0500 Subject: [PATCH 1/2] docs: add Secure EC overview 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 --- README.md | 23 ++++++++---- docs/src/SUMMARY.md | 1 + docs/src/secure-ec-overview.md | 67 ++++++++++++++++++++++++++++++++++ 3 files changed, 83 insertions(+), 8 deletions(-) create mode 100644 docs/src/secure-ec-overview.md diff --git a/README.md b/README.md index 6db8db1..f7b09f0 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,13 @@ Public reference and demo firmware for Embedded Controllers (EC) built on This repository contains development targets suitable for experimentation, integration testing, and as a starting point for downstream EC projects. +The ODP Secure Embedded Controller (Secure EC) project is building an +open-source, microcontroller-agnostic EC platform with reusable Rust firmware, +standardized host interfaces, and security capabilities including secure boot, +device identity, and attestation. See the +[Secure EC overview](./docs/src/secure-ec-overview.md) for the project goals, +architecture, current areas of investment, and key repositories. + ## Scope This repository hosts the four public `dev-*` development targets and their @@ -14,7 +21,7 @@ platforms are maintained separately and are not in scope here. ## Platforms | Crate | Role | Target | -|-------|------|--------| +| ----- | ---- | ------ | | `platform-common` | Shared `no_std` library crate — HAL traits, board abstractions, common services | (library, no build target) | | `dev-imxrt` | Development target on NXP i.MXRT685S (Cortex-M33) | `thumbv8m.main-none-eabihf` | | `dev-mcxa` | Development target on NXP MCXA266 (Cortex-M33) | `thumbv8m.main-none-eabihf` | @@ -37,7 +44,7 @@ invoked inside this repo; no manual `rustup target add` is required. `dev-imxrt`, `dev-mcxa`, and `dev-npcx` link via [`flip-link`](https://github.com/knurling-rs/flip-link) for stack-overflow protection. Install it once: -``` +```console cargo install flip-link --locked ``` @@ -45,7 +52,7 @@ cargo install flip-link --locked Build and lint a single platform: -``` +```console cd platform/ cargo build --locked cargo clippy --locked -- -D warnings @@ -53,14 +60,14 @@ cargo clippy --locked -- -D warnings For example, to build `dev-qemu`: -``` +```console cd platform/dev-qemu cargo build --locked ``` Format checks are run per crate: -``` +```console cd platform/ cargo fmt --check ``` @@ -68,7 +75,7 @@ cargo fmt --check Dependency policy (licenses, sources, advisories) is enforced by [cargo-deny](https://github.com/EmbarkStudios/cargo-deny) using `deny.toml`: -``` +```console cd platform/ cargo deny --locked check ``` @@ -78,7 +85,7 @@ cargo deny --locked check `scripts/check-all.sh` runs every gate (fmt + build + clippy -D warnings + cargo-deny) across all three dev-* platforms — the same checks CI runs: -``` +```console bash scripts/check-all.sh ``` @@ -116,7 +123,7 @@ Project documentation, including the Embedded Controller Interface specification, is maintained as an [mdBook](./docs/README.md). Build it locally with: -``` +```console mdbook serve docs --open ``` diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index e16ff1c..048dcc0 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -1,6 +1,7 @@ # Summary [Introduction](introduction.md) +[Secure EC Overview](secure-ec-overview.md) - [Development](development.md) - [Supply-chain auditing](supply-chain.md) diff --git a/docs/src/secure-ec-overview.md b/docs/src/secure-ec-overview.md new file mode 100644 index 0000000..92c97e4 --- /dev/null +++ b/docs/src/secure-ec-overview.md @@ -0,0 +1,67 @@ +# Secure EC Overview + +The Open Device Partnership (ODP) Secure Embedded Controller (Secure EC) +project strives to build an open-source, microcontroller-agnostic embedded controller +platform for the PC ecosystem. It combines secure firmware, standardized host +interfaces, and reusable Rust components so device makers can reduce effort by building +on a standardized platform that is secure by design and focusing on their unique value added. + +## Goals + +- Security by default leveraging memory-safe Rust +- Standardize communication between the host operating system and the EC across + hardware architectures and operating systems. +- Provide reusable and customizable firmware services for battery, thermal, power, USB-C, HID, + time alarms, and other common EC functions. +- Support collaboration among device makers, silicon vendors, operating-system + vendors, and the open-source community. +- Reduce platform bring-up effort through shared abstractions, reference + implementations, virtual platforms, and test tooling. + +## Architecture + +Secure EC separates portable service logic from platform-specific hardware +support: + +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. +3. **Embedded services** implement reference application logic for EC subsystems. +4. **Host transports and protocols** expose those services to the host through standardized + interfaces + +## Security Direction + +The project is working toward an EC that is an attestable platform component +rather than an implicitly trusted boundary: + +- **Secure boot** verifies that firmware is authorized before execution. +- **DICE** derives device identity from hardware secrets and firmware + measurements. +- **Attestation** allows host OS to assess the identity and state of the + EC. +- **Encrypted communication** provides a standardized mechanism for secure data exchange between the EC and the host OS. + +## Current Work + +Current areas of investment include: + +- Expanding portable Rust services and drivers. +- Supporting reference MCU platforms from multiple silicon vendors. +- Developing standardized HID communication protocol over eSPI and I3C transport with OS support. +- 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 + systems. + +## Key Repositories + +| 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. | +| [`embedded-services`](https://github.com/OpenDevicePartnership/embedded-services) | Reusable EC service implementations and interfaces, including battery, thermal, HID, time and alarms, and UART services. | + +The broader set of projects and community activity is available in the +[Open Device Partnership GitHub organization](https://github.com/OpenDevicePartnership). From 147cc6a39e6aa3b3ce737c6811ad09644aa87fd1 Mon Sep 17 00:00:00 2001 From: Jerry Xie Date: Wed, 26 Aug 2026 15:34:30 -0500 Subject: [PATCH 2/2] docs: address Secure EC review feedback Clarify that security features are planned and improve the overview's architecture, virtual platform, and grammar descriptions. Assisted-by: GitHub Copilot:gpt-5.3-codex --- README.md | 4 ++-- docs/src/secure-ec-overview.md | 10 +++++----- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index f7b09f0..03cc357 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,8 @@ integration testing, and as a starting point for downstream EC projects. The ODP Secure Embedded Controller (Secure EC) project is building an open-source, microcontroller-agnostic EC platform with reusable Rust firmware, -standardized host interfaces, and security capabilities including secure boot, -device identity, and attestation. See the +standardized host interfaces, and planned security capabilities including secure +boot, device identity, and attestation. See the [Secure EC overview](./docs/src/secure-ec-overview.md) for the project goals, architecture, current areas of investment, and key repositories. diff --git a/docs/src/secure-ec-overview.md b/docs/src/secure-ec-overview.md index 92c97e4..53adf58 100644 --- a/docs/src/secure-ec-overview.md +++ b/docs/src/secure-ec-overview.md @@ -4,7 +4,7 @@ The Open Device Partnership (ODP) Secure Embedded Controller (Secure EC) project strives to build an open-source, microcontroller-agnostic embedded controller platform for the PC ecosystem. It combines secure firmware, standardized host interfaces, and reusable Rust components so device makers can reduce effort by building -on a standardized platform that is secure by design and focusing on their unique value added. +on a standardized platform that is secure by design while focusing on their unique value added. ## Goals @@ -25,7 +25,7 @@ support: 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. +2. **Subsystem interfaces** decouple portable service logic from hardware implementations for battery, thermal, power, USB-C, HID, and other common EC subsystems. 3. **Embedded services** implement reference application logic for EC subsystems. 4. **Host transports and protocols** expose those services to the host through standardized interfaces @@ -48,11 +48,11 @@ Current areas of investment include: - Expanding portable Rust services and drivers. - Supporting reference MCU platforms from multiple silicon vendors. -- Developing standardized HID communication protocol over eSPI and I3C transport with OS support. +- Developing a standardized HID communication protocol over eSPI and I3C transports with OS support. - 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 +- Exploring how Rust-based Secure EC components and APIs can interoperate with Zephyr-based systems. ## Key Repositories @@ -60,7 +60,7 @@ Current areas of investment include: | 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. | +| [`odp-platform-qemu-arm-virt`](https://github.com/OpenDevicePartnership/odp-platform-qemu-arm-virt) | End-to-end Secure EC test platform connecting a virtualized RISC-V EC to an Arm64 QEMU host 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. | The broader set of projects and community activity is available in the