Skip to content

C++20 profile

The C++20 language and library features Kokeb Labs code may use, the rules each one comes with, and the ones it may not use, as numbered guidelines. They extend MISRA C++:2023, which is written for C++17, to the C++20 our code is written in, and they define exactly what deviation MD-CPP-001 covers. The C++20 profile page explains each feature's verdict; categories follow MISRA's model (mandatory and required guidelines are must, advisory ones should).

Rule Level Applies to Verified
KB-CPP20-001 Strict ISO C++20, with a conformance build on every target compiler must driver, template, library, hal, firmware checked
KB-CPP20-002 Only profile features; nothing from C++23 or later must driver, template, library, hal, firmware checked
KB-CPP20-003 Nothing C++20 deprecates must driver, template, library, hal, firmware checked
KB-CPP20-004 No feature-test macros to choose behaviour should driver, template, library checked
KB-CPP20-005 Every template parameter is constrained by a named concept must driver, template, library planned
KB-CPP20-006 Port concepts check the exact hook signature and noexcept must driver, template checked
KB-CPP20-007 Optional hooks use named detection concepts; a misdeclared hook is an error must driver, template checked
KB-CPP20-008 One dependent-false helper should driver, template, library review
KB-CPP20-009 Code that does not depend on the port lives outside the class template should driver, template, library planned
KB-CPP20-010 Abbreviated function templates are constrained and stay out of the public API should driver, template, library planned
KB-CPP20-011 Concepts carry meaning; overloads are not chosen by subsumption should driver, template, library review
KB-CPP20-012 Pure computations are constexpr and proved with static_assert must driver, template, library planned
KB-CPP20-013 consteval only for build-time construction should driver, template, library, hal, firmware review
KB-CPP20-014 constinit on every mutable static must library, hal, firmware checked
KB-CPP20-015 if constexpr only on compile-time facts, each branch instantiated by a test must driver, template, library checked
KB-CPP20-016 No std::is_constant_evaluated should driver, template, library checked
KB-CPP20-017 Header-scope variables are constexpr must driver, template, library, hal, firmware checked
KB-CPP20-018 Configuration-dependent inline code: one configuration per program must driver, template, library checked
KB-CPP20-019 No allocation and no virtual functions in constant evaluation must driver, template, library checked
KB-CPP20-020 Every shift count is provably below the operand width must driver, template, library, hal, firmware checked
KB-CPP20-021 Bit work in uint32_t; no promoted narrow operands; no platform-width types must driver, template, library, hal, firmware checked
KB-CPP20-022 Narrowing is explicit, compound assignment included must driver, template, library, hal, firmware checked
KB-CPP20-023 Mixed-sign comparison through std::cmp_less and its siblings should driver, template, library, hal, firmware checked
KB-CPP20-024 Signed reinterpretation of wire values through a named helper must driver, template, library checked
KB-CPP20-025 Integer-to-enum conversion only for proven enumerators must driver, template, library, hal, firmware planned
KB-CPP20-026 One enumeration utility layer should driver, template, library review
KB-CPP20-027 using enum only at block scope must driver, template, library, hal, firmware planned
KB-CPP20-028 <bit> for counting and rotation instead of hand-written loops should driver, template, library, hal, firmware review
KB-CPP20-029 std::bit_cast between equal-size values, never for byte order must driver, template, library, hal, firmware checked
KB-CPP20-030 Strong types for units and easily swapped parameters should driver, template, library review
KB-CPP20-031 Designated initialisers for configuration; every member has a default must driver, template, library, hal, firmware checked
KB-CPP20-032 No parenthesised aggregate initialisation must driver, template, library, hal, firmware planned
KB-CPP20-033 Defaulted operator== only on exactly comparable members must driver, template, library, hal, firmware planned
KB-CPP20-034 No three-way comparison in drivers must driver, template checked
KB-CPP20-035 Structured bindings test the error before the value should driver, template, library, hal, firmware planned
KB-CPP20-036 Class-type template arguments are structural and integral should driver, template, library review
KB-CPP20-037 [[nodiscard]] on every error-carrying type must driver, template, library, hal, firmware checked
KB-CPP20-038 [[maybe_unused]] instead of (void) for conditionally used names should driver, template, library, hal, firmware checked
KB-CPP20-039 No [[fallthrough]] must driver, template, library, hal, firmware checked
KB-CPP20-040 [[likely]] and [[unlikely]] only with a measurement should driver, template, library, hal, firmware checked
KB-CPP20-041 No [[no_unique_address]] in drivers must driver, template checked
KB-CPP20-042 Caller buffers are spans, with a fixed extent when the size is known must driver, template, library, hal, firmware planned
KB-CPP20-043 A dynamic span is checked before it is indexed, wherever it is indexed must driver, template, library, hal, firmware checked
KB-CPP20-044 Views and references never outlive what they refer to must driver, template, library, hal, firmware checked
KB-CPP20-045 Lambdas: explicit captures, local use, no state must driver, template, library, hal, firmware checked
KB-CPP20-046 No lambdas in unevaluated operands or at namespace scope in headers must driver, template, library, hal, firmware planned
KB-CPP20-047 No generic lambdas in drivers should driver, template planned
KB-CPP20-048 std::optional is read only when engaged, never through .value() must driver, template, library, hal, firmware checked
KB-CPP20-049 No variant, any, function or expected in drivers must driver, template checked
KB-CPP20-050 Range algorithms with rules; no views in target code must driver, template, library, hal, firmware checked
KB-CPP20-051 No <format>, std::format or std::print must driver, template, library, hal, firmware checked
KB-CPP20-052 No std::source_location in drivers must driver, template checked
KB-CPP20-053 No char8_t and no u8 literals in target code must driver, template, library, hal, firmware checked
KB-CPP20-054 <numbers> for mathematical constants should driver, template, library, hal, firmware checked
KB-CPP20-055 std::atomic_ref only for lock-free sharing with an interrupt should hal, firmware review
KB-CPP20-056 No coroutines must driver, template, library, hal, firmware checked
KB-CPP20-057 No modules must driver, template, library, hal, firmware checked
KB-CPP20-058 Loops are bounded by a validated constant must driver, template, library, hal, firmware checked

