# KRN-IRQ - Interrupts, Exceptions, Critical Sections, Scheduler Lock

Group `KRN-IRQ`. Design: `docs/specs/SPEC-002-interrupts-and-critical-sections.md`. Related groups: KRN-SCH (v0.1 §4, 03 §2), KRN-RT (v0.1 §4.10), API (SPEC-001).

KRN-IRQ-001 to 003 and 010 to 016 originate in the v0.1 specification (§3.7 and §6.6) and are restated here as the authoritative copy; their statements are unchanged. Numbers 004 to 009 were never assigned and stay unassigned. New requirements start at 017.

---

## Requirements

### KRN-IRQ-001  No blocking in interrupt context
**Statement.** Interrupt context shall not perform blocking operations.
**Rationale.** An ISR has no thread to block; blocking there corrupts the scheduler's model of who is running.
**Status.** Accepted (v0.1)
**Verification.** Test: `tests/conformance/misuse/` calls each thread-only function from an ISR in checked and release builds (API-015).
**Trace.** v0.1 §3.7; SPEC-002 §3.1; SPEC-001 §5.2

### KRN-IRQ-002  Interrupt context is distinguishable
**Statement.** Interrupt context shall be distinguishable from thread context.
**Rationale.** Every context-class check and every ISR-safe code path depends on it.
**Status.** Accepted (v0.1)
**Verification.** Test: `emb_context()` returns `EMB_CONTEXT_ISR` inside every handler level and `EMB_CONTEXT_THREAD` outside, on every port.
**Trace.** v0.1 §3.7; SPEC-002 §2; SPEC-001 §5.1

### KRN-IRQ-003  Wakeup from an interrupt permits scheduling before thread resume
**Statement.** An interrupt that makes a higher-priority thread READY shall permit scheduling before returning to thread execution when preemption is enabled.
**Rationale.** This is the definition of preemptive scheduling driven by events rather than ticks.
**Status.** Accepted (v0.1)
**Verification.** Test: ISR wakes a higher-priority thread; that thread runs before the interrupted thread's next instruction (measured by a sequence counter).
**Trace.** v0.1 §3.7; SPEC-002 §6; KRN-SCH-020

### KRN-IRQ-010  ISR-safe operations are explicit
**Statement.** ISR-safe kernel operations shall be explicitly identified.
**Rationale.** Callers cannot guess; the annotation is the contract.
**Status.** Accepted (v0.1)
**Verification.** Analysis: every public function has a `@ctx` tag (API-003); the ISR-safe set is the functions tagged `thread isr`.
**Trace.** v0.1 §6.6; SPEC-001 §9; API-014

### KRN-IRQ-011  ISR-safe operations never block the caller
**Statement.** An ISR-safe operation shall not require the caller to block.
**Rationale.** Follows from KRN-IRQ-001 for the kernel's own implementation paths.
**Status.** Accepted (v0.1)
**Verification.** Analysis: `@ctx thread isr` functions are `@blocks no`, or `@blocks timeout` with a documented ISR-safe `EMB_NO_WAIT` path.
**Trace.** v0.1 §6.6; API-014

### KRN-IRQ-012  Nesting depth is observable
**Statement.** Nested interrupt depth shall be observable to the kernel when nesting is supported.
**Rationale.** The outermost-exit rule, stack sizing, and diagnostics all need the depth.
**Status.** Accepted (v0.1)
**Verification.** Test: `emb_irq_nesting_depth()` equals the actual depth in a nested-interrupt test on Cortex-M, RISC-V with nesting, and native.
**Trace.** v0.1 §6.6; SPEC-002 §7.1

### KRN-IRQ-013  Reschedule during nested handling stays pending
**Statement.** A reschedule requested during nested interrupt handling shall remain pending until a legal thread-resume boundary.
**Rationale.** Switching threads from inside a nested interrupt would leave an interrupted handler's frame on the wrong stack.
**Status.** Accepted (v0.1)
**Verification.** Test: nested ISR wakes a higher-priority thread; the switch occurs only after the outer handler returns.
**Trace.** v0.1 §6.6; SPEC-002 §6.1; KRN-SCH-021

### KRN-IRQ-014  Bounded kernel masking
**Statement.** Interrupt masking used by kernel internals shall have bounded duration.
**Rationale.** Kernel masking is the floor of every interrupt latency figure.
**Status.** Accepted (v0.1)
**Verification.** Demonstration: `CONFIG_EMB_IRQ_LOCK_STATS` under the stress suite on HIL reports the maximum; it is published per release.
**Trace.** v0.1 §6.6; SPEC-002 §4.2, §10; KRN-RT-003

