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 -Werrorforbidden-patterns/cmake-cxx-standard(implemented): a source scan for a construct the handbook bans; the parameter names the pattern setcpp20-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 testsforbidden-patterns/exceptions-rtti(implemented): a source scan for a construct the handbook bans; the parameter names the pattern setclang-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 runsforbidden-patterns/heap(implemented): a source scan for a construct the handbook bans; the parameter names the pattern setclang-tidy/cppcoreguidelines-no-malloc(implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile databaseclang-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 -Werrorclang-tidy/bugprone-unused-return-value(implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile databasecompile-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 databaseclang-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 databasecppcheck/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 clanginclude-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)
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)
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)
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.
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 databaseclang-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
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.
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 compilehost-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 databaseforbidden-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.
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 clangforbidden-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.
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
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.
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 sethost-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 failclang-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().
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 databaseclang-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 -Werrorclang-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 -Werrorcompiler-warnings/-Wsign-conversion(implemented): the build is warning-free with the named flag and -Werrorclang-tidy/bugprone-narrowing-conversions(implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile databaseclang-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 idcppcheck/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 withDeviceIdMismatch.
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