Skip to content

C++ code

How C++ is written in every Kokeb Labs repository: the language level, what the code may and may not use on a microcontroller, errors, naming and format. The pages under Standards explain the reasoning; this list is what CI and review hold each change to.

Rule Level Applies to Verified
KB-CPP-001 C++20, no compiler extensions must driver, library, hal, firmware, template checked
KB-CPP-002 No exceptions and no RTTI must driver, library, hal, firmware, template checked
KB-CPP-003 No heap in drivers; no heap after start-up anywhere must driver, library, hal, firmware, template checked
KB-CPP-004 Errors are values, and every result is used must driver, library, hal, firmware, template checked
KB-CPP-005 Format with the org clang-format configuration must all checked
KB-CPP-006 Names follow the org naming scheme must all checked
KB-CPP-007 No reinterpret_cast or C-style casts outside the port layer must driver, library, template checked
KB-CPP-008 Static analysis is clean, and every suppression is a recorded deviation must driver, library, hal, firmware, template checked
KB-CPP-009 Register frames have their layout asserted must driver, library, hal (high level and above) planned
KB-CPP-010 Data shared with an interrupt is atomic or explicitly guarded must driver, library, hal, firmware review
KB-CPP-011 Driver code includes only its own headers and the allowed standard headers must driver, template checked
KB-CPP-012 Target code uses only the target library subset and C++20 the pinned compilers share must driver, library, hal, firmware, template checked
KB-CPP-013 Each kb-core part includes only what its layer table allows must library planned
KB-CPP-014 Handlers include only their driver, Base headers and kb-core utilities must library planned
KB-CPP-015 HAL and product code reach hardware only through their bind and handlers must hal, firmware planned
KB-CPP-016 Shared code never tests platform, board or product macros must driver, library, template planned
KB-CPP-017 An MCU family header fails to compile outside its family must library planned
KB-CPP-018 Includes are quoted from the include root and never climb with ../ must driver, library, hal, firmware, template planned
KB-CPP-019 Every header has an #ifndef include guard named after its file; no #pragma must driver, library, hal, firmware, template checked
KB-CPP-020 Includes are grouped own header, standard, other repositories, this repository should driver, library, hal, firmware, template review
KB-CPP-021 Every header includes what it uses and compiles on its own must driver, library, hal, firmware, template checked
KB-CPP-022 Drivers carry no organisation brand must driver, template planned
KB-CPP-023 Driver names derive from the chip must driver, template planned
KB-CPP-024 A driver declares nothing at global scope must driver, template planned
KB-CPP-025 Namespaces follow the layer they belong to must driver, library, hal, firmware, template checked
KB-CPP-026 No using-directives in headers; anonymous namespaces only in source files must driver, library, hal, firmware, template checked
KB-CPP-027 Macros carry their repository's prefix and never leak generic names must driver, library, hal, firmware, template planned
KB-CPP-028 No m_, s_, g_ or p_ prefixes on names should driver, library, hal, firmware, template planned
KB-CPP-029 Function names say whether they touch the chip should driver, library, hal, template review
KB-CPP-030 Quantities carry their unit in the name must driver, library, hal, firmware, template planned
KB-CPP-031 Names describe what they hold guide all none
KB-CPP-032 One CRTP port base per bus, and the driver is constrained by its port concept must driver, template checked
KB-CPP-033 No virtual functions in a driver or its port must driver, template planned
KB-CPP-034 The port base never declares a required hook must driver, template review
KB-CPP-035 Port hooks are PascalCase, noexcept and return bool, with the bus's fixed signatures must driver, template checked
KB-CPP-036 Optional hooks are detected with requires, in one place must driver, template planned
KB-CPP-037 A missing hook fails to compile or falls back in a documented way, never silently must driver, template checked
KB-CPP-038 Driver pins are logical; the port maps them to the board must driver, template review
KB-CPP-039 Drivers use no std::function or printf-family output; callbacks are a function pointer must driver, template planned
KB-CPP-040 Drivers and kb-core utilities hold no mutable global or static state must driver, library, template checked
KB-CPP-041 A driver waits only through the port's delay hooks must driver, template planned
KB-CPP-042 Drivers declare no friends should driver, template review
KB-CPP-043 Run-time configuration is one Config struct passed to the constructor must driver, library, template review
KB-CPP-044 Kconfig values are read in one header must driver, template checked
KB-CPP-045 Destructive chip operations need explicit input must driver, library, template review
KB-CPP-046 Each driver has its own Error enum and a trivially copyable Result type must driver, template planned
KB-CPP-047 Driver error codes 0 to 9 are fixed; chip-specific codes start at 16 must driver, template planned
KB-CPP-048 Every chip-specific error code is returned somewhere must driver, template planned
KB-CPP-049 kb::Status values are fixed and only grow must library planned
KB-CPP-050 A failed bus transfer always reaches the caller must driver, template checked
KB-CPP-051 Above the drivers, one error type per layer and no vendor error types must library, hal, firmware planned
KB-CPP-052 Error mapping follows the fixed tables must library checked
KB-CPP-053 A mapping switch lists every enumerator and ends with default must driver, library, hal, template checked
KB-CPP-054 Code branches on the status, never on its detail must library, hal, firmware planned
KB-CPP-055 Never log an error and return Ok must library, hal, firmware review
KB-CPP-056 Error handling separates recoverable from fatal failures and keeps context guide library, hal, firmware none
KB-CPP-057 Constructors are noexcept, do no I/O and cannot fail must driver, library, template checked
KB-CPP-058 The start-up runs the fixed sequence and leaves nothing half-initialised must driver, template checked
KB-CPP-059 EnsureInitialized is the one start-up entry point, and no call starts as a side effect must driver, library, template checked
KB-CPP-060 Deinitialize leaves the chip in its documented safe state must driver, template checked
KB-CPP-061 Handler files and classes follow the handler naming must library planned
KB-CPP-062 A handler keeps its driver in place and rebuilds it cleanly on a failed start must library checked
KB-CPP-063 Every public handler method holds the handler's mutex for its whole duration must library planned
KB-CPP-064 Locks follow the fixed order and are held for one call only must library, hal review
KB-CPP-065 Handlers lend their driver only through VisitDriver must library checked
KB-CPP-066 The bus adapter implements the driver's port with Base calls only must library review
KB-CPP-067 Every handler reports diagnostics with the common header first must library checked
KB-CPP-068 Channel wrappers live in a fixed array created at start-up must library review
KB-CPP-069 Each Base interface keeps its error list and a ToStatus mapping must library planned
KB-CPP-070 Base interfaces start idempotently and report missing features as Unsupported must library checked
KB-CPP-071 Base interfaces expose operations through non-virtual public functions should library planned
KB-CPP-072 Every overriding function says override must library, hal, firmware checked
KB-CPP-073 Drivers are never stored type-erased as void pointers should library, hal, firmware review
KB-CPP-074 Dispatch is chosen by measurement and changed incrementally guide library, hal, firmware none
KB-CPP-075 RTOS objects are statically allocated must library, hal, firmware planned
KB-CPP-076 Above the bind, threads, locks and delays go through kb::rtos only must library, hal, firmware planned
KB-CPP-077 Code above kb::rtos builds and runs on every RTOS backend must library planned
KB-CPP-078 The only clock above the bind is kb::MonotonicUs must library, hal, firmware planned
KB-CPP-079 Durations are unsigned integers with a unit, and deadlines compare by subtraction must driver, library, hal, firmware, template planned
KB-CPP-080 Delays never return early must library checked
KB-CPP-081 Ticks are converted from milliseconds, never written as raw counts must library, hal, firmware planned
KB-CPP-082 Long busy-waits stay off normal task priorities should library, hal, firmware review
KB-CPP-083 Fixed-rate work uses a periodic timer or a drift-corrected loop must library, hal, firmware review
KB-CPP-084 Interrupt handlers never block must driver, library, hal, firmware planned
KB-CPP-085 Data shared between tasks has exactly one guard must library, hal, firmware review
KB-CPP-086 Memory-mapped registers are accessed through volatile, only in the MCU port must library, hal review
KB-CPP-087 Interrupt handlers keep their stack small should driver, library, hal, firmware review
KB-CPP-088 Stack use is bounded, measured and within budget must driver, library, hal, firmware (high level and above) checked
KB-CPP-089 Task stacks, priorities and core affinity are named in one header must firmware planned
KB-CPP-090 Applications never put the CPU to sleep themselves should firmware review
KB-CPP-091 Managers live in static storage owned by the board facade must hal planned
KB-CPP-092 Managers are thread-safe and report failure state consistently must hal checked
KB-CPP-093 Diagnostics are collected through one facade call into a sink must hal checked
KB-CPP-094 The platform bind uses fixed verbs and fixed slots must hal checked
KB-CPP-096 Borrowed references never outlive their owner must library, hal, firmware checked
KB-CPP-097 Scoped resources are released by RAII guards should driver, library, hal, firmware, template review
KB-CPP-098 Constants are constexpr, not macros should driver, library, hal, firmware, template checked
KB-CPP-099 Const by default should driver, library, hal, firmware, template checked
KB-CPP-100 Large objects are passed by const reference, and moved when ownership moves should driver, library, hal, firmware, template checked
KB-CPP-101 Static initialisation never depends on translation-unit order must library, hal, firmware checked
KB-CPP-102 Members are initialised in declaration order must driver, library, hal, firmware, template checked
KB-CPP-103 Fixed-width integer types where size matters should driver, library, hal, firmware, template review
KB-CPP-104 Integer arithmetic does not overflow or narrow silently must driver, library, hal, firmware, template checked
KB-CPP-105 Bit operations use unsigned operands and shifts stay within the width must driver, library, hal, firmware, template checked
KB-CPP-106 Register fields and wire bytes are packed with masks, shifts and explicit byte order must driver, library, hal, template planned
KB-CPP-107 Register maps are written as tables guide driver, template none
KB-CPP-108 Parsers of external input check length and type before use must driver, library, hal, firmware, template checked
KB-CPP-110 At the safety level, code follows the MISRA subset in the compliance matrix must driver, library, hal, firmware (safety level and above) checked
KB-CPP-111 Comments explain why, and datasheet references are exact should all review
KB-CPP-112 No commented-out code, untracked TODOs, author banners or tool attribution must all planned
KB-CPP-113 Class members are grouped by access guide driver, library, hal, firmware, template none
KB-CPP-114 Slow start-up steps are opt-in or visible guide library, hal, firmware none
KB-CPP-115 Functions stay within the complexity, length and parameter limits of their level must driver, library, hal, firmware, template checked
KB-CPP-116 A reply a stuck or floating line can produce is never data must driver, template planned
KB-CPP-117 The identity check is one a dead or looped bus cannot pass must driver, template checked
KB-CPP-118 After a failed transfer the chip's protocol state is restored first must driver, template planned
KB-CPP-119 Clear-on-read and write-1-to-clear flags collect in one driver-owned latch must driver, template review
KB-CPP-120 A setter updates the driver's copy only after the chip accepted the change must driver, template checked
KB-CPP-121 A setter changes only what it names; state-gated changes are refused outside their state must driver, template review
KB-CPP-122 Control and output registers are written whole from the driver's copy must driver, template review
KB-CPP-123 The bus requirements are constexpr in the bus interface header must driver, template checked
KB-CPP-124 Start-up waits for the chip's own ready indication, bounded by a Config deadline must driver, template planned
KB-CPP-125 The chip variant is confirmed before any variant-specific write must driver, template review
KB-CPP-126 Values are checked against the operating range and never silently clamped must driver, template planned
KB-CPP-127 A state that is not a measurement is an error, never a number must driver, template review
KB-CPP-128 A conversion that depends on another setting uses the chip's actual setting must driver, template review
KB-CPP-129 Every driver offers single-shot raw access and the last raw reply must driver, template checked
KB-CPP-130 An I2C driver handles NACK-by-design, sends no empty probe, and uses repeated START must driver, template planned
KB-CPP-131 Load-dependent diagnostics run only on channels Config declares as loaded must driver, template review

