ADR-0014: Chip-, MCU- and product-specific code each have one place¶
- Status: Accepted
- Date: 2026-11-05
Context¶
"Platform-specific" was used for three different things: code that knows one chip, code that knows one MCU, and
code that knows one product. Treating them alike let MCU calls and #ifdef ESP_PLATFORM blocks spread into shared
code, and let one product's needs (its pins, its channels, its limits) end up in drivers and the core, where every
other product then carried them.
Decision¶
| Kind | Where it lives | Rule |
|---|---|---|
| Chip-specific | Its own driver and its handler | Fine there |
| MCU-specific | Only interfaces/mcu/<family>/ in kb-core (above core: a board HAL's bind, a product's platform/) |
The build selects the family and compiles only that folder; each header there #errors in any other build |
| Product-specific | The product's board HAL or repository | Never in kb-core or a driver |
KB_MCUselects the family. Drivers that need one MCU's peripheral are listed in an MCU gate table incmake/kb_build_settings.cmake("WS2812:ESP32:RMT"), so enabling them on another MCU stops CMake.- Differences between chip variants of one family use the vendor's capability macros, only inside
mcu/<family>/. - Shared code never tests
ESP_PLATFORMor a similar platform macro. - Product needs become generic extension points: config masks, profile tables passed in, backend interfaces, injected loggers.
- The test for a change to kb-core or a driver: could a second, made-up product with a different board use it without editing core?
Consequences¶
- Shared code compiles for every family and on the host, and a lint can check it by searching for platform macros.
- A wrong MCU for a driver is a configure error, not a link error or a bench surprise.
- Some product requests take longer, because the generic extension point has to be designed first.
- A peripheral only one family has gets a
Base*interface and one implementation, which is more code than a direct call but keeps the call sites portable.