Architecture decision records¶
Why the Kokeb Labs standard is what it is. Each record is one decision in the Context / Decision / Consequences
form, numbered in the order it was accepted. A record is never edited to change its decision; a new record
supersedes it, and the old one gets a Superseded by ADR-NNNN status.
| ADR | Decision | Status |
|---|---|---|
| 0001 | Drivers keep <chip>::Error and Result<T>; handlers map to kb::Status |
Accepted |
| 0002 | One lifecycle: I/O-free constructor, Initialize(), EnsureInitialized() |
Accepted, amended by 0021 |
| 0003 | Drivers are templates on a CRTP port constrained by a concept | Accepted |
| 0004 | No heap in drivers; none after start-up anywhere | Accepted |
| 0005 | A shared kb-hal-common repository; board HALs live with their products |
Accepted |
| 0006 | FreeRTOS at 1 kHz everywhere; a delay waits at least the requested time | Accepted |
| 0007 | Drivers pinned in kb-core to release tags; driver.yml, catalog/compat.yml and release trains |
Accepted |
| 0008 | One naming scheme, enforced by clang-tidy |
Accepted |
| 0009 | MIT for firmware and tooling; CERN-OHL-P-2.0 for hardware designs | Accepted |
| 0010 | C++20 in every repository | Accepted |
| 0011 | The root holds only required and first-read files; tool configuration in _config/; platform code only in examples/<platform>/ |
Accepted |
| 0012 | Drivers carry no brand: driver-<chip>, namespace <chip>, <chip>::<chip> |
Accepted |
| 0013 | kb-core is one monorepo with four targets and one version | Accepted |
| 0014 | Chip-, MCU- and product-specific code each have one place | Accepted |
| 0015 | Governance for one maintainer, open to contributors | Accepted |
| 0016 | Virtual functions only at the three run-time boundaries | Accepted |
| 0017 | Target code uses a named subset of the standard library | Accepted |
| 0018 | Commit sdkconfig.defaults, never the generated sdkconfig |
Accepted |
| 0019 | Datasheets are referenced by exact revision, never committed | Accepted |
| 0020 | Complexity limits and coverage floors per assurance level | Accepted |
| 0021 | EnsureInitialized() is the one start-up entry point | Accepted |
Format¶
# ADR-NNNN: <decision as a short sentence>
- Status: Proposed | Accepted | Superseded by ADR-NNNN
- Date: YYYY-MM-DD
## Context
What forced a decision: the problem, the constraints, the options considered.
## Decision
What we do, stated as rules.
## Consequences
What gets better, what gets worse, and what has to change in which repositories.
A new record is added in the same PR as the change to the standard it explains. It is proposed in a PR to
kokeb-labs/.github and stays open for comment for at least seven days unless it fixes a defect.
Where the decisions came from¶
Records 0001 to 0011 were accepted on 3 November 2026, after a read-only review of the code the standard grew from (drivers, libraries, HALs and products) against one checklist: API shape, port, errors, start-up, config, memory and threading, naming, build, tests and docs. The review found the repository shell, docs and CI already uniform, and the C++ contracts not: 5 error models, 6 start-up styles, about 8 spellings of the same port hooks, two handler families, drifting HALs and about 45 error types.
When the standard was set up for Kokeb Labs on 5 November 2026, those records were rewritten for the new org (names, licence, the kb-core layout), and records 0012 to 0015 were added. From then on, the rule at the top of this page applies.
The order of work:
- Write it down: this standard, the org clang configs,
kokeb-labs/driver-templateandci-tools. - kb-core skeleton:
utilswithkb::Status,rtos,interfaceswithToStatus(), each its own target, with the MCU gate andcatalog/compat.yml. - Drivers, in parallel, each released as
driver-<chip>with itsdriver.yml, and each landing with its kb-core handler. - kb-core handlers on one family, with shared adapter bases.
- kb-hal-common: the shared managers, facade base, bind interface, lints and an example board HAL;
board-hal-templateafter it. - The first release train, then the STM32 compile job and bind.