Ironcore

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