### KRN-IRQ-015  No controller assumption in the generic kernel
**Statement.** The generic kernel shall not assume a specific interrupt-controller architecture.
**Rationale.** NVIC, PLIC, CLIC, AVR's fixed vectors, and the simulator are all targets.
**Status.** Accepted (v0.1)
**Verification.** Analysis: `kernel/` includes no architecture header and references no controller register (02 §5 dependency check).
**Trace.** v0.1 §6.6; SPEC-002 §8

### KRN-IRQ-016  Documented entry, exit, save, and reschedule behavior
**Statement.** Architecture documentation shall define interrupt-entry, interrupt-exit, context-save, and rescheduling behavior.
**Rationale.** A port's correctness is reviewable only against a written description.
**Status.** Accepted (v0.1)
**Verification.** Inspection: each `docs/ports/<arch>.md` has the sections named in 05 §9.
**Trace.** v0.1 §6.6; SPEC-002 §13

### KRN-IRQ-017  Two interrupt classes
**Statement.** The kernel shall distinguish kernel-aware interrupts, which it may mask and whose handlers may call ISR-safe API, from kernel-independent interrupts, which it shall never mask and whose handlers shall call no kernel function. The boundary shall be the configured level `CONFIG_EMB_IRQ_KERNEL_LEVEL`. The kernel-independent class shall be available only on architectures with interrupt priority masking and shall be rejected at configuration time elsewhere.
**Rationale.** Zero-latency interrupts are a real-time requirement the kernel can only meet by staying out of their way (v0.1 §6.3).
**Status.** Accepted 2026-10-07
**Verification.** Test: with the class enabled on Cortex-M, a kernel-independent interrupt fires inside a kernel critical section and its handler runs within hardware latency; Analysis: Kconfig rejects `CONFIG_EMB_IRQ_ZERO_LATENCY` on Armv6-M, AVR, and native.
**Trace.** SPEC-002 §3

### KRN-IRQ-018  Key-based, nestable critical sections
**Statement.** The kernel shall provide `emb_irq_lock()` returning the previous mask state and `emb_irq_unlock(key)` restoring exactly that state, callable from thread, interrupt, and pre-kernel context, nestable, with unlocks in reverse order of locks. Both shall be O(1), shall never block or yield, and shall act as compiler barriers.
**Rationale.** Key-based masking nests for free, works identically from ISRs, and maps to one or two instructions on every architecture (SPEC-002 §4.1).
**Status.** Accepted 2026-10-07
**Verification.** Test: nesting test restores the outer state exactly; Analysis: the inline wrappers carry a `"memory"` clobber on all three compilers.
**Trace.** SPEC-002 §4.1; KRN-RT-003

### KRN-IRQ-019  Critical sections are per CPU
**Statement.** `emb_irq_lock()` shall protect against interrupts and preemption on the current CPU only. Data shared across CPUs shall be protected by a spinlock acquired with interrupts masked, which on uniprocessor builds shall compile to the critical section alone.
**Rationale.** Masking is a local operation; pretending otherwise is the classic SMP porting bug (KRN-SMP-004).
**Status.** Accepted 2026-10-07
**Verification.** Analysis: SMP specification lock-ordering rules; Test: the spinlock reduces to `emb_irq_lock()` on UP (symbol inspection).
**Trace.** SPEC-002 §4.3; KRN-SMP-002, KRN-SMP-004

### KRN-IRQ-020  Measured critical-section budgets
**Statement.** Each architecture port shall declare a cycle budget for the kernel's own critical sections and scheduler locks, and a configuration option shall measure the longest observed durations with the cycle counter. The measured maxima shall be published per reference board with full metadata.
**Rationale.** Evidence, not assertion (principle 6, KRN-RT-007).
**Status.** Accepted 2026-10-07
**Verification.** Demonstration: benchmark pipeline output per release; Test: checked builds fault when a declared budget is exceeded under the stress suite.
**Trace.** SPEC-002 §10

### KRN-IRQ-021  No blocking inside a critical section
**Statement.** A blocking call with a nonzero timeout, a thread-only operation, or a scheduler-lock release that would reschedule, made while a critical section opened by the caller is active, shall be misuse: a kernel fault in checked builds and `EMB_EPERM` in release builds.
**Rationale.** A critical section that spans a preemption point leaves interrupts masked for an unbounded time in another thread.
**Status.** Accepted 2026-10-07
**Verification.** Test: `tests/conformance/misuse/` in both build kinds.
**Trace.** SPEC-002 §4.2; SPEC-001 §5.3; KRN-RT-002

### KRN-IRQ-022  Scheduler lock semantics
**Statement.** `emb_sched_lock()` and `emb_sched_unlock()` shall be thread-only, nestable by depth, shall not mask interrupts, and the unlock that reaches depth zero shall perform any pending reschedule immediately. A scheduler-lock operation from interrupt context shall be misuse. Yield while locked shall keep the reschedule pending and shall not switch.
**Rationale.** Restates KRN-SCH-016 to 019 at the API level and fixes the two edge cases v0.1 left open.
**Status.** Accepted 2026-10-07
**Verification.** Test: conformance tests for nesting, ISR wakeup while locked, yield while locked, and the ISR misuse case.
**Trace.** SPEC-002 §5; KRN-SCH-016, KRN-SCH-017, KRN-SCH-018, KRN-SCH-019

