Embedded Firmware

Skill: Embedded Firmware & Device Drivers

Invocation

When this skill is loaded and a user presents a firmware or BSP task, do not execute stages directly. Immediately spawn the digital-chip-design-agents:firmware-orchestrator agent and pass the full user request and any available context to it. The orchestrator enforces the stage sequence, loop-back rules, and sign-off criteria defined below.

Use the domain rules in this file only when the orchestrator reads this skill mid-flow for stage-specific guidance, or when the user asks a targeted reference question rather than requesting a full flow execution.

Pre-run Context

Before executing or advising on any stage, read the following files if they exist:

1. memory/firmware/knowledge.md — known failure patterns, successful tool flags, PDK/tool quirks. Incorporate its guidance into every stage decision. If absent, proceed without it.
2. memory/firmware/run_state.md — current run identity (run_id, design_name, tool, last_stage). Use this to resume correctly after interruption. If absent, a new run is starting; the orchestrator will create this file before the first stage.

This pre-run read applies whether this skill is loaded by a user or called by the orchestrator mid-flow. It ensures the fix database is consulted before any diagnosis step.

Purpose

Guide BSP creation, peripheral driver development, RTOS integration, and system-level firmware validation. The firmware layer is the first software to run on real silicon — correctness here enables all subsequent SW development.

Supported EDA Tools

Open-Source

• GCC cross-compiler (arm-none-eabi-gcc, riscv64-unknown-elf-gcc) — bare-metal firmware compilation
• OpenOCD (openocd) — open-source on-chip debugger; supports JTAG/SWD for bring-up
• GDB cross-debugger (arm-none-eabi-gdb) — source-level debugging over OpenOCD
• QEMU (qemu-system-arm, qemu-system-riscv64) — firmware validation before hardware is available

Proprietary

• J-Link GDB Server (JLinkGDBServer, dialect segger) — high-speed JTAG/SWD probe from SEGGER
• Lauterbach TRACE32 (t32marm, dialect lauterbach) — hardware trace and debug for bring-up
• Arm Development Studio (armds, dialect arm) — Eclipse-based IDE with Arm compiler and debugger

Stage: bsp_development

Domain Rules

1. Startup code (crt0.S/startup.c) must in order:
   • Set stack pointer to __stack_top (from linker script)
   • Copy .data LMA → VMA
   • Zero .bss
   • Call SystemInit()
   • Branch to main()
2. SystemInit() order: power stable → PLLs → clock mux → peripherals
3. Interrupt controller: define vector table, IRQ enable/disable API, priority API
4. memory_map.h: ALL peripheral base addresses and register offsets — no magic numbers
5. All hardware register accesses: volatile pointer dereference
6. Atomic read-modify-write on hardware registers: disable IRQ or use atomic ops
7. Memory barriers (DMB/DSB or equivalent) around hardware access sequences
8. BSP must be RTOS-agnostic — no OS API calls in BSP layer

QoR Metrics to Evaluate

• Boot: chip reaches main() within expected startup time
• Clocks: all PLLs locked; peripherals clocked correctly
• Interrupts: vector table valid; default handler traps unhandled exceptions
• Memory: .data initialised; .bss zeroed (verify with memory read)

Common Issues & Fixes

Output Required

• startup.S and system_init.c
• memory_map.h (complete register definitions)
• Linker scripts
• BSP build system

Stage: peripheral_drivers

Driver Architecture (HAL pattern)

status_t PERIPH_Init(PERIPH_Type *base, const periph_config_t *config);
status_t PERIPH_WriteBlocking(PERIPH_Type *base, const uint8_t *data, size_t len);
status_t PERIPH_TransferNonBlocking(PERIPH_Type *base, periph_handle_t *h, periph_xfer_t *x);
void     PERIPH_HandleIRQ(PERIPH_Type *base, periph_handle_t *handle);

Domain Rules

1. All register accesses: via memory_map.h — no inline hex addresses
2. All polling loops: timeout counter; return error code on timeout
3. All functions: return status_t — never void for operations
4. Thread safety: document per-driver; note mutex requirement if not safe
5. DMA: provide DMA variants for all high-bandwidth peripherals
6. Power management: suspend()/resume() hooks for low-power modes
7. Callbacks: callback function pointers for async completion

Required Peripheral Coverage

QoR Metrics to Evaluate

• All peripheral loopback tests: PASS
• DMA transfers: correct data at correct address
• No infinite loops — all error paths return timeout status
• All error paths return meaningful status codes

Output Required

• Driver source files (.c/.h per peripheral)
• Driver unit test suite
• Driver API documentation (Doxygen-compatible)

Stage: rtos_integration

FreeRTOS Domain Rules

1. Port layer: implement portmacro.h for target architecture
2. Tick timer: hardware timer for RTOS tick (default 1 ms)
3. Context switch: implement SVC and PendSV handlers or equivalent
4. Heap: use heap_4.c (best-fit with coalescence)
5. Stack sizing: profile with uxTaskGetStackHighWaterMark(); add 20% margin
6. configCHECK_FOR_STACK_OVERFLOW: set to 2 during development
7. Priority inversion: use mutexes with priority inheritance