Hardware and porting¶
Porting the stack to an MCU family, bringing up a board, working with vendor-generated code, and what shipping firmware must do on the hardware. The MCU port lives in kb-core's interfaces/mcu/<family>/; the board side is in the board HAL's bind.
| Rule | Level | Applies to | Verified |
|---|---|---|---|
| KB-HW-001 Every MCU family implements the foundation interfaces | must | library | planned |
| KB-HW-002 A port passes the conformance suite before it is done | must | library, hal | planned |
| KB-HW-003 The port owns vendor-callback bridging, one entry point per interrupt family | must | library, hal | review |
| KB-HW-004 Configure peripherals the way the vendor SDK expects | guide | library, hal | none |
| KB-HW-005 Clock speeds and bus settings come from configuration, not literals | should | library, hal | review |
| KB-HW-006 A port publishes its measured performance | should | library | review |
| KB-HW-007 A board HAL starts from a complete hardware picture | guide | hal | none |
| KB-HW-008 STM32 ports use CubeMX, the STM32 HAL, CMake and FreeRTOS by default | guide | library, hal | none |
| KB-HW-009 Vendor-generated code is regenerable and never hand-edited outside its markers | must | hal, firmware | planned |
| KB-HW-010 Heavily used buses use DMA, with a timed-out polled fallback | should | library, hal | review |
| KB-HW-011 Hardware and protocol changes update the specification in the same pull request | should | driver, hal, firmware | review |
| KB-HW-012 Shipping firmware enables the watchdog, serviced from a supervisor task | must | firmware | planned |
| KB-HW-013 Shipping firmware configures brownout reset | must | firmware | planned |
| KB-HW-014 Over-the-air updates verify signatures and can roll back | must | firmware | planned |
| KB-HW-015 Firmware logs why it booted and what it is | should | firmware | review |
| KB-HW-016 Firmware reports its health and keeps a crash record | should | firmware | review |
| KB-HW-017 A factory test mode exists and is documented | should | firmware | review |
| KB-HW-018 Control outputs reach their inactive level before they are enabled | must | driver, library, hal, firmware, template | planned |
| KB-HW-019 Port conformance covers the shared-bus faults found on hardware | must | library, hal | planned |
KB-HW-001: Every MCU family implements the foundation interfaces¶
Proposed
Warns until 2027-03-01, then fails CI. The foundation set is new to the Kokeb standard.
MUST · library · since 1.0 · enforced from 2027-03-01
Each real MCU family in interfaces/mcu/<family>/ implements BaseSpi, BaseI2c, BaseGpio, BaseAdc, BaseNvs,
BaseLogger, BaseTemperature and BasePeriodicTimer. Other Base* interfaces are implemented when the MCU has the
hardware and a consumer needs it; there are no stubs, and enabling one the family lacks fails at CMake configure time.
Why: Every handler, manager and HAL then compiles on a new family without change. A stub that compiles but does nothing turns a configuration mistake into a bench fault.
Verified by:
mcu-foundation-set(planned): each real family under interfaces/mcu/ implements the eight foundation Base* interfaces, and enabling an optional one the family lacks fails at CMake configure time
See also: ADR-0014
Explained in: standards/library.md
KB-HW-002: A port passes the conformance suite before it is done¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · library, hal · since 1.0 · enforced from 2027-03-01
A new or changed MCU port passes the Base* conformance tests: on the host against a mocked vendor SDK where the SDK
allows, and as loopback tests on a board (SPI MOSI to MISO, UART TX to RX, GPIO pairs). After a port, vendor-callback
wiring, MCU-gated drivers and the family's build options are re-tested on the board.
Verified by:
port-conformance(planned): the Base* conformance suite passes for the named MCU family, on the host against a mocked SDK and, on a scheduled job with a board, as loopback tests- review: The pull request links the loopback run on a board, or is marked not verified on hardware.
Explained in: checklists/new-board-hal.md
KB-HW-003: The port owns vendor-callback bridging, one entry point per interrupt family¶
MUST · library, hal · since 1.0
The family's port bridges vendor callbacks (HAL_GPIO_EXTI_Callback, DMA completion) to its objects through a static
dispatch table or a handle lookup, with one documented entry point per interrupt family. The bridge takes no mutex; it
sets an OsEventFlags bit or gives a SignalSemaphore and returns.
Verified by:
- review: Each interrupt family has one entry point documented in the port header, and no code reached from it takes a mutex.
Explained in: standards/threading-and-timing.md
KB-HW-004: Configure peripherals the way the vendor SDK expects¶
GUIDE · library, hal · since 1.0
Where the vendor's culture is a configuration tool (STM32CubeMX, MCUXpresso), the port wraps the generated handles;
where the SDK has a full run-time API (ESP-IDF), the port configures the peripheral itself from a spec. Either way the
rest of the stack sees only the Base* interface.
Explained in: standards/library.md
KB-HW-005: Clock speeds and bus settings come from configuration, not literals¶
SHOULD · library, hal · since 1.0
A port object takes clock speed, mode and pins from its constructor spec or the board config; it hard-codes none of them.
Verified by:
- review: Bus clocks, modes and pins in the port come from the spec or the board config.
Explained in: standards/hal.md
KB-HW-006: A port publishes its measured performance¶
SHOULD · library · since 1.0
A port's documentation lists measured timings for the foundation operations (an 8-byte SPI transfer, a GPIO set, an ADC read, a 2-byte I2C transfer, periodic-timer jitter) with the clock rates used, so HAL authors can tell whether a hot path needs more.
Verified by:
- review: The port's documentation has a measured timing table for the foundation operations.
KB-HW-007: A board HAL starts from a complete hardware picture¶
GUIDE · hal · since 1.0
Before writing a board HAL, have the schematic and pin-out, the full chip list, the chosen MCU variant, and a released driver and kb-core support for every chip and peripheral on the board. A missing peripheral goes into kb-core first.
Explained in: checklists/new-board-hal.md
KB-HW-008: STM32 ports use CubeMX, the STM32 HAL, CMake and FreeRTOS by default¶
GUIDE · library, hal · since 1.0
Start an STM32 family with STM32CubeMX for clocks and pins, the STM32 HAL (LL where latency needs it), CMake, and FreeRTOS or ThreadX at a 1 kHz tick.
See also: ADR-0006
KB-HW-009: Vendor-generated code is regenerable and never hand-edited outside its markers¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · hal, firmware · since 1.0 · enforced from 2027-03-01
A CubeMX project generates peripheral initialisation as .c/.h pairs, copies only the needed libraries and never uses
the single-main.c option. The .ioc and the generated tree are committed; hand-written code goes only between USER
CODE markers or in separate files (vendor weak callbacks are overridden in the project's own interrupt file), and any
other patch to generated files is listed in PATCHES.md.
Why: Regenerating from the .ioc must not lose work or silently revert a fix.
Verified by:
cubemx-discipline(planned): the .ioc sets ProjectManager.CoupleFile=true and the library-copy option, and regenerating from the .ioc reproduces the committed tree except for USER CODE blocks and the patches listed in PATCHES.md
KB-HW-010: Heavily used buses use DMA, with a timed-out polled fallback¶
SHOULD · library, hal · since 1.0
SPI, I2C and UART ports use DMA when the board wires a DMA channel and fall back to polled transfers otherwise; both paths have a timeout and both are tested.
Verified by:
- review: The DMA and polled paths both have a timeout and a test.
KB-HW-011: Hardware and protocol changes update the specification in the same pull request¶
SHOULD · driver, hal, firmware · since 1.0
A change that follows a hardware or protocol change updates the affected Hardware page, board specification or protocol description in the same pull request.
Verified by:
- review: The Hardware or protocol documentation matches the change.
KB-HW-012: Shipping firmware enables the watchdog, serviced from a supervisor task¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · firmware · since 1.0 · enforced from 2027-03-01
Release firmware enables the hardware or task watchdog, and one supervisor task services it only while the tasks it watches report progress.
Why: A hung task with a live actuator must end in a reset, not a stuck output.
Verified by:
sdkconfig-defaults/watchdog(planned): sdkconfig.defaults of every ESP-IDF project sets the named value (freertos-hz is CONFIG_FREERTOS_HZ=1000)- review: The supervisor services the watchdog only when every watched task has reported.
KB-HW-013: Shipping firmware configures brownout reset¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · firmware · since 1.0 · enforced from 2027-03-01
Release firmware enables brownout detection with reset, at a threshold above the board's minimum supply.
Verified by:
sdkconfig-defaults/brownout(planned): sdkconfig.defaults of every ESP-IDF project sets the named value (freertos-hz is CONFIG_FREERTOS_HZ=1000)
KB-HW-014: Over-the-air updates verify signatures and can roll back¶
Proposed
Warns until 2027-03-01, then fails CI.
MUST · firmware · since 1.0 · enforced from 2027-03-01
Firmware that updates over the air keeps the previous image and rolls back to it when the new one fails to confirm itself. A product that signs its images verifies the signature before booting an update.
Verified by:
sdkconfig-defaults/ota(planned): sdkconfig.defaults of every ESP-IDF project sets the named value (freertos-hz is CONFIG_FREERTOS_HZ=1000)- review: The good-update and rollback paths were exercised on a board before release.
KB-HW-015: Firmware logs why it booted and what it is¶
SHOULD · firmware · since 1.0
On every start the firmware logs the reset reason from the bind and its own version, release train and provenance header.
Verified by:
- review: The boot log has the reset reason and the version and provenance.
Explained in: standards/product.md
KB-HW-016: Firmware reports its health and keeps a crash record¶
SHOULD · firmware · since 1.0
Firmware captures free heap, the largest free block and uptime periodically in its diagnostics, and persists a crash record (reason, task, program counter) to NVS or external storage for the next boot.
Verified by:
- review: Health figures are in the diagnostics and a crash record survives a reset.
KB-HW-017: A factory test mode exists and is documented¶
SHOULD · firmware · since 1.0
Production firmware has a factory test mode, entered by a documented method (an NVS flag or a button held at boot), and the product's documentation describes what it tests.
Verified by:
- review: The factory mode, how to enter it and what it tests are documented.
KB-HW-018: Control outputs reach their inactive level before they are enabled¶
Proposed
Warns until 2027-03-01, then fails CI. The polarity half is KB-CPP-038.
MUST · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01
A port drives every control output (reset, enable, soft chip-select, command/data, write-protect) to its inactive level before it enables the pin's output driver and before the first frame; a soft chip-select is written high before its pin is configured as an output. Each pin's idle level and polarity are stated once in the port contract (the driver's Porting page) as logical ACTIVE and INACTIVE.
Why: Observed on hardware: GPIO defaults left an active-low reset asserted and two chip-selects low together until the first driver call.
Verified by:
port-conformance(planned): the Base* conformance suite passes for the named MCU family, on the host against a mocked SDK and, on a scheduled job with a board, as loopback tests- review: Each port sets the output level before the direction; the Porting page lists every control pin with its idle level; on a real MCU the bench bring-up checks the pins at reset.
See also: ADR-0003
Explained in: standards/driver.md
KB-HW-019: Port conformance covers the shared-bus faults found on hardware¶
Proposed
Warns until 2027-03-01, then fails CI. The buffer ownership half is KB-CPP-040 and KB-CPP-043.
MUST · library, hal · since 1.0 · enforced from 2027-03-01
Port conformance (KB-HW-002) also proves: the first frame after any mode or clock change is intact; chip-select lines are at their idle level before any driver starts; UART input is flushed before a transmit and never between transmit and receive, and the turnaround is observed; an I2C bus clear runs before a retried start-up; every operation is bounded by a timeout; transfer buffers live in memory the bus and its DMA can reach, owned by the driver object, never on a caller's stack or in a function-local static.
Why: Observed on hardware, each of these host faults looked like a chip fault on the bench.
Verified by:
port-conformance(planned): the Base* conformance suite passes for the named MCU family, on the host against a mocked SDK and, on a scheduled job with a board, as loopback tests- review: The MCU-specific items (DMA-capable memory, first frame after a clock change) are run on the bench.
Explained in: standards/hal.md