Skip to content

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 -Werror
  • compiler-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