diff --git a/README.md b/README.md index 6db8db1..03cc357 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 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. + ## 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..53adf58 --- /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 while 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 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 + +## 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 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 + 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 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 +[Open Device Partnership GitHub organization](https://github.com/OpenDevicePartnership).