KB-CPP20-001: Strict ISO C++20, with a conformance build on every target compiler

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Every target a repository builds itself (library, tests, fuzzers, host examples, install consumer) compiles as ISO C++20 with CMAKE_CXX_EXTENSIONS OFF and -pedantic-errors. Every public header also compiles on its own at -std=c++20 -pedantic-errors with each compiler the repository ships for: host GCC and Clang, Arm GCC in the cross-build, and the ESP-IDF toolchain, whose own default dialect is newer (a header self-check compiled at -std=c++20 inside the ESP-IDF build).

Why: MD-CPP-001 deviates Rule 4.1.1 for C++20, not for whatever a framework enables. CMake's default leaves extensions on (-std=gnu++20), and ESP-IDF builds as gnu++23 or gnu++26, so without a strict build a GNU extension or a C++23 feature compiles on one toolchain and breaks on another.

Verified by:

  • cpp20-profile/cmake-extensions (implemented): a source check of the C++20 profile (rules/cpp20.yml); the parameter names it: forbidden-features (no coroutines, modules, range views, <format>, char8_t, C++23 features, feature-test macros, [[fallthrough]], and in drivers no <=>, <source_location>, variant, any, function or [[no_unique_address]]), cmake-extensions (every CMakeLists.txt that builds a target sets CMAKE_CXX_EXTENSIONS OFF, itself or in a parent directory), nodiscard-error (Error enumerations and Result types are [[nodiscard]]), inline-requires (no requires-expression in an if constexpr condition), kconfig-leaf (no header includes the Kconfig header)
  • forbidden-patterns/cmake-cxx-standard (implemented): a source scan for a construct the handbook bans; the parameter names the pattern set
  • compiler-warnings/-pedantic-errors (implemented): the build is warning-free with the named flag and -Werror
  • 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: MISRA C++:2023 Rule 4.1.1; MISRA C++:2023 Rule 4.1.2

Explained in: standards/cpp20-profile.md

KB-CPP20-002: Only profile features; nothing from C++23 or later

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Target code uses only the language and library features this profile marks *Use* or *Use with rules*, under the guidelines attached to them, and library headers only from the layer's ADR-0017 subset. No feature of C++23 or later is used, even where a framework's dialect accepts it (std::to_underlying, std::byteswap, std::expected, if consteval, [[assume]], deducing this, the uz literal suffix).

Why: MD-CPP-001 must name what it covers, and a feature that enters without review enters the safety case unexamined. Our own detail::ToUnderlying replaces the C++23 helper at no cost.

Verified by:

  • cpp20-profile/forbidden-features (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
  • include-allowlist/driver (implemented): a script over the include graph that fails on a header outside the allowed set for the directory; the parameter names the table (driver, hosted, kb-core, handlers, hal-boundary)
  • 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)
  • review: A C++20 feature not in the profile joins it and MD-CPP-001 in one pull request, or is not used.

See also: MISRA C++:2023 Rule 4.1.1; MISRA C++:2023 Rule 4.1.2

Explained in: standards/cpp20-profile.md

KB-CPP20-003: Nothing C++20 deprecates

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

No construct deprecated by C++20: compound assignment or ++/-- on a volatile object, volatile parameters and return types, implicit capture of this through [=], a comma expression in a subscript, arithmetic or comparison between two different enumeration types or between an enumeration and a floating-point type.

Why: Deprecated features are candidates for removal and are deprecated because they mislead: a volatile read-modify-write is not atomic, and [=] does not copy the object.

