lab-rv32i-freertos-mutex/doc/card-plan.md

K11 — Mutex, LockGuard and priority inheritance

Position

• Series: FreeRTOS C++
• Lesson: L10, card K11
• Duration: 30 minutes
• Actors: LOW=1, MEDIUM=2, HIGH=3, coordinator=4
• Storage: static mutex control and static task stacks

Outcome

The student distinguishes mutex ownership from semaphore signaling, repairs early returns with LockGuard, and explains every state/priority transition in a measured priority-inheritance schedule.

Lesson plan

Time	Mode	Evidence
0–5	ownership	owner-only give; ordinary mutex non-recursive
5–10	LockGuard	three returns each give exactly once
10–15	setup	LOW takes; HIGH attempts; MEDIUM ready
15–20	inheritance	HIGH blocked; LOW priority rises 1→3
20–25	release	MEDIUM has not run; HIGH acquires next
25–30	restore	LOW returns to 1; protected counter is 11

Acceptance

• mutex handle equals caller static control and heap delta is zero;
• LOW owns at first checkpoint and HIGH owns after handoff;
• HIGH is blocked while waiting;
• LOW priority is exactly 1, then 3, then 1;
• MEDIUM does not run before LOW release;
• event order proves inherited LOW precedes MEDIUM;
• guard restores on every host early-return path;
• ordinary recursive attempt fails;
• target exits with PASS and shared counter 11.

Main traps

1. A binary semaphore is not an ownership mutex and has no inheritance.
2. Ordinary mutex recursion deadlocks/fails; use a recursive type deliberately.
3. Only the owner may unlock.
4. Mutex APIs are not ISR APIs.
5. Inheritance is temporary and bounded by the held mutex lifetime.