docs: Update IRQ dispatch flow documentation with unified architecture.

Rewrites the IRQ dispatch sequence diagram to document the current unified
architecture where all hard IRQ handlers are wrapped as mp_type_gen_instance
objects. Adds sentinel value table, registration phase details, and per-type
dispatch paths (bytecode function, native function, viper, generators,
generic callable). Also updates test_viper_irq.py with cleaner variable names
and direct viper callback test.

Signed-off-by: Andrew Leech <[email protected]>

Author: pi-anl

docs/coroutine-implementation.md

@@ -798,7 +798,81 @@ To understand where time is spent between hardware interrupt and Python callback
 | P13 | `timer.c:1425` | `pyb_timer_counter()` entry | Actual C function entry |
 | Px | Python code | `t.counter()` return | Counter value captured in Python |
 
-### Complete Sequence Diagram
+### Complete IRQ Dispatch Flow (Unified Architecture)
+
+The current implementation uses a unified dispatch architecture where all hard IRQ handlers
+are wrapped as `mp_type_gen_instance` objects at registration time. This eliminates type
+checks in the hot dispatch path and enables per-type optimizations via sentinel values
+in the `exc_sp_idx` field.
+
+#### Phase 1: Registration (tim.callback() call)
+
+```
+Python: tim.callback(handler)
+    │
+    ▼
+pyb_timer_callback()                                 [timer.c:1509]
+    │   Disable timer interrupt
+    ▼
+mp_irq_prepare_handler(callback, parent, ishard)     [mpirq.c:240]
+    │
+    ├─── Is generator function (mp_type_gen_wrap or native_gen_wrap)?
+    │    │
+    │    ▼ YES
+    │    mp_call_function_1(callback, parent)        Instantiate generator
+    │    │
+    │    ▼
+    │    mp_obj_gen_resume(gen, None, NULL)          Prime to first yield
+    │    │
+    │    └── Ready: gen_instance with valid ip/sp at yield point
+    │
+    ├─── Is bytecode function (mp_type_fun_bc)?
+    │    │
+    │    ▼ YES: mp_irq_wrap_bytecode_function()      [mpirq.c:61]
+    │        - Decode prelude: n_state, n_pos_args, scope_flags
+    │        - Reject if scope_flags & GENERATOR (has yield)
+    │        - Reject if n_pos_args != 1
+    │        - Allocate gen_instance with state[] + extra data
+    │        - Call mp_setup_code_state() with dummy arg
+    │        - Cache bytecode_start in extra data
+    │        - Set exc_sp_idx = IRQ_FUNC_BC (-2)
+    │
+    ├─── Is @native function (mp_type_fun_native)?
+    │    │
+    │    ▼ YES: mp_irq_wrap_native_function()        [mpirq.c:120]
+    │        - Decode native prelude for n_state
+    │        - Reject if n_pos_args != 1
+    │        - Allocate gen_instance with state[] + extra data
+    │        - Cache native_entry pointer
+    │        - Set exc_sp_idx = IRQ_FUNC_NAT (-3)
+    │
+    ├─── Is @viper function (mp_type_fun_viper)?
+    │    │
+    │    ▼ YES: mp_irq_wrap_viper_function()         [mpirq.c:156]
+    │        - Allocate gen_instance (minimal state)
+    │        - Entry point at fun_bc->bytecode directly
+    │        - Set exc_sp_idx = IRQ_VIPER (-4)
+    │
+    └─── Other callable (bound method, closure, etc)?
+         │
+         ▼ YES: mp_irq_wrap_callable()               [mpirq.c:194]
+             - Allocate gen_instance with n_state=2
+             - Store callable in state[0]
+             - Set exc_sp_idx = IRQ_CALLABLE (-5)
+```
+
+**Sentinel Values (defined in py/bc.h:169-178):**
+
+| Sentinel | Value | Handler Type |
+|----------|-------|--------------|
+| `SENTINEL` | -1 | Native generator (@native def with yield) |
+| `IRQ_FUNC_BC` | -2 | Wrapped bytecode function |
+| `IRQ_FUNC_NAT` | -3 | Wrapped @native function |
+| `IRQ_VIPER` | -4 | Wrapped @viper function |
+| `IRQ_CALLABLE` | -5 | Generic callable (bound method, etc) |
+| 0+ | n | Bytecode generator (n = exc_stack index) |
+
+#### Phase 2: Hardware IRQ Dispatch
 
 ```
 Hardware Timer Overflow (counter wraps from period→0)
@@ -810,94 +884,151 @@ TIM2_IRQHandler()                                    [stm32_it.c:705]
     │   IRQ_ENTER(TIM2_IRQn)
     ▼
 timer_irq_handler(2)                                 [timer.c:1733]
-    │   Lookup timer object from MP_STATE_PORT
+    │   Lookup: tim = MP_STATE_PORT(pyb_timer_obj_all)[1]
     ▼
 timer_handle_irq_channel(tim, 0, callback)           [timer.c:1716]
-    ├─▶ P0: IRQ_PROFILE_CAPTURE(0)                   [timer.c:1724]
-    │       Check __HAL_TIM_GET_FLAG()
-    │       Check __HAL_TIM_GET_IT_SOURCE()
-    │       __HAL_TIM_CLEAR_IT()
+    │   Check __HAL_TIM_GET_FLAG() & __HAL_TIM_GET_IT_SOURCE()
+    │   __HAL_TIM_CLEAR_IT()
     ▼
-mp_irq_dispatch(callback, tim, ishard=true)          [mpirq.c:97]
-    ├─▶ P1: MP_IRQ_PROFILE_CAPTURE(1)                [mpirq.c:98]
-    │       mp_cstack_init_with_sp_here()            [if STACK_CHECK]
-    │       mp_sched_lock()
-    │       gc_lock()
-    ├─▶ P2: MP_IRQ_PROFILE_CAPTURE(2)                [mpirq.c:116]
-    │       nlr_push(&nlr)
-    ├─▶ P3: MP_IRQ_PROFILE_CAPTURE(3)                [mpirq.c:119]
-    │       mp_obj_is_type(handler, &mp_type_gen_instance)
+mp_irq_dispatch(handler, tim, ishard=true)           [mpirq.c:289]
+    │
+    │   [Stack check setup if MICROPY_STACK_CHECK]
+    │   mp_sched_lock()
+    │   gc_lock()
+    │   nlr_push(&nlr)
+    │
+    │   ════════════════════════════════════════════════════════════
+    │   UNIFIED DISPATCH: All handlers are mp_type_gen_instance
+    │   ════════════════════════════════════════════════════════════
+    ▼
+mp_obj_gen_resume_irq(handler, tim, &ret_val)        [objgenerator.c:260]
+    │
+    │   mp_cstack_check()
+    │   Reentrance check: if (pend_exc == NULL) return ERROR
+    │
+    │   Switch on exc_sp_idx:
+    │
+    ├─── IRQ_FUNC_BC (-2): Wrapped bytecode function
+    │    │                                           [objgenerator.c:275]
+    │    │   Get extra data: bytecode_start
+    │    │   Reset: ip = bytecode_start
+    │    │   Reset: sp = &state[0] - 1
+    │    │   Reset: exc_sp_idx = 0  (for VM)
+    │    │   Place arg: state[n_state-1] = send_value
+    │    │   pend_exc = NULL (mark running)
+    │    │   mp_globals_set()
+    │    ▼
+    │    mp_execute_bytecode(&code_state, NULL)      [vm.c:285]
+    │    │   FRAME_ENTER/SETUP
+    │    │   Execute bytecodes
+    │    │   Return when function ends
+    │    ▼
+    │    Restore: exc_sp_idx = IRQ_FUNC_BC
+    │    pend_exc = mp_const_none (mark idle)
+    │
+    ├─── IRQ_FUNC_NAT (-3): Wrapped @native function
+    │    │                                           [objgenerator.c:310]
+    │    │   Get extra data: native_entry
+    │    │   pend_exc = NULL
+    │    │   args[0] = send_value
+    │    ▼
+    │    native_fun(fun_bc, 1, 0, args)              Direct call
+    │    │   ARM native code executes
+    │    ▼
+    │    pend_exc = mp_const_none
+    │
+    ├─── IRQ_VIPER (-4): Wrapped @viper function
+    │    │                                           [objgenerator.c:322]
+    │    │   Entry = fun_bc->bytecode (direct)
+    │    │   pend_exc = NULL
+    │    │   args[0] = send_value
+    │    ▼
+    │    viper_fun(fun_bc, 1, 0, args)               Direct call
+    │    │   ARM native code executes
+    │    ▼
+    │    pend_exc = mp_const_none
+    │
+    ├─── SENTINEL (-1): Native generator
+    │    │                                           [objgenerator.c:334]
+    │    │   Check: ip == 0? (exhausted)
+    │    │   *sp = send_value
+    │    │   pend_exc = NULL
+    │    │   mp_globals_set()
+    │    ▼
+    │    mp_fun_native_gen_t fun(code_state, NULL)
+    │    │   Native generator resume function
+    │    ▼
+    │    mp_globals_restore()
+    │    pend_exc = mp_const_none
+    │
+    ├─── IRQ_CALLABLE (-5): Generic callable wrapper
+    │    │                                           [objgenerator.c:355]
+    │    │   callable = state[0]
+    │    │   pend_exc = NULL
+    │    ▼
+    │    mp_call_function_1(callable, send_value)    [runtime.c:674]
+    │    │   Full type dispatch
+    │    │   (slowest path - bound method overhead)
+    │    ▼
+    │    pend_exc = mp_const_none
+    │
+    └─── Default (0+): Bytecode generator
+         │                                           [objgenerator.c:365]
+         │   Check: ip == 0? (exhausted)
+         │   *sp = send_value
+         │   pend_exc = NULL
+         │   mp_globals_set()
+         ▼
+         mp_execute_bytecode(&code_state, NULL)      [vm.c:285]
+         │   Resume from saved ip (after yield)
+         │   Execute until next yield or return
+         ▼
+         mp_globals_restore()
+         pend_exc = mp_const_none
     │
-    ├───────────────────────────────────────────────────────────────
-    │  FUNCTION PATH                    │  GENERATOR PATH
-    ├───────────────────────────────────┼───────────────────────────
-    │                                   │
-    ├─▶ P4: (before call)               ├─▶ P4: (before resume)
-    │   [mpirq.c:138]                   │   [mpirq.c:122]
-    ▼                                   ▼
-mp_call_function_1(handler, tim)        mp_obj_gen_resume(handler, tim, ...)
-    │   [py/runtime.c:674]              │   [py/objgenerator.c:153]
-    ▼                                   │
-mp_call_function_n_kw()                 ├─▶ P7: (gen_resume entry)
-    │   [py/runtime.c:671]              │   [objgenerator.c:154]
-    ▼                                   │       mp_cstack_check()
-fun_bc_call(handler, 1, 0, &tim)        │       Check ip != 0
-    │   [py/objfun.c:255]               │       Check pend_exc != NULL
-    ├─▶ P7: (fun_bc_call entry)         │       Place send_value on sp
-    │   [objfun.c:256]                  │       Set pend_exc = NULL
-    │       mp_cstack_check()           │
-    │       DECODE_CODESTATE_SIZE()     ├─▶ P8: (after send_value)
-    │       alloca()/heap for state     │   [objgenerator.c:194]
-    │       INIT_CODESTATE()            │       mp_globals_set()
-    │         - parse prelude           │
-    │         - copy args to locals     │
-    │         - init exception stack    │
-    ├─▶ P8: (after INIT_CODESTATE)      │
-    │   [objfun.c:293]                  │
-    │       mp_globals_set()            │
-    ▼                                   ▼
-mp_execute_bytecode(code_state, ...)    mp_execute_bytecode(code_state, ...)
-    │   [py/vm.c:220]                   │   [py/vm.c:220]
-    ├─▶ P9: (vm entry)                  ├─▶ P9: (vm entry)
-    │   [vm.c:272]                      │   [vm.c:272]
-    │       FRAME_ENTER()               │       FRAME_ENTER()
-    │       FRAME_SETUP()               │       FRAME_SETUP()
-    │       Setup fastn, exc_stack      │       Setup fastn, exc_stack
-    │       nlr_push(&nlr)              │       nlr_push(&nlr)
-    │       Setup ip, sp, qstr_table    │       Restore ip, sp from state
-    │       MICROPY_VM_HOOK_INIT        │       MICROPY_VM_HOOK_INIT
-    ├─▶ P10: (dispatch ready)           ├─▶ P10: (dispatch ready)
-    │   [vm.c:311]                      │   [vm.c:311]
-    │       Enter dispatch_loop         │       Enter dispatch_loop
-    │       DISPATCH() → first opcode   │       DISPATCH() → resume opcode
-    │            ▼                      │            ▼
-    │   ┌────────────────────┐          │   ┌────────────────────┐
-    │   │ Execute bytecodes  │          │   │ Execute bytecodes  │
-    │   │ until t.counter()  │          │   │ after yield resume │
-    │   └────────────────────┘          │   └────────────────────┘
-    │            ▼                      │            ▼
-    └──▶ Px: t.counter()    ◀───────────┴──▶ Px: t.counter()
-             (Python captures             (Python captures
-              TIM2->CNT here)              TIM2->CNT here)
     ═══════════════════════════════════════════════════════════════
     │
-    ▼  [After handler completes...]
-    ├─▶ P5: MP_IRQ_PROFILE_CAPTURE(5)                [mpirq.c:125/140]
-    │       nlr_pop()
-    │       gc_unlock()
-    │       mp_sched_unlock()
-    ├─▶ P6: MP_IRQ_PROFILE_CAPTURE(6)                [mpirq.c:150]
-    │       Restore stack limits        [if STACK_CHECK]
+    ▼  [Common return handling]
+    │   Check ret_kind:
+    │     NORMAL: For real generators, mark exhausted (ip=0)
+    │     YIELD: Success, handler remains active
+    │     EXCEPTION: Print error, return -1
+    │
+    │   nlr_pop()
+    │   gc_unlock()
+    │   mp_sched_unlock()
+    │   [Restore stack limits if STACK_CHECK]
     ▼
 Return to timer_handle_irq_channel()
-    │   Check result, disable if error
+    │   If result < 0: disable callback, set to None
     ▼
 Return to TIM2_IRQHandler()
     │   IRQ_EXIT(TIM2_IRQn)
     ▼
 Hardware resumes interrupted code
 ```
 
+#### Key Files Reference
+
+| Component | File | Key Lines |
+|-----------|------|-----------|
+| Sentinel definitions | `py/bc.h` | 169-178 |
+| Handler wrapping | `shared/runtime/mpirq.c` | 61-210 |
+| Unified prepare | `shared/runtime/mpirq.c` | 240-286 |
+| Unified dispatch | `shared/runtime/mpirq.c` | 289-346 |
+| Resume with sentinels | `py/objgenerator.c` | 260-414 |
+| Timer callback reg | `ports/stm32/timer.c` | 1509-1528 |
+| Timer IRQ handler | `ports/stm32/timer.c` | 1716-1766 |
+| Hardware ISR | `ports/stm32/stm32_it.c` | 705-709 |
+
+#### Soft IRQ Path (ishard=false)
+
+For soft IRQs, the flow is simpler:
+- Generators are still instantiated and primed at registration
+- Other callables are NOT wrapped (passed directly)
+- At IRQ time: `mp_sched_schedule(handler, parent)` queues the callback
+- Later: VM checks `sched_state`, calls `mp_call_function_1_protected()`
+
 ### Profiling Results (11 capture points)
 
 Timer configured at 10MHz (100ns per tick). Warm-state averages after initial cache fills.