| # Architecture | |
| openprot is a `no_std` Rust firmware project for Platform Root-of-Trust | |
| devices, organized as a Bazel module so that HAL traits, OS-abstraction | |
| traits, OS-agnostic services, and target-specific glue can stay decoupled. | |
| ## Repository layout | |
| ``` | |
| openprot/ | |
| ├── MODULE.bazel # Bazel module + crate_universe extensions | |
| ├── workflows.json # Pigweed workflow groups (./pw …) | |
| ├── BUILD.bazel # Top-level Bazel package | |
| ├── openprot/ # Main application crate (lib.rs + main.rs) | |
| ├── drivers/ | |
| │ └── usart/ # Target-agnostic USART API, client, and server | |
| ├── hal/ | |
| │ ├── async/ # Async HAL trait crates | |
| │ ├── blocking/ # Blocking HAL trait crates | |
| │ └── nb/ # Non-blocking (nb) HAL trait crates | |
| ├── platform/ | |
| │ ├── traits/ # OS-abstraction traits | |
| │ └── impls/ # Concrete impls per host environment | |
| ├── services/ | |
| │ ├── i2c/ # I2C API, IPC transports, and server runtime | |
| │ ├── mctp/ # MCTP API, transports, client, and server | |
| │ ├── orchestrator/ # Boot orchestration, capabilities, and HAL adapters | |
| │ ├── spdm/ # SPDM requester, responder, and support crates | |
| │ ├── storage/ # Storage service | |
| │ └── telemetry/ # Telemetry service | |
| ├── target/ | |
| │ ├── ast10x0/ # ASPEED AST10x0 target, backends, and tests | |
| │ ├── earlgrey/ # OpenTitan Earl Grey target | |
| │ ├── mock/ # Host/QEMU board data used by tests | |
| │ └── veer/ # Caliptra VeeR-EL2 target | |
| ├── third_party/ | |
| │ ├── pigweed/ # Pigweed integration | |
| │ └── caliptra/ # caliptra-sw / caliptra-mcu-sw integration | |
| ├── presubmit/ # Python presubmit scripts | |
| └── docs/ # mdbook sources (this site) | |
| ``` | |
| The intent of the split is that hardware-facing contracts live under `hal/` | |
| or a driver's public API, host-OS contracts live under `platform/traits/`, and | |
| reusable protocol and service logic lives under `services/`. Concrete host | |
| implementations belong in `platform/impls/`; silicon-specific backends, | |
| peripherals, linker scripts, system images, and test runners belong under | |
| `target/`. For example, `drivers/usart/` defines a target-agnostic interface | |
| while `target/ast10x0/backend/usart/` implements it for AST10x0. | |
| ## Interfaces, implementations, and protocols | |
| The repository separates contracts from implementations so that protocol | |
| logic can be tested on a host without importing a device PAC or kernel: | |
| - `hal/{async,blocking,nb}/` contains hardware abstraction traits grouped by | |
| execution model. The blocking HAL includes interfaces for flash, GPIO, I2C, | |
| cryptography, key vaults, and system control. | |
| - `platform/traits/` contains operating-system abstraction traits; | |
| `platform/impls/` contains concrete implementations for supported host | |
| environments. | |
| - `drivers/usart/{api,client,server}/` separates the USART wire contract, | |
| client facade, and server dispatcher from its target backend. | |
| - `services/i2c/` and `services/mctp/` follow the same pattern: public API, | |
| platform-independent client/server logic, IPC adapters, and target-specific | |
| backends where required. | |
| - `services/spdm/` builds requester and responder behavior on top of the MCTP | |
| transport and shared cryptographic support crates. | |
| The `README.md` files in each driver or service directory document their | |
| public seams, invariants, and host-test targets. | |
| ## Build system | |
| The build is driven by Bazel via Pigweed's workflow launcher; there is no | |
| Cargo workspace. The relevant pieces: | |
| - `MODULE.bazel` declares Bazel module dependencies (`bazel_skylib`, | |
| `pigweed`, `platforms`, `rules_rust`, `rules_rust_mdbook`, `rules_python`, | |
| plus `caliptra_deps` and `ureg` via overrides). | |
| - `git_override` pins Pigweed to a specific upstream commit | |
| (`MODULE.bazel:23-27`), keeping the kernel/build/log/status/toolchain | |
| pieces reproducible. | |
| - `pw_rust.toolchain` registers Pigweed's managed Rust toolchains | |
| (`MODULE.bazel:35-37`); host C/C++ toolchains and the `rv32imc` RISC-V | |
| C/C++ toolchain are registered via `register_toolchains` | |
| (`MODULE.bazel:39-44`). | |
| - Three `crate_universe` workspaces govern Rust crate dependencies: | |
| - `@rust_crates` — cross-platform crates declared in | |
| `third_party/crates_io/Cargo.toml`. | |
| - `@rust_caliptra_crates` — embedded Caliptra crates (rv32imc, no | |
| std/alloc). | |
| - `@rust_caliptra_crates_host` — Caliptra host tools (need std). | |
| - `./pw` is `bazelisk run //:pw -- "$@"` and dispatches to the named groups | |
| in `workflows.json` (`presubmit`, `default`, `ci`, `upstream_pigweed`). | |
| See [`usage.md`](./usage.md) for the everyday command surface and | |
| [`workflows.json`](https://github.com/OpenPRoT/openprot/blob/main/workflows.json) | |
| for the authoritative workflow definitions. | |
| ## Pigweed integration | |
| The veer target builds on Pigweed's microkernel and runtime crates: | |
| - `@pigweed//pw_kernel` — the microkernel running on `target/veer/`. | |
| Provides scheduling, IPC channels, interrupt objects, userspace | |
| isolation, and the `#[entry]` / `#[process_entry]` macros. System images | |
| are described declaratively in `system.json5` files (see `target/veer/` | |
| for examples) and assembled by Pigweed's `system_image()` macro. | |
| - `@pigweed//pw_log/rust:pw_log` — structured logging used throughout | |
| userspace and target code. | |
| - `@pigweed//pw_status/rust:pw_status` — `Result<T, pw_status::Error>` is | |
| the syscall and IPC return type. | |
| - `@pigweed//pw_toolchain/riscv_clang:riscv_clang_cc_toolchain_rv32imc` — | |
| RISC-V C/C++ toolchain used by the veer target's mixed-language build. | |
| For a concrete cross-process example, see | |
| [`design/pw-kernel-ipc.md`](./design/pw-kernel-ipc.md) and | |
| [`target/veer/ipc/`](https://github.com/OpenPRoT/openprot/tree/main/target/veer/ipc). | |
| ## Terminology | |
| - **Product**: This is the ultimate umbrella term for which we will construct a | |
| firmware bundle, that is, it is where the specific processor, memory map, | |
| board, features, configuration, etc., are finally combined. For two things to | |
| be the same product, they should be able to run the same firmware binary. This | |
| could be a single chip, a family of chips, a board, or a family of boards. | |
| This combines the Pigweed **target** along with all of the details for the | |
| final firmware build. Examples: AST1060 QEMU, Earlgrey Verilator, Caliptra MCU | |
| Test FPGA, Caliptra MCU Emulator. | |
| - **Product class**: Useful to talk about groups of products, like Caliptra MCU | |
| implementations, though not something we will build specific firmware for. | |
| - **Chip**: this is the SoC that a product uses, that is, collecting together | |
| the processor architecture (rv32imc, Cortex-M4F, etc.), interrupt controller, | |
| internal I2C/I3C controllers and targets, and all other internal components, | |
| the memory map, interrupt assignments, I2C/I3C addresses, etc., may | |
| not be static. This corresponds roughly to a Pigweed **target**. For example: | |
| AST1060 chip, Earlgrey 1.0 chip, Caliptra MCU 2.2 VeeR. Drivers might be | |
| chip-specific but rarely should be product-specific (though might be | |
| configured differently per product or product class). | |
| ## Targets | |
| Each silicon/SoC target lives under `target/<name>/` and provides its own | |
| linker script, entry point, `defs.bzl` helpers, register definitions, and | |
| test/runner tooling. | |
| - `target/ast10x0/` — ASPEED AST10x0. It contains board configuration, | |
| peripheral drivers, I2C and USART backends, PFR building blocks, and QEMU or | |
| hardware test harnesses. Run its executable QEMU tests with | |
| `bazel test --config=virt_ast10x0 //target/ast10x0/...`. | |
| - `target/earlgrey/` — OpenTitan Earl Grey. QEMU tests run on every PR; | |
| Verilator-driven tests are gated behind the `verilator` tag and the | |
| corresponding workflow group (see `workflows.json`). | |
| - `target/veer/` — Caliptra VeeR-EL2. Built on `pw_kernel` and exercised | |
| on the Caliptra emulator via `target/veer/tooling/caliptra_runner.bzl`. | |
| When adding a new target, prefer the `target/<name>/defs.bzl` helpers over | |
| hand-rolled `rust_binary` rules, and always set `target_compatible_with = | |
| TARGET_COMPATIBLE_WITH` so wildcard host builds skip target-only crates. | |
| ## Firmware images and tests | |
| Reference firmware is assembled close to the target that supplies its | |
| platform bindings. A target's `system.json5` declares the process topology, | |
| and Bazel `system_image()` rules combine that configuration with the kernel | |
| and application crates. Examples include the AST10x0 USART client/server image | |
| under `target/ast10x0/tests/usart/` and the Earl Grey and VeeR syscall-latency | |
| images under their respective target directories. | |
| Host tests normally live next to the platform-independent API or service. | |
| Emulator, simulator, and hardware-backed tests live under `target/<name>/` | |
| alongside the runner and build configuration they require. This keeps host | |
| wildcard tests from accidentally depending on target-only toolchains while | |
| still exercising the same protocol codecs and dispatch logic used by firmware. | |
| ## Third-party integration | |
| - `third_party/pigweed/` — local Pigweed integration including a | |
| `visibility.patch`. | |
| - `third_party/caliptra/` — integration with `caliptra-sw` and | |
| `caliptra-mcu-sw`. Version bumps go through `uprev.py`, which writes both | |
| `versions.bzl` (commit pins) and the Caliptra `Cargo.lock` files. | |
| - `third_party/crates_io/` — pinned crates.io dependencies for the main | |
| workspace; `third_party/caliptra/crates_io/{embedded,host}/` for the two | |
| Caliptra crate hubs. | |
| ## Where to read next | |
| - [`coding-style.md`](./coding-style.md) — formatter configs and Rust | |
| conventions. | |
| - [`contributing.md`](./contributing.md) and | |
| [`development-process.md`](./development-process.md) — review and merge | |
| process. | |
| - [`design/`](./design/index.md) — focused notes on individual subsystems | |
| (e.g. [pw_kernel IPC](./design/pw-kernel-ipc.md)). |