diff --git a/.github/workflows/publish-guide-book.yml b/.github/workflows/publish-guide-book.yml index 58a379d..16751ca 100644 --- a/.github/workflows/publish-guide-book.yml +++ b/.github/workflows/publish-guide-book.yml @@ -1,25 +1,20 @@ -# @file publish-mdbook.yml -# -# A Github workflow that compiles an mdbook located at guide_book/* and publishes it -# to the repository's github page. -# -name: Build and Publish Guide Book +name: Build and Publish ODP Books on: - # Trigger this workflow manually if necessary workflow_dispatch: - - # Triggers this workflow if a commit is pushed to main in which a file in - # bookshelf/** has been updated push: branches: - main paths: - guide_book/** + - tracks/** + - .github/workflows/publish-guide-book.yml + - tracks/** + - .github/workflows/publish-guide-book.yml jobs: build: - name: Build Guide Book + name: Build All Books runs-on: ubuntu-latest steps: @@ -29,30 +24,89 @@ jobs: - name: Install Rust uses: dtolnay/rust-toolchain@stable - - name: Install MdBook - run: cargo install mdbook - - - name: Install Mermaid - run: cargo install mdbook-mermaid + - name: Install mdBook and Plugins + run: | + cargo install mdbook + cargo install mdbook-mermaid + + - name: Prepare Output Folders + run: | + mkdir -p .temp/guide + mkdir -p .temp/tracks + - name: Install mdBook and Plugins + run: | + cargo install mdbook + cargo install mdbook-mermaid - - name: Build the Guide Book + - name: Prepare Output Folders + run: | + mkdir -p .temp/guide + mkdir -p .temp/tracks + + - name: Build Main Guide Book run: | cd guide_book + mdbook clean + mdbook clean mdbook build + cp -r book/* ../.temp/guide/ + + - name: Prepare and Build Track Books + run: | + # Reusable copy function for TOML and mermaid files + for TRACK in contributor embedded_controller integrator patina security value_proposition; do + cp -r guide_book/book.toml tracks/$TRACK/ + cp -r guide_book/mermaid* tracks/$TRACK/ + done - - name: Upload Github Pages Site Artifact + # Shared content for specific tracks + mkdir -p tracks/value_proposition/src/why + cp -r guide_book/src/why/* tracks/value_proposition/src/why/ + + cp -r guide_book/src/intro/concepts/patina.md tracks/patina/src/patina_concepts.md + + cp -r guide_book/src/intro/concepts/Embedded_controller.md tracks/embedded_controller/src/general.md + cp -r guide_book/src/architecture/embedded_controller.md tracks/embedded_controller/src/architecture.md + cp -r guide_book/src/architecture/ec_components.md tracks/embedded_controller/src/component_arch.md + cp -r guide_book/src/architecture/ec_services.md tracks/embedded_controller/src/ec_services_arch.md + mkdir -p tracks/embedded_controller/src/images + cp -r guide_book/src/intro/concepts/images/simplified_layers.png tracks/embedded_controller/src/images/ + cp -r guide_book/src/intro/concepts/images/odp_arch.png tracks/embedded_controller/src/images/ + cp -r guide_book/src/intro/concepts/EC_Services.md tracks/embedded_controller/src/secure_ec_services.md + + cp -r guide_book/src/why/secure_trust.md tracks/security/src/secure_trust.md + cp -r guide_book/src/architecture/security_architecture.md tracks/security/src/security_architecture.md + cp -r guide_book/src/architecture/secure_boot.md tracks/security/src/secure_boot.md + cp -r guide_book/src/architecture/secure_firmware_updates.md tracks/security/src/secure_firmware_updates.md + cp -r guide_book/src/architecture/secure_ec_services.md tracks/security/src/secure_ec_services.md + + # Build each track + for TRACK in contributor embedded_controller integrator patina security value_proposition; do + cd tracks/$TRACK + mdbook clean + mdbook build + mkdir -p ../../.temp/tracks/$TRACK/ + cp -r book/* ../../.temp/tracks/$TRACK/ + cd ../.. + done + + - name: Create Root Redirect to Guide Book + run: | + echo '' > .temp/index.html + + - name: Upload Pages Artifact uses: actions/upload-pages-artifact@v3 with: name: github-pages - path: guide_book/book/ + path: .temp/ publish: - name: Publish Guide Book - needs: [build] + name: Publish Site + needs: build runs-on: ubuntu-latest environment: - name: github-pages # ๐Ÿ‘ˆ Required for GitHub Pages deployment + name: github-pages permissions: id-token: write @@ -60,8 +114,9 @@ jobs: pages: write steps: - - name: Deploy Github Page + - name: Deploy GitHub Pages uses: actions/deploy-pages@v4 with: token: ${{ github.token }} - artifact_name: github-pages \ No newline at end of file + artifact_name: github-pages + diff --git a/.gitignore b/.gitignore index 0ebf465..b189ecb 100644 --- a/.gitignore +++ b/.gitignore @@ -13,14 +13,73 @@ Cargo.lock # MSVC Windows builds of rustc generate these, which store debugging information *.pdb +# VSCODE settings +.vscode + # Ignore book output book # Ignore local site build .temp/guide +.temp/tracks + +# Ignore common copied files +# These are copied from the guide book to the tracks +# and are not needed in the repository +tracks/advisor/book.toml +tracks/advisor/mermaid-init.js +tracks/advisor/mermaid.min.js +tracks/contributor/book.toml +tracks/contributor/mermaid-init.js +tracks/contributor/mermaid.min.js +tracks/embedded_controller/book.toml +tracks/embedded_controller/mermaid-init.js +tracks/embedded_controller/mermaid.min.js +tracks/engineer/book.toml +tracks/engineer/mermaid-init.js +tracks/engineer/mermaid.min.js +tracks/integrator/book.toml +tracks/integrator/mermaid-init.js +tracks/integrator/mermaid.min.js +tracks/patina/book.toml +tracks/patina/mermaid-init.js +tracks/patina/mermaid.min.js +tracks/security/book.toml +tracks/security/mermaid-init.js +tracks/security/mermaid.min.js +tracks/value_proposition/book.toml +tracks/value_proposition/mermaid-init.js +tracks/value_proposition/mermaid.min.js + +tracks/embedded_controller/src/general.md +tracks/embedded_controller/src/architecture.md +tracks/embedded_controller/src/component_arch.md +tracks/embedded_controller/src/ec_services_arch.md +tracks/embedded_controller/src/images/ +tracks/embedded_controller/src/secure_ec_services.md + +tracks/security/src/secure_trust.md +tracks/security/src/security_architecture.md +tracks/security/src/secure_boot.md +tracks/security/src/secure_firmware_updates.md +tracks/security/src/secure_ec_services.md + +# Ignore files duplicated for 'tracks' +tracks\value_proposition\src\why +tracks\patina\src\patina_concepts.md + +tracks\embedded_controller\src\general.md +tracks\embedded_controller\src\architecture.md +tracks\embedded_controller\src\component_arch.md +tracks\embedded_controller\src\ec_services_arch.md +tracks\embedded_controller\src\images + +tracks\security\src\secure_trust.md +tracks\security\src\security_architecture.md +tracks\security\src\secure_boot.md +tracks\security\src\secure_firmware_updates.md +tracks\security\src\secure_ec_services.md -# Ignore file generated by mdbook for return to library in inde -bookshelf/Shelf\ 4\ Specifications/library.html # Ignore local notes cheat_sheet.md diff --git a/.temp/build.bat b/.temp/build.bat index 5ac50b0..3c701a6 100644 --- a/.temp/build.bat +++ b/.temp/build.bat @@ -1,12 +1,70 @@ REM make book +md .temp +md .temp\guide +md .temp\tracks cd guide_book mdbook clean mdbook build +REM move into place +xcopy "book\*" ".\..\.temp\guide" /E /I /Y -REM build site directory -cd ..\ -md .\.temp -cd .\.temp -md .\guide -cd ..\guide_book -xcopy "book\*" "..\.temp\guide" /E /I /Y +REM copy the common toml and mermaid files +copy ".\book.toml" "..\tracks\contributor\" /Y +copy ".\mermaid*" "..\tracks\contributor\" /Y +copy ".\book.toml" "..\tracks\embedded_controller\" /Y +copy ".\mermaid*" "..\tracks\embedded_controller\" /Y +copy ".\book.toml" "..\tracks\integrator\" /Y +copy ".\mermaid*" "..\tracks\integrator\" /Y +copy ".\book.toml" "..\tracks\patina\" /Y +copy ".\mermaid*" "..\tracks\patina\" /Y +copy ".\book.toml" "..\tracks\security\" /Y +copy ".\mermaid*" "..\tracks\security\" /Y +copy ".\book.toml" "..\tracks\value_proposition\" /Y +copy ".\mermaid*" "..\tracks\value_proposition\" /Y + +REM copy content shared across tracks +xcopy ".\src\why\*" "..\tracks\value_proposition\src\why" /E /I /Y +xcopy ".\src\intro\concepts\patina.md" "..\tracks\patina\src\patina_concepts.md" /E /I /Y + +copy ".\src\intro\concepts\Embedded_controller.md" "..\tracks\embedded_controller\src\general.md" /Y +copy ".\src\architecture\embedded_controller.md" "..\tracks\embedded_controller\src\architecture.md" /Y +copy ".\src\architecture\ec_components.md" "..\tracks\embedded_controller\src\component_arch.md" /Y +copy ".\src\architecture\ec_services.md" "..\tracks\embedded_controller\src\ec_services_arch.md" /Y +md "..\tracks\embedded_controller\src\images" +copy ".\src\intro\concepts\images\simplified_layers.png" "..\tracks\embedded_controller\src\images\simplified_layers.png" /Y +copy ".\src\intro\concepts\images\odp_arch.png" "..\tracks\embedded_controller\src\images\odp_arch.png" /Y +copy ".\src\intro\concepts\EC_Services.md" "..\tracks\embedded_controller\src\secure_ec_services.md" /Y + +copy ".\src\why\secure_trust.md" "..\tracks\security\src\secure_trust.md" /Y +copy ".\src\architecture\security_architecture.md" "..\tracks\security\src\security_architecture.md" /Y +copy ".\src\architecture\secure_boot.md" "..\tracks\security\src\secure_boot.md" /Y +copy ".\src\architecture\secure_firmware_updates.md" "..\tracks\security\src\secure_firmware_updates.md" /Y +copy ".\src\architecture\secure_ec_services.md" "..\tracks\security\src\secure_ec_services.md" /Y + + + +REM make all track books and copy into place +cd ..\tracks\contributor +mdbook clean +mdbook build +xcopy "book\*" "..\..\.temp\tracks\contributor" /E /I /Y +cd ..\embedded_controller +mdbook clean +mdbook build +xcopy "book\*" "..\..\.temp\tracks\embedded_controller" /E /I /Y +cd ..\integrator +mdbook clean +mdbook build +xcopy "book\*" "..\..\.temp\tracks\integrator" /E /I /Y +cd ..\patina +mdbook clean +mdbook build +xcopy "book\*" "..\..\.temp\tracks\patina" /E /I /Y +cd ..\security +mdbook clean +mdbook build +xcopy "book\*" "..\..\.temp\tracks\security" /E /I /Y +cd ..\value_proposition +mdbook clean +mdbook build +xcopy "book\*" "..\..\.temp\tracks\value_proposition" /E /I /Y \ No newline at end of file diff --git a/guide_book/src/SUMMARY.md b/guide_book/src/SUMMARY.md index cdc1b35..e3eb689 100644 --- a/guide_book/src/SUMMARY.md +++ b/guide_book/src/SUMMARY.md @@ -6,7 +6,8 @@ - [Developer Experience](./why/developer_experience.md) - [Sustainability and Cost](./why/sustainability.md) - [Industry Standards](./why/standards.md) -- [Introduction](./intro/welcome.md) +- [Introduction](./intro/getting_started.md) + - [Welcome Developer](./intro/welcome.md) - [Concepts](./intro/concepts/Concepts.md) - [A Quick Look at Rust](./intro/concepts/rust_quick_look.md) - [Patina](./intro/concepts/patina.md) @@ -21,6 +22,16 @@ - [Button](./intro/tutorial/UserButton.md) - [Listener](./intro/tutorial/LEDApi.md) - [Logic](./intro/tutorial/Logic.md) +- [Architecture](./architecture/architecture.md) + - [Patina Framework](./architecture/patina_framework.md) + - [Component Model](./architecture/patina_components.md) + - [Embedded Controller](./architecture/embedded_controller.md) + - [Component Model](./architecture/ec_components.md) + - [EC Services](./architecture/ec_services.md) + - [Security Model](./architecture/security_architecture.md) + - [Secure Boot](./architecture/secure_boot.md) + - [Firmware Updates](./architecture/secure_firmware_updates.md) + - [Secure EC Services](./architecture/secure_ec_services.md) - [Tracks of ODP](./tracks.md) - [What is in ODP?](./what/what.md) - [Building a virtual laptop](./laptop/laptop.md) @@ -88,12 +99,12 @@ - [Integration](./how/ec/integration/integration.md) -[Integration Tests](./how/ec/integration/integration_tests.md) - [Embedded Targeting](./how/ec/embedded_target/embedded_targeting.md) - - [Project Board](./how/ec/embedded_target/project_board.md) - - [Dependencies](./how/ec/embedded_target/embedded_dependencies.md) - - [Code Changes](./how/ec/embedded_target/embedded_code_changes.md) - - [Logging](./how/ec/embedded_target/embedded_logging.md) - - [Flashing](./how/ec/embedded_target/embedded_flashing.md) - - [Testing](./how/ec/embedded_target/embedded_testing.md) + - [Project Board](./how/ec/embedded_target/project_board.md) + - [Dependencies](./how/ec/embedded_target/embedded_dependencies.md) + - [Code Changes](./how/ec/embedded_target/embedded_code_changes.md) + - [Logging](./how/ec/embedded_target/embedded_logging.md) + - [Flashing](./how/ec/embedded_target/embedded_flashing.md) + - [Testing](./how/ec/embedded_target/embedded_testing.md) - [Integrating the Virtual Laptop](./laptop/integrating.md) - [Summary and Takeaways](./conclusions.md) @@ -114,5 +125,3 @@ - [EC Manufacturing Service](./specs/ec_interface/ec-manufacturing-service.md) - [EC OEM Service](./specs/ec_interface/ec-oem-service.md) - [Sample System Implementation](./specs/ec_interface/sample-system-implementation.md) - - diff --git a/guide_book/src/architecture/architecture.md b/guide_book/src/architecture/architecture.md new file mode 100644 index 0000000..49dfc59 --- /dev/null +++ b/guide_book/src/architecture/architecture.md @@ -0,0 +1,22 @@ +# ODP Architecture +The __Open Device Partnership (ODP)__ architecture is designed to provide a modular, scalable, and secure framework for developing embedded systems. Rooted in Rust's safety guarantees and shaped by a philosophy of composable components, ODP offers a consistent foundation for both low-level and system-level firmware development. + +ODP spans two distinct domains: The __Patina framework__, a Rust-based system for building DXE-style boot firmware, and the __Embedded Controller (EC)__, architecture, supporting microcontroller-based runtime services and coordination. + +Though their implementations differ, these domains are united under the ODP model by shared principles and architectural patterns. Together, they promote a unified approach to firmware engineering that emphasizes safety, reuse, and composability. + +![ODP Architecture Patterns](./media/odp_domains.png) +> #### Figure: ODP Architecture Across Domains +> The ODP Core expresses a set of shared design patterns -- such as modularity, safety, and flexibility -- that are applied independently within two distinct ecosystems: Patina (x86 firmware) and Embedded Controller (ฮผC runtime). Each domain develops its own components, tooling, and conventions while adhering to the same architectural principles. + + +## Common Patterns of ODP +While Patina and EC serve different ends of the firmware spectrum, they share a common set of patterns and priorities that define the ODP approach: +- **Modularity**: ODP components are explicitly modular. Each unit is independently defined and can be composed into larger systems through clearly defined interfaces. This is central to the dependency-injection models used by both Patina and EC's service registry architecture. +- **Safety**: Rustโ€™s type system and ownership model are used to enforce memory and concurrency safety at compile time. This baseline ensures that ODP firmware avoids common pitfalls typical of C-based implementations. +- **Reusability**: Components are designed to be reusable across platforms, configurations, and targets. Traits and message interfaces abstract functionality, enabling code reuse without sacrificing clarity or safety. +- **Flexibility**: The ODP structure supports adaptation to a wide variety of host platforms and runtime environments. This flexibility allows implementers to scale from minimal EC services up to full boot firmware stacks. +- **Community**: ODP is built on open standards and community contributions. This encourages collaboration, knowledge sharing, and the evolution of best practices across the ecosystem, which only enhances the robustness of the architecture and its promises of safety and modularity. + + +The Open Device Partnership is founded more upon _alignment_ than _unification_ and is supported and extended by the principles of a strong Open Source community, where it will expand and evolve. \ No newline at end of file diff --git a/guide_book/src/architecture/ec_components.md b/guide_book/src/architecture/ec_components.md new file mode 100644 index 0000000..9c798c8 --- /dev/null +++ b/guide_book/src/architecture/ec_components.md @@ -0,0 +1,39 @@ +# EC Component Model + +A component that implements a specification and depends upon a HAL interface. + +```mermaid +flowchart TD + A[Component] + B[Specification Trait] + C[HAL Trait] + + A --> B + A --> C + ``` + + A component is housed within a subsystem, which is controlled by a service. The service orchestrates the component's behavior and manages its lifecycle. + +```mermaid +flowchart TD + A[__Controller__
Implements Service Interface Trait] + B[__Device__
Implements Component Type Trait] + C[__Component__
Implements Specification Trait] + + A --> B + B --> C + +``` + +Component interactions are generally initiated in response to message events. The controller receives a message, which it routes to the component. The component then calls into the HAL to perform the requested operation. + +```mermaid +flowchart TD + A[__Service Layer__
e.g. _Controller_] + B[__Device Layer__
_Wrapped Component_] + C[__Component Layer__
_Handles Message_] + + M["Incoming Message"] --> A + A -->|calls _handle_| B + B -->|calls _handle_| C +``` diff --git a/guide_book/src/architecture/ec_services.md b/guide_book/src/architecture/ec_services.md new file mode 100644 index 0000000..96e7b18 --- /dev/null +++ b/guide_book/src/architecture/ec_services.md @@ -0,0 +1,58 @@ +# EC Services Architecture + + +## Communication Pathways +```mermaid +flowchart TD + A[Host OS or Firmware] + B[ACPI Interface / Mailbox / HID] + C[EC Service Dispatcher] + D[Subsystem Controller - Battery, Thermal, etc.] + + A --> B + B --> C + C --> D +``` +> Figure: EC Service Entry Points +> Host platforms interact with EC services through one or more communication pathways. These may include ACPI-defined regions, mailbox protocols, or vendor-defined HID messages. The EC processes these via service dispatch logic. + +## Messaging Exchange Format (Conceptual) +```mermaid +sequenceDiagram + participant Host + participant EC + + Host->>EC: Request {Service ID, Command, Payload} + EC-->>Host: Response {Status, Data} + +``` +> __Figure: Message Exchange__ +> +> The diagram above illustrates the basic message handshake. +> +> This table explains the field data exchanged: +> | Field | Description | +> |-------|-------------| +> | Service ID | Identifies target subsystem | +> | Command | Specific operation to perform | +> | Payload | Data required for operation | +> | Status | Result of operation | +> | Data | Optional result values | + + +## Secure and Non-Secure Implementations +In the diagram below, the dark blue sections are those elements that are part of normal (non-secure) memory space and may be called from a service interface directly. As we can see on the Non-Secure side, the ACPI transport channel has access to the EC component implementations either directly or through the FF-A (Firmware Framework Memory Management Protocol). + +Secure implementation architecture can be seen in the upcoming Security discussion. + +```mermaid +flowchart TD + A[Untrusted Host OS] + B[Trusted Runtime Services] + C[EC Service Gateway] + D[EC Subsystems] + + A -.->|Filtered Access| C + B -->|Secure Channel| C + C --> D +``` diff --git a/guide_book/src/architecture/embedded_controller.md b/guide_book/src/architecture/embedded_controller.md new file mode 100644 index 0000000..7fb39de --- /dev/null +++ b/guide_book/src/architecture/embedded_controller.md @@ -0,0 +1,79 @@ +# Embedded Controller Architecture + +The construction of a typical component under the control of a service subsystem looks as follows: + +```mermaid +flowchart LR + A[Some Service
Service initiates query] + B[Subsystem Controller
Orchestrates component behavior] + C[Component Trait Interface
Defines the functional contract] + D[HAL Implementation
Implements trait using hardware-specific logic] + E[EC / Hardware Access
Performs actual I/O operations] + + A --> B + B --> C + C --> D + D --> E + + subgraph Service Layer + A + end + + subgraph Subsystem Layer + B + end + + subgraph Component Layer + C + D + end + + subgraph Hardware Layer + E + end +``` + +When in operation, it conducts its operations in response to message events + +```mermaid +sequenceDiagram + participant Service as Some Service + participant Controller as Subsystem Controller + participant Component as Component (Trait) + participant HAL as HAL (Hardware or Mock) + + Service->>Controller: query_state() + Note right of Controller: Subsystem logic directs call via trait + Controller->>Component: get_state() + Note right of Component: Trait implementation calls into HAL + Component->>HAL: read_some_level() + HAL-->>Component: Ok(0) + Component-->>Controller: Ok(State { value: 0 }) + Controller-->>Service: Ok(State) + + alt HAL returns error + HAL-->>Component: Err(ReadError) + Component-->>Controller: Err(SomeError) + Controller-->>Service: Err(SomeUnavailable) + end + +``` + +A core pattern of the ODP architecture is one of __Dependency Injection__. The service and subsystem `Traits` define the functional contract of the component, while the HAL implementation provides the hardware-specific logic. This allows for a clear separation of concerns and enables the component to be easily tested and reused across different platforms. Components are eligible to be registered for their subservice if they match the required traits. + +```mermaid +flowchart TD + subgraph Component + A[Needs Logger and Config] + end + + subgraph Framework + B[Provides ConsoleLogger] + C[Provides NameConfig] + D[Injects Dependencies] + end + + B --> D + C --> D + D --> A +``` diff --git a/guide_book/src/architecture/media/PI_Boot_Phases.jpg b/guide_book/src/architecture/media/PI_Boot_Phases.jpg new file mode 100644 index 0000000..e5f053c Binary files /dev/null and b/guide_book/src/architecture/media/PI_Boot_Phases.jpg differ diff --git a/guide_book/src/architecture/media/odp_domains.png b/guide_book/src/architecture/media/odp_domains.png new file mode 100644 index 0000000..dd1b73d Binary files /dev/null and b/guide_book/src/architecture/media/odp_domains.png differ diff --git a/guide_book/src/architecture/patina_components.md b/guide_book/src/architecture/patina_components.md new file mode 100644 index 0000000..9bf2f78 --- /dev/null +++ b/guide_book/src/architecture/patina_components.md @@ -0,0 +1,37 @@ +# Patina Components + +Patina components are built according to Traits and introduced via Dependency Injection (DI) into the Patina framework. This allows for a modular and reusable design that can be easily adapted to different platforms and configurations. + +## Component Development + +Please refer to the [Patina documentation]() for more details, but the basic pseudo-code steps for creating a component are actually pretty simple: + +```rust +use log::info; +use patina_sdk::{component::params::Config, error::Result}; + +#[derive(Default, Clone, Copy)] +pub struct Name(pub &'static str); + +pub fn run_test_component(name: Config) -> Result<()> { + info!("============= Test Component ==============="); + info!("Hello, {}!", name.0); + info!("========================================="); + Ok(()) +} +``` +One creates a component as a function with parameters that implement the required traits (in this case the Config trait). The function can then be registered with the Patina framework, which will handle the dependency injection and execution of the component. + +```rust +Core::default() + .with_component(test_component::run_test_component) + .with_config(test_component::Name("World")) + .start() +``` + +What the component actually does is up to the developer, but the structure remains consistent. The component can be as simple or complex as needed, and it can interact with other components through the Patina framework's messaging system. + + +Refer to Patina's [component model documentation](https://github.com/OpenDevicePartnership/patina/blob/728c7e3a345a0a74351b14c1ff9a6bf948248fed/docs/src/dxe_core/component_model.md) +and the Patina [dispatcher documentation](https://github.com/OpenDevicePartnership/patina/blob/728c7e3a345a0a74351b14c1ff9a6bf948248fed/docs/src/dxe_core/dispatcher.md) +for official details on the component model and how to implement components in Patina. diff --git a/guide_book/src/architecture/patina_framework.md b/guide_book/src/architecture/patina_framework.md new file mode 100644 index 0000000..fb169dc --- /dev/null +++ b/guide_book/src/architecture/patina_framework.md @@ -0,0 +1,24 @@ +# Patina Framework Architecture + +Traditional UEFI architecture describes a series of boot phases that are executed in a specific order to initialize the system and prepare it for use. The Patina framework is designed to fit within this architecture, specifically focusing on the DXE (Driver Execution Environment) phase. + +![Boot Phases](./media/PI_Boot_Phases.jpg) + +Patina re-imagines the DXE phase as a framework for building modular, reusable components that can be dynamically loaded and executed. This approach allows for greater flexibility and agility in firmware development, enabling developers to create components that can be easily reused across different platforms and configurations. + +```mermaid +flowchart TD + A[UEFI] --> B[Patina Framework] + B --> C[Component Registration] + B --> D[EFI Binary Output] + B --> E[Platform Boot] + C --> F[Device Drivers] + E --> G[System Services] + E --> H[User Applications] + F --> G +``` +> #### Figure: Patina Framework within UEFI Boot Phases + +For architectural details, refer to the Patina [DXE Core documentation](https://github.com/OpenDevicePartnership/patina/blob/728c7e3a345a0a74351b14c1ff9a6bf948248fed/docs/src/patina.md#patina-dxe-core). + + diff --git a/guide_book/src/architecture/secure_boot.md b/guide_book/src/architecture/secure_boot.md new file mode 100644 index 0000000..513c677 --- /dev/null +++ b/guide_book/src/architecture/secure_boot.md @@ -0,0 +1,47 @@ +# Secure Boot Architecture + +__Secure Boot__ is a cryptographically enforced boot validation mechanism that ensures each stage of system initialization is authenticated and unmodified. Its goal is to prevent unauthorized firmware or operating systems from executing on the platform. + +```mermaid +flowchart TD + A[__Boot ROM__
Immutable Trust Anchor] + B[__Bootloader__
- _e.g. BL1, Coreboot_] + C[__Patina DXE Core__
Signed EFI Binary] + D[__OS Bootloader__
_Optional Verification_] + E[__Operating System__
Signed Kernel and Drivers] + + A --> B + B --> C + C --> D + D --> E +``` +> __Figure: Secure Boot Chain of Trust__ +> +> Each stage validates the integrity and authenticity of the next using cryptographic signatures or measured hashes. Patina fits into this chain as the DXE-phase firmware payload, typically signed and validated prior to execution. + +## Role of Patina in Secure Boot + +1. The DXE Core produced by Patina is signed and stored as an .efi binary. +2. The platform bootloader (coreboot, U-Boot, etc.) or UEFI Secure Boot loader validates the Patina payload before execution. +3. Patina itself does not contain its own secure bootloader but is designed to be a signed leaf node in a secure boot chain. + +On platforms with measured boot (e.g., DRTM or TPM-backed environments), Patina binaries can also be hashed and extended into a PCR register. + +## Signature and Validation Workflow + +```mermaid +flowchart TD + A[__Patina EFI Binary__] + B[__Public Key__ - _in Bootloader_] + C[__Signature Verification__] + D[__Execution__] + + A --> C + B --> C + C -->|If Valid| D + C -->|If Invalid| E[Halt / Recovery] +``` + +A secure boot process is only one part of the platform's trust chain. To preserve integrity after boot, Firmware Updates must be signed and verified, and Runtime E access must be validated and isolated. + + diff --git a/guide_book/src/architecture/secure_ec_services.md b/guide_book/src/architecture/secure_ec_services.md new file mode 100644 index 0000000..dc83b82 --- /dev/null +++ b/guide_book/src/architecture/secure_ec_services.md @@ -0,0 +1,30 @@ +# Secure EC Services + + +```mermaid +flowchart TD + subgraph Host System + A1[ACPI Methods] + A2[ACPI Notification Events] + end + + subgraph Secure World + B1["Hafnium (FFA Handler)"] + end + + subgraph EC + C1[EC Dispatcher] + C2[Subsystem Controller] + end + + A1 -->|"Secure Path (ARM/FFA)"| B1 + A2 -->|Notifications| B1 + B1 -->|Structured Command| C1 + C1 --> C2 + + A1 -->|"Non-Secure (x86)"| C1 +``` + +> __Figure: Hostโ€“EC Communication Paths__ +> +> The host communicates with the EC via __ACPI__ calls and notification events. On __ARM__ platforms with secure world enforcement, messages are routed through __Hafnium__ via __FF-A__ interfaces. On __x86__ platforms, communication is direct. The EC dispatcher then forwards commands to appropriate subsystem controllers. diff --git a/guide_book/src/architecture/secure_firmware_updates.md b/guide_book/src/architecture/secure_firmware_updates.md new file mode 100644 index 0000000..41c7572 --- /dev/null +++ b/guide_book/src/architecture/secure_firmware_updates.md @@ -0,0 +1,24 @@ +# Secure Firmware Updates +Secure firmware update mechanisms are critical to preserving system trust over time. They prevent unauthorized or malicious firmware from being flashed, and protect the system from rollback to known-vulnerable versions. ODP-based firmware components, including Patina and the EC runtime, support signed and validated update flows. + +## Update Integrity Requirements +Firmware updates must meet several key integrity requirements: +- **Authentication**: Updates must be signed by a trusted vendor key. +- **Integrity**: Payloads must not be tampered with (crytopgraphic hashes are checked). +- **Rollback Protection**: Systems must prevent downgrading to older, potentially vulnerable firmware versions. +- **Isolation**: Updates must not interfere with runtime operations, allow modification of unrelated components, or expose sensitive data. + +```mermaid +flowchart LR + A[Host System or Update Agent] + B[Receives Update Payload] + C[Verifies Signature] + D[Checks Version Policy] + E[Applies Update] + F[Reboots to New Firmware] + + A --> B --> C --> D --> E --> F +``` +> __Figure: Generic Secure Update Flow__ +> +> Update delivery may be initiated by the OS or host firmware. The platform verifies signatures and version constraints before committing the update and restarting the system. \ No newline at end of file diff --git a/guide_book/src/architecture/security_architecture.md b/guide_book/src/architecture/security_architecture.md new file mode 100644 index 0000000..fe6df13 --- /dev/null +++ b/guide_book/src/architecture/security_architecture.md @@ -0,0 +1,45 @@ +# ODP Security Architecture + +Whether in the Patina or Embedded Controller domain, ODP's security architecture is designed to ensure the integrity and trustworthiness of firmware components. This architecture is built upon several key principles: + +- __Least Privilege__: Components operate with the minimum privileges necessary to perform their functions, reducing the risk of unauthorized access or damage. +- __Isolation__: Components are isolated from one another to prevent unintended interactions and to contain potential security breaches. +- __Verification__: Components are verified at boot time to ensure they have not been tampered with and that they meet the expected security standards. +- __Layered Defense__: Security concerns are enforced at multiple levels โ€” bootloader, firmware, EC messaging, and runtime service dispatch. + +```mermaid +flowchart TD + A[Reset Vector / ROM] + B[Bootloader / Core Root of Trust] + C[Patina DXE Core] + D[OS Boot] + E[EC Runtime] + F[EC Services] + + A --> B + B --> C + C --> D + + B -->|Key Exchange, FFA| E + E --> F + + subgraph Secure World + B + E + end + + subgraph Non-Secure World + C + D + F + end +``` +> __Figure: System Trust Boundaries__ +> +> The ODP system defines strong isolation between secure and non-secure execution. Firmware integrity is established early and extended to runtime services. EC services may operate in either domain, depending on platform architecture. + +| Area | Concerns | Enforced By | +| ------------------- | ---------------------------------------- | -------------------------------------- | +| **Secure Boot** | Root trust, signed firmware, measurement | Bootloader / Patina | +| **Firmware Update** | Verification, rollback protection | Update agent, signing keys | +| **EC Services** | Isolation, message auth, FF-A routing | Hafnium, UUID filtering, runtime logic | diff --git a/guide_book/src/conclusions.md b/guide_book/src/conclusions.md index 6027caa..12c97e2 100644 --- a/guide_book/src/conclusions.md +++ b/guide_book/src/conclusions.md @@ -1 +1,20 @@ # Summary and Takeaways +Thank you for following along with our exploration of the Open Device Partnership project and its subsystems. In this guide, we have covered a range of topics from component architecture to testing strategies, all while adhering to the principles of modularity and reusability. + +## Key Takeaways +- **Modular Design**: We emphasized the importance of modularity in firmware development, allowing for easier maintenance and upgrades. +- **Asynchronous Programming**: We utilized asynchronous programming patterns to handle events and messages efficiently, which is crucial for embedded systems. +- **Testing**: We implemented comprehensive testing strategies, including unit tests and integration tests, to ensure the reliability of our components. +- **Dependency Injection**: We demonstrated how to use generic types and dependency injection to create flexible and reusable components. +- **Real-World Applications**: We provided practical examples of how to implement battery and charger subsystems, showcasing the real-world applicability of the ODP framework. +- **Community and Contribution**: We highlighted the importance of community involvement and how to contribute to the ODP project, fostering a collaborative environment for innovation. + +## Next Steps +_TODO_ + +Return to the [ODP Documentation Home](../index.md) to explore more about the Open Device Partnership, or dive deeper into specific subsystems and components that interest you. + +Return to the [Tracks of ODP](../tracks.md) to revisit the various guided paths through the documentation and find the next topic that aligns with your interests or role. + +View the [ODP Specifications](../specs/index.md) to understand the standards and protocols that underpin the ODP framework. + diff --git a/guide_book/src/how/ec/embedded_controller.md b/guide_book/src/how/ec/embedded_controller.md index 9851a7a..444a84a 100644 --- a/guide_book/src/how/ec/embedded_controller.md +++ b/guide_book/src/how/ec/embedded_controller.md @@ -1,8 +1,7 @@ # Embedded Controller Components -_TODO_ +The Embedded Controller orchestrates a number of individual Device Components. Each component is tailored to meet a given subservice feature that is defined by traits. A Device signature that fulfills these traits can be injected as a component into the system in a modular way. -The Embedded Controller topic comes first, because this is where most of the modern features live, it will need to wait for this to be ready and then also connect to it for certain runtime operations. +In the following exercises we will build a few such components -- Battery, Charger, and Thermal -- and learn the patterns for constructing and testing Embedded Controller components that are ready for embedded targeting and integration. -Basic idea is to reference the Battery effort currently in place, and the soon to follow Charger and Thermal examples. This should provide a pretty good blueprint for building a mock or real EC for these components and inspire the pattern for things not covered by the examples. diff --git a/guide_book/src/how/ec/embedded_target/embedded_dependencies.md b/guide_book/src/how/ec/embedded_target/embedded_dependencies.md index 3c3f15c..37338fe 100644 --- a/guide_book/src/how/ec/embedded_target/embedded_dependencies.md +++ b/guide_book/src/how/ec/embedded_target/embedded_dependencies.md @@ -1 +1,2 @@ # Dependencies +_TODO: This section will discuss the dependencies required for building and running the embedded controller components, including any specific libraries or tools needed._ \ No newline at end of file diff --git a/guide_book/src/how/ec/embedded_target/embedded_flashing.md b/guide_book/src/how/ec/embedded_target/embedded_flashing.md index 52eeab4..2ec19a4 100644 --- a/guide_book/src/how/ec/embedded_target/embedded_flashing.md +++ b/guide_book/src/how/ec/embedded_target/embedded_flashing.md @@ -1 +1,2 @@ # Flashing +_TODO: This section will discuss how to flash the embedded controller firmware onto the target hardware, including the tools and processes involved._ \ No newline at end of file diff --git a/guide_book/src/how/ec/embedded_target/embedded_logging.md b/guide_book/src/how/ec/embedded_target/embedded_logging.md index b921bbe..cd13d7b 100644 --- a/guide_book/src/how/ec/embedded_target/embedded_logging.md +++ b/guide_book/src/how/ec/embedded_target/embedded_logging.md @@ -1 +1,2 @@ # Logging +_TODO: This section will discuss how to implement logging in the embedded controller components, including best practices for logging in embedded systems and how to integrate logging into the existing codebase._ \ No newline at end of file diff --git a/guide_book/src/how/ec/embedded_target/embedded_targeting.md b/guide_book/src/how/ec/embedded_target/embedded_targeting.md index bb85efe..6e7d78b 100644 --- a/guide_book/src/how/ec/embedded_target/embedded_targeting.md +++ b/guide_book/src/how/ec/embedded_target/embedded_targeting.md @@ -1 +1,2 @@ # Embedded Targeting +_TODO: This section will discuss how to target embedded systems with the ODP EC components we have built, including how to set up the environment, build for embedded targets, and test on those targets._ diff --git a/guide_book/src/how/ec/embedded_target/project_board.md b/guide_book/src/how/ec/embedded_target/project_board.md index 61baf83..4691d2d 100644 --- a/guide_book/src/how/ec/embedded_target/project_board.md +++ b/guide_book/src/how/ec/embedded_target/project_board.md @@ -1 +1,2 @@ # Project Board +_TODO: This section will discuss how to set up a project board for managing the development of embedded controller components, including battery, charger, and thermal services._ \ No newline at end of file diff --git a/guide_book/src/how/ec/integration/integration.md b/guide_book/src/how/ec/integration/integration.md index 50a133c..a480f17 100644 --- a/guide_book/src/how/ec/integration/integration.md +++ b/guide_book/src/how/ec/integration/integration.md @@ -1 +1,2 @@ # Integration +_TODO: Integration of battery, charger, and thermal services into the embedded controller._ \ No newline at end of file diff --git a/guide_book/src/how/ec/integration/integration_tests.md b/guide_book/src/how/ec/integration/integration_tests.md new file mode 100644 index 0000000..206b406 --- /dev/null +++ b/guide_book/src/how/ec/integration/integration_tests.md @@ -0,0 +1,3 @@ +# Integration Tests +_TODO: The tests of the full integration_ + diff --git a/guide_book/src/intro/concepts/Bookshelves.md b/guide_book/src/intro/concepts/Bookshelves.md deleted file mode 100644 index 6b5a762..0000000 --- a/guide_book/src/intro/concepts/Bookshelves.md +++ /dev/null @@ -1,16 +0,0 @@ -# ODP Repositories and bookshelves - -There are currently more than a dozen separate repositories that make up the ODP offering. This is deliberate - rather than having a single Mono-Repo that -contains the full suite, individual repositories allows contributors focused on specific areas to only concern themselves with their repositories of interest rather than devote time and resources to managing a local copy of a large single repository. - -However, with separated repositories, a challenge arises when trying to introduce and document the whole of ODP in a consistent manner. For that reason, documents are organized as separate books but "placed on different shelves" according to their scope and audience. - -## Bookshelves -In the same way that a book shelf in the physical world is a holder of books, an ODP library bookshelf is a holder of web page content. This content may be generated Rust API documentation, or mdbook style contextual information, or in some cases other imported web-displayable content. - -The shelves are organized as follows: -- Shelf 1: Introduction and Concepts -- Shelf 2: Examples and Tutorials -- Shelf 3: Supporting crates and SDKs -- Shelf 4: Specifications and API references - diff --git a/guide_book/src/intro/concepts/EC_Services.md b/guide_book/src/intro/concepts/EC_Services.md index 0f7f885..d5891da 100644 --- a/guide_book/src/intro/concepts/EC_Services.md +++ b/guide_book/src/intro/concepts/EC_Services.md @@ -33,7 +33,7 @@ describes the relationship of a hypervisor controlling a set of secure memory pa FF-A is available for Arm devices only. A common solution for x64 is still in development. For x64 implementations, use of SMM is employed to orchestrate hypervisor access using the [Hafnium] Rust product. -In a Non-Secure implementation _without_ a hyperviser, the ACPI connected components can potentially change the state within any accessible memory space. An implementation with a hypervisor cannot. It may still be considered a "Non-Secure" implementation, however, as the ACPI data itself is unable to be verified for trust. +In a Non-Secure implementation _without_ a hypervisor, the ACPI connected components can potentially change the state within any accessible memory space. An implementation with a hypervisor cannot. It may still be considered a "Non-Secure" implementation, however, as the ACPI data itself is unable to be verified for trust. In a fully "Secure" implementation, controller code is validated at boot time to insure the trust of the data it provides. Additionally, for certain types of data, digital signing and/or encryption may be used on the data exchanged to provide an additional level of trust. diff --git a/guide_book/src/intro/getting_started.md b/guide_book/src/intro/getting_started.md new file mode 100644 index 0000000..76b2936 --- /dev/null +++ b/guide_book/src/intro/getting_started.md @@ -0,0 +1,38 @@ +# Getting Started with ODP + +![Choose Your Path](./media/choose_path.png) + +## Welcome to the Open Device Partnership (ODP)! + +ODP is a community-driven framework for building **secure**, **modular**, and **reusable** firmware components across a range of systems. Whether youโ€™re interested in low-level boot firmware, embedded controller services, or integrating a complete firmware stack, ODP has something for you. + +## What is ODP? + +ODP brings modern software engineering practicesโ€”like memory safety and dependency injectionโ€”to the world of firmware. It leverages Rust to improve confidence, maintainability, and modularity across diverse hardware and system designs. + +It also embraces existing standards like UEFI, DICE, ACPI, and EC protocolsโ€”but makes them more accessible and safer to implement. + +--- + +## How to Use This Guide +This documentation is designed to serve multiple audiences working with the Open Device Partnership (ODP). Whether you're a firmware engineer, technology advisor, integrator, or contributor, you'll find resources tailored to your needs. + +In the [Tracks of ODP](../tracks.md), you will find curated content organized into guided paths. Each track is designed to help you learn about ODP from different perspectives, whether you're focused on value propositions, specific technologies like Patina, or roles such as engineering or advising. + +### Role-Based Reading Guidance + +| Role | Recommended Path | +|-------------------|-----------------------------------------------------------------------------| +| __Firmware Engineer__ | Follow the documentation from start to finish. Includes technical tutorials, architectural insights, and integration exercises. | +| __Technology Advisor__ | Read the mainline content up through the Architectural Overview. Skip hands-on exercises. Then proceed to the Tracks page to explore summaries and technical overviews by topic.| +| __Integrator__ | Read through the Architectural Overview and Integration sections, then follow the [Integrator Track](../../tracks/integrator/track_overview.md) for platform-specific setup and bundling guidance. | +| __Contributor__ | Review the mainline Value Proposition and Architecture Overview, then head to the [Contributor Track](../../tracks/contributor/track_overview.md) for community, contribution standards, and roadmap content. | +| __Security Reviewer__ | Jump to the [Security Track](../../tracks/security/track_overview.md). It includes collected topics around trusted boot, isolation, and other security concerns, with cross-links to affected design areas. | +| __Patina SDK (UEFI) Developer__ | Refer to external Patina resources with context provided in the [Patina Track](../../tracks/patina/track_overview.md). Youโ€™ll find links to upstream Patina crates, code examples, and implementation notes. | + + +--- + +### Where to next? + +If you are not a developer, you can skip the next section and go directly to the [Tracks of ODP](../tracks.md) to explore the various paths available. However, even non-developers may find it useful to understand the basics of Rust and how ODP uses it to ensure safety and reliability in firmware development. diff --git a/guide_book/src/intro/media/choose_path.png b/guide_book/src/intro/media/choose_path.png new file mode 100644 index 0000000..9133457 Binary files /dev/null and b/guide_book/src/intro/media/choose_path.png differ diff --git a/guide_book/src/intro/tutorial/tutorial.md b/guide_book/src/intro/tutorial/tutorial.md index 7275fcc..c112b86 100644 --- a/guide_book/src/intro/tutorial/tutorial.md +++ b/guide_book/src/intro/tutorial/tutorial.md @@ -2,12 +2,14 @@ #### _Ready to go hands-on?_ +If you are not a developer, you can skip this section and go directly to the [Tracks of ODP](../tracks.md) to explore the various paths available. However, even non-developers may find it useful to understand the basics of Rust and how ODP uses it to ensure safety and reliability in firmware development. + Later in this book we will be writing real embedded code for real hardware, using one of many easily sourced and affordable development boards, such as the [STM32F3Discovery Board](https://www.st.com/en/evaluation-tools/stm32f3discovery.html), which is used in the Rust Embedded Book and is suitable for the exercises we will conduct here. If you have a different development board, that's fine -- the examples are not really tied to any particular piece of hardware, and only minor adjustments may be needed to adapt the instructions here to different hardware. -If you are new to embedded programming in Rust, you may find the guide and excercises in the -[Rust Embedded Book](https://doc.rust-lang.org/stable/embedded-book/start) to be a great introduction. +>๐Ÿ‘“ ๐Ÿ‘‰ If you are new to embedded programming in Rust, you may find the guide and exercises in the +[Rust Embedded Book](https://doc.rust-lang.org/stable/embedded-book/start) to be a great introduction. Once we have learned the basic principles of how to use the Rust language in an embedded environment, and have set up the tooling, we are ready to move into the ODP framework to structure our designs. diff --git a/guide_book/src/intro/welcome.md b/guide_book/src/intro/welcome.md index afbd159..abe65e7 100644 --- a/guide_book/src/intro/welcome.md +++ b/guide_book/src/intro/welcome.md @@ -1,9 +1,12 @@ -# Getting Started +# Welcome Developer! +Welcome! If you're a firmware engineer new to the Open Device Partnership, this is the right place to begin. -Welcome! If you're new to the Open Device Partnership, this is the right place to begin. +If you're also new to the world of Embedded Controllers and the software that drives them, don't worry โ€” you're still in the right place. + +If you are a previous UEFI developer, you may find some of the concepts familiar, but ODP introduces new patterns and practices that will help you build more secure and modular firmware components. ODP introduces Patina, a Rust-based framework that provides a modern approach to firmware development, focusing on safety, modularity, and reusability. Patina honors the legacy and traditions of UEFI while introducing new paradigms that make firmware development more efficient and secure. +For more specific information about Patina, you can refer to the [Patina Track](../../tracks/patina/track_overview.md) or the [Patina Concepts](./intro/concepts/patina.md) section. -If you're also new to the world of Embedded Controllers and the software that drives them, don't worryโ€”you're still in the right place. |   |   |---|--- diff --git a/guide_book/src/sample-system-implementation.md b/guide_book/src/sample-system-implementation.md deleted file mode 100644 index 8d47c74..0000000 --- a/guide_book/src/sample-system-implementation.md +++ /dev/null @@ -1 +0,0 @@ -# Sample System Implementation diff --git a/guide_book/src/specs/ec_interface/ec_interface.md b/guide_book/src/specs/ec_interface/ec_interface.md index 80fc146..a1e96d3 100644 --- a/guide_book/src/specs/ec_interface/ec_interface.md +++ b/guide_book/src/specs/ec_interface/ec_interface.md @@ -1,6 +1,6 @@ # Embedded Controller Interface Specification -Embedded Controller(EC) Interface Specification describes base set of requirements to interface to core windows features. +Embedded Controller(EC) Interface Specification describes base set of requirements to interface to core Windows features. It covers the following areas: - Firmware Management - Battery diff --git a/guide_book/src/specs/sample-system-implementation.md b/guide_book/src/specs/sample-system-implementation.md deleted file mode 100644 index 8d47c74..0000000 --- a/guide_book/src/specs/sample-system-implementation.md +++ /dev/null @@ -1 +0,0 @@ -# Sample System Implementation diff --git a/guide_book/src/tracks.md b/guide_book/src/tracks.md index 69a8da1..ecb30e3 100644 --- a/guide_book/src/tracks.md +++ b/guide_book/src/tracks.md @@ -15,8 +15,36 @@ ODP does not usurp this development paradigm but rather empowers it further thro This book is geared to a couple of different distinct audiences. If you are concerned primarily with any one of the particular 'tracks' of ODP and are interested in a guide to which ODP repositories are relevant for that track, continue with [What is in ODP?](./what/what.md) -If you are interested in examples of _how_ to develop along any of these tracks, follow the examples in [Building a Virtual Laptop](./laptop/laptop.md), either those relevant to the topic of your interest alone, or follow the entire exercise to build a complete virtual laptop comprised of each of these elements. +If you are a __Firmware Engineer__ you likely will want to continue following ahead into the hands-on projects for building Embedded Controller components and services, ultimately resulting in the project for building a virtual laptop with Patina firmware. To continue on this track, simply continue to the next article. +Depending on your interest or role, we offer guided tracks through the documentation: + +#### Subject-based: +- ๐Ÿ… [**Value Proposition**](../tracks/value_proposition/track_overview.md) + Understand the core benefits of ODP, including security, modularity, and cross-domain coherence. + +- ๐Ÿ›ซ [**Patina Boot Firmware**](../tracks/patina/track_overview.md) + Learn to build UEFI firmware with Rust using the Patina framework. + +- ๐Ÿ”‹ [**Embedded Controller and Services**](../tracks/embedded_controller/track_overview.md) + Dive into EC subsystems like battery, charger, and thermal control with real component walkthroughs. + +- ๐Ÿ” [**Security Architecture**](../tracks/security/track_overview.md) + Explore trusted boot, firmware identity, and the DICE model. + + + +#### Role-based: + +- ๐Ÿ”ง [**Integrator**](../tracks/integrator/track_overview.md) + Discover how to integrate ODP components into larger systems. + +- ๐Ÿง‘โ€๐Ÿคโ€๐Ÿง‘ [**Contributor**](../tracks/contributor/track_overview.md) + Get involved in the ODP community by contributing code, documentation, or reporting issues. + +Technical readers may also be interested in the [Specifications](./specs/specifications.md) section, which provides detailed technical specifications for ODP components and services. + +--- diff --git a/tracks/contributor/src/SUMMARY.md b/tracks/contributor/src/SUMMARY.md new file mode 100644 index 0000000..87c2bf5 --- /dev/null +++ b/tracks/contributor/src/SUMMARY.md @@ -0,0 +1,6 @@ +[Overview](./track_overview.md) +- [Where to Contribute](./where_to_contribute.md) +- [Contribution Workflow](./contribution_workflow.md) +- [Code Guidelines](./code_guidelines.md) +- [Documentation Contributions](./docs.md) +- [Design Discussions and Governance](./governance.md) diff --git a/tracks/contributor/src/code_guidelines.md b/tracks/contributor/src/code_guidelines.md new file mode 100644 index 0000000..7bc8f40 --- /dev/null +++ b/tracks/contributor/src/code_guidelines.md @@ -0,0 +1,13 @@ +# Code Guidelines +Please see the [ODP Governance Statement](https://github.com/OpenDevicePartnership/governance/blob/main/README.md) for more details on the contribution process and how decisions are made within the ODP community. + +# Format, style, and linting +In general, all code contributions should include: +- โœ… **Unit Tests**: Use `cargo tarpaulin` to ensure coverage. +- ๐Ÿ“š **Documentation**: Update docs, READMEs, or rustdoc as needed. +- ๐Ÿงน **Linting and Formatting**: Follow the project's coding style and use tools like `cargo fmt` and `clippy`. +- ๐Ÿ‘€ **Code Review**: Be ready for review by maintainers. +- ๐Ÿ” **Feedback and Revisions**: Collaborate to improve quality. + +For more details on the contribution workflow for Patina-related contributions, please also see [Patina Developer Documentation](https://github.com/OpenDevicePartnership/patina/blob/728c7e3a345a0a74351b14c1ff9a6bf948248fed/docs/src/SUMMARY.md#summary). + diff --git a/tracks/contributor/src/contribution_workflow.md b/tracks/contributor/src/contribution_workflow.md new file mode 100644 index 0000000..a121361 --- /dev/null +++ b/tracks/contributor/src/contribution_workflow.md @@ -0,0 +1,11 @@ +## Contribution Workflow +Contributions to an ODP repository should start with a fork of the repository into a downstream repository under the contributor's GitHub account. This allows the contributor to make changes without affecting the upstream repository until the changes are ready to be merged. The typical workflow is as follows: +1. ๐Ÿด **Fork the Repository**: Create a personal copy of the repository. +2. ๐Ÿ’ป **Clone the Fork**: Download your forked repository to your machine. +3. ๐ŸŒฟ **Create a Branch**: Create a new branch for your changes to keep changes isolated and organized. +4. ๐Ÿ”„ **Sync with Upstream**:Stay up to date with the main project. +5. โœ๏ธ **Make Changes**: Code, docs, or other contributions. +6. ๐Ÿงพ **Commit Changes**: Use clear, meaningful commit messages. +7. ๐Ÿš€ **Push Changes**: Send changes to your GitHub fork. +8. ๐Ÿ“ฌ **Create a Pull Request**: Open a pull request (PR) upstream to propose your changes. + diff --git a/tracks/contributor/src/docs.md b/tracks/contributor/src/docs.md new file mode 100644 index 0000000..c1d6822 --- /dev/null +++ b/tracks/contributor/src/docs.md @@ -0,0 +1,11 @@ +# Documentation Contributions +Accurate and informative documentation is crucial for the success of any open-source project. When contributing to ODP, please ensure that your documentation contributions meet the following standards: +- ๐Ÿง  **Clarity**: Avoid jargon, explain things simply. +- ๐ŸŽฏ **Relevance**: Match doc to the feature or code behavior. +- ๐ŸŽจ **Consistency**: Follow project doc style. +- ๐Ÿ’ก **Examples**: Show how things work with real usage. +- โœ๏ธ **Review**: Accept and apply constructive feedback. +- ๐Ÿ”„ **Updates**:Keep docs aligned with code changes. + +Whether you are contributing to this documentation in the [Documentation repository](https://github.com/OpenDevicePartnership/documentation/) or adding/updating [rustDoc](https://doc.rust-lang.org/rustdoc/) comments in the codebase, your contributions are valuable. They help ensure that ODP remains accessible and understandable to all users and developers. + diff --git a/tracks/contributor/src/governance.md b/tracks/contributor/src/governance.md new file mode 100644 index 0000000..85e253b --- /dev/null +++ b/tracks/contributor/src/governance.md @@ -0,0 +1,5 @@ +# Governance + +๐Ÿ›๏ธ Governance policies, including Charter, Code of Conduct, Trademark and AntiTrust Policies, and the [RFC process](https://github.com/OpenDevicePartnership/governance/blob/main/rfc/README.md) for new projects and standards are covered in the [Governance document repository](https://github.com/OpenDevicePartnership/governance/blob/main/README.md). + + diff --git a/tracks/contributor/src/track_overview.md b/tracks/contributor/src/track_overview.md new file mode 100644 index 0000000..d7b0757 --- /dev/null +++ b/tracks/contributor/src/track_overview.md @@ -0,0 +1,11 @@ +# ODP Contributor Track Overview +The Contributor track is designed for individuals who actively contribute to the Open Device Partnership (ODP) ecosystem. Contributors play a vital role in enhancing the ODP framework by developing new features, fixing bugs, and improving documentation. This track is ideal for those who want to deepen their understanding of ODP and make meaningful contributions to its growth and success. + +## Friendly and Simple +The Open Device Partnership (ODP) repositories are open for public contributions. + +- ๐Ÿ™Œ No permission is required to contribute code, documentation, or report issues. +- ๐Ÿ“ No contribution is too small -- even a simple typo fix is valuable. +- ๐Ÿค The ODP community is welcoming and eager to help new contributors get started. + + diff --git a/tracks/contributor/src/where_to_contribute.md b/tracks/contributor/src/where_to_contribute.md new file mode 100644 index 0000000..bdc9da7 --- /dev/null +++ b/tracks/contributor/src/where_to_contribute.md @@ -0,0 +1,4 @@ +# Where to Contribute +There are a large number of repositories under the ODP umbrella, and many of them are open for contributions. You will find a list of repositories that are particularly suitable for contributions in the [What's In ODP?](../../guide/what/what.md) section. This includes repositories for code, documentation, and other resources. + +--- diff --git a/tracks/embedded_controller/src/SUMMARY.md b/tracks/embedded_controller/src/SUMMARY.md new file mode 100644 index 0000000..42a8e28 --- /dev/null +++ b/tracks/embedded_controller/src/SUMMARY.md @@ -0,0 +1,12 @@ +[Overview](./track_overview.md) +- [General](./general.md) +- [Architecture](./architecture.md) +- [Components](./component_arch.md) +- [Runtime Behavior](./runtime_behavior.md) +- [Service Registration](./service_registry.md) +- [EC Services](./ec_services.md) +- [EC Services Architecture](./ec_services_arch.md) +- [EC Services Security](./ec_security.md) +- [Secure EC Services](./secure_ec_services.md) +- [Secure EC Example](./secure_ec_example.md) +- [Hands-on](./hands_on.md) \ No newline at end of file diff --git a/tracks/embedded_controller/src/ec_security.md b/tracks/embedded_controller/src/ec_security.md new file mode 100644 index 0000000..8fdb029 --- /dev/null +++ b/tracks/embedded_controller/src/ec_security.md @@ -0,0 +1,11 @@ +# Embedded Controller Security + +Naturally, as the scope of concerns that fall to the Embedded Controller has grown, security for these features becomes paramount. + +ODP provides support for hardware-enforced isolation of the Embedded Controller Service Interface enforced with __Hafnium__ for hypervisor control. + + + + + + diff --git a/tracks/embedded_controller/src/ec_services.md b/tracks/embedded_controller/src/ec_services.md new file mode 100644 index 0000000..05a62d5 --- /dev/null +++ b/tracks/embedded_controller/src/ec_services.md @@ -0,0 +1,16 @@ +# EC Services + +The Embedded Controller is responsible for an increasing number of tasks that are meant to be always available, independent of the main CPU. The scope of these EC services often goes beyond hardware device concerns alone. +These services often need to be exposed to the Operating System and Application layers so that higher-level monitoring and control designs can interact to inspect conditions or configure operating parameters. + +Conceptually, any number of services could be exposed to the Operating System in this way. The Windows Operating System specifies a particular set of EC Services that it requires. + +These Windows services are discussed in the [Embedded Controller Interface Specification](../../guide/specs/ec_interface/ec_interface.md) + +Windows-specific management features such as the [Microsoft Power Thermal Framework (MPTF)](../../guide/how/ec/thermal/mptf/mptf.md) implementation notes are relevant to this discussion also. + + + + + + diff --git a/tracks/embedded_controller/src/hands_on.md b/tracks/embedded_controller/src/hands_on.md new file mode 100644 index 0000000..c72e6f0 --- /dev/null +++ b/tracks/embedded_controller/src/hands_on.md @@ -0,0 +1,4 @@ +# Embedded Controller Exercises + +For a hands-on walkthrough for creating key Embedded Controller components, such as Battery, Charger, and Thermal devices, please see the [Component Examples](../../guide/how/ec/embedded_controller.md) + diff --git a/tracks/embedded_controller/src/runtime_behavior.md b/tracks/embedded_controller/src/runtime_behavior.md new file mode 100644 index 0000000..c95692b --- /dev/null +++ b/tracks/embedded_controller/src/runtime_behavior.md @@ -0,0 +1,29 @@ +## Runtime Behaviors of an Embedded Controller + +Component code is typically executed as an asynchronous task invoked by __Embassy Executor__. +A component reacts to events that are produced at higher levels of the Embedded Controller logic, through one or more policy manager tasks. + +Tasks are generally event-driven actions dispatched in response to messages. + +Messages are conveyed through a `comms` implementation. Events may be handled exclusively be a single component or reacted to by more than one component. + +Messages are queued and dispatched in order but are handled asynchronously. Signaling may be required to enforce an ordered flow. + +A component is wrapped within a defined `Device` wrapper that implements the traits that identify and control the implemented device type. The `Controller` for the device reacts to various events issued at the direction of policy manager logic, and in turn invokes the component hardware in appropriate response. + +```mermaid +sequenceDiagram + participant Policy as Policy Manager Task + participant Comms as Comms Dispatcher + participant Ctrl as Controller + participant Dev as Device Wrapper + participant Comp as Component (Implements Trait) + + Policy->>Comms: Emit Message (e.g. BatteryEvent) + Comms->>Ctrl: dispatch_message() + Ctrl->>Dev: handle() + Dev->>Comp: perform_action() + Comp-->>Dev: Result + Dev-->>Ctrl: Response + Ctrl-->>Comms: Ack or follow-up message +``` \ No newline at end of file diff --git a/tracks/embedded_controller/src/secure_ec_example.md b/tracks/embedded_controller/src/secure_ec_example.md new file mode 100644 index 0000000..92ef85c --- /dev/null +++ b/tracks/embedded_controller/src/secure_ec_example.md @@ -0,0 +1,4 @@ +# Secure EC Example + +Consult the [Secure EC Services Specification](../../guide/specs/ec_interface/secure-ec-services-overview.md) for more explanation and a sample implementation discussion. + diff --git a/tracks/embedded_controller/src/service_registry.md b/tracks/embedded_controller/src/service_registry.md new file mode 100644 index 0000000..9c5fabd --- /dev/null +++ b/tracks/embedded_controller/src/service_registry.md @@ -0,0 +1,107 @@ +# Embedded Controller Service Registration + +Embedded Controller components and services in ODP are statically composed at build time but must be registered with the **service infrastructure** to become discoverable and operational during execution. + +This registration model allows each **policy domain** (e.g. power, thermal, charging) to **own and manage the devices** associated with it. + +--- + +## Registration Pattern + +> **Pseudocode (concept only)** +> The registration flow is: construct โ†’ init services โ†’ register. +> +> ```rust,ignore +> let battery = BatteryDevice::new(DeviceId(1)); +> // ... +> // in an async task function +> embedded_services::init().await; +> embedded_services::power::policy::register_device(&battery).await.unwrap(); +> ``` +> +> This omits static allocation (`StaticCell`), executor wiring for async tasks, and controller setup, for clarity. + +### Realistic skeleton (matches the sample projects) + +Refer to the [Battery implementation example](../../guide/how/ec/battery/10-service_registry.html) or the [examples in the embedded-services repository](https://github.com/OpenDevicePartnership/embedded-services/blob/main/examples/std/src/bin/battery.rs#L474) for more concrete examples. + +```rust +// statically allocate single ownership +static BATTERY: StaticCell = StaticCell::new(); + +// Construct a device handle +let battery = BATTERY.init(MockBatteryDevice::new(DeviceId(1))); + +// In an async context, initialize services once, then register the device +embedded_services::init().await; +embedded_services::power::policy::register_device(&battery).await.unwrap(); + +// Controller setup is covered in the next section. +``` +_Semantics note_: In ODP, โ€œDeviceโ€ types are __handles__ to a single underlying component; the service runtime serializes access. Introducing the controller simply gives policy logic a dedicated handle to act on; it does not create a second owner of the hardware. + +### Bringing in the Controller + +``` rust +let controller = CONTROLLER.init( + MockBatteryController::<&'static mut MockBattery>::new(battery.inner_battery()) +); +``` +The controller is given a handle to the inner `MockBattery` (`inner_battery()`), not a second owner of the hardware. All access is serialized through the service runtime. + +### What Registration Enables +| Feature | Enabled by Registration | +|---------|------------------------| +| Message Routing | The `comms` system delivers events to services | +| Task Spawning | Services are polled and run by the executor | +| Feature Exposure | Subfeatures (e.g. _fuel_gauge_) declared via trait contracts | +| Test Visibility | Services and devices can be observed in tests | + +```mermaid +flowchart TD + A[Component
_Implements Trait_] --> B[Device Wrapper] + B --> C[Controller
_Implements Service Trait_] + C --> D[SERVICE_REGISTRY] + D --> E[Policy Manager
_via Comms_] + D -->|_Provides_| F[Async Task Execution] + +``` +>__Figure: Service Registration and Runtime Execution__ +> +> Devices are wrapped and managed by controllers. These are registered into the service registry, which exposes them to both the message dispatcher and the async runtime for polling and task orchestration. + +## Message Dispatch and Service Binding +Once a controller is registered, the service registry allows the comms system to route incoming events to the correct service based on: +- The __device ID__ +- The __message type__ +- The controller's implementation of the `handle()` function (_as defined by ServiceTraits_) + +When a message is emitted (e.g. `BatteryEvent::UpdateStatus`), the comms channel looks up the appropriate service and dispatches the message. + +Where `ServiceTraits` represent the service traits that define a Controller action, +implementation may look something like this (in this case, `ServiceTraits` defines a function +named `handle`, and it calls upon a local function defined in the device implementation): +```rust +impl ServiceTraits for BatteryController { + async fn handle(&mut self, msg: Message) -> Result<()> { + match msg { + Message::Battery(BatteryEvent::UpdateStatus) => { + self.device.update().await + } + _ => Ok(()), + } + } +} +``` +This provides a flexible pattern where __services are matched to message types__ through trait implementations and static dispatch. No dynamic routing or introspection is used โ€” behavior is known at compile time. + +### Static Composition, Dynamic Coordination +While all services and components are statically bound into the final binary: +- __Message routing and task polling occur dynamically__ +- __Controllers only receive messages for devices they were registered to manage__ +- __Multiple services can be registered independently and coexist without conflict__ + +This pattern supports: +- Easy testing with mocks or alternate HALs +- Additive subsystem design (battery, charger, thermal) +- Isolated debugging of service behavior \ No newline at end of file diff --git a/tracks/embedded_controller/src/track_overview.md b/tracks/embedded_controller/src/track_overview.md new file mode 100644 index 0000000..0a82945 --- /dev/null +++ b/tracks/embedded_controller/src/track_overview.md @@ -0,0 +1,2 @@ +# ODP Embedded Controller Track Overview +The Embedded Controller (EC) track is designed for individuals who are interested in developing and integrating embedded controller systems within the Open Device Partnership (ODP) framework. This track focuses on the design, implementation, and testing of embedded controllers, which are essential components in modern computing devices. Readers will learn how ODP supports creating robust EC solutions that enhance device functionality, improve power management, and ensure system reliability. \ No newline at end of file diff --git a/tracks/integrator/src/SUMMARY.md b/tracks/integrator/src/SUMMARY.md new file mode 100644 index 0000000..fef9ad5 --- /dev/null +++ b/tracks/integrator/src/SUMMARY.md @@ -0,0 +1,7 @@ +[Overview](./track_overview.md) +[Integration Facets](./facets.md) +[Patina Integration Overview](./patina.md) +[EC Integration Overview](./ec.md) +[Shared Patterns and Divergences](./shared_patterns.md) +[Preparing for Hardware Targets](./hardware_targets.md) + diff --git a/tracks/integrator/src/ec.md b/tracks/integrator/src/ec.md new file mode 100644 index 0000000..aafc2f6 --- /dev/null +++ b/tracks/integrator/src/ec.md @@ -0,0 +1,41 @@ +# Embedded Controller Integration + +EC integration, like Patina, is performed statically at build time. Subsystems, services, and hardware abstraction layers (HALs) are all compiled into the final binary. There is no dynamic component registration at runtime. Integration focuses on correctly assembling services, devices, and component instances into the expected structure and ensuring testability and modularity are preserved. + +## Embedded Controller Integration Goals + +- Build and wire up __runtime subsystems__ (e.g., Battery, Charger, Thermal) +- Inject real or simulated __hardware abstraction layers (HALs)__ +- Ensure __Service trait__ implementations are registered and running +- Test full EC behavior with `cargo test`, using mock HALs + +```mermaid +flowchart TD + A[Component - _Implements Trait_] --> B[Device - _Manages State + HAL_] + B --> C[Controller - _Implements Service Trait_] + C --> D[Service Registry - _Static at Compile Time_] + D --> E[Executor - _Runs Polling Loop_] + +``` + +### Key Integration Elements + +- `Device`: A wrapper around a trait-implementing component that manages shared state, message passing, and HAL access +- `Controller`: Implements the Service trait; manages component lifecycle and message dispatch +- `ServiceRegistry`: Central runtime registry for services, used by the executor to poll or handle messages +- `Executor`: The async runtime (usually `embassy::executor::Executor`) that drives services + + +## Integration Test Example +In the [Battery Subsystem Walkthrough](../../guide/how/ec/battery/0-overview.html), we construct a `BatteryController`, register it with the service registry, and run a full test loop using a virtualized `SmartBattery` device. This integration-style test validates runtime behavior without requiring actual hardware. + +> _pseudo-code_ +> +>```rust +>let battery = BatteryDevice::new(...); +>let controller = BatteryController::new(battery.clone()); +> +>SERVICE_REGISTRY.register(controller); +>EXECUTOR.run(); +>``` +> diff --git a/tracks/integrator/src/facets.md b/tracks/integrator/src/facets.md new file mode 100644 index 0000000..884e9c8 --- /dev/null +++ b/tracks/integrator/src/facets.md @@ -0,0 +1,12 @@ +# Integration Facets + +Overall integration may be broken down into separate areas of concern, often managed by different individuals or teams: + +| Facet | Role/Responsibility | +|-------|---------------------| +| Patina Platform | Build and sign DXE Core Images | +| EC Runtime Integration | Connect EC Services to HAL and mock/live backends | +| Update + Bootflow | ENsure Patina and EC stay in sync across restarts | +| Test Infrastructure | Run Integration Test suites, validate behaviors | +| Security/Compliance | Validate signature chain, FF-A flows, runtime policies | + diff --git a/tracks/integrator/src/hardware_targets.md b/tracks/integrator/src/hardware_targets.md new file mode 100644 index 0000000..473ac83 --- /dev/null +++ b/tracks/integrator/src/hardware_targets.md @@ -0,0 +1,45 @@ +# Preparing for Hardware Targets +While QEMU-based builds are ideal for development and testing, most real-world use cases require deployment to actual hardware platforms. Here we will point out some of the key steps, challenges, and considerations when preparing an ODP-based firmware system for hardware targets. + +## Changes when targeting real hardware +| Aspect | QEMU | Hardware | +|--------|------|----------| +| Peripherals | Virtualized and generic | Must match actual hardware | +| Flash Layout | Loosely defined | Must adhere to board specifications | +| Console / Logs | `stdout` or `debug.log` | UART/serial or memory-mapped output | +| Bootloader | `stuart_build` wrapper | coreboot, U-Boot, ROM Bootloader | +| EC-HAL | Fully mocked | Must be implemented for real I/O | + +## Firmware Packaging +- For __Patina__: + - The `.efi` binary must be embedded into the platform firmware image + - Secure boot considerations apply (keys, signatures) + - On some platforms (coreboot, U-Boot), a custom payload loader may be required + +- For __EC__: + - The final `.elf` or `.bin` must target your microcontroller's flash layout. + - Build system should include appropriate memory map + - External flash programming may be needed (e.g. SWD/JTAG, USB DFU) + +## HAL Transition Checklist +Replacing mocks with real hardware access requires caution and hardware validation. + + โ˜ Is your HAL for I2C, GPIO, ADC, etc. implemented for your board? + + โ˜ Are your EC services updated to use the correct HAL instance? + + โ˜ Have you validated pin mappings and timing constraints? + + โ˜ Is your async runtime configured correctly for interrupts, clocks, and wake/sleep behavior? + + โ˜ Are all non-implemented traits hidden behind feature flags or marked `unimplemented!()`? + +## Secure Services and Platform Constraints + +- __FF-A support__ (used by EC secure services) is _not available on x86 platforms_ โ€” fallback mechanisms are needed + +- Memory buffers for __FF-A__ (on ARM) must be in reserved and trusted memory regions + +- __BIOS/UEFI__ loaders on some x86 platforms may block or filter EC messages + +- Ensure your platformโ€™s firmware is not intercepting __ACPI__ or __EC I/O__, unless explicitly intended diff --git a/tracks/integrator/src/patina.md b/tracks/integrator/src/patina.md new file mode 100644 index 0000000..4c1590e --- /dev/null +++ b/tracks/integrator/src/patina.md @@ -0,0 +1,14 @@ +# Patina Integration + +Integration approaches for Patina are covered at [Patina DXE Core Platform Integration](https://sturdy-adventure-nv32gqw.pages.github.io/integrate/patina_dxe_core_requirements.html) + +This is part of the larger [Developer documentation for Patina](https://sturdy-adventure-nv32gqw.pages.github.io/) that should be fully reviewed before attempting integrations. + +Integration for a virtual environment for examples or testing may benefit from the QEMU support repositories + +- [QEMU DXE Core Binaries](https://github.com/openDevicePartnership/patina-dxe-core-qemu?tab=readme-ov-file#qemu-dxe-core-binaries) +- [Patina Platform Repository](https://github.com/openDevicePartnership/patina-qemu?tab=readme-ov-file#patina-platform-repository) + +Find other Patina relevant repositories in the +[What's in ODP?](../../guide/what/what.md) table. + diff --git a/tracks/integrator/src/shared_patterns.md b/tracks/integrator/src/shared_patterns.md new file mode 100644 index 0000000..e27deae --- /dev/null +++ b/tracks/integrator/src/shared_patterns.md @@ -0,0 +1,11 @@ + +## Comparison of Patina vs EC Integration Concerns +| Concern | Patina | EC | +|---------|--------|----| +| โœ… Component Registration | Static via `.with_component()` chaining | Static via `init()` + `register()` | +| โœ… Execution Model | EFI boot entrypoint | `embassy` async executor | +| โœ… Dependency Injection | Function-level parameters | Struct-wrapped traits | +| โœ… Component Lifetime Management | Core-managed | Controller-managed | +| โœ… Unit test support | Host-driven tests (mocked context) | Host-driven tests (mocked HALs) | +| โœ… Integration Testing | Possible via QEMU or structured test harness | Async harness + host logging + diff --git a/tracks/integrator/src/track_overview.md b/tracks/integrator/src/track_overview.md new file mode 100644 index 0000000..50e2ffb --- /dev/null +++ b/tracks/integrator/src/track_overview.md @@ -0,0 +1,15 @@ +# ODP Integrator Track Overview +The Integrator track is designed for individuals who are interested in integrating various components and systems within the Open Device Partnership (ODP) framework. This track focuses on the design, implementation, and testing of integration solutions that ensure seamless interoperability between different ODP components. Participants will learn how to create robust integration solutions that enhance system functionality, improve performance, and ensure reliability across ODP implementations. + +```mermaid +flowchart TD + A[Bootloader / Coreboot] + B[Patina DXE Core - _EFI_] + C[Runtime OS] + D[EC Subsystem - _Services_] + E[EC Hardware Platform] + + A --> B --> C + C --> D + D --> E +``` diff --git a/tracks/patina/src/SUMMARY.md b/tracks/patina/src/SUMMARY.md new file mode 100644 index 0000000..a6d82a7 --- /dev/null +++ b/tracks/patina/src/SUMMARY.md @@ -0,0 +1,3 @@ +[Overview](./track_overview.md) +[Patina Background](./patina_concepts.md) +[More Patina Links](./more_patina.md) \ No newline at end of file diff --git a/guide_book/src/intro/concepts/images/uefi_evolution.png b/tracks/patina/src/images/uefi_evolution.png similarity index 100% rename from guide_book/src/intro/concepts/images/uefi_evolution.png rename to tracks/patina/src/images/uefi_evolution.png diff --git a/tracks/patina/src/more_patina.md b/tracks/patina/src/more_patina.md new file mode 100644 index 0000000..2df4fd0 --- /dev/null +++ b/tracks/patina/src/more_patina.md @@ -0,0 +1,9 @@ +# Additional Patina Resources + +You can find more resources related to Patina in the following locations: + +[Developing UEFI with Rust](https://sturdy-adventure-nv32gqw.pages.github.io/) + +[Patina Repository](https://github.com/OpenDevicePartnership/patina?tab=readme-ov-file#patina) + +[Other repositories](../../guide/what/what.md) diff --git a/tracks/patina/src/patina_concepts.md b/tracks/patina/src/patina_concepts.md new file mode 100644 index 0000000..1c0da65 --- /dev/null +++ b/tracks/patina/src/patina_concepts.md @@ -0,0 +1,127 @@ +# Patina Background + +## Overview + +Firmware and UEFI firmware in particular has long been written in C. Firmware operates in a unique environment compared +to other system software. It is written to bootstrap a system often at the host CPU reset vector and as part of a chain +of trust established by a hardware rooted immutable root of trust. Modern PC and server firmware is extraordinarily +complex with little room for error. + +We call the effort to evolve and modernize UEFI firmware in the Open Device Partnership (ODP) project "Patina". The +remainder of this document will discuss the motivation for this effort, a high-level overview of the current state of +Patina, and the current state of Rust in UEFI firmware. + +### Firmware Evolution + +From a functional perspective, firmware must initialize the operating environment of a device. To do so involves +integrating vendor code for dedicated microcontrollers, security engines, individual peripherals, System-on-Chip (SOC) +initialization, and so on. Individual firmware blobs may be located on a number of non-volatile media with very limited +capacity. The firmware must perform its functional tasks successfully or risk difficult to diagnose errors in higher +levels of the software stack that may impede overall device usability and debuggability. + +These properties have led to slow but incremental expansion of host firmware advancements over time. + +![Host FW Evolution](./images/uefi_evolution.png) + +### Firmware Security + +From a security perspective, firmware is an important component in the overall system Trusted Computing Base (TCB). +Fundamental security features taken for granted in later system software such as kernels and hypervisors are often +based on secure establishment in a lower layer of firmware. At the root is a concept of "trust". + +While operating systems are attractive targets due to their ubiquity across devices and scale, attackers are +beginning to shift more focus to firmware as an attack surface in response to increasingly effective security measures +being applied in modern operating systems. While significant research has been devoted across the entire boot process, +UEFI firmware on the host CPU presents a unique opportunity to gain more visibility into early code execution details +and intercept the boot process before essential activities take place such as application of important security +register locks, cache/memory/DMA protections, isolated memory regions, etc. The result is code executed in this +timeframe must carry forward proper verification and measurement of future code while also ensuring it does not +introduce a vulnerability in its own execution. + +### Performant and Reliable + +From a performance perspective, firmware code is often expected to execute exceedingly fast. The ultimate goal is for +an end user to not even be aware such code is present. In a consumer device scenario, a user expects to press a power +button and immediately receive confirmation their system is working properly. At a minimum, a logo is often shown to +assure the user something happened and they will be able to interact with the system soon. In a server scenario, +fleet uptime is paramount. Poorly written firmware can lead to long boot times that impact virtual machine +responsiveness and workload scaling or, even worse, Denial of Service if the system fails to boot entirely. In an +embedded scenario, government regulations may require firmware to execute fast enough to show a backup camera within a +fixed amount of time. + +All of this is to illustrate that firmware must perform important work in a diverse set of hardware states with code +that is as small as possible and do so quickly and securely. In order to transition implementation spanning millions of +lines of code written in a language developed over 50 years ago requires a unique and compelling alternative. + +## Rust and Firmware + +As previously stated, modern systems necessitate a powerful language that can support low-level programming with +maximum performance, reliability, and safety. While C has provided the flexibility needed to implement relatively +efficient firmware code, it has failed to prevent recurring problems around memory safety. + +### Stringent Safety + +Common pitfalls in C such as null pointer dereferences, buffer and stack overflows, and pointer mismanagement continue +to be at the root of high impact firmware vulnerabilities. These issues are especially impactful if they compromise +the system TCB. Rust is compelling for UEFI firmware development because it is designed around strong memory safety +without the usual overhead of a garbage collector. In addition, it enforces stringent type safety and concurrency rules +that prevent the types of issues that often lead to subtle bugs in low-level software development. + +Languages aside, UEFI firmware has greatly fallen behind other system software in its adoption of basic memory +vulnerability mitigation techniques. For example, data execution protection, heap and stack guards, stack cookies, +and null pointer dereference detection is not present in the vast majority of UEFI firmware today. More advanced +(but long time) techniques such as Address Space Layout Randomization (ASLR), forward-edge control flow integrity +technologies such as x86 Control Flow Enforcement (CET) Indirect Branch Tracking (IBT) or Arm Branch Target +Identification (BTI) instructions, structured exception handling, and similar technologies are completely absent in +most UEFI firmware today. This of course exacerbates errors commonly made as a result of poor language safety. + +Given firmware code also runs in contexts with high privilege level such as System Management Mode (SMM) in x86, +implementation errors can be elevated by attackers to gain further control over the system and subvert other +protections. + +### Developer Productivity + +The Rust ecosystem brings more than just safety. As a modern language firmware development can now participate +in concepts and communities typically closed to firmware developers. For example: + +- Higher level multi-paradigm programming concepts such as those borrowed from functional programming in addition to + productive polymorphism features such as generics and traits. + +- Safety guarantees that prevent errors and reduce the need for a myriad of static analysis tools with flexibility to + still work around restrictions when needed in an organized and well understood way (unsafe code). + +### Modern Tooling + +Rust includes a modern toolchain that is well integrated with the language and ecosystem. This standardizes tooling +fragmented across vendors today and lends more time to firmware development. Examples of tools and community support: + +- An official package management system with useful tools such as first-class formatters and linters that reduce + project-specific implementations and focus discussion on functional code changes. + +- High quality reusable bundles of code in the form of crates that increase development velocity and engagement with + other domain experts. + +- Useful compilation messages and excellent documentation that can assist during code development. + +- A modern testing framework that allows for unit, integration, and on-platform tests to be written in a consistent + way. Code coverage tools that are readily available and integrate seamlessly with modern IDEs. + +Rust's interoperability with C code is also useful. This enables a phased adoption pathway where codebases can start +incorporating Rust while still relying upon its extensive pre-existing code. At the same time, Rust has been conscious +of low-level needs and can precisely structure data for C compatibility. + +## Patina in ODP + +The Patina team in ODP plans to participate within the open Rust development community by: + +1. Engaging with the broader Rust community to learn best practices and share low-level system programming knowledge. +2. Leveraging and contributing back to popular crates and publishing new crates that may be useful to other projects. + - A general design strategy is to solve common problems in a generic crate that can be shared and then integrate it + back into firmware. +3. Collaborating with other firmware vendors and the UEFI Forum to share knowledge and best practices and + incorporate elements of memory safety languages like Rust into industry standard specifications where appropriate. + Some specifications have interfaces defined around concepts and practices common in unsafe languages that could + be improved for safety and reliability. + +Looking forward, we're continuing to expand the coverage of our firmware code written in Rust. We are excited to +continue learning more about Rust in collaboration with the community and our partners. diff --git a/tracks/patina/src/track_overview.md b/tracks/patina/src/track_overview.md new file mode 100644 index 0000000..e8ba6b5 --- /dev/null +++ b/tracks/patina/src/track_overview.md @@ -0,0 +1,2 @@ +# ODP Patina Track Overview +The Patina track is designed for individuals who are interested in developing and maintaining the Patina framework within the Open Device Partnership (ODP). This track focuses on the design, implementation, and testing of Patina solutions, which are essential for creating efficient and scalable applications. Readers will learn how to leverage the Patina framework to build robust applications that enhance user experience, improve performance, and ensure system reliability. \ No newline at end of file diff --git a/tracks/security/src/SUMMARY.md b/tracks/security/src/SUMMARY.md new file mode 100644 index 0000000..67a81d1 --- /dev/null +++ b/tracks/security/src/SUMMARY.md @@ -0,0 +1,6 @@ +- [Overview](./track_overview.md) +- [Secure Foundations](./secure_trust.md) +- [Secure Architecture](./security_architecture.md) +- [Secure Boot](./secure_boot.md) +- [Secure Firmware Updates](./secure_firmware_updates.md) +- [Secure EC Services](./secure_ec_services.md) diff --git a/tracks/security/src/track_overview.md b/tracks/security/src/track_overview.md new file mode 100644 index 0000000..6ea2f82 --- /dev/null +++ b/tracks/security/src/track_overview.md @@ -0,0 +1,2 @@ +# ODP Security Track Overview +The Security track is designed for individuals who are interested in enhancing the security posture of the Open Device Partnership (ODP) framework. This track focuses on the design, implementation, and testing of security solutions that protect ODP components and applications from threats and vulnerabilities. Readers will learn how ODP creates robust security measures that ensure data integrity, confidentiality, and availability across ODP implementations. The track covers various aspects of security, including threat modeling, risk assessment, secure coding practices, and incident response strategies. diff --git a/tracks/value_proposition/src/SUMMARY.md b/tracks/value_proposition/src/SUMMARY.md new file mode 100644 index 0000000..28d2629 --- /dev/null +++ b/tracks/value_proposition/src/SUMMARY.md @@ -0,0 +1,10 @@ +- [Overview](./track_overview.md) +- [Why ODP?](./why/why.md) + - [Secure Trust](./why/secure_trust.md) + - [Modularity](./why/modular.md) + - [Cross-Domain Coherence](./why/cross_domain_coherence.md) + - [Developer Experience](./why/developer_experience.md) + - [Sustainability and Cost](./why/sustainability.md) + - [Industry Standards](./why/standards.md) +- [Design Tradeoffs](./design_tradeoffs.md) +- [Open-source Strategy](./open_source_strategy.md) \ No newline at end of file diff --git a/tracks/value_proposition/src/design_tradeoffs.md b/tracks/value_proposition/src/design_tradeoffs.md new file mode 100644 index 0000000..ca58e5b --- /dev/null +++ b/tracks/value_proposition/src/design_tradeoffs.md @@ -0,0 +1,38 @@ +# Design Tradeoffs +Every system architecture makes tradeoffs. The Open Device Partnership intentionally prioritizes safety, modularity, and clarity over raw performance or legacy compatibility. These decisions reflect ODPโ€™s goal: to build secure, reusable firmware systems that are maintainable and testable over time. + +### ๐Ÿฆ€ Rust vs C +- __Benefit:__ Memory safety, currency safety, modern tooling. +- __Tradeoff:__ Steeper learning curve for traditional firmware developers; ecosystem immaturity in some low-level areas. + +> _Rust enables ODP to eliminate entire classes of bugs that plague C-based firmware โ€” but requires new patterns, and tooling is still evolving._ + +### ๐Ÿ”ŒModular Architecture / Dependency Injection Model +- __Benefit:__ Highly testable, configurable systems; mockable components. +- __Tradeoff:__ Increased complexity in initial setup; requires developers to think in terms of interfaces and traits rather than monolithic code. + +> _The Patina and EC models both rely on traits and injection to decouple implementation from interface, enabling better testing and reuse โ€” but at the cost of simplicity._ + +### ๐Ÿงฑ Component-Based Architecture +- __Benefit:__ Clear separation of concerns; reusable components across systems. +- __Tradeoff:__ Requires more upfront structure and discipline. + +### ๐Ÿงช Testability and Mocks as First-Class Concerns +- __Benefit:__ Enables structured unit and integration testing of firmware logic. +- __Tradeoff:__ Requires more boilerplate and test harness infrastructure. + +> _Testing isn't something bolted on after the fact โ€” it's a design feature, which adds friction up front but pays off in long-term reliability._ + +### ๐Ÿ”’ Security by Design +- __Benefit:__ FF-A boundaries, UUID filtering, and strict service mediation provide robust enforcement. +- __Tradeoff:__ Complex runtime validation logic and configuration. + +> _Security enforcement is baked into the system model, which adds complexity โ€” but reflects a modern threat landscape._ + +### ๐Ÿ”„ Portability over Specialization +- __Benefit:__ ODP components can be reused across different hardware and system designs. +- __Tradeoff:__ Avoidance of vendor-specific optimizations or interfaces. + + +ODP is not designed to be the fastest path to a boot screen โ€” itโ€™s designed to be the most trustworthy, auditable, and maintainable firmware foundation for modern systems. The tradeoffs reflect a long-term investment in security and correctness over legacy speed or familiarity. + diff --git a/tracks/value_proposition/src/open_source_strategy.md b/tracks/value_proposition/src/open_source_strategy.md new file mode 100644 index 0000000..07881d0 --- /dev/null +++ b/tracks/value_proposition/src/open_source_strategy.md @@ -0,0 +1,27 @@ +# Open-source Strategy +The Open Device Partnership (ODP) is open source by design, not by afterthought. Its goal is to create a shared foundation for secure, modular firmware that anyone can audit, extend, or build upon โ€” whether you're a silicon vendor, OEM, platform integrator, or open hardware enthusiast. + +## Open Source Strategic Advantages +- **Transparency**: ODP's open source nature allows anyone to inspect the code, ensuring that security and design decisions are visible and verifiable. This transparency builds trust among users and developers. +- **Community-Driven**: ODP thrives on community contributions. Developers can propose changes, report issues, and collaborate on features. This collective effort accelerates innovation and improves the quality of the codebase. +- **Interoperability**: By adhering to open standards and interfaces, ODP components can be reused across different hardware and software ecosystems. This reduces vendor lock-in and promotes a more diverse ecosystem. +- **Sustainability**: Open source fosters long-term sustainability. As the community grows, the project benefits from a wider pool of contributors, ensuring that it can adapt to new challenges and technologies over time. +- **Education and Onboarding**: Open source projects provide an excellent learning platform for new developers. ODP's documentation, examples, and community support make it easier for newcomers to get involved and contribute. +- **Innovation**: Open source encourages experimentation and innovation. Developers can build on existing ODP components, creating new features or adapting them for specific use cases without starting from scratch. +- **Vendor Neutrality**: ODP is designed to be vendor-neutral, allowing any organization to implement it without being tied to a specific vendor's ecosystem. This promotes healthy competition and prevents monopolistic practices. + +### What's Open? (And What Isn't) +ODP is committed to open source principles, but there are some exceptions for some of the referenced specific integrations, accessories and tools: +| Area | Status | +|------|--------| +| Patina SDK | โœ… Fully Open (Rust DXE Core + sample components) | +| EC Runtime | โœ… Fully Open (async executor + services + mocks) | +| Tooling (FW patcher, setup scripts) | โœ… Open | +| Platform-Specific Drivers | โš ๏ธ Some may be proprietary or stubbed | +| Reference Boards | โš ๏ธ May include closed blobs for silicon init | +| Contributor Roadmap | โœ… Open (community-driven)
โœ… Transparent (tracked in GitHub issues/PRs) | + +## A rising tide raises all boats +ODP's open source strategy is not just about making code available; it's about fostering a culture of collaboration and shared learning. By engaging with the broader open source community, ODP aims to raise the standards of firmware development across the industry. This means not only sharing code but also best practices, design patterns, and lessons learned. This fosters a higher standard of quality and security in firmware development, benefiting everyone involved. + + diff --git a/tracks/value_proposition/src/track_overview.md b/tracks/value_proposition/src/track_overview.md new file mode 100644 index 0000000..a6e025a --- /dev/null +++ b/tracks/value_proposition/src/track_overview.md @@ -0,0 +1,2 @@ +# ODP Value Proposition Overview +The Value Proposition track is designed to help you understand the core benefits of the Open Device Partnership (ODP). This track covers the key advantages of using ODP, including security, modularity, cross-domain coherence, and more. Whether you're a decision-maker, a developer, or just curious about ODP, this track will provide you with a solid foundation in why ODP is a compelling choice for modern firmware development. \ No newline at end of file diff --git a/tracks/value_proposition/src/why/cross_domain_coherence.md b/tracks/value_proposition/src/why/cross_domain_coherence.md new file mode 100644 index 0000000..16ff106 --- /dev/null +++ b/tracks/value_proposition/src/why/cross_domain_coherence.md @@ -0,0 +1,29 @@ +# Cross-Domain Coherence + +ODP is not just a patch atop of old layers. It is explicitly aligning system layers to reduce duplication, ambiguity, and failure points. + +ODP is not just a firmware stack, but a vision that unites the embedded controller, main firmware, and even secure services under a coherent design and tooling approach. + + +## Common patterns with clearly defined lanes + +> _โ€œSecure systems require secure interfaces โ€” everywhere.โ€_ + +Shared services and conventions allow clear division of responsibility between firmware, EC, and OSโ€”while promoting reuse and coordination. + +```mermaid +graph LR + Host[Host Domain] --> HostServiceA + Host --> HostServiceB + + HostServiceA --> HostDriverA + HostServiceB --> HostDriverB + + EC[Embedded Controller Domain] --> ECServiceA + EC --> ECServiceB + + subgraph Shared Interface + HostServiceA <---> ECServiceA + HostServiceB <---> ECServiceB + end + ``` \ No newline at end of file diff --git a/tracks/value_proposition/src/why/developer_experience.md b/tracks/value_proposition/src/why/developer_experience.md new file mode 100644 index 0000000..388f509 --- /dev/null +++ b/tracks/value_proposition/src/why/developer_experience.md @@ -0,0 +1,40 @@ +# Improved Developer Experience + +ODP reduces developer friction and increases confidence, thus shortening the time to value for the development effort. + +> _"Firmware development shouldnโ€™t feel like archaeology."_ + +Developers can build and test components in isolation (e.g., battery, GPIO, boot timer), aided by QEMU emulation, mocks, and test harnesses. + +![Then and Now](./media/dev-then-now.png) + +ODP can improve developer engagement and productivity by: +- ๐Ÿš€ Reducing developer friction +- ๐Ÿ› ๏ธ Supporting tooling thatโ€™s approachable and efficient +- ๐Ÿงช Enabling fast iteration and confident change +- ๐Ÿ’ฌ Reinforcing that firmware development is not arcane magic, just solid coding. + +The Rust ecosystem brings built-in unit testing, logging, dependency control (Cargo), and static analysis. + +```mermaid +timeline + title Developer Workflow Evolution + 2000 : Edit ASM/C, guess BIOS behavior + 2010 : Use UEFI drivers, painful debug cycle + 2023 : Rust-based firmware prototypes emerge + 2024 : ODP introduces modular build + Stuart tools + 2025 : Fully testable DXE + EC code in Rust with shared tooling +``` +```mermaid +flowchart LR + Idea["๐Ÿ’ก Idea"] --> Dev["๐Ÿงฉ Create Service Component"] + Dev --> Test["๐Ÿงช Unit & Desktop Test"] + Test --> Build["๐Ÿ”ง Cross-target Build
(host & EC)"] +``` +```mermaid +flowchart LR + Build --> Sim["๐Ÿ–ฅ๏ธ Simulate with Mock Devices"] + Sim --> Flash["๐Ÿš€ Build & Flash"] + Flash --> Log["๐Ÿ“„ Review Logs / Debug"] + Log --> Iterate["๐Ÿ” Iterate with Confidence"] +``` \ No newline at end of file diff --git a/tracks/value_proposition/src/why/media/dev-then-now.png b/tracks/value_proposition/src/why/media/dev-then-now.png new file mode 100644 index 0000000..1fbba65 Binary files /dev/null and b/tracks/value_proposition/src/why/media/dev-then-now.png differ diff --git a/tracks/value_proposition/src/why/modular.md b/tracks/value_proposition/src/why/modular.md new file mode 100644 index 0000000..55df7d9 --- /dev/null +++ b/tracks/value_proposition/src/why/modular.md @@ -0,0 +1,28 @@ +# Modular and Composable Firmware Architecture + +ODP offers Modularity and Agility not normally found in the firmware domain. + +The buzz and the headlines generated by advances in the computer world typically belong to those +who have created magic at the application layer. As such, this portion of the development community has seen exponential advances in the tooling and languages at their disposal. This has provided a high level of modularity and with it, agility, that has become synonymous with the market responsiveness we see in the evolution of our favorite applications. + +Firmware development, on the other hand, has generally been mired in the processes of the past, and has +not enjoyed this same level of modularity and agility. + +> _โ€œSystems scale better when their parts can evolve independently.โ€_ + +## Composable and portable component modules + +ODP changes that paradigm and raises the tide. It is inspired by modern software engineering practices: composability, dependency injection, testability. + +Components (e.g., battery service, serial logging, boot policies) are decoupled and swappable, enabling faster iteration and better maintainability. + +```mermaid +graph LR + PowerPolicy --> BatteryService + PowerPolicy --> ChargerService + PowerPolicy --> ThermalService + BatteryService --> MockBattery + ChargerService --> SMbusDriver + ``` +Because Rust enforces its memory and safety management guarantees at compile time, tooling such as that found in ODP Patina for example will build a DXE Core monolithically, without the need for an RTOS, and supports a composed modularity paradigm by design, streamlining certification and troubleshooting. + diff --git a/tracks/value_proposition/src/why/secure_trust.md b/tracks/value_proposition/src/why/secure_trust.md new file mode 100644 index 0000000..b5919f4 --- /dev/null +++ b/tracks/value_proposition/src/why/secure_trust.md @@ -0,0 +1,27 @@ +# Security + +Reduce firmware attack surface significantly, and meet modern security expectations using proven tools and patterns. + +## Security and Trustworthiness from the Ground Up + +> _โ€œIf the foundation is weak, nothing built on top can be trusted.โ€_ + +Rust is a modern, memory-safe language that mitigates entire classes of vulnerabilities endemic to C memory management, buffer overflows, use-after-free, and so forth by detecting and addressing these issues at compile time -- so there are few, if any, unpleasant surprises at runtime. + +ODP is foundationally centered around Rust and not only embraces these philosophies, it defines patterns that further enhance the memory-safe paradigm, by preventing unauthorized access between ownership domains and guarding against possible malicious intrusions while implementing proven industry-standard patterns. + +```mermaid +flowchart LR + Start[Power On] --> ROM + ROM --> FirmwareCheck[Validate Firmware Signature] + FirmwareCheck --> DXECore[Load DXE Core] + DXECore --> OSLoader[Invoke Bootloader] + OSLoader --> OSVerify[Validate OS Signature] + OSVerify --> OSBoot[Launch OS] + OSBoot --> Ready[Platform Ready] +``` + +Adoption of standards and patterns of DICE and EL2 Hypervisor supported architectures -- from a Rust-driven baseline - enables a hardware-rooted chain of trust across boot phases, aligning with NIST and platform security goals and requirements. + +ODP makes component modularity and portability with a transparent provenance a practical and safe proposition by making it feasiable to audit and verify firmware behavior in specifically constrained ways. + diff --git a/tracks/value_proposition/src/why/standards.md b/tracks/value_proposition/src/why/standards.md new file mode 100644 index 0000000..815b42e --- /dev/null +++ b/tracks/value_proposition/src/why/standards.md @@ -0,0 +1,27 @@ +# Alignment with Industry Trends and Standards + +ODP is forward-facing from its original concept, and embodied in its design. Adoption of ODP positions you at the forefront of secure, future-facing firmware innovation. + +> _โ€œODP doesnโ€™t rewrite the rules โ€” it implements them with confidence.โ€_ + +### Perfectly Timed +ODP taps into the growing ecosystem momentum around Rust and embedded standards. Rust adoption at Microsoft, Google, and the Linux kernel reflects a broader industry shift. + +### Open Source and Collaborative +ODP Encourages upstream contributions and compliance with modern firmware interfaces (UEFI, ACPI, DICE). + +An open collaboration model invites cross-vendor reuse and innovation while building upon existing standards known to the industry. + +```mermaid +graph TD + A1[UEFI Spec] --> B1[DXE Core] + A2[ACPI] --> B2[Runtime Services] + A3[DICE] --> B3[Secure Boot] + A4[SPDM] --> B3 + A5[DMTF] --> B4[Mgmt Layer] + + B1 --> C[ODP Framework] + B2 --> C + B3 --> C + B4 --> C +``` \ No newline at end of file diff --git a/tracks/value_proposition/src/why/sustainability.md b/tracks/value_proposition/src/why/sustainability.md new file mode 100644 index 0000000..90b16b9 --- /dev/null +++ b/tracks/value_proposition/src/why/sustainability.md @@ -0,0 +1,41 @@ +# Sustainability and Long-Term Cost Reduction + +ODP can help cut tech debt at its root by investing in sustainable design by enabling leaner teams and cleaner codebases. + +> _โ€œTechnical debt is financial debt โ€” just hidden in your firmware.โ€_ + +## Build right and reuse +Replacing legacy code with safer, testable, and reusable modules means lower maintenance costs over time. + +```mermaid +flowchart LR + Legacy["Legacy Stack"] --> Duplication["๐Ÿ’ฅ Code Duplication"] + Legacy --> Debugging["๐Ÿ› Opaque Bugs"] + Legacy --> Porting["๐Ÿ”ง Costly Platform Bring-up"] + Legacy --> Compliance["โš–๏ธ Expensive Security Reviews"] + Legacy --> Waste["๐Ÿ—‘๏ธ Rewrite Instead of Reuse"] +``` + +### HAL separation +The ability to reuse and recompose across product lines (via ODP libraries) reduces the need to "reinvent the wheel" for each board/platform, as Hardware Abstraction Layers can be cleanly isolated from the business logic of a component design, and easily expanded upon for new features. + +#### More than HAL +This component philosophy extends much further than replaceable HAL layers -- it permeates throughout the component and service structure patterns ODP exposes. This allows agile modularity, greater reuseability, and shorter development cycles. + + +```mermaid +sequenceDiagram + participant Dev as Developer + participant Repo as Shared Component Repo + participant DeviceA as Platform A + participant DeviceB as Platform B + + Dev->>Repo: Build & Test Component + DeviceA->>Repo: Pull Component A + DeviceB->>Repo: Pull Component A + Dev->>DeviceA: Customize Config + Dev->>DeviceB: Customize Config + Note right of Dev: One codebase, many targets +``` + + diff --git a/tracks/value_proposition/src/why/why.md b/tracks/value_proposition/src/why/why.md new file mode 100644 index 0000000..4463d0e --- /dev/null +++ b/tracks/value_proposition/src/why/why.md @@ -0,0 +1,40 @@ +# Why ODP? + +Modern computing devices are ubiquitous in our lives. They are integral to multiple aspects of our lives, from our workplace, to our finances, our creative endeavors, and our personal lifestyles. + +Computer technology seemingly lept from its cradle a half century ago and never slowed its pace. It is easy to take much of it for granted. + +We marvel as the new applications show us increasingly amazing opportunities. We also recognize and guard against the threats these applications pose to ourselves and society. + +And in this heady environment, it is sometimes easy to forget that the "hidden parts" of these computers we use -- the lower-level hardware and firmware -- is often built upon languages and processes that, although having evolved to meet the demands of the time, are reaching the end of their practical sustainability for keeping up with the accelerating pace of the world around us. + +What was originally just a "boot layer" and a few K of code for key hardware interfacing is now shouldering the responsibility of securing personal information and behavior patterns that a malicious intruder could use for nefarious purposes. + +High-value proprietary algorithms and Artificial Intelligence models are now built into the firmware and must be locked down. An increasing number of "always ready" peripherals, such as the battery and charger, biometric identification mechanisms, network connections, and other concerns are being increasingly handled by independent MCUs that must coordinate with one another and with the host system in a responsive, increasingly complex, yet highly secure manner. + +Trying to manage all of this with what has been the status-quo for these concerns in past decades, without memory-safe languages and with a loosely-federated collection of standards and patterns agreed upon by an ad-hoc consortium of vendors is increasingly dangerous and costly. + +--------------------- + + +| __Legacy Approach__ | __ODP Approach__ | +| --------------------| -----------------| +| ๐Ÿœ Many vendor-specific changesets โŒ | ๐Ÿงฉ Cross-platform modularity ๐Ÿ”’| +| โ„๏ธ Weak component isolation ๐Ÿฉธ | ๐Ÿ” Secure runtime services ๐Ÿค– | +| ๐Ÿ”ฉ Proprietary tool building โš”๏ธ | ๐Ÿ› ๏ธ Rust-based build tools, Stuart ๐Ÿง‘โ€๐Ÿ”ง| + + + +> _The firmware we once almost ignored is now the front line of platform security_ + +--------------------- + +The Open Device Partnership offers an alternative and a way forward to a more sustainable future that, while still built upon the proven paradigms of the past, boldly rejects the patterns that are known to be costly and ineffective in favor of future-ready, portable, sustainable, and expandable alternatives. + +Key to this is the adoption of the programming language Rust as the successor to C. This immediately brings greater confidence that the code will not be susceptible to programming-error related vulnerabilities that may lead to either costly performance behaviors or be maliciously exploited by opportunistic bad actors. Code may be marked `unsafe` to allow certain difficult-to-static-analyze behaviors that can be asserted to be risk-free, so potentially dangerous area must be carefully justified. Furthermore, the patterns adopted by ODP provides the confidence that code from outside of one's immediate provenance of control may be audited and trusted and ready to join into a firmware construction built upon industry standards. + +In the pages ahead, we'll look a little more closely at the advantages of ODP one at a time. + + + +