blob: 400bd3a6826bdbd5fb495268da417be698002b1c [file] [view]
# 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`. Tests under
`target/veer/tests/` run on the Caliptra emulator with
`bazel test //target/veer/...` and on a VCK190 FPGA with
`bazel test --config=fpga //target/veer/...`; see
[`target/veer/tooling/fpga/README.md`](https://github.com/OpenPRoT/openprot/blob/main/target/veer/tooling/fpga/README.md).
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)).