### KRN-IRQ-023  Enumerated preemption points
**Statement.** A thread switch shall occur only at: the outermost exit of a kernel-aware interrupt when a reschedule is pending and the scheduler is not locked; inside a thread-context kernel operation that changes schedulability when the caller is not in a critical section and the scheduler is not locked; and kernel start. A thread switch shall never occur inside a nested interrupt or inside a critical section.
**Rationale.** A closed list of preemption points is what makes the kernel's behavior analyzable and the reference model finite (ADR-013).
**Status.** Accepted 2026-10-07
**Verification.** Test: differential tests against the reference model's switch oracle on the native port; Analysis: the kernel has one switch call site per architecture path.
**Trace.** SPEC-002 §6.1; KRN-SCH-021; KRN-IRQ-013

### KRN-IRQ-024  Reschedule on outermost exit
**Statement.** When an ISR-safe operation changes the scheduling decision, the kernel shall set the per-CPU reschedule-pending flag and request the architecture's deferred switch; the architecture's outermost interrupt exit shall perform the switch when the flag is set and the scheduler is not locked, and shall clear the flag.
**Rationale.** This is the single mechanism by which interrupts drive scheduling (KRN-SCH-020, KRN-IRQ-003).
**Status.** Accepted 2026-10-07
**Verification.** Test: ISR wakeup latency test on each port; the switch happens exactly once per outermost exit.
**Trace.** SPEC-002 §6.2; KRN-SCH-020

### KRN-IRQ-025  Portable handler declaration
**Statement.** The kernel shall provide `EMB_ISR(name)` as the only portable declaration of a kernel-aware handler, expanding per architecture to the form that provides the kernel's entry and exit behavior, and `EMB_ISR_RAW(name)` for handlers that call no kernel function.
**Rationale.** Cortex-M handlers are plain functions, AVR needs a full-context `naked` vector, RISC-V needs a dispatcher entry; the application should not know (09 §8).
**Status.** Accepted 2026-10-07
**Verification.** Test: the same handler source builds and passes the ISR conformance tests on every port.
**Trace.** SPEC-002 §6.2, §8.3

### KRN-IRQ-026  Bounded nesting
**Statement.** Kernel-aware interrupt nesting shall be enabled only where the architecture permits and the configuration selects it. The maximum depth shall be a configuration constant used to size the interrupt stack, and exceeding it shall be a kernel fault in checked builds.
**Rationale.** Unbounded nesting is unbounded stack use.
**Status.** Accepted 2026-10-07
**Verification.** Test: nesting-depth test on the native port with fault injection; Analysis: Kconfig gating per architecture.
**Trace.** SPEC-002 §7.1

### KRN-IRQ-027  Interrupt stacks
**Statement.** Where the architecture permits, kernel-aware interrupts shall execute on a dedicated per-CPU interrupt stack sized from the maximum nesting depth and the handlers' measured frames. Where it does not (AVR), every thread's stack budget shall include a configured interrupt reserve, and the architecture documentation shall state its size derivation.
**Rationale.** Thread stacks must be sized for thread work only wherever the hardware allows (KRN-MEM-011).
**Status.** Accepted 2026-10-07
**Verification.** Analysis: `-fstack-usage` sums in the stack report; Test: interrupt-stack overflow detection fires in checked builds under the nesting stress test.
**Trace.** SPEC-002 §7.2; KRN-MEM-011

### KRN-IRQ-028  Generic interrupt priority numbering
**Statement.** Generic interrupt priorities shall use the thread convention (a larger number is more urgent), with level 0 the least urgent kernel-aware level and levels above `CONFIG_EMB_IRQ_KERNEL_LEVEL` kernel-independent. The architecture port shall map generic levels to hardware encodings, and the hardware description shall store generic levels.
**Rationale.** One priority direction across threads and interrupts removes a documented source of configuration mistakes, and the mapping belongs in one place per architecture.
**Status.** Accepted 2026-10-07
**Verification.** Test: `emb_irq_set_level()` followed by observed preemption order on each port; Analysis: generator emits encoded values from generic input.
**Trace.** SPEC-002 §8.1

### KRN-IRQ-029  Interrupt management API
**Statement.** The kernel shall provide O(1), non-blocking `emb_irq_enable`, `emb_irq_disable`, `emb_irq_is_enabled`, `emb_irq_set_level`, `emb_irq_pend`, and `emb_irq_clear_pending`, and, only when `CONFIG_EMB_IRQ_DYNAMIC` is selected, `emb_irq_connect`. By default the vector table shall be generated from the hardware description and static.
**Rationale.** A static table costs no RAM and no init code; dynamic connection is an option for the applications that need it.
**Status.** Accepted 2026-10-07
**Verification.** Test: API conformance per port; Analysis: no RAM vector table in the tiny profile image.
**Trace.** SPEC-002 §8.2; HW-001

