C code¶
Most Kokeb Labs code is C++, but C still appears: C APIs that kb-core keeps for compatibility, MCU vendor code and code generated by CubeMX or ESP-IDF. These rules say how our own C is written and how vendor and generated C is kept apart. The C++ rules on heap, errors, integers and static analysis apply to C as well.
| Rule | Level | Applies to | Verified |
|---|---|---|---|
| KB-CC-001 C is C17 without compiler extensions | must | driver, library, hal, firmware, template | planned |
| KB-CC-002 C headers work from C++ and expose only C types | must | driver, library, hal, firmware, template | checked |
| KB-CC-003 C names are snake_case with the repository prefix; file-local functions are static | must | driver, library, hal, firmware, template | planned |
| KB-CC-004 C APIs return an error enum whose zero is success, and the result is used | must | driver, library, hal, firmware, template | review |
| KB-CC-005 Every C function has a prototype | must | driver, library, hal, firmware, template | checked |
| KB-CC-006 Generated vendor code is edited only between its user-code markers | must | hal, firmware | planned |
| KB-CC-007 Vendor and third-party code lives in excluded directories | must | driver, library, hal, firmware, template | review |
KB-CC-001: C is C17 without compiler extensions¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01
Our own C sources build as ISO C17 (CMAKE_C_STANDARD 17, CMAKE_C_STANDARD_REQUIRED ON, CMAKE_C_EXTENSIONS OFF).
Vendor and generated code keeps the standard its supplier uses.
Why: Neither source handbook fixed a C standard. The pinned GCC toolchains default to C17 with GNU extensions; turning the extensions off keeps the code portable to clang on the host.
Verified by:
forbidden-patterns/cmake-c-standard(planned): a source scan for a construct the handbook bans; the parameter names the pattern set
KB-CC-002: C headers work from C++ and expose only C types¶
MUST · driver, library, hal, firmware, template · since 1.0
A header that declares a C API wraps its declarations in extern "C" guarded by __cplusplus, and its signatures use
only C types (<stdint.h>, <stdbool.h>, plain structs and enums), so C and C++ callers see the same ABI.
Verified by:
header-self-contained(implemented): every public header compiles on its own as the first include of a translation unit- review: Each C API header has the extern "C" guard and uses only C types in its signatures.
KB-CC-003: C names are snake_case with the repository prefix; file-local functions are static¶
Proposed
Warns until 2027-03-01, then fails CI. Needs C-specific naming options for .c files in place of the C++ ones
config/.clang-tidy applies today.
MUST · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01
C functions and variables are snake_case and public ones start with the repository prefix (kb_, <chip>_); typedefs
end in _t with that prefix, and enumerators are UPPER_SNAKE with the type's prefix. Functions used only in one file
are static.
Why: C has no namespaces, so the prefix is the namespace. The org .clang-tidy naming options are written for C++ and
today also lint .c files.
Verified by:
c-naming(planned): clang-tidy readability-identifier-naming with C options (snake_case functions and variables, *_t typedefs, UPPER_CASE enumerators, repository prefix) run on .c files and C API headers
See also: ADR-0008
KB-CC-004: C APIs return an error enum whose zero is success, and the result is used¶
MUST · driver, library, hal, firmware, template · since 1.0
A C function that can fail returns its module's error enum, with the success value equal to 0, and is declared with
__attribute__((warn_unused_result)) (or the project's macro for it) so a caller cannot drop the result.
Verified by:
- review: Each new fallible C function returns the module's error enum and is marked warn_unused_result.
See also: ADR-0001; SEI CERT C ERR33-C
KB-CC-005: Every C function has a prototype¶
Proposed
Warns until 2027-03-01, then fails CI. The C build must add both flags with -Werror.
MUST · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01
Every C function is declared with a full prototype (void f(void), never void f()), and every function with external
linkage has a prototype in a header before it is defined.
Verified by:
compiler-warnings/-Wstrict-prototypes(implemented): the build is warning-free with the named flag and -Werrorcompiler-warnings/-Wmissing-prototypes(implemented): the build is warning-free with the named flag and -Werror
KB-CC-006: Generated vendor code is edited only between its user-code markers¶
MUST · hal, firmware · since 1.0
Code generated by CubeMX or another vendor tool is changed only between its USER CODE BEGIN/END markers; any other
change is recorded in PATCHES.md beside it. Regenerating from the committed project file reproduces the committed
code.
Why: Changes outside the markers are lost silently at the next regeneration.
Verified by:
vendor-regen-diff(planned): CI regenerates vendor code (CubeMX) from the committed project file and fails if the result differs from the committed sources outside user-code markers and PATCHES.md- review: Edits to generated files are inside user-code markers or listed in PATCHES.md.
KB-CC-007: Vendor and third-party code lives in excluded directories¶
MUST · driver, library, hal, firmware, template · since 1.0
Vendor, generated and third-party sources live under third_party/, external/, managed_components/ or the
generator's own directory, which format and lint exclude. Our code is never placed there to avoid the checks.
Why: Reformatting vendor code makes every vendor update a conflict, so it is excluded, which only holds if the exclusion covers vendor code and nothing else.
Verified by:
- review: Code written by us is not under an excluded directory.
See also: ADR-0009