Home › Embedded / firmware › Embedded C (bare metal / RTOS) AGENTS.md

Embedded C (bare metal / RTOS) AGENTS.md

AGENTS.md for embedded C firmware (bare metal, Zephyr, FreeRTOS): safety-minded C rules, memory, and hardware access.

AGENTS.mdEmbedded / firmware

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Embedded C firmware

## Commands
- Build: `cmake --preset <board> && cmake --build --preset <board>` (or `west build -b <board>` for Zephyr).
- Host tests: `ctest --preset host` (Unity/CMock or ztest on `native_sim`). Static analysis: `cppcheck --enable=warning,style src/` or clang-tidy if configured.
- Never flash or erase hardware from the agent unless asked.

## C rules (MISRA-inspired)
- C11/C17 with `-Wall -Wextra -Werror`. Fixed-width types (`uint32_t`) for hardware and protocol data; `bool` from `<stdbool.h>`.
- No dynamic allocation after init. Static buffers sized with named constants; check every bound.
- Every function returning a status is checked. Use an `enum` error type, not magic ints.
- `volatile` only for memory-mapped registers and variables shared with ISRs. Shared multi-byte data needs critical sections or atomics.
- No recursion, no variable-length arrays, no `goto` except a single cleanup label.
- Register access through the vendor HAL/CMSIS or the project's driver layer, not raw addresses scattered in app code.
- Interrupts: short handlers, clear flags, defer to tasks/main loop.
- Avoid floating point in ISRs and on MCUs without an FPU unless the project already uses it.

## Structure
- `drivers/` (hardware), `app/` (logic, hardware-independent so it's testable on host), `bsp/` (board config).

## Done
Clean build with zero warnings, host tests pass, and you report flash/RAM size changes from the map/size output.