embedded-code-logic

embedded-code-logic

A Claude Code skill that helps design and review the control flow and concurrency of embedded firmware — state machines, ISR↔task cooperation, driver logic, and the classic concurrency hazards (race conditions, deadlock, priority inversion, shared-resource protection, timeouts, watchdog integration).

It targets MCU bare-metal / register-level code and FreeRTOS, and it is deliberately about logic — not register config or datasheet lookups. When the question is "which bit in USART1->CR1," that belongs to the chip's Reference Manual; when the question is "this driver deadlocks sometimes" or "how should I structure this state machine," that is this skill's territory.

Install

Copy (or symlink) the folder into your Claude Code skills directory:

# macOS / Linux
cp -r embedded-code-logic ~/.claude/skills/

# Windows (Git Bash)
cp -r embedded-code-logic ~/.claude/skills/

The skill auto-triggers on natural language. Try:

• "帮我看看这段 ISR 写得对不对" (+ paste interrupt code)
• "设计一个带重试和故障态的传感器状态机"
• "TaskH 偶尔卡死几百毫秒，帮我诊断"
• "review this FreeRTOS driver for race conditions"

What it covers

Six principles, each tied to the concrete failure mode it prevents rather than a list of MUSTs:

1. ISRs signal, they do not compute — keep the handler tiny, defer to a task.
2. Shared data crossing the ISR↔task boundary must be protected — volatile is not atomic and not a memory barrier; pick ring buffer / queue / critical section.
3. Never block without a timeout — every wait is finite and has a handler.
4. Prefer non-blocking state machines over delays — poll-with-deadline, not vTaskDelay.
5. Concurrency hazards and the right fix for each — race (mutual exclusion), deadlock (lock ordering), priority inversion (mutex with inheritance, not a binary semaphore).
6. Driver control flow & single ownership — one owning task per peripheral, checked init sequence, errors propagated not swallowed.

Plus a reviewer checklist that turns the principles into yes/no questions.

Structure

embedded-code-logic/
├── SKILL.md                       # principles + reviewer checklist (main entry)
└── references/                    # load-on-demand, with C examples
    ├── isr-task-cooperation.md    # deferred-ISR pattern, FromISR APIs, SPSC ring buffer
    ├── concurrency-protection.md  # race fixes, deadlock matrix, priority-inversion example
    ├── state-machines.md          # enum+switch, transition table, hidden state, worked driver
    └── timing-timeouts.md         # non-blocking delay, timeouts, watchdog, deadline scheduling

SKILL.md stays lean; the references are read only when a principle needs concrete code (progressive disclosure).

License

MIT — see LICENSE.