feat: add lab-rv32i-freertos-event-group card

2026-07-21 19:13:55 +02:00
commit b72408da7f
67 changed files with 37880 additions and 0 deletions
@@ -0,0 +1,49 @@
+# K13 — EventGroup and coordinated state
+
+K13 provides a typed `EventMask<Enum>` and `EventGroup<Enum>` over static
+FreeRTOS event-group storage. Wait policy is explicit (`any`/`all`) and clear
+policy is explicit (`keep`/`clear_on_exit`). `WaitResult` retains the snapshot
+returned by the kernel and evaluates it against the requested policy.
+
+Three workers publish UART, GPIO and APP readiness bits. The coordinator then
+executes a deterministic state sequence:
+
+```text
+wait all, keep          -> snapshot 0x7, current 0x7
+clear GPIO              -> clear returns 0x7, current 0x5
+wait all, 3 ticks       -> timeout snapshot 0x5, unsatisfied
+wait any UART|APP, clear-> snapshot 0x5, current 0x0
+```
+
+Setting UART twice leaves the mask at `0x1`, proving an event bit is idempotent
+state and not an occurrence counter.
+
+## Build
+
+```sh
+make check
+```
+
+## Debug
+
+```gdb
+b event_group_debug_checkpoint
+p g_coordinator_state_seen
+p g_worker_set_result
+p g_uart_repeat_mask
+p/x g_all_snapshot
+p/x g_mask_after_gpio_clear
+p/x g_timeout_snapshot
+p g_timeout_ticks
+p/x g_any_snapshot
+p/x g_final_mask
+p g_event_group_pass
+```
+
+## Scope boundary
+
+Bits coordinate state but carry neither payload nor occurrence count. A
+clear-on-exit policy can race with other consumers unless designed explicitly.
+The ISR form of setting bits is not a direct edit of the event group; FreeRTOS
+defers that operation through the timer service path, which is outside this
+task-context card.