AI agent skill · by @GadaaLabs

Ironcore

State machines, ISRs, RTOS, hardware abstraction, and timing analysis — domain expertise for electrical and embedded systems engineers

Archived 2026-10-23 · Source updated 2026-04-29. Check the original repository for the latest version.

SKILL.md instructions

# 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

| Skill | Integration |
|-------|-------------|
| `forge` | Write hardware-in-loop tests first |
| `hunter` | Debug timing violations, race conditions |
| `sentinel` | Verify timing budgets before claiming success |
| `chronicle` | Store hardware-specific patterns |

---

## 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