### KRN-IRQ-030  Exceptions route to the fault manager
**Statement.** Synchronous faults shall enter through the architecture fault entry, which shall capture the available context and dispatch to the fault manager, classifying a fault from an unprivileged partition as a partition fault and any other as a kernel fault. System-call traps shall not be treated as faults. The crash record shall be written before any recovery action.
**Rationale.** Fault handling that is designed, not improvised (01 §6); isolation requires the partition classification.
**Status.** Accepted 2026-10-07
**Verification.** Test: provoked faults of each class on native and Cortex-M (emulated) produce decodable crash records and the right classification.
**Trace.** SPEC-002 §9; 03 §10; FLT-001, FLT-002

### KRN-IRQ-031  Timer interrupt level and bound
**Statement.** The system timer interrupt shall be a kernel-aware interrupt whose level defaults to the highest kernel-aware level and is configurable, and whose handler shall be bounded to moving expired timeouts to READY, setting the reschedule flag, and programming the next event.
**Rationale.** Timeout jitter should depend on critical sections and zero-latency interrupts only, and the handler must not become a place where work accumulates.
**Status.** Accepted 2026-10-07
**Verification.** Demonstration: timer jitter benchmark; Analysis: handler `-fstack-usage` and cycle budget.
**Trace.** SPEC-002 §11; KRN-TIM-006

### KRN-IRQ-032  Latency metrics are defined and published
**Statement.** The project shall define interrupt latency, kernel masking latency, ISR overhead, ISR-to-thread latency, and scheduler-lock latency as in SPEC-002 §10.1, shall measure them on every reference board with the benchmark pipeline, and shall publish worst observed values with full metadata.
**Rationale.** KRN-RT-004 to 007 require measurability; this fixes what is measured.
**Status.** Accepted 2026-10-07
**Verification.** Demonstration: published benchmark data per release.
**Trace.** SPEC-002 §10; KRN-RT-004, KRN-RT-005, KRN-RT-006, KRN-RT-007; TEST-006

### KRN-IRQ-033  The kernel never unmasks behind a caller
**Statement.** An ISR-safe kernel operation called while the caller holds a critical section shall return with the caller's mask state unchanged; kernel internals shall save and restore mask state with the same key-based primitive and shall never unconditionally enable interrupts.
**Rationale.** A kernel that enables interrupts inside a caller's critical section breaks the caller's invariant silently.
**Status.** Accepted 2026-10-07
**Verification.** Test: every ISR-safe function called under `emb_irq_lock()`; the key read after the call equals the key before; Analysis: no unconditional enable instruction in `kernel/` or in the ports' kernel paths.
**Trace.** SPEC-002 §4.2

### KRN-IRQ-034  Context query is O(1) and exact
**Statement.** `emb_context()` shall be O(1), callable from any context including nested interrupts and pre-kernel, and shall agree with the hardware's notion of exception activity on architectures that expose one.
**Rationale.** It is executed on every checked API entry and must be cheap and right.
**Status.** Accepted 2026-10-07
**Verification.** Test: context query inside nested interrupts and before kernel start on every port.
**Trace.** SPEC-002 §2.1; KRN-IRQ-002

### KRN-IRQ-035  Checked-build detection
**Statement.** Checked builds shall detect and raise a kernel fault for: out-of-order `emb_irq_unlock()`, scheduler-lock operations from interrupt context, nesting beyond the configured maximum, interrupt stack overflow, and kernel calls from `EMB_ISR_RAW` handlers on architectures where context can be distinguished.
**Rationale.** These bugs are invisible in release builds until they corrupt state.
**Status.** Accepted 2026-10-07
**Verification.** Test: `tests/conformance/misuse/irq/` provokes each condition on the native port and on an emulated Cortex-M.
**Trace.** SPEC-002 §12; API-015

### KRN-IRQ-036  Handoff from kernel-independent interrupts
**Statement.** The architecture port shall provide `emb_arch_irq_pend_soft()`, callable from a kernel-independent handler, that pends a kernel-aware software interrupt whose handler may perform kernel work on behalf of the kernel-independent handler. Documentation shall present this as the only sanctioned path from a kernel-independent handler to the kernel.
**Rationale.** Zero-latency handlers need a way to wake threads without touching kernel state.
**Status.** Accepted 2026-10-07
**Verification.** Test: on Cortex-M with the class enabled, a kernel-independent handler pends the software interrupt and a thread is woken with measured latency.
**Trace.** SPEC-002 §3.2