Architecture¶
How the stack is put together: which layer may depend on which, where chip-, MCU- and product-specific code lives, and what drivers, kb-core, kb-hal-common, board HALs and products each own. The include tables are on Layers; the per-layer pages under Standards hold the detail. Rules marked guide are design advice for review.
| Rule | Level | Applies to | Verified |
|---|---|---|---|
| KB-ARCH-001 Dependencies point down the stack only | must | driver, library, hal, firmware, template | planned |
| KB-ARCH-002 A layer skip is a defect even when it works | must | library, hal, firmware | planned |
| KB-ARCH-003 The submodule graph is acyclic and points down | must | driver, library, hal, firmware | planned |
| KB-ARCH-004 Inside kb-core: utils, then rtos, then interfaces, then handlers | must | library | planned |
| KB-ARCH-005 Drivers and kb-core meet only in the handler adapter | must | driver, library, template | checked |
| KB-ARCH-006 Port hooks move raw bytes; the driver never configures the bus | must | driver, template | review |
| KB-ARCH-007 Drivers never lock, sleep or call an RTOS | must | driver, template | checked |
| KB-ARCH-008 Only a chip's driver and handler know its registers | must | library, hal, firmware | review |
| KB-ARCH-009 MCU-specific code lives only in the selected family's folders | must | driver, library, hal, firmware | planned |
| KB-ARCH-010 Product-specific needs reach kb-core and drivers only as generic extension points | must | driver, library, template | review |
| KB-ARCH-011 Virtual functions only at the three run-time boundaries | must | driver, library, hal, template | checked |
| KB-ARCH-012 A peripheral only one MCU family has gets a Base* interface and a gate row | must | driver, library | review |
| KB-ARCH-013 A protocol client follows the driver contract except the chip rules | should | driver | review |
| KB-ARCH-014 Split a large chip into sub-object facades that share the driver | guide | driver | none |
| KB-ARCH-015 utils take locks and clocks as arguments; CANopen frames are values | must | library | planned |
| KB-ARCH-016 The kb-core logger is the one logging API above the bind | must | driver, library, hal, firmware | planned |
| KB-ARCH-017 Raw pin numbers appear only in the board's pin table and its bind | must | library, hal, firmware | planned |
| KB-ARCH-018 Adapters are mechanical and build on the shared adapter bases | should | library | review |
| KB-ARCH-019 A driver feature reached through VisitDriver in two places becomes a typed method | should | library | review |
| KB-ARCH-020 A board HAL never copies kb-hal-common; shared managers move there | must | hal | planned |
| KB-ARCH-021 Common managers take board specifics as configuration and never name a board | must | hal, library | planned |
| KB-ARCH-022 One manager per board function, owning its handlers | must | hal | review |
| KB-ARCH-023 The facade starts managers in a fixed, documented order | must | hal | review |
| KB-ARCH-024 Start-up fails closed and leaves every actuator safe | must | hal, firmware | planned |
| KB-ARCH-025 The facade is the product's only way into the board | must | hal, firmware | planned |
| KB-ARCH-026 The bind is the only HAL code that names the MCU family | must | hal | planned |
| KB-ARCH-027 A board function the facade lacks is added to the HAL first | should | firmware, hal | review |
| KB-ARCH-028 Application logic lives in the application, not in platform/ or the HAL | must | firmware, hal | review |
| KB-ARCH-029 Run-time faults follow the fault catalogue's reaction | guide | hal, firmware | none |
| KB-ARCH-030 A safety-classified product records its classification and what it implies | should | firmware (safety level and above) | review |
| KB-ARCH-031 Only kb-core rtos includes RTOS headers; everything above uses kb::rtos | must | driver, library, hal, firmware | planned |
| KB-ARCH-032 Only the product or a HAL manager creates tasks | must | driver, library, hal, firmware | planned |
| KB-ARCH-033 Core affinity is the product's decision | should | hal, firmware | review |
| KB-ARCH-034 Handler callbacks run in the caller's task | should | library, hal, firmware | review |
| KB-ARCH-035 kb-core pins each driver to a release tag, with its handler and catalogue entry | must | library | planned |
| KB-ARCH-036 The compatibility catalogue is generated from the pinned drivers | must | library | planned |
| KB-ARCH-037 Extend what exists before adding a new entity | guide | library, hal | none |
| KB-ARCH-038 Design for bounded memory and cheap bus traffic | guide | driver, library, hal, firmware | none |
| KB-ARCH-039 Real-time paths have bounded latency and named priorities | guide | hal, firmware | none |
| KB-ARCH-040 Review architecture before details | guide | driver, library, hal, firmware | none |
| KB-ARCH-041 Extra read-back and verification are chosen per call, off by default | must | driver, template | review |
| KB-ARCH-042 A reply is accepted only when the protocol proves it answers the request | must | driver, template | planned |
| KB-ARCH-043 A pipelined exchange completes inside one public call, keyed on reply content | must | driver, library, template | review |
| KB-ARCH-044 Retries repeat only idempotent frames, are bounded and are counted | must | driver, library, template | review |
KB-ARCH-001: Dependencies point down the stack only¶
MUST · driver, library, hal, firmware, template · since 1.0
No layer includes, links or calls anything above it in the stack on Layers (product, board HAL with its bind, kb-core handlers, interfaces, rtos, utils, drivers). Each file includes only what the Layers include table allows for its folder.
Why: An upward dependency makes a lower layer untestable without the one above and lets lock, lifecycle and error mapping be bypassed. Downward-only dependencies let any driver sit under any product.
Verified by:
include-graph/all(planned): every #include in library code is allowed by the Layers include table for its folder; the parameter names the layer (driver, utils, rtos, interfaces, mcu, handlers, hal, product) orall- review: Every new include is allowed by the Layers include table for the folder it is in.
See also: ADR-0013; IEC 62304:2006+A1:2015 5.3.2 (interfaces between software items)
Explained in: standards/layers.md
KB-ARCH-002: A layer skip is a defect even when it works¶
MUST · library, hal, firmware · since 1.0
Code that reaches past the layer directly below it (a manager calling a driver through a handler's driver pointer, an
application calling an Esp* class or raw FreeRTOS, middleware including a handler) is fixed by adding the missing call
to the skipped layer, not by allowing the skip.
Why: The skipped layer's lock, lifecycle and error mapping silently stop applying.
Verified by:
hal-lint/driver-access(planned): the kb-hal-common lints run in a board HAL's or product's CI; the parameter names the lint (boundary, driver-access, allocation, lock)- review: No call reaches past the layer below it; a missing feature is added to the skipped layer.
Explained in: standards/layers.md
KB-ARCH-003: The submodule graph is acyclic and points down¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · driver, library, hal, firmware · since 1.0 · enforced from 2027-03-01
Submodules point only down the stack: a product pins its board HAL, a board HAL pins kb-hal-common and kb-core, and kb-core pins drivers. No repository pins one above it or forms a cycle.
Verified by:
submodule-graph(planned): walking .gitmodules across the org's repositories finds no cycle and no submodule that points up the stack (product -> board HAL -> kb-hal-common and kb-core -> drivers)
Explained in: standards/layers.md
KB-ARCH-004: Inside kb-core: utils, then rtos, then interfaces, then handlers¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · library · since 1.0 · enforced from 2027-03-01
kb-core's parts are the separate CMake targets kb::utils, kb::rtos, kb::interfaces and kb::handlers, and each
links only the targets before it in that order, so an upward include fails to build.
Verified by:
layer-deps(planned): kb-core's CMake targets link only downward (kb::utils <- kb::rtos <- kb::interfaces <- kb::handlers), read from the CMake file API, and each builds alone with KB_MCU=NONE and KB_MCU=HOST
See also: ADR-0013
Explained in: standards/library.md
KB-ARCH-005: Drivers and kb-core meet only in the handler adapter¶
MUST · driver, library, template · since 1.0
A driver depends on nothing in kb-core or any other Kokeb Labs repository; kb_core_min in driver.yml is its only
mention of kb-core. kb-core's utils, rtos and interfaces never depend on a driver. The handler's adapter, which
implements the driver's port with Base* calls, is the one place they meet.
Why: A driver must be usable and forkable without anything else from the org, and the core must not change when a chip is added.
Verified by:
host-tests(implemented): the unit tests build and pass on the host with gcc and clanginclude-graph/driver(planned): every #include in library code is allowed by the Layers include table for its folder; the parameter names the layer (driver, utils, rtos, interfaces, mcu, handlers, hal, product) orall- review: Driver code names nothing from kb-core; kb-core code outside handlers/ includes no driver header.
Explained in: standards/layers.md
KB-ARCH-006: Port hooks move raw bytes; the driver never configures the bus¶
MUST · driver, template · since 1.0
Port hooks transfer bytes and nothing else; register addresses travel in the payload. The driver does not set bus speed, mode or pins: the port or the board does.
Verified by:
- review: No driver code or hook argument configures bus speed, mode or pins.
See also: ADR-0003
Explained in: standards/driver.md
KB-ARCH-007: Drivers never lock, sleep or call an RTOS¶
MUST · driver, template · since 1.0
A driver is not thread-safe: it takes no lock, creates no task and calls no RTOS (waiting is KB-CPP-041). The kb-core handler that owns it does the locking.
Why: One owner for locking avoids double locks and lets the same driver run bare-metal or on any RTOS.
Verified by:
host-tests(implemented): the unit tests build and pass on the host with gcc and clanginclude-graph/driver(planned): every #include in library code is allowed by the Layers include table for its folder; the parameter names the layer (driver, utils, rtos, interfaces, mcu, handlers, hal, product) orall- review: The driver has no lock, task or RTOS call.
See also: ADR-0003
Explained in: standards/driver.md
KB-ARCH-008: Only a chip's driver and handler know its registers¶
MUST · library, hal, firmware · since 1.0
A chip's register map, start-up sequence and quirks live in its driver and its handler only. Managers, HALs and products
use the handler's typed API or VisitDriver() and never name a register.
Verified by:
- review: No code outside the chip's driver and handler names its registers or bit fields.
See also: ADR-0014
Explained in: standards/layers.md
KB-ARCH-009: MCU-specific code lives only in the selected family's folders¶
MUST · driver, library, hal, firmware · since 1.0
Code that knows an MCU family lives only in kb-core's interfaces/mcu/<family>/, a board HAL's bsp_bind/<family>/ and
a product's platform/. The build compiles only the selected family's folders, and every other folder compiles for
every family and on the host.
Why: KB-CPP-016 bans the platform macros that would let MCU code hide elsewhere; this rule says where it goes.
Verified by:
include-graph/mcu(planned): every #include in library code is allowed by the Layers include table for its folder; the parameter names the layer (driver, utils, rtos, interfaces, mcu, handlers, hal, product) orall- review: New MCU-specific code is in an
mcu/<family>/,bsp_bind/<family>/orplatform/folder.
See also: ADR-0014
Explained in: standards/layers.md
KB-ARCH-010: Product-specific needs reach kb-core and drivers only as generic extension points¶
MUST · driver, library, template · since 1.0
Nothing in kb-core or a driver is specific to one product: no product macro, pin, channel choice, limit, profile table
or fault catalogue. A product need becomes a config mask, a table passed in as std::span, a Base* backend interface
or an injected logger, or it stays in the product's board HAL.
Why: Whatever one product puts in the core, every other product carries. The second-product test catches it before merge.
Verified by:
- review: A second, made-up product with a different board could use this change to kb-core or the driver without editing it.
See also: ADR-0014
Explained in: standards/layers.md
KB-ARCH-011: Virtual functions only at the three run-time boundaries¶
MUST · driver, library, hal, template · since 1.0
Virtual functions appear only in kb-core's Base* peripheral interfaces, kb-hal-common's ManagerBase, FacadeBase
and their sink interfaces, and kb-core's BaseThread and BaseThreadsManager. Drivers, ports, handlers and utilities
have none; code above the bind holds a Base*&.
Why: Static dispatch keeps drivers and handlers inlined and checkable at compile time; the two run-time boundaries are where the concrete type is not known until the board is built (the MCU object, the board's managers).
Verified by:
forbidden-patterns/virtual-outside-interfaces(implemented): a source scan for a construct the handbook bans; the parameter names the pattern set- review: A new virtual function is in one of the three boundaries of ADR-0016, nowhere else.
See also: ADR-0016; ADR-0003; ADR-0005
Explained in: standards/library.md
KB-ARCH-012: A peripheral only one MCU family has gets a Base* interface and a gate row¶
MUST · driver, library · since 1.0
A peripheral that only one family has (the ESP32 RMT) gets a Base* interface in interfaces/base/ and an
implementation in that family's folder only. A driver that needs it stays platform-free, names the family and peripheral
in driver.yml, says it is MCU-bound in its README and Contract page, and becomes a row in the MCU gate table.
Verified by:
- review: The peripheral has a
Base*interface, one family implementation, adriver.ymlentry and an MCU gate row; the driver'sinc/andsrc/include no vendor SDK.
Explained in: standards/driver.md
KB-ARCH-013: A protocol client follows the driver contract except the chip rules¶
SHOULD · driver · since 1.0
A driver for a device reached over a protocol (a CANopen node) skips the chip-ID check, register model, datasheet
defaults and register mock, and follows the rest of the driver contract. Its Initialize() checks the remote identity
(device type, vendor ID).
Verified by:
- review: The client checks the remote identity in Initialize() and otherwise follows the driver contract.
Explained in: standards/driver.md
KB-ARCH-014: Split a large chip into sub-object facades that share the driver¶
GUIDE · driver · since 1.0
A chip with many subsystems may expose them as sub-object facades held by the driver
(driver.telemetry().ReadSupplyMv()). Each facade follows the driver contract and shares the driver's port, lifecycle
and Error.
Explained in: standards/driver.md
KB-ARCH-015: utils take locks and clocks as arguments; CANopen frames are values¶
MUST · library · since 1.0
A kb-core utils helper that needs a lock or a clock takes it as a parameter or template argument instead of reaching
up to kb/rtos/ or the interfaces. utils/canopen depends on no CAN interface or driver, does not allocate, and builds
frames as values the caller sends.
Verified by:
include-graph/utils(planned): every #include in library code is allowed by the Layers include table for its folder; the parameter names the layer (driver, utils, rtos, interfaces, mcu, handlers, hal, product) orall- review: A new utils helper takes its lock or clock as an argument; CANopen helpers return frames by value.
Explained in: standards/library.md
KB-ARCH-016: The kb-core logger is the one logging API above the bind¶
MUST · driver, library, hal, firmware · since 1.0
Code above the bind logs only through the kb-core logger, whose sink the board HAL injects at start-up. kb-core prints nothing on its own and carries no product's log format; drivers do not format log text.
Verified by:
forbidden-patterns/direct-logging(planned): a source scan for a construct the handbook bans; the parameter names the pattern set- review: No
printf,ESP_LOG*or vendor logging call above the bind; logging goes through the kb-core logger.
Explained in: standards/library.md
KB-ARCH-017: Raw pin numbers appear only in the board's pin table and its bind¶
MUST · library, hal, firmware · since 1.0
The pincfg framework holds no board's pins. MCU pin numbers appear only in a board HAL's pin table under
board/<board>/ and in its bind; managers and everything above use functional pin names.
Verified by:
forbidden-patterns/raw-pins(planned): a source scan for a construct the handbook bans; the parameter names the pattern set- review: No
GPIO_NUM_*or literal pin number outside the board pin table andbsp_bind/.
Explained in: standards/hal.md
KB-ARCH-018: Adapters are mechanical and build on the shared adapter bases¶
SHOULD · library · since 1.0
A handler's adapter derives from the shared base in handlers/common/ for its bus (HalSpiCommBase, HalI2cCommBase,
HalUartCommBase), which holds the bus reference, pin mapping and delay and log hooks, and adds only what is
chip-specific. Retry policy and other decisions live in the handler, not the adapter.
Verified by:
- review: The adapter uses the shared base for its bus and contains translation only.
Explained in: standards/handler.md
KB-ARCH-019: A driver feature reached through VisitDriver in two places becomes a typed method¶
SHOULD · library · since 1.0
When the same driver feature is used through VisitDriver() in more than one place, the handler gains a typed method
for it.
Verified by:
- review: No driver feature is reached through VisitDriver() in two places without a typed handler method.
Explained in: standards/handler.md
KB-ARCH-020: A board HAL never copies kb-hal-common; shared managers move there¶
MUST · hal · since 1.0
kb-hal-common holds the manager and facade bases, the bind interface, the common managers and the lints; a board HAL holds only its board config, pin table, bind and board-specific managers. A board HAL carries no copy of kb-hal-common code, and a manager two boards need moves to kb-hal-common.
Why: Copied managers drift; the review behind ADR-0005 found six near-copies.
Verified by:
duplicate-code(planned): jscpd finds no block in a board HAL that duplicates kb-hal-common code above the configured threshold- review: The HAL adds no copy of a kb-hal-common class; a manager a second board needs is moved there.
See also: ADR-0005
Explained in: standards/hal.md
KB-ARCH-021: Common managers take board specifics as configuration and never name a board¶
MUST · hal, library · since 1.0
The managers in kb-hal-common receive everything board-specific (channels, LEDs, NVS namespaces) as configuration and contain no board or product name.
Verified by:
forbidden-patterns/board-names(planned): a source scan for a construct the handbook bans; the parameter names the pattern set- review: No board or product name or board-specific constant in kb-hal-common.
See also: ADR-0005
Explained in: standards/hal.md
KB-ARCH-022: One manager per board function, owning its handlers¶
MUST · hal · since 1.0
A board HAL has one manager per board function; the manager owns that function's handlers and the Base* objects the
bind created for them. A new chip in an existing category, a board variant or a cross-category feature extends an
existing manager rather than adding one.
Verified by:
- review: A new manager covers a board function no existing manager covers.
See also: ADR-0005
Explained in: standards/hal.md
KB-ARCH-023: The facade starts managers in a fixed, documented order¶
MUST · hal · since 1.0
The board facade derives from FacadeBase and passes its managers in a start-up order fixed at compile time. The order,
and why, is on the HAL's Architecture page; managers do not start each other.
Verified by:
- review: The start order is a compile-time list passed to FacadeBase and matches the Architecture page.
Explained in: standards/hal.md
KB-ARCH-024: Start-up fails closed and leaves every actuator safe¶
MUST · hal, firmware · since 1.0
Initialize() stops at the first failing manager, deinitialises the ones already started in reverse order and returns
the failing manager and its status. Only managers the board can run without are optional, never safety-relevant ones;
after a failed start-up the product reports the fault and starts no control task.
Why: A half-started board with a live actuator and no supervising task is the dangerous case.
Verified by:
hal-startup-test(planned): a HAL host test with the host bind injects a failure into each manager in turn and checks that start-up stops, deinitialises the started managers in reverse and reports the failing ManagerId- review: A host test injects a failure into each manager in turn and checks the reverse deinitialisation; no safety-relevant manager is optional.
See also: ADR-0002
Explained in: standards/hal.md
KB-ARCH-025: The facade is the product's only way into the board¶
MUST · hal, firmware · since 1.0
The application uses only the HAL facade and its managers' public API, kb::rtos and the kb-core logger. The facade
exposes managers by reference and nothing below them.
Verified by:
hal-lint/boundary(planned): the kb-hal-common lints run in a board HAL's or product's CI; the parameter names the lint (boundary, driver-access, allocation, lock)- review: The application reaches hardware only through the facade and its managers.
See also: ADR-0005
Explained in: standards/product.md
KB-ARCH-026: The bind is the only HAL code that names the MCU family¶
MUST · hal · since 1.0
In a board HAL only bsp_bind/<family>/ names MCU types. It implements the one bind interface declared in kb-hal-common
by creating kb-core's interfaces/mcu/<family>/ objects; it never reimplements a peripheral, and a peripheral kb-core
lacks is added to kb-core first.
Verified by:
hal-lint/boundary(planned): the kb-hal-common lints run in a board HAL's or product's CI; the parameter names the lint (boundary, driver-access, allocation, lock)- review: The bind creates kb-core MCU objects and contains no peripheral implementation of its own.
Explained in: standards/hal.md
KB-ARCH-027: A board function the facade lacks is added to the HAL first¶
SHOULD · firmware, hal · since 1.0
When the application needs a board function the facade does not offer (for example CAN), it is added to the board HAL and then used; the application does not reach around the facade for it.
Verified by:
- review: New board access in the application goes through a facade or manager method.
Explained in: standards/product.md
KB-ARCH-028: Application logic lives in the application, not in platform/ or the HAL¶
MUST · firmware, hal · since 1.0
A product's platform/ holds app_main(), partitions, OTA and the console. app_main() creates the facade,
initialises it, reports a failed start-up and starts the tasks. Behaviour (tasks, protocols, state machines, faults)
lives in the application, never in platform/ or the board HAL.
Verified by:
- review: platform/ and the HAL contain start-up and board code only, no application behaviour.
Explained in: standards/product.md
KB-ARCH-029: Run-time faults follow the fault catalogue's reaction¶
GUIDE · hal, firmware · since 1.0
Detect bus and device faults, and react as the product's fault catalogue says (stop, derate, warn) rather than ad hoc. Degraded operation is a designed reaction listed in the catalogue; start-up stays fail-closed.
Explained in: standards/product.md
KB-ARCH-030: A safety-classified product records its classification and what it implies¶
SHOULD · firmware (safety level and above) · since 1.0
A product meant for a safety-classified use records its software safety class (IEC 62304 class, SIL or ASIL), the reasoning, and the verification that class requires, in its own ADRs.
Verified by:
- review: The product's docs/adr/ has a classification record naming the class and the verification it needs.
See also: IEC 62304:2006+A1:2015 4.3 (software safety classification)
Explained in: assurance-levels.md
KB-ARCH-031: Only kb-core rtos includes RTOS headers; everything above uses kb::rtos¶
MUST · driver, library, hal, firmware · since 1.0
Drivers, utils and pincfg use no RTOS. Only kb-core's rtos/ backend folders include RTOS headers; handlers, HALs and
products use kb::rtos only, and only the bind and a product's platform/ may call the SDK or RTOS directly.
Verified by:
include-graph/rtos(planned): every #include in library code is allowed by the Layers include table for its folder; the parameter names the layer (driver, utils, rtos, interfaces, mcu, handlers, hal, product) orallforbidden-patterns/raw-rtos(planned): a source scan for a construct the handbook bans; the parameter names the pattern set- review: No raw RTOS call or header,
std::mutexorstd::threadabove the bind.
See also: ADR-0013
Explained in: standards/threading-and-timing.md
KB-ARCH-032: Only the product or a HAL manager creates tasks¶
MUST · driver, library, hal, firmware · since 1.0
Tasks are created through kb::rtos (BaseThread, BaseThreadsManager) by the product or a HAL manager, never by a
handler or a driver.
Verified by:
forbidden-patterns/task-creation(planned): a source scan for a construct the handbook bans; the parameter names the pattern set- review: No handler or driver creates a task.
Explained in: standards/threading-and-timing.md
KB-ARCH-033: Core affinity is the product's decision¶
SHOULD · hal, firmware · since 1.0
Which core a task runs on is set in the product's task configuration header. HAL code does not assume a dual-core MCU or pin work to a core.
Verified by:
- review: No core affinity is set or assumed outside the product's task configuration.
Explained in: standards/threading-and-timing.md
KB-ARCH-034: Handler callbacks run in the caller's task¶
SHOULD · library, hal, firmware · since 1.0
A callback from a handler into the product runs in the task that made the call. A callback that must reach another task
posts to an OsQueue instead of doing that task's work.
Verified by:
- review: Callbacks that cross tasks post to a queue.
Explained in: standards/threading-and-timing.md
KB-ARCH-035: kb-core pins each driver to a release tag, with its handler and catalogue entry¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · library · since 1.0 · enforced from 2027-03-01
kb-core includes each driver as the submodule drivers/driver-<chip>/ at the commit of a release tag, never through a
package registry. The driver is released and pinned before its handler lands, and every pinned driver has a handler and
an entry in catalog/compat.yml.
Verified by:
kb-core-catalog(planned): every drivers/driver-<chip> gitlink is the commit of a v* release tag, has a handlers/<chip>/ folder and a catalog/compat.yml entry, and regenerating compat.yml and the MCU gate table from the pinned driver.yml files changes nothing
Explained in: standards/release.md
KB-ARCH-036: The compatibility catalogue is generated from the pinned drivers¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · library · since 1.0 · enforced from 2027-03-01
catalog/compat.yml is built from the driver.yml of every pinned driver and generates the MCU gate table in
cmake/kb_build_settings.cmake. CI regenerates both and fails on any difference, and kb-core's release notes list the
same driver versions.
Verified by:
kb-core-catalog(planned): every drivers/driver-<chip> gitlink is the commit of a v* release tag, has a handlers/<chip>/ folder and a catalog/compat.yml entry, and regenerating compat.yml and the MCU gate table from the pinned driver.yml files changes nothing
See also: ADR-0007
Explained in: standards/release.md
KB-ARCH-037: Extend what exists before adding a new entity¶
GUIDE · library, hal · since 1.0
Before adding a handler, manager or interface, check whether an existing one should grow. A new chip gets a handler; a new board function gets a manager; a new chip in an existing function does not.
Explained in: standards/hal.md
KB-ARCH-038: Design for bounded memory and cheap bus traffic¶
GUIDE · driver, library, hal, firmware · since 1.0
Batch bus transactions, use DMA for large transfers, pick cache-friendly algorithms, and size pools and buffers at compile time. Caching is fine; lazy allocation and run-time pools from the heap are not.
See also: ADR-0004
KB-ARCH-039: Real-time paths have bounded latency and named priorities¶
GUIDE · hal, firmware · since 1.0
Code on a real-time path has a known worst-case time, takes no unbounded wait, and runs at a priority named in the product's task configuration. Resources it needs are reserved at start-up.
Explained in: standards/threading-and-timing.md
KB-ARCH-040: Review architecture before details¶
GUIDE · driver, library, hal, firmware · since 1.0
A reviewer checks layering, ownership, locking, error mapping, fault reaction and timing before line-level comments, and a design problem is raised first.
Explained in: standards/layers.md
KB-ARCH-041: Extra read-back and verification are chosen per call, off by default¶
Proposed
The caller decides at the call site where the extra traffic is worth it, for example a factory write, while a control loop calling the same driver pays nothing. A per-call argument, not a Config field, so one driver object can serve both.
MUST · driver, template · since 1.0 · enforced from 2026-12-01
A driver call sends only the bus traffic the datasheet needs for that operation. A read-back of what was just written, a
second read to compare, or any other check the datasheet does not require is requested per call with a trailing Verify
argument that defaults to Verify::None, documented with its cost in transfers and what it catches. Start-up checks
inside EnsureInitialized() and steps the datasheet requires (an OTP or fuse guard-band read, a busy poll before a
command) are not extra and stay unconditional.
Verified by:
- review: Every read-back or compare outside EnsureInitialized() runs only when the call passes a Verify value other than None, or is cited to the datasheet step that requires it; a host test shows the default call sends no extra transfer.
Explained in: standards/driver.md
KB-ARCH-042: A reply is accepted only when the protocol proves it answers the request¶
Proposed
Warns until 2027-03-01, then fails CI. The fuzz target gains a stale-reply mutator (KB-TST-020).
MUST · driver, template · since 1.0 · enforced from 2027-03-01
A driver decodes a reply only when every check the protocol offers passes: the CRC or checksum, the reply's type and
width, and the echoed opcode, address or tag where the protocol has one. A reply that fails any of them is not decoded:
the call returns Crc or a chip-specific mismatch code, or retries per KB-ARCH-044.
Why: Observed on hardware: on a shared or long bus a frame can arrive intact but late, so a reply with a valid CRC still decoded as the wrong register. A CRC proves the bits arrived; only the tag proves which request they answer.
Verified by:
fuzzing(planned): each parser's libFuzzer target runs on the host for a fixed time under ASan and UBSan without a finding- review: Every read path checks CRC, reply type or width, and the echoed tag the protocol provides before it decodes; a model test that replays the previous reply, or answers with the wrong tag, fails each read.
Explained in: standards/driver.md
KB-ARCH-043: A pipelined exchange completes inside one public call, keyed on reply content¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · driver, library, template · since 1.0 · enforced from 2027-03-01
When a chip answers one or more frames later, the driver sends the request and collects its reply inside the same public call, and matches each result to its request by the reply's content (tag, address, opcode), never by frame position. The Porting page states that no other access to the chip may come between those frames, and a handler holds the bus for the whole call.
Why: Observed on hardware: a reply that arrives in a later frame is lost or attributed to the wrong request when another access comes in between. A model test that interleaves a foreign frame shows a mismatch error, not wrong data.
Verified by:
- review: No public call leaves a request whose reply a later call reads; results are matched on reply content; the Porting page states the no-interleave requirement and the handler holds its lock across the call.
Explained in: standards/driver.md
KB-ARCH-044: Retries repeat only idempotent frames, are bounded and are counted¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · driver, library, template · since 1.0 · enforced from 2027-03-01
A retry, in a driver or a handler, repeats only frames that are safe to send twice. When the outcome of a write is unknown, only the reply request is sent again. A retry never repeats a reset pulse, an enable toggle or a deinitialise unless the datasheet requires it. Every retry loop has a fixed upper bound and counts its attempts, and the count is visible to the caller or in the diagnostics.
Why: Observed on hardware: repeating a side effect restarted the very wait being retried, doubled a write and made outputs flicker.
Verified by:
- review: Each retry loop names its bound and repeats only idempotent frames; a handler test counts reset and enable toggles per retried call and expects none beyond the datasheet sequence.
See also: NASA/JPL Power of Ten Rule 2 (fixed upper bound on loops)
Explained in: standards/driver.md