KB-CPP-001: C++20, no compiler extensions

MUST · driver, library, hal, firmware, template · since 1.0

Code is written in ISO C++20 and builds with CMAKE_CXX_STANDARD 20, CMAKE_CXX_STANDARD_REQUIRED ON and CMAKE_CXX_EXTENSIONS OFF. Features beyond C++20 are not used.

Why: One language level across the stack lets any driver sit under any library. C++20 gives concepts and constexpr enough for zero-cost ports without the toolchain lag of C++23 on vendor compilers. Which C++20 features are used, and under which rules, is the C++20 profile (KB-CPP20-001 to 058).

Verified by:

  • compiler-warnings/-Wpedantic (implemented): the build is warning-free with the named flag and -Werror
  • forbidden-patterns/cmake-cxx-standard (implemented): a source scan for a construct the handbook bans; the parameter names the pattern set
  • cpp20-profile/cmake-extensions (implemented): a source check of the C++20 profile (rules/cpp20.yml); the parameter names it: forbidden-features (no coroutines, modules, range views, <format>, char8_t, C++23 features, feature-test macros, [[fallthrough]], and in drivers no <=>, <source_location>, variant, any, function or [[no_unique_address]]), cmake-extensions (every CMakeLists.txt that builds a target sets CMAKE_CXX_EXTENSIONS OFF, itself or in a parent directory), nodiscard-error (Error enumerations and Result types are [[nodiscard]]), inline-requires (no requires-expression in an if constexpr condition), kconfig-leaf (no header includes the Kconfig header)
  • strict-dialect (implemented): every public header, and through the driver header its src/*.ipp, compiles as ISO C++20 (-std=c++20 -pedantic-errors, extensions off) with each compiler the repository ships for: host GCC and Clang, Arm GCC in the cross-build, and the ESP-IDF toolchain through a header self-check built at -std=c++20 inside the ESP-IDF build, whose own default dialect is newer

See also: ADR-0010; MISRA C++:2023 Rule 4.1.1 (the language standard is fixed)

Explained in: standards/cpp20-profile.md

KB-CPP-002: No exceptions and no RTTI

MUST · driver, library, hal, firmware, template · since 1.0

Code does not throw, catch or use typeid or dynamic_cast. Every target, including the exported library target, compiles with -fno-exceptions -fno-rtti.

Why: Exceptions and RTTI cost flash and RAM, are disabled on most embedded toolchains, and hide control flow that a safety review has to see. Errors travel as values (KB-CPP-004).

Verified by:

  • exceptions-rtti-off (planned): the exported library target compiles with -fno-exceptions -fno-rtti, not only the tests
  • forbidden-patterns/exceptions-rtti (implemented): a source scan for a construct the handbook bans; the parameter names the pattern set
  • clang-tidy/cert-err58-cpp (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database

See also: MISRA C++:2023 Rule 18.1.1 (no exceptions in our profile); C++ Core Guidelines E.6

KB-CPP-003: No heap in drivers; no heap after start-up anywhere

MUST · driver, library, hal, firmware, template · since 1.0

Driver code never allocates from the heap. In libraries, HALs and firmware, dynamic allocation happens only during start-up, before the scheduler runs; after that no code calls new, malloc or anything that does.

Why: Heap fragmentation and allocation failure after start-up are failure modes that cannot be tested away. Fixed memory makes the worst case the normal case.

Verified by:

  • no-heap-link (planned): a test binary that links the library with operator new, malloc and free removed builds and runs
  • forbidden-patterns/heap (implemented): a source scan for a construct the handbook bans; the parameter names the pattern set
  • clang-tidy/cppcoreguidelines-no-malloc (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • clang-tidy/cppcoreguidelines-owning-memory (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database

See also: ADR-0004; MISRA C++:2023 Rule 21.6.1 (dynamic memory should not be used); NASA/JPL Power of Ten Rule 3; SEI CERT C++ MEM51-CPP

KB-CPP-004: Errors are values, and every result is used

MUST · driver, library, hal, firmware, template · since 1.0

A function that can fail returns <chip>::Result<T> (drivers) or kb::Result<T> / kb::Status (above the drivers), marked [[nodiscard]]. A caller never discards a result; each layer boundary maps errors once.

Why: A bus error that is dropped turns into a stale reading. Typed results make the failure visible at every call and keep the original code for diagnostics.

Verified by:

  • compiler-warnings/-Wunused-result (implemented): the build is warning-free with the named flag and -Werror
  • clang-tidy/bugprone-unused-return-value (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • compile-fail-tests (implemented): a misuse of the public API is a compile error, proved by a test that must fail to compile

See also: ADR-0001; MISRA C++:2023 Rule 0.1.2 (the value returned by a function shall be used); SEI CERT C ERR33-C

Explained in: standards/errors.md

KB-CPP-005: Format with the org clang-format configuration

MUST · all · since 1.0

Every C and C++ file is formatted with the handbook's config/.clang-format (LLVM base, 2-space indent, 100 columns). Formatting is never argued in review; the tool decides.

Verified by:

  • clang-format (implemented): clang-format with config/.clang-format; any difference fails

Explained in: standards/naming-and-style.md

KB-CPP-006: Names follow the org naming scheme

MUST · all · since 1.0

Types and public functions are PascalCase, private member functions camelBack, variables snake_case, private members snake_case_, constants and enumerators kPascalCase, namespaces lower_case, macros UPPER_SNAKE, exactly as config/.clang-tidy encodes it.

Verified by:

  • clang-tidy/readability-identifier-naming (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database

See also: ADR-0008

Explained in: standards/naming-and-style.md

KB-CPP-007: No reinterpret_cast or C-style casts outside the port layer

MUST · driver, library, template · since 1.0

Driver and library code does not use reinterpret_cast or C-style casts. Register access that needs them lives in the MCU port, behind a function whose comment names the datasheet register.

Verified by:

  • clang-tidy/cppcoreguidelines-pro-type-reinterpret-cast (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • clang-tidy/cppcoreguidelines-pro-type-cstyle-cast (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database

See also: MISRA C++:2023 Rule 8.2.5; C++ Core Guidelines Type.1

KB-CPP-008: Static analysis is clean, and every suppression is a recorded deviation

MUST · driver, library, hal, firmware, template · since 1.0

clang-tidy and cppcheck report nothing. A finding on correct code is suppressed on its line with NOLINT(<check>) or cppcheck-suppress <id> and a reason; at the high and safety levels each suppression also has a deviation record (see Deviations).

Verified by:

  • clang-tidy/all (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • cppcheck/all (implemented): cppcheck in strict mode; the parameter names the cppcheck message id
  • review: Each new NOLINT or cppcheck-suppress names the check and says why the code is correct.

See also: IEC 62304:2006+A1:2015 5.5.3 (software unit acceptance criteria)

Explained in: deviations.md

KB-CPP-009: Register frames have their layout asserted

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, library, hal (high level and above) · since 1.0 · enforced from 2027-03-01

A struct or union that mirrors a hardware register or a wire frame has static_asserts on its size and on the offset of every field, and states its byte order.

Why: Padding and byte order differ between compilers and targets; a silent layout change reads the wrong register.

Verified by:

  • register-layout-asserts (planned): every register or wire frame struct has static_assert on its size and field offsets

See also: SEI CERT C EXP42-C

KB-CPP-010: Data shared with an interrupt is atomic or explicitly guarded

MUST · driver, library, hal, firmware · since 1.0

A variable written in an interrupt handler and read elsewhere (or the reverse) is a lock-free std::atomic or is accessed only inside a critical section, and the function that runs in interrupt context says so in its documentation. volatile is for memory-mapped registers only, never for synchronisation.

Verified by:

  • review: Every variable shared with an ISR is atomic or guarded, and the ISR-context function is documented as such.

See also: SEI CERT C SIG31-C; C++ Core Guidelines CP.8

KB-CPP-011: Driver code includes only its own headers and the allowed standard headers

MUST · driver, template · since 1.0

Files in a driver's inc/ and src/ include only the driver's own headers and the standard headers listed on the Layers page (such as <cstdint>, <array>, <span>, <optional> and <bit>). They never include kb-core, another Kokeb Labs repository, an SDK, RTOS or vendor header, or <iostream>, <cstdio>, <string>, <functional>, <memory>, <vector>, <map>, <thread> or <mutex>.

Why: A driver that includes nothing but its own code and the target library subset (ADR-0017) builds on any MCU and in any framework. The host build without SDK include paths already rejects SDK headers.

Verified by:

  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang
  • include-allowlist/driver (implemented): a script over the include graph that fails on a header outside the allowed set for the directory; the parameter names the table (driver, hosted, kb-core, handlers, hal-boundary)

See also: ADR-0012; ADR-0014

Explained in: standards/layers.md

KB-CPP-012: Target code uses only the target library subset and C++20 the pinned compilers share

MUST · driver, library, hal, firmware, template · since 1.0

Code that runs on a target includes only the standard headers ADR-0017 allows for its part (no allocating, throwing or OS-dependent header such as <string>, <vector>, <memory>, <functional>, <iostream> or <thread>) and uses only C++20 features both the pinned ESP-IDF GCC and the CI clang support. Host-only test code is exempt.

Why: Hosted-only headers pull in allocation, locale and threading support that a microcontroller build either lacks or pays for in flash.

Verified by:

  • include-allowlist/target (implemented): a script over the include graph that fails on a header outside the allowed set for the directory; the parameter names the table (driver, hosted, kb-core, handlers, hal-boundary)
  • cross-build/esp-idf (implemented): the code compiles warning-free for the named target (arm-none-eabi Cortex-M cores, esp-idf, riscv32)

See also: ADR-0017; ADR-0010

KB-CPP-013: Each kb-core part includes only what its layer table allows

Proposed

Warns until 2027-03-01, then fails CI.

MUST · library · since 1.0 · enforced from 2027-03-01

Each kb-core part follows its include table on the Layers page: utils/ includes no RTOS, SDK or Base* header, interfaces/base/ never includes mcu/ or an SDK header, a base/ header includes nothing that is missing on any MCU family, and kb/utils/Status.h depends on nothing. Drivers never include Status.h.

Verified by:

  • include-allowlist/kb-core (planned): a script over the include graph that fails on a header outside the allowed set for the directory; the parameter names the table (driver, hosted, kb-core, handlers, hal-boundary)

See also: ADR-0013; ADR-0014

Explained in: standards/layers.md

KB-CPP-014: Handlers include only their driver, Base headers and kb-core utilities

Proposed

Warns until 2027-03-01, then fails CI.

MUST · library · since 1.0 · enforced from 2027-03-01

A handler includes only its driver's umbrella header, Base*.h, kb/rtos, kb/utils and kb/handlers/common. It never includes mcu/, an SDK, a HAL, product code or another handler.

Why: A handler that cannot see another handler cannot call it while holding its own locks.

Verified by:

  • include-allowlist/handlers (planned): a script over the include graph that fails on a header outside the allowed set for the directory; the parameter names the table (driver, hosted, kb-core, handlers, hal-boundary)

Explained in: standards/layers.md

KB-CPP-015: HAL and product code reach hardware only through their bind and handlers

Proposed

Warns until 2027-03-01, then fails CI.

MUST · hal, firmware · since 1.0 · enforced from 2027-03-01

Outside bsp_bind/, HAL code never includes an SDK, esp_*, FreeRTOS, mcu/ or driver header, and managers reach chips only through a handler's typed API or VisitDriver(); the bind's interface header includes only Base* and standard headers. Outside platform/, product code never includes handlers, drivers, Base*, mcu/ or raw FreeRTOS headers.

Verified by:

  • include-allowlist/hal-boundary (planned): a script over the include graph that fails on a header outside the allowed set for the directory; the parameter names the table (driver, hosted, kb-core, handlers, hal-boundary)

See also: ADR-0005

Explained in: standards/hal.md

KB-CPP-016: Shared code never tests platform, board or product macros

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, library, template · since 1.0 · enforced from 2027-03-01

Drivers, kb-core outside interfaces/mcu/ and the RTOS backends, and kb-hal-common never test ESP_PLATFORM, STM32*, __ZEPHYR__ or a board or product macro. Variant differences inside one MCU family use the vendor's capability macros (SOC_*_SUPPORTED, HAL_*_MODULE_ENABLED) only inside mcu/<family>/.

Why: Each #ifdef on a platform is a build nobody tests on the other platforms. Chip, MCU and product code each have one place.

Verified by:

  • forbidden-patterns/platform-macros (planned): a source scan for a construct the handbook bans; the parameter names the pattern set

See also: ADR-0014; NASA/JPL Power of Ten Rule 8 (limited use of the preprocessor)

Explained in: standards/layers.md

KB-CPP-017: An MCU family header fails to compile outside its family

Proposed

Warns until 2027-03-01, then fails CI.

MUST · library · since 1.0 · enforced from 2027-03-01

Every header in interfaces/mcu/<family>/ begins with a check that stops the build with #error unless KB_MCU_<FAMILY> is defined.

Verified by:

  • mcu-header-guards (planned): every header under interfaces/mcu/<family>/ starts with an #error guard on KB_MCU_<FAMILY>

Explained in: standards/layers.md

KB-CPP-018: Includes are quoted from the include root and never climb with ../

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01

Project headers are included in quotes from their include root ("kb/utils/Status.h", "<chip>.hpp"), never with angle brackets and never with a relative path that climbs out of the directory ("../"). Each kb-core part has one include root; a driver has a flat inc/.

Verified by:

  • forbidden-patterns/include-style (planned): a source scan for a construct the handbook bans; the parameter names the pattern set

See also: ADR-0008

Explained in: standards/naming-and-style.md

KB-CPP-019: Every header has an #ifndef include guard named after its file; no #pragma

Proposed

Warns until 2027-03-01, then fails CI. Owner decision 2026-11-08: include guards replace #pragma once (which this rule required until then). python checks/source_checks.py guard --repo . <path> prints the guard a header needs.

MUST · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01

Every header is wrapped in #ifndef GUARD / #define GUARD at the top and #endif at the very end; only comments may come before the guard. The guard is <NAME>_<FILE_STEM>_<EXT> in upper case: NAME is the repository's name (the chip for a driver, the CMake package for a library), FILE_STEM the file name without its extension in snake case, EXT its extension, and NAME is not repeated when the stem already starts with it: ADS7952_TYPES_HPP for inc/ads7952_types.hpp, MAX22200_SPI_INTERFACE_HPP, ADS7952_HPP for inc/ads7952.hpp, ADS7952_MOCK_ADS7952_HPP for tests/mock_ads7952.hpp; a configured <name>_version.h.in guards as the .h it becomes. A guard never starts with an underscore and never holds a double underscore (reserved identifiers). No code uses #pragma once, any other #pragma or _Pragma: compiler options live in the build.

Why: #pragma once is a compiler extension whose meaning depends on how the compiler identifies a file (links, copies, network mounts), and MISRA C++:2023 requires a standard include guard. A name derived from the file cannot collide with another repository's header, and a script can check it.

Verified by:

  • include-guards (implemented): every header in inc/, src/, tests/ and examples/ has an #ifndef/#define/#endif guard that wraps the whole file and is not a reserved name; in inc/ and src/ it is the KB-CPP-019 name; no #pragma or _Pragma anywhere in that code; guard names are unique

See also: MISRA C++:2023 Rule 19.2.1; MISRA C++:2023 Rule 19.6.1; MISRA C++:2023 Rule 5.10.1 (reserved identifiers)

Explained in: standards/naming-and-style.md

KB-CPP-020: Includes are grouped own header, standard, other repositories, this repository

SHOULD · driver, library, hal, firmware, template · since 1.0

A file includes its own header first, then standard headers, then headers from other repositories, then headers from this repository, with a blank line between groups.

Why: Including its own header first proves the header compiles on its own. The org clang-format keeps IncludeBlocks: Preserve, so the order is not enforced by the formatter.

Verified by:

  • review: Include groups are in the order own header, standard, other repositories, this repository.

Explained in: standards/naming-and-style.md

KB-CPP-021: Every header includes what it uses and compiles on its own

Proposed

Warns until 2027-03-01, then fails CI. clang-tidy misc-include-cleaner could add to this once config/.clang-tidy enables it.

MUST · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01

A header includes every header it uses and compiles as the first include of an otherwise empty translation unit. It does not rely on what its includer happened to include first.

Verified by:

  • header-self-contained (implemented): every public header compiles on its own as the first include of a translation unit

See also: C++ Core Guidelines SF.11

KB-CPP-022: Drivers carry no organisation brand

MUST · driver, template · since 1.0

No name in a driver carries an organisation prefix: not kb_, kb::, KB_, hf_ or any other, in its namespace, types, macros, CMake target and options, Kconfig symbols or file names. The prefix table on the naming page says which prefix each kind of repository uses.

Why: A driver is the part most likely to be used alone or forked; a brand in its symbols forces a fork to keep it or break its users. Today only the template's self-test bans foreign prefixes.

Verified by:

  • forbidden-patterns/org-prefix (planned): a source scan for a construct the handbook bans; the parameter names the pattern set
  • review: The driver adds no name with an organisation prefix.

See also: ADR-0012

Explained in: standards/naming-and-style.md

KB-CPP-023: Driver names derive from the chip

MUST · driver, template · since 1.0

A driver for chip <chip> lives in namespace <chip>, its class is <chip>::<CHIP> (the part number in capitals, never Device or Driver), its target is <chip>::<chip>, its macros start <CHIP>_ and its Kconfig symbols start CONFIG_<CHIP>_.

Verified by:

  • driver-names (planned): the driver's namespace, class, CMake target, macro prefix and Kconfig prefix all derive from the chip name in the repository name (driver-<chip>)
  • review: Namespace, class, target, macro and Kconfig names follow the chip name.

See also: ADR-0012

Explained in: standards/driver.md

KB-CPP-024: A driver declares nothing at global scope

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

Everything a driver declares, including GetDriverVersion() and any using declaration, is inside namespace <chip> or <chip>::detail.

Verified by:

  • ast-rules/global-scope (planned): a clang-query or libclang script over the compile database for one structural rule; the parameter names it (global-scope, driver-virtual, handler-names, handler-lock-guard, base-nvi, base-tostatus, detail-branch, deadline-compare, isr-calls, bitfield-frames)

See also: ADR-0008

KB-CPP-025: Namespaces follow the layer they belong to

MUST · driver, library, hal, firmware, template · since 1.0

Drivers use <chip> and <chip>::detail; kb-core uses kb or kb::<area>; the shared HAL uses kb::hal; board code uses <board> and <board>::bsp; products use <board>::app. New kb-core API is C++ in kb; the legacy os_* functions and kb_*_t types keep their names, and no new names are added in those forms.

Verified by:

  • clang-tidy/readability-identifier-naming (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • review: New code is in its layer's namespace and adds no os_* function or kb_*_t type.

See also: ADR-0008; ADR-0013

Explained in: standards/naming-and-style.md

KB-CPP-026: No using-directives in headers; anonymous namespaces only in source files

Proposed

Warns until 2027-03-01, then fails CI. config/.clang-tidy must enable google-global-names-in-headers and google-build-namespaces first.

MUST · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01

A header never contains using namespace. Anonymous namespaces appear only in .cpp files, for helpers local to that file.

Verified by:

  • clang-tidy/google-global-names-in-headers (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • clang-tidy/google-build-namespaces (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database

See also: C++ Core Guidelines SF.7; C++ Core Guidelines SF.21

Explained in: standards/naming-and-style.md

KB-CPP-027: Macros carry their repository's prefix and never leak generic names

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01

Every macro is UPPER_CASE and starts with its repository's prefix: <CHIP>_ in a driver, KB_ in kb-core, KB_HAL_ in kb-hal-common, CONFIG_ for Kconfig. Public headers define no generic macro such as MIN, MAX or ARRAY_SIZE.

Why: The macro namespace is global across every library linked into a firmware image; clang-tidy checks the case but not the prefix.

Verified by:

  • forbidden-patterns/macro-prefix (planned): a source scan for a construct the handbook bans; the parameter names the pattern set

See also: ADR-0008; ADR-0012

Explained in: standards/naming-and-style.md

KB-CPP-028: No m_, s_, g_ or p_ prefixes on names

Proposed

Warns until 2027-03-01, then fails CI.

SHOULD · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01

Names carry no Hungarian-style prefix (m_, s_, g_, p_). Private and protected data members, static ones included, use the trailing underscore form snake_case_; pointers get a descriptive name.

Why: clang-tidy accepts m_count_ as snake_case, so a second scheme can creep in unless a check rejects the prefixes.

Verified by:

  • forbidden-patterns/name-prefixes (planned): a source scan for a construct the handbook bans; the parameter names the pattern set

See also: ADR-0008

KB-CPP-029: Function names say whether they touch the chip

SHOULD · driver, library, hal, template · since 1.0

Read* performs I/O; Get* returns a cached value without I/O; Set* and Write* change the chip; Is* and Has* return bool without I/O.

Verified by:

  • review: Read/Get/Set/Write/Is/Has names match whether the call does I/O.

See also: ADR-0008

Explained in: standards/naming-and-style.md

KB-CPP-030: Quantities carry their unit in the name

MUST · driver, library, hal, firmware, template · since 1.0

Every identifier holding a physical quantity ends in its unit in the identifier's case (timeout_ms, ReadVoltageMv, kResetDelayUs), from the naming page's unit table; _mA, MilliAmps and Unit enums are not used. Prefer integers in SI-derived units; a float in a public API says its unit.

Why: A missing or ambiguous unit is a silent factor-of-1000 bug.

Verified by:

  • forbidden-patterns/unit-spellings (planned): a source scan for a construct the handbook bans; the parameter names the pattern set
  • review: Every new quantity has a unit suffix from the naming table.

See also: ADR-0008

Explained in: standards/naming-and-style.md

KB-CPP-031: Names describe what they hold

GUIDE · all · since 1.0

Names are descriptive rather than abbreviated (short loop and template names such as i, n, T and reg are fine), never confusable (l1 and I1), and keep acronyms in one form within a file. Boolean parameters read as a condition (is_enabled, has_crc); limits and defaults read kMax... and kDefault....

See also: ADR-0008

KB-CPP-032: One CRTP port base per bus, and the driver is constrained by its port concept

MUST · driver, template · since 1.0

A driver's port base is <chip>::{Spi,I2c,Uart,Adc}Interface<Derived>, one per bus, non-copyable with a protected constructor, and the driver template is constrained by the concept <chip>::{Spi,I2c,Uart,Adc}Port, so a port that lacks a required hook fails to compile where it is used.

Verified by:

  • compile-fail-tests (implemented): a misuse of the public API is a compile error, proved by a test that must fail to compile
  • review: The port base and concept follow the bus naming and the driver template is constrained by the concept.

See also: ADR-0003

Explained in: standards/driver.md

KB-CPP-033: No virtual functions in a driver or its port

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

Neither the driver class nor its port base declares a virtual function. Dispatch to the port is static, through CRTP.

Why: Virtual dispatch costs a vtable per port and stops the compiler inlining register access.

Verified by:

  • ast-rules/driver-virtual (planned): a clang-query or libclang script over the compile database for one structural rule; the parameter names it (global-scope, driver-virtual, handler-names, handler-lock-guard, base-nvi, base-tostatus, detail-branch, deadline-compare, isr-calls, bitfield-frames)

See also: ADR-0003

Explained in: standards/driver.md

KB-CPP-034: The port base never declares a required hook

MUST · driver, template · since 1.0

The port base may offer helpers but never declares or forwards a hook that the port concept requires; only the derived port defines it.

Why: A base that forwards a hook to the derived class turns a missing override into infinite recursion.

Verified by:

  • review: The port base declares none of the hooks named in the port concept.

See also: ADR-0003

KB-CPP-035: Port hooks are PascalCase, noexcept and return bool, with the bus's fixed signatures

MUST · driver, template · since 1.0

Every port hook is PascalCase, noexcept and returns bool (never void), and each bus uses the hook signatures fixed on the driver page (SPI Transfer; I2C Write, WriteRead, optional Read; UART Write, Read, FlushInput; ADC ReadVoltageMv), plus EnsureInitialized.

Why: A void hook cannot report a bus failure, so the driver returns a stale value as if it were fresh.

Verified by:

  • compile-fail-tests (implemented): a misuse of the public API is a compile error, proved by a test that must fail to compile
  • review: Every hook is noexcept, returns bool and matches the bus signature on the driver page.

See also: ADR-0003

Explained in: standards/driver.md

KB-CPP-036: Optional hooks are detected with requires, in one place

MUST · driver, template · since 1.0

Whether a port has an optional hook is tested with a C++20 requires expression in one place in <chip>::detail, never with void_t and never through the port base.

Verified by:

  • forbidden-patterns/void-t (planned): a source scan for a construct the handbook bans; the parameter names the pattern set
  • review: Optional-hook detection is one set of requires expressions in detail.

See also: ADR-0003; ADR-0010

KB-CPP-037: A missing hook fails to compile or falls back in a documented way, never silently

MUST · driver, template · since 1.0

A port without DelayUs/DelayMs fails to compile at the first call that needs a delay; a chip with timing requirements never skips a wait. A missing GPIO hook makes the call return Unsupported or a documented fallback, a missing Log hook means no output, and the driver itself never formats text.

Why: One reviewed driver skipped required delays when its port had no delay hook.

Verified by:

  • compile-fail-tests (implemented): a misuse of the public API is a compile error, proved by a test that must fail to compile
  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang

See also: ADR-0003

Explained in: standards/driver.md

KB-CPP-038: Driver pins are logical; the port maps them to the board

MUST · driver, template · since 1.0

A driver names pins by function (CtrlPin) and level by meaning (GpioSignal::ACTIVE is asserted); the port maps them to physical pins and polarity. The port's EnsureInitialized() brings the bus up on first use and is idempotent. Status bits follow the same rule: the API exposes them by meaning (healthy or fault, moved or stuck), never by raw polarity, and a bit whose meaning is inverted in the datasheet has a callout in the documentation.

Verified by:

  • review: The driver uses logical pins and levels only; polarity is resolved in the port. Status accessors are named by meaning, and an inverted bit is called out.

See also: ADR-0003

Explained in: standards/driver.md

KB-CPP-039: Drivers use no std::function or printf-family output; callbacks are a function pointer

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

Driver code does not use std::function, std::string or any printf-family function. A callback is a function pointer plus a void* context.

Why: std::function may allocate and printf pulls in a formatter of several kilobytes; a driver that never formats text costs nothing on a board with no console.

Verified by:

  • forbidden-patterns/driver-banned (planned): a source scan for a construct the handbook bans; the parameter names the pattern set

See also: ADR-0004

Explained in: standards/driver.md

KB-CPP-040: Drivers and kb-core utilities hold no mutable global or static state

MUST · driver, library, template · since 1.0

Driver code and kb-core's utils/ hold no mutable variable at namespace scope and no mutable static variable, function-local or member. State lives in the driver object.

Why: Two instances of a driver on two buses must not share hidden state.

Verified by:

  • clang-tidy/cppcoreguidelines-avoid-non-const-global-variables (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • forbidden-patterns/static-mutable (planned): a source scan for a construct the handbook bans; the parameter names the pattern set

See also: ADR-0004; C++ Core Guidelines I.2

KB-CPP-041: A driver waits only through the port's delay hooks

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

A driver never sleeps, spins on a clock or calls vTaskDelay, usleep or std::this_thread; every wait goes through the port's DelayUs/DelayMs hooks.

Verified by:

  • forbidden-patterns/driver-sleep (planned): a source scan for a construct the handbook bans; the parameter names the pattern set

Explained in: standards/driver.md

KB-CPP-042: Drivers declare no friends

SHOULD · driver, template · since 1.0

A driver class declares no friend; if a handler needs access, the driver widens its public API instead.

Verified by:

  • review: The driver adds no friend declaration.

KB-CPP-043: Run-time configuration is one Config struct passed to the constructor

MUST · driver, library, template · since 1.0

A driver's run-time settings are one Config struct with unit-suffixed fields and datasheet defaults, passed to the constructor (its last parameter, defaulted) and changed with ApplyConfig(). Capacity limits are constexpr constants a board can size, and buffers are members sized by those limits or a caller's std::span.

Verified by:

  • review: Settings are fields of one Config; buffers are fixed members or caller spans.

See also: ADR-0004; ADR-0021

Explained in: standards/driver.md

KB-CPP-044: Kconfig values are read in one header

MUST · driver, template · since 1.0

CONFIG_<CHIP>_* symbols are read only in inc/<chip>_kconfig.hpp, which turns them into KconfigDefaults(). No other header and no public signature refers to a CONFIG_ symbol.

Verified by:

  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang
  • forbidden-patterns/config-outside-kconfig (planned): a source scan for a construct the handbook bans; the parameter names the pattern set

Explained in: standards/driver.md

KB-CPP-045: Destructive chip operations need explicit input

MUST · driver, library, template · since 1.0

Calls that erase or rewrite a chip permanently (firmware update, OTP write, factory reset) take explicit data or a confirmation argument; no default argument triggers them.

Verified by:

  • review: No destructive call can be reached with default arguments.

KB-CPP-046: Each driver has its own Error enum and a trivially copyable Result type

MUST · driver, template · since 1.0

Each driver defines <chip>::Error and <chip>::Result<T> (with Result<void>), usable without kb-core: [[nodiscard]] structs with value, error, ok() and an explicit bool conversion. T is default-constructible and trivially copyable, and a failed call leaves the value at its default.

Why: A per-driver type keeps drivers independent of kb-core. std::expected is C++23 and not available on the pinned toolchains.

Verified by:

  • result-type-traits (planned): static_asserts that the driver's Result<T> is [[nodiscard]], has ok() and an explicit bool conversion, and that T is default-constructible and trivially copyable
  • review: The driver's Result follows the shape on the errors page.

See also: ADR-0001

Explained in: standards/errors.md

KB-CPP-047: Driver error codes 0 to 9 are fixed; chip-specific codes start at 16

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

Every driver's Error starts with the base set Ok to Unsupported at the fixed values 0 to 9, in the order on the errors page. Chip-specific codes start at 16. When a driver needs one of these chip-specific meanings it uses this name for it: NoDevice (nothing answers; a reply a stuck or floating line produces, KB-CPP-116), Pin (a GpioSet or GpioRead hook failed), NotReady (the chip answered but is not ready, or the value is not a measurement yet, KB-CPP-124 and KB-CPP-127). The base codes keep their meaning in every driver: Bus is a transfer the port reported as failed (a failed probe is Bus, not NoDevice), Timeout a wait that expired, Crc a checksum or tag mismatch, Busy a command the chip refused while busy.

Why: The same value means the same failure in every driver, so a handler maps all of them with one table. Observed on hardware: drivers that reported a pin failure or an absent chip as Bus sent the bench after the wrong fault.

Verified by:

  • error-enum-values/driver (planned): a compiled test asserts the enumerator values of an error enum against the table on the errors page; the parameter names the enum (driver, kb-status)

See also: ADR-0001

Explained in: standards/errors.md

KB-CPP-048: Every chip-specific error code is returned somewhere

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

Each chip-specific Error value (16 and up) is returned by at least one call; a value nothing returns is deleted.

Verified by:

  • unused-error-codes (planned): every chip-specific Error enumerator (16 and up) is returned somewhere in src/ or inc/

See also: ADR-0001

KB-CPP-049: kb::Status values are fixed and only grow

Proposed

Warns until 2027-03-01, then fails CI.

MUST · library · since 1.0 · enforced from 2027-03-01

kb::Status keeps the values Ok = 0 to Unknown = 11 listed on the errors page. A new code is added by changing the page and the header together; no value is ever renumbered or reused.

Verified by:

  • error-enum-values/kb-status (planned): a compiled test asserts the enumerator values of an error enum against the table on the errors page; the parameter names the enum (driver, kb-status)

See also: ADR-0001

Explained in: standards/errors.md

KB-CPP-050: A failed bus transfer always reaches the caller

MUST · driver, template · since 1.0

Every port failure propagates as Bus (or Crc or Timeout when the driver can tell). Returning a stale or zero value after a failed read is a defect.

Why: A dropped bus error turns into a plausible but wrong reading.

Verified by:

  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang
  • review: Each new call path has a host test with a failing port hook.

See also: ADR-0001; SEI CERT C ERR33-C

Explained in: standards/errors.md

KB-CPP-051: Above the drivers, one error type per layer and no vendor error types

MUST · library, hal, firmware · since 1.0

Above the drivers, fallible calls return kb::Status or kb::Result<T>: never a driver's Result, esp_err_t, HAL_StatusTypeDef or bool, and no layer adds a second error enum (ManagerError, HalError, CommError). A sticky error getter may exist but never replaces the call's result.

Verified by:

  • forbidden-patterns/vendor-error-types (planned): a source scan for a construct the handbook bans; the parameter names the pattern set
  • review: No public signature above the drivers returns a driver result, a vendor status or bool for a failure.

See also: ADR-0001

Explained in: standards/errors.md

KB-CPP-052: Error mapping follows the fixed tables

MUST · library · since 1.0

A driver Error maps to kb::Status by the table on the errors page (for example DeviceIdMismatch to NotFound, Crc to Bus), done once by ToStatus() in the handler's adapter header; kb_*_err_t values map by their name pattern. ALREADY_INITIALIZED from an idempotent Initialize counts as success.

Verified by:

  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang
  • review: Each ToStatus follows the mapping table on the errors page.

See also: ADR-0001

Explained in: standards/errors.md

KB-CPP-053: A mapping switch lists every enumerator and ends with default

MUST · driver, library, hal, template · since 1.0

A switch that maps one error enum to another (ToStatus, ToString) names every enumerator and ends with default: break; followed by the fallback the function returns for a value that is no enumerator (MISRA C++ Rule 9.4.2 requires the default for a scoped enumeration). The code builds with -Wswitch-enum, so a new enumerator is still a compiler warning although a default is present. ToString() returns a static string for every value.

Verified by:

  • compiler-warnings/-Wswitch-enum (implemented): the build is warning-free with the named flag and -Werror
  • review: Mapping switches over enums cover every enumerator and end with default.

Explained in: standards/errors.md

KB-CPP-054: Code branches on the status, never on its detail

MUST · library, hal, firmware · since 1.0

Callers decide on kb::Status alone; the detail field is for diagnostics and is never tested in an if or switch. Products map Status and ManagerId to their fault catalogue in one table and never inspect a driver Error or a kb_*_err_t.

Verified by:

  • ast-rules/detail-branch (planned): a clang-query or libclang script over the compile database for one structural rule; the parameter names it (global-scope, driver-virtual, handler-names, handler-lock-guard, base-nvi, base-tostatus, detail-branch, deadline-compare, isr-calls, bitfield-frames)
  • review: No new code branches on a status detail or a lower layer's error code.

See also: ADR-0001

Explained in: standards/errors.md

KB-CPP-055: Never log an error and return Ok

MUST · library, hal, firmware · since 1.0

A function that hits an error returns it. Logging a failure and then reporting success is a defect.

Verified by:

  • review: No error path logs and then returns Ok.

See also: SEI CERT C ERR33-C

Explained in: standards/errors.md

KB-CPP-056: Error handling separates recoverable from fatal failures and keeps context

GUIDE · library, hal, firmware · since 1.0

Decide for each failure whether it is recoverable (retry, report, degrade) or fatal (safe state, reset), and make the choice visible at the call site. Where an error is logged above the drivers, the message carries the context needed to act on it: bus, address, length and status.

KB-CPP-057: Constructors are noexcept, do no I/O and cannot fail

MUST · driver, library, template · since 1.0

Driver and handler constructors are noexcept, touch no hardware, allocate nothing and cannot fail; they store references and defaults. A handler's constructor does not create its driver.

Why: A caller can then create objects in static storage and choose when the bus is first touched.

Verified by:

  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang
  • review: Constructors only store references and defaults.

See also: ADR-0002

Explained in: standards/driver.md

KB-CPP-058: The start-up runs the fixed sequence and leaves nothing half-initialised

MUST · driver, template · since 1.0

The first EnsureInitialized() of a driver validates the stored config, brings the port up with the port's EnsureInitialized, resets the chip (hardware reset if wired, else software), checks the chip ID (or the closest equivalent, documented, if the chip has none), applies the config and only then marks itself initialised. On any failure it stays uninitialised and the next call starts again. It never trusts state from before the host reset: when the chip can keep its configuration across a host reset or an enable cycle, it resets the chip or rewrites every register, and it reads and clears, or reports, every fault latched before the start, so the fault output reflects new faults only.

Why: Observed on hardware, faults latched before a host reset held the fault output after a clean start.

Verified by:

  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang
  • review: The start-up follows the sequence on the driver page, each failure leaves the driver uninitialised, and faults latched before the start are cleared or reported.

See also: ADR-0002; ADR-0021

Explained in: standards/driver.md

KB-CPP-059: EnsureInitialized is the one start-up entry point, and no call starts as a side effect

MUST · driver, library, template · since 1.0

EnsureInitialized() is the only public way to start a driver or handler; there is no public Initialize(). Once started it returns Ok with no I/O. Before it has succeeded, every call that needs the chip returns NotInitialized and sends nothing; no read or write calls EnsureInitialized() or starts the chip.

Verified by:

  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang

See also: ADR-0002; ADR-0021

Explained in: standards/driver.md

KB-CPP-060: Deinitialize leaves the chip in its documented safe state

MUST · driver, template · since 1.0

Deinitialize() puts the chip in the safe state its documentation names and clears the initialised flag; on an uninitialised driver it returns Ok.

Verified by:

  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang
  • review: The safe state is documented and Deinitialize reaches it.

See also: ADR-0002

Explained in: standards/driver.md

KB-CPP-061: Handler files and classes follow the handler naming

Proposed

Warns until 2027-03-01, then fails CI.

MUST · library · since 1.0 · enforced from 2027-03-01

A handler lives in <Chip>Handler.h/.cpp as class kb::<Chip>Handler in namespace kb; its bus adapter is Hal<Bus><Chip>Comm.

Verified by:

  • ast-rules/handler-names (planned): a clang-query or libclang script over the compile database for one structural rule; the parameter names it (global-scope, driver-virtual, handler-names, handler-lock-guard, base-nvi, base-tostatus, detail-branch, deadline-compare, isr-calls, bitfield-frames)

Explained in: standards/handler.md

KB-CPP-062: A handler keeps its driver in place and rebuilds it cleanly on a failed start

MUST · library · since 1.0

A handler stores its driver in a std::optional member, never through new, nothrow new or make_unique, and is neither copyable nor movable. EnsureInitialized() emplaces the driver and runs the driver's EnsureInitialized(); on failure it destroys the driver so the next call retries from scratch.

Verified by:

  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang
  • review: The driver is an optional member and the failure path resets it.

See also: ADR-0002; ADR-0004

Explained in: standards/handler.md

KB-CPP-063: Every public handler method holds the handler's mutex for its whole duration

MUST · library · since 1.0

Each handler owns one kb::RtosMutex, and every public method takes a MutexLockGuard on it before doing anything else and holds it until it returns.

Verified by:

  • ast-rules/handler-lock-guard (planned): a clang-query or libclang script over the compile database for one structural rule; the parameter names it (global-scope, driver-virtual, handler-names, handler-lock-guard, base-nvi, base-tostatus, detail-branch, deadline-compare, isr-calls, bitfield-frames)
  • review: Every new public handler method starts with a MutexLockGuard on the handler mutex.

See also: C++ Core Guidelines CP.20

Explained in: standards/handler.md

KB-CPP-064: Locks follow the fixed order and are held for one call only

MUST · library, hal · since 1.0

Locks are taken in the order manager, handler, bus, and all are released before the call returns. A lock is never held across a long delay, a callback or a call into another handler.

Why: One global order makes deadlock impossible by construction.

Verified by:

  • review: New lock acquisitions follow manager, handler, bus order and no lock is held across a callback.

See also: SEI CERT C++ CON53-CPP; C++ Core Guidelines CP.22

Explained in: standards/threading-and-timing.md

KB-CPP-065: Handlers lend their driver only through VisitDriver

MUST · library · since 1.0

A handler has no public GetDriver() and returns no raw pointer or reference to its driver. VisitDriver(fn) takes the handler's locks, returns NotInitialized without calling fn when uninitialised, and fn must not keep the reference.

Verified by:

  • forbidden-patterns/get-driver (planned): a source scan for a construct the handbook bans; the parameter names the pattern set
  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang
  • review: No VisitDriver callback stores the driver reference.

Explained in: standards/handler.md

KB-CPP-066: The bus adapter implements the driver's port with Base calls only

MUST · library · since 1.0

A handler's adapter derives from the driver's port base and implements each hook with Base* calls, turning a kb_*_err_t failure into false. Its delay hooks call kb::DelayUs/kb::DelayMs and its Log hook forwards to the kb-core logger.

Verified by:

  • review: The adapter's hooks call only Base*, kb::Delay* and the kb-core logger.

See also: ADR-0003

Explained in: standards/handler.md

KB-CPP-067: Every handler reports diagnostics with the common header first

MUST · library · since 1.0

Every handler has GetDiagnostics() returning a struct whose first member is DiagnosticsHeader, updated on every call and copied out under the handler's lock.

Verified by:

  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang
  • review: The diagnostics struct starts with DiagnosticsHeader and is copied under the lock.

Explained in: standards/handler.md

KB-CPP-068: Channel wrappers live in a fixed array created at start-up

MUST · library · since 1.0

Per-channel wrappers a handler hands out live in a fixed array it owns, are created by EnsureInitialized() and forward through the handler's locked API. They are never shared_ptrs and never created on first use.

Verified by:

  • review: Wrappers are array members built in EnsureInitialized.

See also: ADR-0004

Explained in: standards/handler.md

KB-CPP-069: Each Base interface keeps its error list and a ToStatus mapping

Proposed

Warns until 2027-03-01, then fails CI.

MUST · library · since 1.0 · enforced from 2027-03-01

Each Base<Periph>.h defines its kb_<periph>_err_t values with an X-macro list and a ToStatus() that maps every value to kb::Status.

Verified by:

  • ast-rules/base-tostatus (planned): a clang-query or libclang script over the compile database for one structural rule; the parameter names it (global-scope, driver-virtual, handler-names, handler-lock-guard, base-nvi, base-tostatus, detail-branch, deadline-compare, isr-calls, bitfield-frames)

See also: ADR-0001

Explained in: standards/library.md

KB-CPP-070: Base interfaces start idempotently and report missing features as Unsupported

MUST · library · since 1.0

A Base* Initialize() is idempotent and EnsureInitialized() initialises on first use; neither allocates after start-up. An optional capability a port lacks (interrupts, statistics, diagnostics) returns the interface's unsupported code rather than failing silently.

Verified by:

  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang

See also: ADR-0002

Explained in: standards/library.md

KB-CPP-071: Base interfaces expose operations through non-virtual public functions

Proposed

Warns until 2027-03-01, then fails CI.

SHOULD · library · since 1.0 · enforced from 2027-03-01

A Base* class exposes its operations as non-virtual public functions that call protected virtual *Impl() functions; only capability queries (IsPinAvailable, GetMaxPins, SupportsInterrupts) are public virtual. Callers cannot set a raw electrical level.

Why: The public wrapper is one place to check arguments, lock and count, whatever the MCU port does.

Verified by:

  • ast-rules/base-nvi (planned): a clang-query or libclang script over the compile database for one structural rule; the parameter names it (global-scope, driver-virtual, handler-names, handler-lock-guard, base-nvi, base-tostatus, detail-branch, deadline-compare, isr-calls, bitfield-frames)

KB-CPP-072: Every overriding function says override

MUST · library, hal, firmware · since 1.0

A function that overrides a virtual function, including every MCU port's *Impl(), is marked override (or final) and not repeated as virtual.

Verified by:

  • clang-tidy/modernize-use-override (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database

See also: C++ Core Guidelines C.128

KB-CPP-073: Drivers are never stored type-erased as void pointers

SHOULD · library, hal, firmware · since 1.0

A CRTP driver is never stored or passed as void*. Code that needs to treat different drivers alike goes through a Base* interface or a template.

Verified by:

  • review: No driver object is held as void*.

KB-CPP-074: Dispatch is chosen by measurement and changed incrementally

GUIDE · library, hal, firmware · since 1.0

Keep hot paths (tight loops, single call sites above 1 kHz) on templates rather than Base* calls, and move code to a different dispatch only when a measurement shows the cost. Change dispatch step by step: add the new overload or interface, migrate callers, then delete the old one.

See also: C++ Core Guidelines Per.6

KB-CPP-075: RTOS objects are statically allocated

Proposed

Warns until 2027-03-01, then fails CI.

MUST · library, hal, firmware · since 1.0 · enforced from 2027-03-01

The RTOS backends create tasks, queues, mutexes and semaphores with the static-allocation API (xTaskCreateStatic, xSemaphoreCreateMutexStatic), never the heap-allocating variants.

Verified by:

  • forbidden-patterns/rtos-dynamic-create (planned): a source scan for a construct the handbook bans; the parameter names the pattern set

See also: ADR-0004; NASA/JPL Power of Ten Rule 3

KB-CPP-076: Above the bind, threads, locks and delays go through kb::rtos only

Proposed

Warns until 2027-03-01, then fails CI.

MUST · library, hal, firmware · since 1.0 · enforced from 2027-03-01

Above the platform bind, code never calls xTaskCreate, xSemaphoreTake, vTaskDelay or another raw RTOS function, and never uses std::thread or std::mutex. The only mutex is kb::RtosMutex with MutexLockGuard; no other mutex wrapper is written.

Why: The same code then runs on the FreeRTOS, ThreadX and no-RTOS backends.

Verified by:

  • forbidden-patterns/raw-rtos (planned): a source scan for a construct the handbook bans; the parameter names the pattern set

Explained in: standards/threading-and-timing.md

KB-CPP-077: Code above kb::rtos builds and runs on every RTOS backend

Proposed

Warns until 2027-03-01, then fails CI.

MUST · library · since 1.0 · enforced from 2027-03-01

Code that uses kb::rtos works with KB_RTOS=FREERTOS, THREADX and NONE; anything specific to one backend stays in that backend.

Verified by:

  • kb-rtos-matrix (planned): kb-core builds and its host tests pass with KB_RTOS set to FREERTOS (host shim), THREADX and NONE

Explained in: standards/threading-and-timing.md

KB-CPP-078: The only clock above the bind is kb::MonotonicUs

Proposed

Warns until 2027-03-01, then fails CI.

MUST · library, hal, firmware · since 1.0 · enforced from 2027-03-01

Above the bind, time is read only with kb::MonotonicUs() (64-bit, monotonic, safe in an ISR); never esp_timer_get_time, xTaskGetTickCount, HAL_GetTick or std::chrono::steady_clock. Waits that may exceed the tick counter's wrap (about 71 minutes) use it too.

Verified by:

  • forbidden-patterns/raw-clock (planned): a source scan for a construct the handbook bans; the parameter names the pattern set

See also: ADR-0006

Explained in: standards/threading-and-timing.md

KB-CPP-079: Durations are unsigned integers with a unit, and deadlines compare by subtraction

MUST · driver, library, hal, firmware, template · since 1.0

Durations and timestamps are uint32_t or uint64_t with a unit suffix. A deadline is checked by signed subtraction (static_cast<int32_t>(now - deadline) >= 0), never with > on raw values, so it survives wrap-around.

Verified by:

  • ast-rules/deadline-compare (planned): a clang-query or libclang script over the compile database for one structural rule; the parameter names it (global-scope, driver-virtual, handler-names, handler-lock-guard, base-nvi, base-tostatus, detail-branch, deadline-compare, isr-calls, bitfield-frames)
  • review: New deadline checks use signed subtraction.

See also: ADR-0006

Explained in: standards/threading-and-timing.md

KB-CPP-080: Delays never return early

MUST · library · since 1.0

A delay waits at least the time asked for. os_delay_msec rounds up to whole ticks and adds one; kb::DelayUs busy-waits on kb::MonotonicUs() below 1 ms and rounds 1000 us or more up to a millisecond delay; a delay of 0 returns at once or yields and never waits a tick.

Why: A datasheet wait that is one tick short works on the bench and fails in the field.

Verified by:

  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang

See also: ADR-0006

Explained in: standards/threading-and-timing.md

KB-CPP-081: Ticks are converted from milliseconds, never written as raw counts

Proposed

Warns until 2027-03-01, then fails CI.

MUST · library, hal, firmware · since 1.0 · enforced from 2027-03-01

Code that calls the RTOS converts milliseconds with pdMS_TO_TICKS() or the kb::rtos helpers and never passes a raw tick count.

Verified by:

  • forbidden-patterns/raw-ticks (planned): a source scan for a construct the handbook bans; the parameter names the pattern set

See also: ADR-0006

Explained in: standards/threading-and-timing.md

KB-CPP-082: Long busy-waits stay off normal task priorities

SHOULD · library, hal, firmware · since 1.0

Busy-waits longer than about 100 us are avoided in tasks above idle priority; use an RTOS delay or a timer.

Verified by:

  • review: No new busy-wait over 100 us runs above idle priority.

Explained in: standards/threading-and-timing.md

KB-CPP-083: Fixed-rate work uses a periodic timer or a drift-corrected loop

MUST · library, hal, firmware · since 1.0

Work that must run at a fixed rate uses kb::PeriodicTimer or a loop that waits until the next absolute deadline, never a chain of relative delays.

Verified by:

  • review: Periodic work is driven by PeriodicTimer or absolute deadlines.

Explained in: standards/threading-and-timing.md

KB-CPP-084: Interrupt handlers never block

MUST · driver, library, hal, firmware · since 1.0

An interrupt handler never takes a mutex, waits or calls a function that may; it signals a task with OsEventFlags or a SignalSemaphore and returns. A manager or handler method that locks is never called from an ISR.

Verified by:

  • ast-rules/isr-calls (planned): a clang-query or libclang script over the compile database for one structural rule; the parameter names it (global-scope, driver-virtual, handler-names, handler-lock-guard, base-nvi, base-tostatus, detail-branch, deadline-compare, isr-calls, bitfield-frames)
  • review: Every function documented as ISR context calls only ISR-safe functions.

See also: SEI CERT C SIG31-C

Explained in: standards/threading-and-timing.md

KB-CPP-085: Data shared between tasks has exactly one guard

MUST · library, hal, firmware · since 1.0

Data read and written by more than one task is protected by one kb::RtosMutex, passed through an OsQueue, or published with a SeqlockSnapshot. A plain counter or flag may instead be a lock-free std::atomic with its memory order stated.

Verified by:

  • review: Each new piece of cross-task state names its guard.

See also: C++ Core Guidelines CP.2

Explained in: standards/threading-and-timing.md

KB-CPP-086: Memory-mapped registers are accessed through volatile, only in the MCU port

MUST · library, hal · since 1.0

Only MCU port and bind code touches memory-mapped registers, through volatile-qualified accesses wrapped in a function that names the register. Drivers and code above the bind never touch MMIO.

Verified by:

  • review: MMIO access is volatile, inside mcu/ or bsp_bind/, and names its register.

See also: SEI CERT C EXP32-C (never access a volatile object through a non-volatile reference)

KB-CPP-087: Interrupt handlers keep their stack small

SHOULD · driver, library, hal, firmware · since 1.0

An interrupt handler declares no large local buffer and makes no deep or unbounded call chain; anything substantial is deferred to a task.

Verified by:

  • review: New ISR code has no large locals or deep call chains.

KB-CPP-088: Stack use is bounded, measured and within budget

Proposed

Warns until 2027-03-01, then fails CI. config/.clang-tidy must enable misc-no-recursion first.

MUST · driver, library, hal, firmware (high level and above) · since 1.0 · enforced from 2027-03-01

Target code is not recursive, and each task and interrupt stack has a budget that the compiler's stack-usage report (-fstack-usage) shows it stays within.

Why: A stack overflow on a microcontroller corrupts memory silently long before anything faults.

Verified by:

  • stack-usage (planned): the target build with -fstack-usage reports every task entry and ISR within the stack budget in the repository's budget file; unbounded (dynamic) frames fail
  • clang-tidy/misc-no-recursion (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database

See also: NASA/JPL Power of Ten Rule 1 (no recursion)

KB-CPP-089: Task stacks, priorities and core affinity are named in one header

MUST · firmware · since 1.0

A product names every task's stack size, priority and core affinity in one header (<board>::app::kTaskConfig) and creates tasks through kb::rtos with those values, never with literals at the call site.

Verified by:

  • forbidden-patterns/literal-task-config (planned): a source scan for a construct the handbook bans; the parameter names the pattern set
  • review: New tasks take their stack, priority and core from kTaskConfig.

Explained in: standards/product.md

KB-CPP-090: Applications never put the CPU to sleep themselves

SHOULD · firmware · since 1.0

Application code delays through the OS abstraction and never calls a sleep or wait-for-interrupt primitive (esp_light_sleep_start, __WFI) directly; the HAL chooses power modes.

Verified by:

  • review: No application code calls a CPU sleep primitive.

KB-CPP-091: Managers live in static storage owned by the board facade

MUST · hal · since 1.0

Managers are objects in static storage owned by the board facade, which is the only way to reach them; there are no per-manager singletons. Any allocation during Initialize is on the HAL's start-up allowlist.

Verified by:

  • allocation-allowlist (planned): a host run with malloc and operator new wrapped records every allocation; any outside start-up or not on the HAL's allowlist fails
  • review: New managers are facade members and add no GetInstance().

See also: ADR-0004; ADR-0005

Explained in: standards/hal.md

KB-CPP-092: Managers are thread-safe and report failure state consistently

MUST · hal · since 1.0

Every manager method either holds the manager's kb::RtosMutex or delegates to a thread-safe handler. Every fallible call returns kb::Status; the manager keeps the last non-Ok status for GetLastError() until ClearLastError(), and while a dependency has failed every call returns DependencyNotReady.

Verified by:

  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang
  • review: Each manager method is locked or delegates to a locked handler.

Explained in: standards/hal.md

KB-CPP-093: Diagnostics are collected through one facade call into a sink

MUST · hal · since 1.0

The facade's CollectDiagnostics() visits every manager, and each manager writes its state and its handlers' diagnostics headers into the sink without logging. During start-up the facade gives the kb-core logger its sink.

Verified by:

  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang
  • review: New managers contribute to CollectDiagnostics and do not log from it.

See also: ADR-0005

Explained in: standards/hal.md

KB-CPP-094: The platform bind uses fixed verbs and fixed slots

MUST · hal · since 1.0

Bind functions are named Create*, Destroy* or Acquire*; Create* returns nullptr or false on failure and is idempotent per slot. Buses are slots numbered below kMax*, and the bind stores its objects statically.

Verified by:

  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang
  • review: New bind functions use the Create/Destroy/Acquire verbs and slot limits.

Explained in: standards/hal.md

KB-CPP-095: Raw pin numbers appear only in the pin table and the bind

Retired

Duplicate of KB-ARCH-017, merged when the rules were loaded. Replaced by KB-ARCH-017.

MUST · hal, firmware · since 1.0

GPIO numbers and other physical pin identifiers appear only in the board's pin table and the bind; managers and products use functional 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 pin number appears outside the pin table and bind.

Explained in: standards/hal.md

KB-CPP-096: Borrowed references never outlive their owner

MUST · library, hal, firmware · since 1.0

A reference or pointer to an object owned elsewhere (a manager's component, a handler's driver, a caller's buffer) is never stored beyond the owner's lifetime. Getters return references to objects the owner keeps.

Verified by:

  • clang-tidy/bugprone-dangling-handle (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • review: No new member stores a borrowed reference that can outlive its owner.

KB-CPP-097: Scoped resources are released by RAII guards

SHOULD · driver, library, hal, firmware, template · since 1.0

A lock, critical section, chip select or other resource held for a scope is released by a guard object's destructor, never by a matching manual call on every path; guards delete their copy operations. Hardware is still acquired in Initialize(), not in a constructor (KB-CPP-057).

Verified by:

  • review: New scoped resources are released by a guard.

See also: C++ Core Guidelines R.1

KB-CPP-098: Constants are constexpr, not macros

SHOULD · driver, library, hal, firmware, template · since 1.0

Constants and simple functions are constexpr variables, enums or constexpr functions, not macros. Macros are left for conditional compilation and the few cases that need the preprocessor.

Verified by:

  • clang-tidy/cppcoreguidelines-macro-usage (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • clang-tidy/modernize-macro-to-enum (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database

See also: C++ Core Guidelines ES.31

KB-CPP-099: Const by default

SHOULD · driver, library, hal, firmware, template · since 1.0

Member functions that do not change the object are const, and reference parameters are const& unless the function changes the argument. Locals and members that never change are const or constexpr.

Verified by:

  • clang-tidy/readability-make-member-function-const (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database

See also: C++ Core Guidelines Con.2

KB-CPP-100: Large objects are passed by const reference, and moved when ownership moves

SHOULD · driver, library, hal, firmware, template · since 1.0

Parameters that are expensive to copy are passed by const&; cheap types by value. Where a value's ownership passes to the callee, it is moved rather than copied.

Verified by:

  • clang-tidy/performance-unnecessary-value-param (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database

See also: C++ Core Guidelines F.16

KB-CPP-101: Static initialisation never depends on translation-unit order

MUST · library, hal, firmware · since 1.0

No object with static storage is initialised from another translation unit's static object. Objects that need each other are initialised explicitly, in order, at start-up.

Verified by:

  • clang-tidy/cppcoreguidelines-interfaces-global-init (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • review: New static objects do not read other translation units' statics during initialisation.

See also: C++ Core Guidelines I.22; SEI CERT C++ DCL56-CPP

KB-CPP-102: Members are initialised in declaration order

MUST · driver, library, hal, firmware, template · since 1.0

Constructor initialiser lists name members in the order they are declared, and reference members are initialised there rather than assigned in the body; members that depend on each other are declared in dependency order.

Verified by:

  • compiler-warnings/-Wreorder (implemented): the build is warning-free with the named flag and -Werror
  • clang-tidy/cppcoreguidelines-prefer-member-initializer (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database

See also: C++ Core Guidelines C.47

KB-CPP-103: Fixed-width integer types where size matters

SHOULD · driver, library, hal, firmware, template · since 1.0

Register values, wire fields, counters and anything whose width matters use <cstdint> fixed-width types (uint8_t, int32_t); size_t for sizes and indices, and bool for truth values. Plain int and long are not used for such data.

Verified by:

  • review: New register, frame and counter fields use fixed-width types.

KB-CPP-104: Integer arithmetic does not overflow or narrow silently

MUST · driver, library, hal, firmware, template · since 1.0

Arithmetic on sizes, offsets, register values and durations cannot overflow a signed type or narrow without an explicit, range-checked conversion. The build is clean with -Wconversion and -Wsign-conversion.

Verified by:

  • compiler-warnings/-Wconversion (implemented): the build is warning-free with the named flag and -Werror
  • compiler-warnings/-Wsign-conversion (implemented): the build is warning-free with the named flag and -Werror
  • clang-tidy/bugprone-narrowing-conversions (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • clang-tidy/bugprone-implicit-widening-of-multiplication-result (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database

See also: SEI CERT C INT31-C; SEI CERT C INT32-C; C++ Core Guidelines ES.46

KB-CPP-105: Bit operations use unsigned operands and shifts stay within the width

MUST · driver, library, hal, firmware, template · since 1.0

Masks, shifts and bit tests use unsigned operands, and no shift count is negative or at least the width of the shifted type.

Verified by:

  • cppcheck/shiftTooManyBits (implemented): cppcheck in strict mode; the parameter names the cppcheck message id
  • cppcheck/shiftNegative (implemented): cppcheck in strict mode; the parameter names the cppcheck message id
  • review: New bit manipulation uses unsigned operands.

See also: SEI CERT C INT34-C; C++ Core Guidelines ES.101

KB-CPP-106: Register fields and wire bytes are packed with masks, shifts and explicit byte order

MUST · driver, library, hal, template · since 1.0

Register fields and multi-byte wire values are built and read with masks, shifts and explicit byte order. Bit fields do not describe hardware or wire layouts, and a byte buffer is never cast or memcpy'd into a multi-byte integer whose byte order is assumed.

Why: Bit-field order and padding are implementation-defined, and byte order differs between targets.

Verified by:

  • ast-rules/bitfield-frames (planned): a clang-query or libclang script over the compile database for one structural rule; the parameter names it (global-scope, driver-virtual, handler-names, handler-lock-guard, base-nvi, base-tostatus, detail-branch, deadline-compare, isr-calls, bitfield-frames)
  • review: New register and frame code uses masks, shifts and explicit byte order.

See also: SEI CERT C EXP39-C

KB-CPP-107: Register maps are written as tables

GUIDE · driver, template · since 1.0

Describe a chip's registers once, as a table (an X-macro list or constexpr array of address, width, reset value and access), and derive accessors from it, rather than scattering addresses through the code.

KB-CPP-108: Parsers of external input check length and type before use

MUST · driver, library, hal, firmware, template · since 1.0

Code that parses bytes from outside the program (bus frames, CANopen, Modbus, OTA images, CRC-protected records) checks length, type and range before reading any field and returns an error for malformed input.

Verified by:

  • sanitizers (implemented): host tests pass under AddressSanitizer and UndefinedBehaviorSanitizer
  • review: Each new parser rejects short, oversized and mistyped input before reading fields.

See also: SEI CERT C ARR30-C; NASA/JPL Power of Ten Rule 7

KB-CPP-109: Frame, CRC and protocol parsers have fuzz targets

Retired

Duplicate of KB-TST-020, merged when the rules were loaded. Replaced by KB-TST-020.

MUST · driver, library, hal (high level and above) · since 1.0

Each parser of external input has a libFuzzer target built on the host and run in CI for a fixed time with AddressSanitizer and UndefinedBehaviorSanitizer.

Verified by:

  • fuzzing (planned): each parser's libFuzzer target runs on the host for a fixed time under ASan and UBSan without a finding

KB-CPP-110: At the safety level, code follows the MISRA subset in the compliance matrix

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, library, hal, firmware (safety level and above) · since 1.0 · enforced from 2027-03-01

Repositories at the safety level follow the MISRA C++:2023 and MISRA C:2025 subset the compliance matrix adopts, checked by a MISRA-capable analyser, and every departure is a recorded deviation.

Verified by:

  • misra-checker (planned): a commercial MISRA C++:2023 / C:2025 checker run, mapped to the compliance matrix (safety level)
  • misra-matrix (implemented): the MISRA C++:2023 compliance matrix lists all 179 guidelines once, never weakens a category, names a verification for each, and its deviations cite existing non-mandatory guidelines (checks/misra_matrix.py)

See also: MISRA C++:2023; MISRA C:2025

Explained in: deviations.md

KB-CPP-111: Comments explain why, and datasheet references are exact

SHOULD · all · since 1.0

Comments say why the code does what it does, not what it does. A reference to a datasheet names the document, section and table or register.

Verified by:

  • review: New comments explain intent and datasheet references name section and table.

Explained in: standards/naming-and-style.md

KB-CPP-112: No commented-out code, untracked TODOs, author banners or tool attribution

MUST · all · since 1.0

Source files contain no commented-out code, no TODO without an issue link, no author, date or copyright banner (the SPDX line carries the licence), and no line crediting a tool or agent.

Why: Git already records who wrote what and when; banners go stale and attribution lines leak tooling.

Verified by:

  • forbidden-patterns/comment-hygiene (planned): a source scan for a construct the handbook bans; the parameter names the pattern set
  • review: The change adds no commented-out code, untracked TODO, banner or attribution line.

Explained in: standards/naming-and-style.md

KB-CPP-113: Class members are grouped by access

GUIDE · driver, library, hal, firmware, template · since 1.0

Within a class, list public members first, then protected, then private; constructors and destructor first in their section and data members last.

KB-CPP-114: Slow start-up steps are opt-in or visible

GUIDE · library, hal, firmware · since 1.0

A start-up step that can take long (probing a bus with retries, waiting for a chip to boot) is either behind a configuration option or reported to the caller, so a board does not appear to hang at boot.

KB-CPP-115: Functions stay within the complexity, length and parameter limits of their level

MUST · driver, library, hal, firmware, template · since 1.0

Every function in library code stays within the limits of the repository's level, measured by lizard with the modified cyclomatic complexity: standard 15 / 80 lines / 7 parameters; high 15 / 60 / 6; safety 10 / 60 / 6. A function over a limit that is clearer as one piece has a deviation record.

Why: Complex functions are where defects hide and where tests miss paths; the numbers and their sources are in ADR-0020.

Verified by:

  • complexity/level (implemented): lizard finds no library function over the complexity, length or parameter limit of the level (ADR-0020)

See also: ADR-0020; NASA/JPL Power of Ten Rule 4; C++ Core Guidelines F.3

Explained in: deviations.md

KB-CPP-116: A reply a stuck or floating line can produce is never data

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

A reply that a stuck, floating or looped-back line can produce (all zeros, all ones, the command echoed back, the same word repeated) is never returned as a value: the driver maps it to NoDevice or another error. A ready or idle status that a line could fake counts only when a second read confirms it.

Why: Observed on hardware: a floating input reads as a plausible value and hides an absent or unpowered chip; an idle status read from a line held high let a driver go on to write into nothing.

Verified by:

  • error-paths-tested (planned): every error value the public API can return is asserted by at least one host test
  • review: The chip model has StuckLow, FloatHigh, Echo and Deaf line modes, and a test runs each against the start-up and every read path and expects an error, never a value.

Explained in: standards/driver.md

KB-CPP-117: The identity check is one a dead or looped bus cannot pass

Proposed

Warns until 2027-03-01, then fails CI. Sharpens the identity step of KB-CPP-058.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

The start-up identity check needs an active answer from the chip: a select-and-echo, a bit the chip must toggle, or a write followed by a read-back. A stuck, looped-back or deaf line cannot pass it, and a partial, bit-shifted or phantom ID is refused. A chip that answers its ID but is not ready still fails (KB-CPP-124).

Why: Observed on hardware: a passive ID read is satisfied by line states, so identity checks passed on dead buses and on a looped-back data line.

Verified by:

  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang
  • review: The line modes of KB-CPP-116 applied to EnsureInitialized() each fail start-up; a shifted or partial ID is refused with DeviceIdMismatch.

Explained in: standards/driver.md

KB-CPP-118: After a failed transfer the chip's protocol state is restored first

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

After a transfer that failed, or whose outcome is unknown, the driver first brings the chip's protocol back to a known point before it sends a new command: a no-op that is harmless both as a command and as data, a frame that closes an open sequence, or the command byte sent again. A lost half of a multi-frame command never turns the next command into data.

Why: Observed on hardware and in the fuzzer: a lost first half of a two-frame write made the next command data, which desynchronised the chip and in one model armed an irreversible write.

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: The fuzz harness's lost-transfer mode runs against the driver's invariants and the resync is documented.

Explained in: standards/driver.md

KB-CPP-119: Clear-on-read and write-1-to-clear flags collect in one driver-owned latch

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

Every read of a clear-on-read or write-1-to-clear flag that the driver makes, internal reads included (a ready poll, a verify read), ORs the flags into one latch the driver owns. The caller reads it with a Get* accessor that does no I/O and empties it with an explicit Clear* call. A write-1-to-clear write is never verified by reading it back.

Why: Observed on hardware: internal reads consumed fault and warning flags the caller never saw, so a fault output fired with no recorded cause.

Verified by:

  • review: Each clear-on-read flag is ORed into the latch on every read path; a model test raises a flag, triggers an internal read, and still finds the flag in the latch.

Explained in: standards/driver.md

KB-CPP-120: A setter updates the driver's copy only after the chip accepted the change

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

A setter changes the driver's copy of a setting only after the frame that changes the chip succeeded. When the chip applies a change later (a pipeline, the next chip-select edge, a separate program bit), the setter completes the change before it returns, or discards the replies taken before it.

Why: Observed on hardware: a copy that disagreed with the chip produced conversions off by a factor of two and channels that silently stayed off.

Verified by:

  • host-tests (implemented): the unit tests build and pass on the host with gcc and clang
  • review: A model test fails the change frame and expects the getter to return the old value.

Explained in: standards/driver.md

KB-CPP-121: A setter changes only what it names; state-gated changes are refused outside their state

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

A setter never changes another setting as a side effect (a mode, another channel's enable, a shared field). When the chip accepts a change only in some state (all channels off, standby, sleep), a call outside that state returns a chip-specific error and sends nothing.

Why: Observed on hardware: the chip ignored a change made in the wrong state, and a setter rewrote a shared mode field, so a duty-cycle setting became a current setting and another channel's enable was cleared.

Verified by:

  • review: Each state-gated field has a model test that calls the setter in the wrong state and sees no frame.

Explained in: standards/driver.md

KB-CPP-122: Control and output registers are written whole from the driver's copy

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

Control and output registers are written as a whole from the driver's validated copy. A read-modify-write uses only a read validated per KB-ARCH-042, so a corrupt read cannot flip other fields (enables, resets, restart bits).

Why: Observed on hardware, a corrupt read inside a read-modify-write flipped unrelated control bits.

Verified by:

  • review: Every control-register write comes from the copy, or from a read that passed its integrity checks.

Explained in: standards/driver.md

KB-CPP-123: The bus requirements are constexpr in the bus interface header

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

inc/<chip>_<bus>_interface.hpp declares what the chip needs from the bus as constexpr values. SPI: kSpiMode, kMsbFirst, kMaxClockHz, kMinCsHighNs, kCsSetupNs, kCsHoldNs and kContinuousWord (a word must be clocked with no idle between bytes). I2C: kI2cAddress (the 7-bit address, or the base address when pins select it), kMaxClockHz and kRepeatedStart (a read needs a combined write-read). UART: kMaxBaudRate and kTurnaroundUs. Turnaround and inter-frame gaps the chip needs are added the same way. The Porting page lists them, and the example ports check their settings against them with static_assert.

Why: Observed on hardware: requirements kept as prose were violated: idle clocks inside a word, a clock above what the chip's firmware accepts, the wrong mode on a shared bus. Constants make the port prove its settings at compile time.

Verified by:

  • bus-requirements (implemented): for every SPI, I2C or UART bus in driver.yml, inc/<chip>_<bus>_interface.hpp declares the KB-CPP-123 constants as constexpr
  • review: Each example port and the board config static_assert their bus settings against the constants.

Explained in: standards/driver.md

KB-CPP-124: Start-up waits for the chip's own ready indication, bounded by a Config deadline

Proposed

Warns until 2027-03-01, then fails CI. Works with KB-CPP-080 and KB-CPP-114.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

Start-up waits for the chip's own ready indication: first the datasheet minimum, then a bounded poll of the ready, busy or ID bit with a deadline from Config. A fixed delay alone is not enough, a correct ID is not readiness, and a delay never returns early. An expired deadline returns Timeout or NotReady.

Why: Observed on hardware: chips answered their ID before they were ready, and the wake time varied with the supply ramp by more than ten times.

Verified by:

  • model-virtual-clock (planned): a chip model for a driver whose port has DelayUs or DelayMs advances a virtual clock in those hooks, and a test runs a delayed-ready mode against it
  • review: A model with a virtual clock and a delayed-ready mode shows the driver neither returns early nor waits past its deadline.

See also: NASA/JPL Power of Ten Rule 2 (fixed upper bound on loops)

Explained in: standards/driver.md

KB-CPP-125: The chip variant is confirmed before any variant-specific write

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

Before its first variant-specific write the driver confirms the variant: detected from the chip, or configured and then checked. An inconclusive detection fails start-up; where detection is not guaranteed, the variant is a Config field.

Why: Observed on hardware: a write to a register the variant lacks, or a formula taken from the other variant, gave errors up to 256 times the intended value.

Verified by:

  • review: Every variant-specific path runs after the variant check; a model test covers each mismatch.

Explained in: standards/driver.md

KB-CPP-126: Values are checked against the operating range and never silently clamped

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

Arguments and Config fields are checked against the datasheet's operating range, not the register's range, and a value outside it returns InvalidArgument; nothing is silently clamped. When a value is quantised, the call returns or exposes the value actually programmed. A conversion that lacks an input it needs returns an error, never 0 or a sentinel.

Why: Observed on hardware: silent clamps and zero returns produced plausible but wrong outputs, a move to position zero and a reading 17 % off.

Verified by:

  • error-paths-tested (planned): every error value the public API can return is asserted by at least one host test
  • review: Each range comes from the datasheet's operating conditions; quantised setters report what was set.

See also: MISRA C++:2023 Dir 0.3.2 (preconditions are checked, not assumed)

Explained in: standards/driver.md

KB-CPP-127: A state that is not a measurement is an error, never a number

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

A reading that is not a measurement (a settling sentinel, frozen feedback, the first conversion after a reset, a sensor not fitted, a magnet or gain warning) is returned as NotReady or a chip-specific error, never as a value. A multi-item read reports validity per item; it neither fails the whole group nor fills in zeros.

Why: Observed on hardware, settling sentinels and frozen feedback decoded as confident wrong values.

Verified by:

  • review: Each sentinel the datasheet names has a model test that expects an error or an invalid item.

Explained in: standards/driver.md

KB-CPP-128: A conversion that depends on another setting uses the chip's actual setting

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

A conversion that depends on another chip setting (a chopping frequency, a timebase, counts per revolution, a period register) takes it from the validated copy or reads it, never from a fixed default.

Why: Observed on hardware, scale factors computed from a default setting were off by 3 to 460 times.

Verified by:

  • review: Every conversion lists the settings it depends on and reads each from the copy or the chip.

Explained in: standards/driver.md

KB-CPP-129: Every driver offers single-shot raw access and the last raw reply

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

A driver offers a single-shot raw access with no retries (a raw register read or a frame trace) and a GetLast* accessor, with no I/O, for the last raw reply or status byte. Diagnostic reads have no side effects, or their documentation names them.

Why: Observed on hardware: the raw single-shot access located a deaf input and a host bus fault that the retried paths hid.

Verified by:

  • raw-access (implemented): the driver header declares a single-shot raw access (ReadRegister..., ReadRaw... or Trace...) and a no-I/O GetLast... accessor
  • review: The raw access does not retry and the API guide names any side effect of a diagnostic read.

Explained in: standards/driver.md

KB-CPP-130: An I2C driver handles NACK-by-design, sends no empty probe, and uses repeated START

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

An I2C driver documents which transfers the chip NACKs by design (a reset command, a busy chip) and does not report those as bus errors. It never probes with an empty or zero-length transfer, and it uses a combined write-read (repeated START) wherever the chip requires one (kRepeatedStart, KB-CPP-123).

Why: Observed on hardware: empty probes locked up a device and corrupted later reads, and a write-STOP-read sequence was NACKed by a chip that needs a repeated START.

Verified by:

  • forbidden-patterns/zero-length-i2c (planned): a source scan for a construct the handbook bans; the parameter names the pattern set
  • review: The Porting page lists the NACK-by-design transfers and the driver's handling of each.

Explained in: standards/driver.md

KB-CPP-131: Load-dependent diagnostics run only on channels Config declares as loaded

Proposed

Warns until 2027-03-01, then fails CI.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

A driver turns on a load-dependent diagnostic (open load, plunger or motion detection) only for channels the Config declares as loaded, and sets the routing of faults to a shared fault pin from the same declaration before the chip is armed.

Why: Observed on hardware: open-load warnings on unloaded channels held the shared fault line and looked like a failing chip.

Verified by:

  • review: A model test arms the chip with an unloaded channel and sees no load diagnostic and no fault output.

Explained in: standards/driver.md