| # 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` for the everyday command surface and `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` and | |
| `target/veer/ipc/`. | |
| ## 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` — formatter configs and Rust conventions. | |
| - `contributing.md` and `development-process.md` — review and merge process. | |
| - `design/` — focused notes on individual subsystems (e.g. pw_kernel IPC). |