gadaalabs/claude-code-on-steroids/ironcore

Embedded Systems Patterns

Overview

IRONCORE — Iron is hard, precise, and unforgiving — exactly like embedded systems. When invoked: assesses hardware context (bare-metal / RTOS / HAL / ISR), loads the relevant pattern file, and enforces embedded discipline — deterministic timing, ISR safety, lock-free queues, type-safe register access.

Core principle: Embedded systems have zero margin for error — timing violations, race conditions, and memory corruption cause real-world failures. Design for determinism and verifiability.

Announce at start: "Running IRONCORE for embedded systems patterns."

Entry Point — First 5 Minutes

HARDWARE CONTEXT ASSESSMENT:
 
"What platform and RTOS?"
A) Bare-metal (no RTOS) — Cortex-M, AVR, PIC
B) FreeRTOS / Zephyr / ThreadX
C) Linux embedded (Yocto, Buildroot)
D) FPGA / HDL
E) Mixed (Linux + MCU co-processor)
 
"What is failing or being designed?"
1) State machine / control flow
2) ISR / interrupt handling
3) RTOS task design / scheduling
4) Hardware register / peripheral driver
5) Timing / real-time requirements
6) Communication protocol (SPI, I2C, UART, CAN)
7) Memory / stack corruption

Context → Section mapping:

• Any + 1 → State Machine Design (patterns/state-machines.md)
• Any + 2 → ISR Safety Rules (patterns/isr-safety.md)
• B + 3 → RTOS Task Decomposition (patterns/rtos-tasks.md)
• Any + 4 → Hardware Register Abstraction (patterns/hardware-abstraction.md)
• Any + 5 → Deadline Analysis (patterns/rtos-tasks.md — WCRT section)
• Any + 7 → Stack Size Estimation + run hunter

Critical first question for ALL embedded work: "Is this hard real-time (missed deadline = failure) or soft real-time (missed deadline = degraded performance)?"

State Machine Design

Load patterns: `patterns/state-machines.md`

Required elements:

1. HSM structure — entry/exit actions, parent states for hierarchy
2. Transition table — explicit (from, event, to, action) rows — no implicit transitions
3. Guard conditions — typed guards, not raw conditionals inside handlers
4. Tests — transition coverage, no unreachable states

Rule: All events must be handled in all states (even if the handler is explicit ignore).

ISR Safety Rules

Load patterns: `patterns/isr-safety.md`

Non-negotiable rules:

1. Minimal ISR work — read hardware register, push to buffer, set flag. Nothing else.
2. volatile for all ISR-shared variables — compiler cannot cache these
3. Memory barriers — __DMB() before setting flags, before reading data
4. Lock-free queues for ISR→main — SPSC queue, no mutex (mutexes block ISRs)
5. No malloc/free in ISRs — ever

RTOS Task Decomposition

Load patterns: `patterns/rtos-tasks.md`

Steps:

1. Identify tasks by rate: control loop, communication, UI, logging
2. Assign priorities by rate monotonic: shorter period = higher priority
3. Verify schedulability: Σ(WCET/period) ≤ n(2^(1/n)−1) (for n=3: ≤ 0.78)
4. Measure stack usage with watermark pattern, add 25% margin
5. Choose IPC — queue for data, semaphore for events, mutex for shared resources

Priority inversion: Always use xSemaphoreCreateMutex() (has priority inheritance), never binary semaphore for resource protection.

Hardware Register Abstraction

Load patterns: `patterns/hardware-abstraction.md`

Required:

1. Type-safe register structs — volatile fields, bitfield macros (REG_SET/GET/MASK)
2. MMIO safety — NULL check, alignment check, __DMB() after writes
3. Endianness macros — HTONS/HTONL/NTOHS/NTOHL for all network/protocol data
4. Timing checklist — clock freq, setup/hold times, interrupt latency, watchdog timeout

Red Flags

Never:

• Do blocking operations in ISR
• Share ISR↔main data without volatile
• Use malloc/free in ISRs or time-critical code
• Ignore stack overflow potential
• Skip deadline analysis for hard real-time tasks

Always:

• Use memory barriers for ISR-main communication
• Verify RMS utilization bound before deploying
• Test state machines for unreachable states
• Validate MMIO access bounds
• Document timing requirements and verify them

Integration with Superpowers

Final Checklist

• [ ] State machine has no unreachable states
• [ ] ISR does minimal work (deferred processing used)
• [ ] Lock-free data structures for ISR-main communication
• [ ] Memory barriers in place
• [ ] RMS utilization bound verified (≤ 0.78 for 3 tasks)
• [ ] Stack sizes validated with watermark + 25% margin
• [ ] WCRT analysis passes for all tasks
• [ ] MMIO access validated and bounded
• [ ] Endianness handled correctly
• [ ] Timing requirements documented and verified