Skip to content

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) or all
  • 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)

See also: ADR-0007; ADR-0013

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 clang
  • include-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) or all
  • review: Driver code names nothing from kb-core; kb-core code outside handlers/ includes no driver header.

See also: ADR-0012; ADR-0013

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 clang
  • include-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) or all
  • 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) or all
  • review: New MCU-specific code is in an mcu/<family>/, bsp_bind/<family>/ or platform/ 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, a driver.yml entry and an MCU gate row; the driver's inc/ and src/ include no vendor SDK.

See also: ADR-0014; ADR-0007

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) or all
  • 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 and bsp_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.

See also: ADR-0002; ADR-0005

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.

See also: ADR-0005; ADR-0014

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) or all
  • forbidden-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::mutex or std::thread above 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

See also: ADR-0007; ADR-0013

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