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 setcompiler-warnings/-pedantic-errors(implemented): the build is warning-free with the named flag and -Werrorstrict-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 newerinclude-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 -Werrorcompiler-warnings/-Wdeprecated-enum-enum-conversion(implemented): the build is warning-free with the named flag and -Werrorcompiler-warnings/-Wdeprecated-enum-float-conversion(implemented): the build is warning-free with the named flag and -Werrorclang-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 compilecodeql/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 statesnoexcepton 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
autoparameter 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 databasecodeql/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 databasecodeql/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 setinclude-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 databasesanitizers(implemented): host tests pass under AddressSanitizer and UndefinedBehaviorSanitizercodeql/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 databasecodeql/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_tbefore bit operations; noULwidths.
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 -Werrorclang-tidy/bugprone-narrowing-conversions(implemented): a clang-tidy check from config/.clang-tidy, run with the CMake compile databasecodeql/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 |= unsignedstyle 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 databaseclang-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 enumonly 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 databasecodeql/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_castfrom 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 databaseclang-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 -Werrorclang-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 trapssanitizers(implemented): host tests pass under AddressSanitizer and UndefinedBehaviorSanitizercodeql/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 databasecodeql/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 databasecodeql/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 databaseclang-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_assertofis_always_lock_freesits next to eachatomic_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 databasecodeql/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