Verified by:

  • compiler-warnings/-Wdeprecated (implemented): the build is warning-free with the named flag and -Werror
  • compiler-warnings/-Wdeprecated-enum-enum-conversion (implemented): the build is warning-free with the named flag and -Werror
  • compiler-warnings/-Wdeprecated-enum-float-conversion (implemented): the build is warning-free with the named flag and -Werror
  • clang-tidy/cppcoreguidelines-misleading-capture-default-by-value (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database

See also: MISRA C++:2023 Rule 4.1.2; MISRA C++:2023 Rule 10.1.2

Explained in: standards/cpp20-profile.md

KB-CPP20-004: No feature-test macros to choose behaviour

SHOULD · driver, template, library · since 1.0

Shared code does not test __cpp_ or __cpp_lib_ macros or include <version> to pick an implementation. There is one language level; a missing feature is a toolchain problem, not a branch.

Why: Two code paths per feature means one of them is untested on any given CI matrix.

Verified by:

  • cpp20-profile/forbidden-features (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)

See also: MISRA C++:2023 Rule 4.1.1; MISRA C++:2023 Rule 19.0.1

Explained in: standards/cpp20-profile.md

KB-CPP20-005: Every template parameter is constrained by a named concept

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Each type template parameter in target code has a constraint: a named concept in the template head (template <SpiPort Port>) or a requires clause. A callable parameter is constrained with std::invocable and its result type.

Why: An unconstrained parameter accepts anything; misuse is reported deep inside the body, or compiles.

Verified by:

  • codeql/unconstrained-template (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: Every new template parameter names its concept.

See also: MISRA C++:2023 Rule 17.8.1; MISRA C++:2023 Dir 0.3.2

Explained in: standards/cpp20-profile.md

KB-CPP20-006: Port concepts check the exact hook signature and noexcept

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

A port concept accepts only hooks with exactly the signature on the driver's Porting page: each argument is probed with a type that converts to the documented parameter type and to nothing else, each compound requirement states noexcept, and each result type is checked with std::same_as. Compile-fail tests prove that a narrowed parameter and a missing noexcept are rejected.

Why: A concept that probes with plain values is satisfied by Transfer(..., uint16_t len), so the driver's length is truncated at every call without a diagnostic; KB-CPP-035 asks for noexcept, and the concept is where it can be proved.

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
  • codeql/port-hook-signature (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: Each port concept probes with detail::Exactly<T> and states noexcept on every hook.

See also: MISRA C++:2023 Rule 7.0.6; MISRA C++:2023 Rule 0.1.2; MISRA C++:2023 Rule 4.1.3

Explained in: standards/cpp20-profile.md

KB-CPP20-007: Optional hooks use named detection concepts; a misdeclared hook is an error

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Each optional hook has a named concept Has<Hook> in <chip>::detail that checks argument types exactly, the result type and noexcept, and a Declares<Hook> concept that only tests the name; the driver static_asserts !Declares<Hook> || Has<Hook>. No anonymous requires-expression appears in an if constexpr condition.

Why: Detection that silently falls back when a hook is misdeclared turns a wiring mistake into a missing delay or a dropped GPIO error; one named concept is also what KB-CPP-036 asks for.

Verified by:

  • cpp20-profile/inline-requires (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)
  • compile-fail-tests (implemented): a misuse of the public API is a compile error, proved by a test that must fail to compile

See also: MISRA C++:2023 Rule 0.1.2; MISRA C++:2023 Rule 9.6.5

Explained in: standards/cpp20-profile.md

KB-CPP20-008: One dependent-false helper

SHOULD · driver, template, library · since 1.0

A branch that must never be instantiated fails with static_assert(detail::kAlwaysFalse<T>, "..."), from one template <typename> inline constexpr bool kAlwaysFalse = false; per repository, not with ad hoc spellings such as sizeof(T) == 0.

Why: C++20 does not allow static_assert(false) in a discarded template branch; one named helper states the intent.

Verified by:

  • review: Discarded branches use detail::kAlwaysFalse.

See also: MISRA C++:2023 Rule 0.0.1

Explained in: standards/cpp20-profile.md

KB-CPP20-009: Code that does not depend on the port lives outside the class template

SHOULD · driver, template, library · since 1.0

Register encoders and decoders, validation, CRC, unit conversion and error text are namespace-scope constexpr functions, not members of the driver's class template.

Why: A member of Driver<Port> is emitted once per port type; a free constexpr function is emitted once or folded away, and can be proved with static_assert.

Verified by:

  • codeql/port-independent-member (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: A static member that never names the port moves out.

See also: MISRA C++:2023 Rule 6.2.3

Explained in: standards/cpp20-profile.md

KB-CPP20-010: Abbreviated function templates are constrained and stay out of the public API

SHOULD · driver, template, library · since 1.0

A function parameter declared auto has a type-constraint (std::unsigned_integral auto), and public driver member functions have no auto parameters.

Why: void f(auto x) is a template that instantiates for every argument type, bool and char included, and hides that from the reader and the code-size budget.

Verified by:

  • codeql/unconstrained-auto-parameter (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: No auto parameter in public driver API.

See also: MISRA C++:2023 Rule 17.8.1

Explained in: standards/cpp20-profile.md

KB-CPP20-011: Concepts carry meaning; overloads are not chosen by subsumption

SHOULD · driver, template, library · since 1.0

A concept names a contract a reader can state in one sentence. Driver code does not build overload sets chosen by concept subsumption, and does not define concepts that every type satisfies; a choice between behaviours is an if constexpr on a named concept.

Why: Subsumption depends on the exact spelling of atomic constraints, so a harmless edit can switch the chosen overload without a diagnostic.

Verified by:

  • review: No two overloads differ only in one being more constrained.

See also: MISRA C++:2023 Rule 17.8.1

Explained in: standards/cpp20-profile.md

KB-CPP20-012: Pure computations are constexpr and proved with static_assert

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

A function that computes only from its arguments (register encoder or decoder, frame builder, CRC, unit conversion, Validate) is constexpr. Each such function in a _registers or _types header is named in at least one static_assert with a datasheet value; an encode and decode pair has a round-trip static_assert; each preset asserts Validate(preset) == Error::Ok; and an array whose size mirrors a register count uses the named constant.

Why: A static_assert is evidence that costs nothing at run time and runs on every compiler, and undefined behaviour inside a constant evaluation is a compile error, so the vectors are also proved free of it.

Verified by:

  • codeql/unasserted-constexpr (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: Every new pure function has a datasheet static_assert; encode and decode pairs a round trip.

See also: MISRA C++:2023 Rule 0.0.1; MISRA C++:2023 Rule 4.1.3

Explained in: standards/cpp20-profile.md

KB-CPP20-013: consteval only for build-time construction

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

consteval is used for what must never run at run time: checked configuration values, generated tables, validated constants. A failed check calls a declared but undefined function whose name states the error. A consteval check never replaces the run-time validation of a value that can come from outside the build.

Why: A board's configuration is usually a constant, and rejecting a bad one at build time is better than at boot; the run-time Validate() stays for everything else.

Verified by:

  • review: The run-time Validate() call stays in the start-up path.

See also: MISRA C++:2023 Rule 0.1.2; MISRA C++:2023 Dir 0.3.2

Explained in: standards/cpp20-profile.md

KB-CPP20-014: constinit on every mutable static

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Every object with static storage duration that is not constexpr (the cases MD-CPP-005 allows) is declared constinit. Drivers have no such objects (KB-CPP-040).

Why: constinit turns constant initialisation from a review claim into a compiler error and closes the static initialisation order hazard.

Verified by:

  • clang-tidy/cppcoreguidelines-avoid-non-const-global-variables (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • codeql/constinit (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: Every mutable static is constinit.

See also: MISRA C++:2023 Rule 6.7.2; MISRA C++:2023 Rule 6.7.1

Explained in: standards/cpp20-profile.md

KB-CPP20-015: if constexpr only on compile-time facts, each branch instantiated by a test

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

The condition of if constexpr depends on a template parameter or a build-configuration constant, and each branch of a hook dispatch is instantiated by at least one host test (a minimal port and a full port).

Why: A discarded branch is not compiled for that instantiation, so a branch no test instantiates is unverified code.

Verified by:

  • coverage-floor/level (implemented): gcovr coverage of library code by the host tests at or above the floor (coverage-floor/level for lines and branches, coverage-floor/mcdc for condition coverage), as ADR-0020 defines it
  • review: The tests have a minimal and a full port, so both branches compile.

See also: MISRA C++:2023 Rule 0.0.1; MISRA C++:2023 Rule 0.0.2

Explained in: standards/cpp20-profile.md

KB-CPP20-016: No std::is_constant_evaluated

SHOULD · driver, template, library · since 1.0

Code does not branch on std::is_constant_evaluated().

Why: Inside if constexpr it is always true, a classic mistake; outside it, two implementations of one function have to be kept equivalent, and the clean form is C++23.

Verified by:

  • cpp20-profile/forbidden-features (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)

See also: MISRA C++:2023 Rule 0.0.2

Explained in: standards/cpp20-profile.md

KB-CPP20-017: Header-scope variables are constexpr

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

A variable defined in a header at namespace scope is inline constexpr; a static data member of a class template is static constexpr. No mutable inline variable exists.

Why: An inline variable is one object for the whole program, so a mutable one is a global by another name.

Verified by:

  • clang-tidy/cppcoreguidelines-avoid-non-const-global-variables (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • codeql/mutable-inline-variable (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)

See also: MISRA C++:2023 Rule 6.2.4; MISRA C++:2023 Rule 6.2.1; MISRA C++:2023 Rule 6.7.2

Explained in: standards/cpp20-profile.md

KB-CPP20-018: Configuration-dependent inline code: one configuration per program

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

A header whose inline function bodies depend on configuration macros (<chip>_kconfig.hpp, or anything that uses __has_include for configuration) is a leaf: no other library header includes it, every translation unit of one program sees the same configuration, and its file comment says so.

Why: Different macro values in two translation units give two definitions of one inline function: an ODR violation with no diagnostic.

Verified by:

  • cpp20-profile/kconfig-leaf (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)
  • review: The Kconfig header's comment states one configuration per program.

See also: MISRA C++:2023 Rule 6.2.1

Explained in: standards/cpp20-profile.md

KB-CPP20-019: No allocation and no virtual functions in constant evaluation

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

constexpr code does not use new, std::allocator or an allocating container, and no function is constexpr virtual.

Why: C++20 allows transient allocation during constant evaluation, but the headers that offer it are outside the target subset, and the same code would run with the heap at run time.

Verified by:

  • forbidden-patterns/heap (implemented): a source scan for a construct the handbook bans; the parameter names the pattern set
  • include-allowlist/driver (implemented): a script over the include graph that fails on a header outside the allowed set for the directory; the parameter names the table (driver, hosted, kb-core, handlers, hal-boundary)

See also: MISRA C++:2023 Rule 21.6.1; MISRA C++:2023 Rule 21.6.2

Explained in: standards/cpp20-profile.md

KB-CPP20-020: Every shift count is provably below the operand width

Proposed

Category mandatory; warns until 2027-03-01, then fails CI.

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

A shift whose count is not a constant is preceded, in the same function, by a check or a mask that bounds the count below the width of the promoted left operand. A public helper that shifts by an enumeration or an integer argument masks the count itself.

Why: A shift by the width or more is undefined behaviour, and an enum class with a uint8_t base can hold any value from 0 to 255, so being an enumeration proves nothing.

Verified by:

  • clang-tidy/clang-analyzer-core.BitwiseShift (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • sanitizers (implemented): host tests pass under AddressSanitizer and UndefinedBehaviorSanitizer
  • codeql/shift-range (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: Every run-time shift count is masked or checked in the same function.

See also: MISRA C++:2023 Rule 7.0.4; MISRA C++:2023 Rule 4.1.3

Explained in: standards/cpp20-profile.md

KB-CPP20-021: Bit work in uint32_t; no promoted narrow operands; no platform-width types

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Operands of ~, <<, >>, &, |, ^ and arithmetic on register values are uint32_t (or uint64_t) before the operator; uint8_t and uint16_t values are cast up first. unsigned, unsigned long, int and the UL suffix never set a width: literals are uint32_t{1}, or 1U when the other operand is already uint32_t. A loop counter used as a shift count is unsigned.

Why: Narrow unsigned values promote to signed int, and unsigned long is 32 bits on our targets but 64 bits on the host, so host tests cannot show a width bug.

Verified by:

  • clang-tidy/hicpp-signed-bitwise (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • codeql/narrow-bitwise-operand (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: Narrow operands are widened to uint32_t before bit operations; no UL widths.

See also: MISRA C++:2023 Rule 7.0.5; MISRA C++:2023 Rule 7.0.4; MISRA C++:2023 Rule 6.9.2

Explained in: standards/cpp20-profile.md

KB-CPP20-022: Narrowing is explicit, compound assignment included

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Every conversion to a narrower or differently signed integer type is a static_cast where it happens, including the hidden one in |=, &=, +=, in initialisation, argument passing and return. A value whose range is not proved by a mask or a preceding check is tested with std::in_range<T> first.

Why: -Wconversion is silent when it can prove the value fits, so the conversion stays unseen until the commercial checker runs; an explicit cast is also where a reviewer looks for the range argument.

Verified by:

  • compiler-warnings/-Wconversion (implemented): the build is warning-free with the named flag and -Werror
  • clang-tidy/bugprone-narrowing-conversions (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • codeql/compound-narrowing (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: No uint8_t |= unsigned style compound assignment.

See also: MISRA C++:2023 Rule 7.0.6

Explained in: standards/cpp20-profile.md

KB-CPP20-023: Mixed-sign comparison through std::cmp_less and its siblings

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

When a signed and an unsigned value must be compared, the code uses std::cmp_less (or cmp_equal, cmp_greater, ...) instead of a cast.

Why: A cast picks a direction and can wrap; the C++20 functions compare the mathematical values.

Verified by:

  • compiler-warnings/-Wsign-compare (implemented): the build is warning-free with the named flag and -Werror

See also: MISRA C++:2023 Rule 7.0.5

Explained in: standards/cpp20-profile.md

KB-CPP20-024: Signed reinterpretation of wire values through a named helper

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

A same-width signed value read from a wire or register comes from std::bit_cast<intN_t> or static_cast<intN_t> (both defined in C++20) inside a named helper whose comment states the encoding; an N-bit field narrower than its container is sign-extended by a named helper in int32_t arithmetic. Never through a union, memcpy or a pointer cast.

Why: C++20 fixed two's complement and made the conversion modular, but the encoding should be named once.

Verified by:

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

See also: MISRA C++:2023 Rule 12.3.1; MISRA C++:2023 Rule 6.8.1; MISRA C++:2023 Rule 8.2.5

Explained in: standards/cpp20-profile.md

KB-CPP20-025: Integer-to-enum conversion only for proven enumerators

Proposed

Category mandatory; warns until 2027-03-01, then fails CI.

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

static_cast<E>(x) from a non-constant integer is allowed only when every value x can take is an enumerator: the mask's range equals the contiguous enumerator set, stated by a static_assert next to the enumeration, or the value is checked first and a non-enumerator becomes an Error.

Why: A non-enumerator in an enumeration defeats every switch and every == test that follows.

Verified by:

  • codeql/enum-from-integer (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: Each integer-to-enum cast is preceded by a range check or proof.

See also: MISRA C++:2023 Rule 4.1.3; MISRA C++:2023 Rule 10.2.1

Explained in: standards/cpp20-profile.md

KB-CPP20-026: One enumeration utility layer

SHOULD · driver, template, library · since 1.0

Conversion to the underlying type goes through one detail::ToUnderlying function template, and range checks through one detail::IsEnumerator with an EnumLast<E> class template specialised next to each contiguous enumeration. Function templates are never explicitly specialised.

Why: Hand-written static_cast<uint8_t>(x) > static_cast<uint8_t>(Last) checks must each be updated when an enumerator is added.

Verified by:

  • review: Enumeration range checks use detail::IsEnumerator.

See also: MISRA C++:2023 Rule 17.8.1

Explained in: standards/cpp20-profile.md

KB-CPP20-027: using enum only at block scope

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

using enum E; appears only inside a function body, never at namespace or class scope in a header.

Why: At namespace scope it exports every enumerator into the enclosing namespace and undoes the scoping that scoped enumerations exist for.

Verified by:

  • codeql/using-enum-scope (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: using enum only inside function bodies.

See also: MISRA C++:2023 Rule 6.4.1; MISRA C++:2023 Rule 10.2.2

Explained in: standards/cpp20-profile.md

KB-CPP20-028: <bit> for counting and rotation instead of hand-written loops

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

Population count, leading and trailing zero counts, single-bit tests and rotations use std::popcount, std::countl_zero, std::countr_zero, std::has_single_bit, std::bit_width, std::rotl and std::rotr. On a timing-critical path the generated code is checked once per target.

Why: They accept only unsigned types, are constexpr and are simpler to review than a loop.

Verified by:

  • review: Bit counting uses <bit>.

See also: MISRA C++:2023 Rule 7.0.4; MISRA C++:2023 Rule 9.5.1

Explained in: standards/cpp20-profile.md

KB-CPP20-029: std::bit_cast between equal-size values, never for byte order

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

std::bit_cast is used only between trivially copyable value types of the same size, never to or from a pointer, and never to read a multi-byte wire value: byte order is always explicit shifts. std::endian appears only in a static_assert or in MCU port code.

Why: A bit_cast of a 4-byte buffer to uint32_t silently assumes the host byte order (KB-CPP-106).

Verified by:

  • clang-tidy/bugprone-bitwise-pointer-cast (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • codeql/bit-cast-byte-order (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: No bit_cast from a byte array.

See also: MISRA C++:2023 Rule 8.2.5; MISRA C++:2023 Rule 8.2.4; MISRA C++:2023 Rule 8.2.6; MISRA C++:2023 Rule 6.8.1

Explained in: standards/cpp20-profile.md

KB-CPP20-030: Strong types for units and easily swapped parameters

SHOULD · driver, template, library · since 1.0

A public function with two or more adjacent parameters of the same arithmetic type but different meanings, or a physical quantity whose unit is easy to confuse, takes single-member strong types (Milliamps, Microseconds, I2cAddress7): trivially copyable aggregates of one integer with only the operations the unit supports.

Why: CurrentCode(uint32_t ma, uint32_t rref_ohm) compiles with the arguments swapped; a one-member struct is passed in a register on the Arm and Xtensa ABIs, so the safety costs nothing.

Verified by:

  • review: Adjacent same-typed parameters with different units use strong types.

See also: MISRA C++:2023 Rule 7.0.6

Explained in: standards/cpp20-profile.md

KB-CPP20-031: Designated initialisers for configuration; every member has a default

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Every member of a configuration or value aggregate has a default member initialiser. Code that sets more than one member of such an aggregate in one expression uses designated initialisers; positional brace initialisation of a multi-member aggregate is used only inside the type's own header.

Why: C++20 already orders designators and forbids mixing; the defaults make an omitted designator mean the datasheet default, and designators keep a call site right when a field is inserted.

Verified by:

  • clang-tidy/modernize-use-designated-initializers (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • clang-tidy/cppcoreguidelines-pro-type-member-init (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database

See also: MISRA C++:2023 Rule 11.6.1; MISRA C++:2023 Rule 15.1.4; MISRA C++:2023 Rule 7.0.6

Explained in: standards/cpp20-profile.md

KB-CPP20-032: No parenthesised aggregate initialisation

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Aggregates are never initialised with parentheses (Config(a, b)).

Why: The C++20 parenthesised form is positional and, unlike braces, allows narrowing, so Config(1000, 2.5) compiles; it also reads like a constructor that does not exist.

Verified by:

  • codeql/paren-aggregate-init (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: Aggregates use braces.

See also: MISRA C++:2023 Rule 7.0.6

Explained in: standards/cpp20-profile.md

KB-CPP20-033: Defaulted operator== only on exactly comparable members

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

operator== of a value type is defaulted, never hand-written, and only when every member is an integer, bool, enumeration, std::array of those, or a type that itself follows this guideline. Types with floating-point or pointer members have no operator==.

Why: A defaulted == compares floats exactly and pointers by address, which is rarely what the same configuration means.

Verified by:

  • codeql/float-defaulted-equality (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: No defaulted == on a type with a float or pointer member.

See also: MISRA C++:2023 Rule 16.6.1; MISRA C++:2023 Dir 0.3.1

Explained in: standards/cpp20-profile.md

KB-CPP20-034: No three-way comparison in drivers

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Drivers do not declare or use operator<=> and do not include <compare>. Libraries may default <=> for a type with a genuine total order, under KB-CPP20-033's member rules.

Why: Driver configurations, statuses and errors have no order, and <compare> is outside the driver subset.

Verified by:

  • cpp20-profile/forbidden-features (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)
  • include-allowlist/driver (implemented): a script over the include graph that fails on a header outside the allowed set for the directory; the parameter names the table (driver, hosted, kb-core, handlers, hal-boundary)

See also: MISRA C++:2023 Rule 16.6.1

Explained in: standards/cpp20-profile.md

KB-CPP20-035: Structured bindings test the error before the value

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

Structured bindings may decompose an aggregate returned by value. When it is a Result, the error binding is tested before the value binding is read. Bindings are by value, or const auto& to a named object.

Why: [[nodiscard]] is satisfied by the binding, so the compiler no longer helps when the value is used first.

Verified by:

  • codeql/structured-binding-order (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: The error binding is tested first.

See also: MISRA C++:2023 Rule 0.1.2; MISRA C++:2023 Rule 11.6.2

Explained in: standards/cpp20-profile.md

KB-CPP20-036: Class-type template arguments are structural and integral

SHOULD · driver, template, library · since 1.0

A class type used as a non-type template parameter has only public integral, bool and enumeration members: no floating-point members, no pointers.

Why: Integral members keep instantiation identity obvious and portable across our compilers.

Verified by:

  • review: Class NTTPs have integral members only.

See also: MISRA C++:2023 Rule 17.8.1

Explained in: standards/cpp20-profile.md

KB-CPP20-037: [[nodiscard]] on every error-carrying type

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Result<T>, Result<void>, every Error enumeration and every status type are declared [[nodiscard]] on the type, and every const query member function is [[nodiscard]]. A deliberate discard is a (void) cast with a comment saying why.

Why: With the attribute on the type, every function returning it is covered, Validate() and bus helpers included, and the compiler proves what review used to.

Verified by:

  • cpp20-profile/nodiscard-error (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)
  • compiler-warnings/-Wunused-result (implemented): the build is warning-free with the named flag and -Werror
  • clang-tidy/bugprone-unused-return-value (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database

See also: MISRA C++:2023 Rule 0.1.2

Explained in: standards/cpp20-profile.md

KB-CPP20-038: [[maybe_unused]] instead of (void) for conditionally used names

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

A parameter or variable used only in some if constexpr branches is declared [[maybe_unused]]; a (void)x; statement is kept for discarding a result.

Why: It keeps (void) meaning one thing: an explicit discard.

Verified by:

  • compiler-warnings/-Wunused-parameter (implemented): the build is warning-free with the named flag and -Werror

See also: MISRA C++:2023 Rule 0.2.2

Explained in: standards/cpp20-profile.md

KB-CPP20-039: No [[fallthrough]]

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Every non-empty switch clause ends with break, return or a [[noreturn]] call; [[fallthrough]] is not used.

Why: The attribute documents a fall-through our switch layout does not allow at all; adjacent case labels already cover several values with one action.

Verified by:

  • cpp20-profile/forbidden-features (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)
  • compiler-warnings/-Wimplicit-fallthrough (implemented): the build is warning-free with the named flag and -Werror

See also: MISRA C++:2023 Rule 9.4.2

Explained in: standards/cpp20-profile.md

KB-CPP20-040: [[likely]] and [[unlikely]] only with a measurement

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

These attributes are added only with a recorded measurement on the target (KB-CPP-074), named in a comment on the same line that contains the word measured.

Why: Their effect depends on the compiler and target; a wrong hint slows the path it was meant to speed up.

Verified by:

  • cpp20-profile/forbidden-features (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)

Explained in: standards/cpp20-profile.md

KB-CPP20-041: No [[no_unique_address]] in drivers

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Drivers do not use [[no_unique_address]], and no type whose layout is asserted (KB-CPP-009) uses it anywhere.

Why: It lets members overlap, which changes size and offsets differently per compiler, so layout assertions pass on one and fail on another.

Verified by:

  • cpp20-profile/forbidden-features (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)

See also: MISRA C++:2023 Rule 12.2.1; MISRA C++:2023 Rule 21.2.4

Explained in: standards/cpp20-profile.md

KB-CPP20-042: Caller buffers are spans, with a fixed extent when the size is known

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

A function in target code that takes a buffer takes std::span<T> or std::span<const T>, with a fixed extent when the size is a property of the chip or the frame, and a dynamic extent only when the caller chooses the count. Pointer-and-length pairs exist only in the port hook signatures (KB-CPP-035), where the driver passes .data() and .size() of an array or span it owns.

Why: The size travels with the pointer, so the callee can check it, and a fixed extent turns the check into a compile error. MD-CPP-001's justification relies on it.

Verified by:

  • codeql/pointer-length-parameter (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: No pointer-and-length parameter outside port hooks.

See also: MISRA C++:2023 Rule 7.11.2; MISRA C++:2023 Rule 8.7.1

Explained in: standards/cpp20-profile.md

KB-CPP20-043: A dynamic span is checked before it is indexed, wherever it is indexed

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Before the first element access, a function that receives a dynamic-extent span checks its size against the contract (not empty, not above the documented maximum, the output at least as large as the input). A helper that copies into a fixed buffer checks the length itself instead of trusting its callers. first, last and subspan take only counts proved in range. Host tests and fuzzers build with the standard library's assertions, so an out-of-range access traps.

Why: C++20 std::span has no checked at(); an out-of-range operator[], first(n) or subspan is undefined.

Verified by:

  • library-hardening (implemented): host tests and fuzz targets build with the standard library's assertions (_GLIBCXX_ASSERTIONS, libc++ hardening), so an out-of-range span or array access traps
  • sanitizers (implemented): host tests pass under AddressSanitizer and UndefinedBehaviorSanitizer
  • codeql/unchecked-span-index (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: Every dynamic span is size-checked before its first access.

See also: MISRA C++:2023 Rule 8.7.1; MISRA C++:2023 Rule 4.1.3

Explained in: standards/cpp20-profile.md

KB-CPP20-044: Views and references never outlive what they refer to

Proposed

Category mandatory; warns until 2027-03-01, then fails CI.

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

A std::span (and above the drivers a std::string_view) is never a data member, never returned when it refers to a local or a temporary, and never built from a temporary container. A lambda that captures by reference is never stored or returned. A member function that returns a reference into *this is &-qualified, with the rvalue overload deleted.

Why: Dangling access is undefined behaviour that tests reusing the stack the same way never show, and since C++17 a non-copyable driver can be a temporary.

Verified by:

  • clang-tidy/bugprone-dangling-handle (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • codeql/span-member (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: No span member; reference accessors are &-qualified.

See also: MISRA C++:2023 Rule 6.8.2; MISRA C++:2023 Rule 6.8.3; MISRA C++:2023 Rule 6.8.1; MISRA C++:2023 Rule 6.8.4

Explained in: standards/cpp20-profile.md

KB-CPP20-045: Lambdas: explicit captures, local use, no state

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Lambdas in target code list every capture ([this, address], never [=] or [&]), are not mutable, are called within the full expression or passed down the stack to a constrained template, and are never stored beyond the enclosing function. No lambda calls itself.

Why: A default capture hides what a closure depends on, a stored closure is a lifetime hazard, and recursion breaks the stack bound.

Verified by:

  • clang-tidy/cppcoreguidelines-misleading-capture-default-by-value (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • codeql/lambda-capture (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: Every lambda capture is explicit.

See also: MISRA C++:2023 Rule 8.1.1; MISRA C++:2023 Rule 8.1.2; MISRA C++:2023 Rule 7.11.3

Explained in: standards/cpp20-profile.md

KB-CPP20-046: No lambdas in unevaluated operands or at namespace scope in headers

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

No lambda appears in decltype, sizeof, a template argument or a default template argument, and no header defines a namespace-scope variable initialised with a lambda.

Why: Every lambda expression has its own type, so the same declaration in two translation units names different types: an ODR trap with no diagnostic.

Verified by:

  • codeql/lambda-unevaluated (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: No lambda in an unevaluated operand.

See also: MISRA C++:2023 Rule 6.2.1

Explained in: standards/cpp20-profile.md

KB-CPP20-047: No generic lambdas in drivers

SHOULD · driver, template · since 1.0

Drivers do not use []<typename T>(...) or auto lambda parameters; a generic helper is a named, constrained function template in detail.

Why: A generic lambda is an unconstrained template (KB-CPP20-005) that is harder to read in review.

Verified by:

  • codeql/generic-lambda (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: No generic lambda in driver code.

See also: MISRA C++:2023 Rule 17.8.1

Explained in: standards/cpp20-profile.md

KB-CPP20-048: std::optional is read only when engaged, never through .value()

Proposed

Category mandatory; warns until 2027-03-01, then fails CI.

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

*opt and opt-> are used only where a test of opt.has_value() (or if (opt)) dominates them; .value() is never called. Failure is modelled with Result, not std::optional: an optional means may be absent, and that is fine.

Why: Dereferencing an empty optional is undefined behaviour, and .value() throws, which with -fno-exceptions ends the program.

Verified by:

  • clang-tidy/bugprone-unchecked-optional-access (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • clang-tidy/bugprone-optional-value-conversion (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • review: No .value() on an optional.

See also: MISRA C++:2023 Rule 4.1.3; MISRA C++:2023 Rule 0.1.2; MISRA C++:2023 Dir 0.3.2

Explained in: standards/cpp20-profile.md

KB-CPP20-049: No variant, any, function or expected in drivers

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Drivers do not use std::variant, std::any, std::function or std::expected. Libraries may use std::variant with std::get_if or std::visit over an exhaustive overload set, never std::get.

Why: std::get and std::visit on a valueless variant throw, std::function may allocate, std::any needs RTTI, and std::expected is C++23.

Verified by:

  • cpp20-profile/forbidden-features (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)
  • include-allowlist/driver (implemented): a script over the include graph that fails on a header outside the allowed set for the directory; the parameter names the table (driver, hosted, kb-core, handlers, hal-boundary)

See also: MISRA C++:2023 Rule 21.6.1

Explained in: standards/cpp20-profile.md

KB-CPP20-050: Range algorithms with rules; no views in target code

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Non-allocating algorithms from <algorithm>, the std::ranges:: overloads included, may be used on named arrays and spans with side-effect-free predicates. <ranges> and range views are not used in target code.

Why: The algorithms are bounded loops with clear contracts; views evaluate lazily and hold references, so a lifetime error moves away from where it is written, and they are slow in unoptimised debug images.

Verified by:

  • cpp20-profile/forbidden-features (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)
  • include-allowlist/driver (implemented): a script over the include graph that fails on a header outside the allowed set for the directory; the parameter names the table (driver, hosted, kb-core, handlers, hal-boundary)

See also: MISRA C++:2023 Rule 28.3.1; MISRA C++:2023 Rule 9.5.2; MISRA C++:2023 Rule 6.8.1

Explained in: standards/cpp20-profile.md

KB-CPP20-051: No <format>, std::format or std::print

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Target code does not include <format> or <print> or call their functions. Text above the drivers is formatted with snprintf into a caller's buffer (ADR-0017).

Why: std::format returns a heap string, throws on a bad format and pulls in locale support.

Verified by:

  • cpp20-profile/forbidden-features (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)

See also: MISRA C++:2023 Rule 21.6.1; MISRA C++:2023 Rule 21.10.1

Explained in: standards/cpp20-profile.md

KB-CPP20-052: No std::source_location in drivers

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

Drivers do not include <source_location>. Above the drivers it is used only as a defaulted parameter of the logging facade, which stores only the line and a file identifier.

Why: Drivers never format text (KB-CPP-037), and each use places file and function strings in flash.

Verified by:

  • cpp20-profile/forbidden-features (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)
  • include-allowlist/driver (implemented): a script over the include graph that fails on a header outside the allowed set for the directory; the parameter names the table (driver, hosted, kb-core, handlers, hal-boundary)

Explained in: standards/cpp20-profile.md

KB-CPP20-053: No char8_t and no u8 literals in target code

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

char8_t and u8 character and string literals are not used.

Why: Drivers move bytes, not text, and C++20 changed the type of u8 literals, which breaks code moving between dialects.

Verified by:

  • cpp20-profile/forbidden-features (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)

See also: MISRA C++:2023 Rule 7.0.3

Explained in: standards/cpp20-profile.md

KB-CPP20-054: <numbers> for mathematical constants

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

Mathematical constants come from <numbers> (std::numbers::pi_v<float>) wherever the layer's ADR-0017 subset includes it, never as hand-typed digits.

Why: Constants only, no code; it removes hand-typed digits and the suppression that goes with them.

Verified by:

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

See also: MISRA C++:2023 Dir 0.3.1

Explained in: standards/cpp20-profile.md

KB-CPP20-055: std::atomic_ref only for lock-free sharing with an interrupt

SHOULD · hal, firmware · since 1.0

HAL code may use std::atomic_ref<T> for an object shared with an interrupt handler only when std::atomic_ref<T>::is_always_lock_free is asserted and every access to the object goes through it.

Why: It makes a plain member atomic without changing its type, but mixing atomic and plain access is a data race.

Verified by:

  • review: A static_assert of is_always_lock_free sits next to each atomic_ref.

See also: MISRA C++:2023 Rule 10.1.2

Explained in: standards/cpp20-profile.md

KB-CPP20-056: No coroutines

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

No co_await, co_yield or co_return, and no <coroutine>.

Why: The coroutine frame is heap-allocated unless the optimiser removes it, which is not guaranteed; the generated state machine is hard to bound for stack and timing; and the RTOS task model already gives concurrency.

Verified by:

  • cpp20-profile/forbidden-features (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)
  • clang-tidy/cppcoreguidelines-avoid-capturing-lambda-coroutines (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database

See also: MISRA C++:2023 Rule 21.6.1; MISRA C++:2023 Rule 8.2.10

Explained in: standards/cpp20-profile.md

KB-CPP20-057: No modules

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

No import, export module, module partitions or header units.

Why: ESP-IDF's build does not support them, GCC's support is partial, CMake needs a scanning generator, and the analysis tools lag; header-only drivers gain little.

Verified by:

  • cpp20-profile/forbidden-features (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)

See also: MISRA C++:2023 Rule 4.1.1

Explained in: standards/cpp20-profile.md

KB-CPP20-058: Loops are bounded by a validated constant

Proposed

Category required; warns until 2027-03-01, then fails CI.

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

A loop whose bound comes from configuration or input compares its counter with < against a bound that Validate() or a preceding check limited to a named maximum. <= against an unsigned bound that can be the type's maximum is not used, a for condition has one counter comparison and no extra error flag, and one index never serves two different arrays.

Why: ms <= timeout with timeout == UINT32_MAX never ends because the counter wraps; a bounded loop is what lets us state the worst-case time of a call.

Verified by:

  • clang-tidy/bugprone-too-small-loop-variable (implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile database
  • codeql/unbounded-loop (planned): a query of the Kokeb CodeQL pack for C++ over the CMake build; the parameter names the query (for example shift-range, compound-narrowing, enum-from-integer, unbounded-loop, pointer-length-parameter)
  • review: Every loop bound from configuration or input is validated against a named maximum.

See also: MISRA C++:2023 Rule 9.5.1; MISRA C++:2023 Rule 0.0.2

Explained in: standards/cpp20-profile.md