lab-rv32i-freertos-kernel-facade/doc/card-plan.md

K09 — Scheduler facade and scoped kernel guards

Position

• Series: FreeRTOS C++
• Lesson: L08, card K09
• Duration: 30 minutes
• Platform: Hazard3 / RV32I, FreeRTOS V11.3.0
• Evidence: kernel state, xCriticalNesting, mstatus.MIE, ELF assembly

Outcome

After 30 minutes the student can distinguish scheduler suspension from a critical section, choose a static facade versus an RAII guard, and prove that three early-return paths restore the paired kernel state.

Lesson plan

Time	Mode	Evidence
0–5	raw API	classify service calls and paired calls
5–10	critical nesting	record 0→1→2→1→0 and MIE transitions
10–15	critical guard	run three early returns; prove depth 0/MIE 1
15–20	scheduler guard	prove suspended state with interrupts enabled
20–25	nesting/this_task	nested guards, current handle, tick and yield
25–30	ABI and repair	no wrapper symbols; repair three-exit function

Canonical comparison

Operation	Context switch	Interrupt MIE	Pair
vTaskSuspendAll	deferred	remains enabled	xTaskResumeAll
taskENTER_CRITICAL	prevented	disabled	taskEXIT_CRITICAL

Scheduler suspension can nest. The inner guard's destructor decreases the nesting level but the state remains suspended until the outer guard exits. Critical sections also nest; MIE is enabled only when depth returns to zero.

Student repair

Start with a function containing a manual enter/suspend call and three returns. Replace only the pairing mechanism with the appropriate guard. Verify every path at the checkpoint rather than accepting source-level appearance as proof.

Acceptance

• static facade is non-constructible;
• both guards are non-copyable/non-movable and restore all three paths;
• raw critical values are exactly 0/1/2/1/0 and MIE 1/0/0/0/1;
• scheduler suspension leaves MIE enabled;
• nested scheduler guard remains suspended after inner destruction;
• this_task::current() equals the worker handle;
• facade and guard calls are inline with no vtable, RTTI or hosted runtime;
• target exits with PASS.

Main traps

1. Scheduler is a facade, not a scoped owner.
2. Scheduler suspension is not interrupt masking.
3. Never block while the scheduler is suspended.
4. A task-context critical guard is not an ISR-safe mutex.
5. RAII balances control flow; it does not make an invalid operation valid.