mohitmishra786/low-level-dev-skills / skills/baremetal/interrupts-and-exceptions-baremetal
interrupts-and-exceptions-baremetal
VerifiedBare-metal interrupt and exception skill for Cortex-M NVIC. Use when writing ISRs, configuring priorities, handling HardFault, or measuring interrupt latency. Activates on queries about NVIC, ISR, vector table, HardFault, tail-chaining, or interrupt priority.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.0 KB |
SKILL.md
View on GitHub---
name: interrupts-and-exceptions-baremetal
description: Bare-metal interrupt and exception skill for Cortex-M NVIC. Use when writing ISRs, configuring priorities, handling HardFault, or measuring interrupt latency. Activates on queries about NVIC, ISR, vector table, HardFault, tail-chaining, or interrupt priority.
---
# Interrupts and Exceptions (Bare-Metal)
## Purpose
Guide agents through bare-metal interrupt handling on ARM Cortex-M: NVIC configuration, ISR writing rules, exception handlers (HardFault, BusFault), priority grouping, nesting, tail-chaining, and latency considerations.
## Triggers
- Configuring peripheral IRQ priorities
- Writing ISRs that must not block
- Debugging HardFault after enabling interrupts
- Sharing data between ISR and main loop
- Optimizing interrupt latency
## Workflow
### 1. NVIC overview (Cortex-M)
```text
Exception / IRQ flow
├── NVIC receives IRQ (priority compare with BASEPRI/PRIMask)
├── Stacking: automatic save r0-r3, r12, lr, pc, psr
├── Branch to handler from vector table
├── Handler runs (should be short)
└── Unstack and return — tail-chain if another IRQ pending
```
### 2. Enable and prioritize an IRQ
```c
#include "stm32f4xx.h" /* CMSIS device header */
void uart_irq_init(void) {
NVIC_SetPriority(USART2_IRQn, NVIC_EncodePriority(NVIC_GetPriorityGrouping(), 2, 0));
NVIC_EnableIRQ(USART2_IRQn);
}
```
Priority: lower numeric value = higher urgency (on most Cortex-M implementations). Check vendor docs for grouping bits.
### 3. ISR template
```c
void USART2_IRQHandler(void) {
if (USART2->SR & USART_SR_RXNE) {
uint8_t b = (uint8_t)USART2->DR; /* read clears RXNE */
ringbuf_push(b);
}
if (USART2->SR & USART_SR_ORE) {
(void)USART2->DR; /* clear overrun */
}
}
```
ISR rules:
- No blocking calls (`printf`, `malloc`, long loops)
- Minimize work — defer to main via flag/ring buffer
- Clear interrupt flags per datasheet (read-to-clear vs write-1-clear)
### 4. Critical sections
```c
uint32_t primask = __get_PRIMASK();
__disable_irq();
/* atomic section */
__set_PRIMASK(primask);
```
Or raise `BASEPRI` to mask lower-priority IRQs only.
### 5. HardFault handler
```c
void HardFault_Handler(void) {
__asm volatile(
"tst lr, #4\n"
"ite eq\n"
"mrseq r0, msp\n"
"mrsne r0, psp\n"
"b hard_fault_c\n"
);
}
void hard_fault_c(uint32_t *stack) {
uint32_t r0 = stack[0];
uint32_t pc = stack[6];
uint32_t psr = stack[7];
/* log pc — GDB: info registers, bt */
while (1);
}
```
Decode CFSR/HFSR registers for fault cause:
```c
volatile uint32_t cfsr = SCB->CFSR;
volatile uint32_t hfsr = SCB->HFSR;
volatile uint32_t bfar = SCB->BFAR;
```
### 6. Latency and tail-chaining
| Factor | Impact |
|--------|--------|
| Higher priority IRQ | Preempts lower |
| Tail-chaining | Back-to-back IRQs skip unstack/restack |
| FPU context | Lazy stacking adds latency on M4F/M7 |
| Long ISRs | Starves other IRQs and main |
Measure with GPIO toggle + scope, or DWT cycle counter (`DWT->CYCCNT`).
### 7. Agent usage examples
```text
/interrupts-and-exceptions-baremetal Configure NVIC priority for UART vs SysTick
/interrupts-and-exceptions-baremetal Decode HardFault stacked PC with GDB
```
## Common Problems
| Symptom | Cause | Fix |
|---------|-------|-----|
| IRQ never fires | NVIC not enabled or IRQ masked | `NVIC_EnableIRQ`; check `PRIMASK` |
| Spurious re-entry | Flag not cleared | Clear per RM (ORE needs DR read) |
| HardFault in ISR | Stack overflow | Increase `_estack`; check ISR stack |
| Lost bytes | ISR too slow | Ring buffer + higher IRQ priority |
| Priority inversion | Long critical section | Shorten `__disable_irq` window |
## Related skills
- `skills/baremetal/baremetal-startup` — vector table entries
- `skills/baremetal/uart-serial-baremetal` — UART IRQ handlers
- `skills/embedded/openocd-jtag` — GDB breakpoint in ISR
- `skills/debuggers/gdb` — examine fault stack frame
- `skills/low-level-programming/assembly-arm` — fault handler asm
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |