Exercises — FreeRTOS IPC — queues, semaphores, mutexes, event groups

Object: binary semaphore (given from the ISR with xSemaphoreGiveFromISR). Why: the ISR only needs to signal "something happened" — a single yes/no wake-up. A binary semaphore is exactly a 0/1 flag. Why not a mutex: a mutex has an owner — only the task that took it may give it. An ISR has no task identity, so there is nobody to own or inherit priority. Ownership rules forbid an ISR releasing a mutex, so priority inheritance would be undefined. Signalling is not locking.

Object: queue of uint16_t items. Why: you need to transfer data (the reading itself), keep order (FIFO), and buffer a few while B is slow. A queue copies the bytes into kernel-owned storage, so A can overwrite its local variable the instant it returns without harming the message already in flight. This is the Producer–Consumer Pattern.

Object: event group with two bits, waited on with the AND rule (xWaitForAllBits = pdTRUE). Why: you're waiting on a logical combination of independent conditions. One semaphore answers one yes/no; you'd need awkward juggling of two of them. An event group lets a single task block until the chosen mask (both bits) is satisfied — regardless of the order they arrive.

Call: xQueueCreate(8, sizeof(struct sensor_sample)); → xQueueCreate(8, 12); Storage for messages: length × itemSize = 8 × 12 = 96 bytes. Why this size: a queue copies each item by value, so it must own length × itemSize bytes to hold up to length full copies at once. (There is also a small control block and two lists of blocked tasks, but the message buffer itself is 96 bytes.)

The real macro rounds up. In FreeRTOS the definition is essentially $\text{pdMS\_TO\_TICKS}(ms)=\frac{ms\times \text{configTICK\_RATE\_HZ}}{1000}$ computed in integer arithmetic — and the common implementation adds a rounding bias so partial ticks are rounded up, e.g. ((ms * configTICK_RATE_HZ) + 999) / 1000 on some ports. This matters whenever the tick rate does not divide 1000 evenly.

Why +999, step by step (the integer-arithmetic "why"). Integer division a / b in C throws away the remainder — it floors, i.e. rounds down. But a timeout must never be shorter than requested, so we need to round up. The universal integer trick for "divide and round up" is: $\lceil \frac{a}{b}\rceil =\lfloor \frac{a+(b-1)}{b}\rfloor$ Why exactly $b-1$ and not some other number? Write $a=qb+r$ with remainder $0\le r\le b-1$.

• If $r=0$ (divides evenly): adding $b-1$ gives $qb+(b-1)$, and $\lfloor (qb+b-1)/b\rfloor =q$ — unchanged, correct.
• If $r\ge 1$ (there is a leftover partial tick): $a+(b-1)=qb+r+b-1\ge (q+1)b$, so the floor becomes $q+1$ — bumped up by exactly one, correct. Adding less than $b-1$ would fail to bump some cases; adding more could over-bump when $r=0$. So $b-1$ is the unique smallest bias that rounds up only when a remainder exists. Here $b=1000$ (the ms→s denominator), so the bias is $1000-1=999$.

At 1000 Hz: $\frac{50\times 1000}{1000}=50$ exactly, no rounding needed. So the sender blocks up to 50 ticks (= 50 ms). At 300 Hz (does not divide 1000): take $ms=52$: exact is $\frac{52\times 300}{1000}=15.6$. Plain truncation gives $\lfloor 15.6\rfloor =15$ ticks (too short!); the round-up form $\lfloor (52\times 300+999)/1000\rfloor =\lfloor 16599/1000\rfloor =16$ ticks. The rounded-up answer guarantees you wait at least the requested time, never less. Why &v: the API takes a pointer to the item to copy. FreeRTOS reads itemSize bytes starting at that address and copies them into the queue. Passing v (the value) would be a type error — the function does not know your item's type, only its byte count and a source address.

BaseType_t woke = pdFALSE;                 // (1) a flag the API sets
xSemaphoreGiveFromISR(sem, &woke);         //     if a higher-prio task woke
portYIELD_FROM_ISR(woke);                  // (2) switch to it on ISR exit

Why the woke flag: giving the semaphore may unblock a task higher priority than whatever was interrupted. xSemaphoreGiveFromISR sets woke = pdTRUE to tell you so. Why portYIELD_FROM_ISR: if a higher-priority task became ready, we context-switch to it immediately on ISR return, instead of waiting for the next scheduler tick — this minimises wake-up latency. This is Interrupt Service Routines & Deferred Processing in action.

#define WIFI_BIT (1 << 0)   // = 0b01 = 1
#define CFG_BIT  (1 << 1)   // = 0b10 = 2
 
EventGroupHandle_t eg = xEventGroupCreate();      // one word of bits, all 0
 
// from the WiFi task, when the link comes up:
xEventGroupSetBits(eg, WIFI_BIT);                 // sets bit 0
// from the config task, when config is loaded:
xEventGroupSetBits(eg, CFG_BIT);                  // sets bit 1
 
// the OTA task blocks until BOTH are set:
EventBits_t b = xEventGroupWaitBits(
    eg,
    WIFI_BIT | CFG_BIT,   // mask to wait on = 0b11 = 3
    pdTRUE,               // xClearOnExit: clear those bits when we unblock
    pdTRUE,               // xWaitForAllBits: pdTRUE = AND (both), pdFALSE = OR (any)
    portMAX_DELAY);       // block forever until satisfied

The "both bits" mask numerically: WIFI_BIT | CFG_BIT = 1 | 2 = 3 (binary 0b11). The bitwise-OR combines two single-bit flags into one mask; waiting on that mask with xWaitForAllBits = pdTRUE means "wake only when all set bits in the mask are set in the group." Why pdTRUE for clear-on-exit: without it the bits stay set, and the next loop iteration would fire immediately on stale bits instead of waiting for fresh events. Why portMAX_DELAY: the OTA task has nothing to do until both conditions hold — let the kernel sleep it forever (no busy-waiting) rather than time out. (portMAX_DELAY = block forever, defined at the top of this page.)

Count: each Give tries c += 1 but saturates at the max, 3. Starting at 0: gives 1→1, 2→2, 3→3, 4→still 3, 5→still 3. Final count = 3. Takes that succeed immediately: the count is 3, so the worker can Take 3 times without blocking (3→2→1→0). The 4th and 5th events were lost because the semaphore saturated. Lesson: a counting semaphore "remembers how many, up to its max." Choose the max ≥ the worst-case burst you must not lose.

A full self-contained timeline in words — and the figure below draws exactly these two timelines side by side so you can see the difference.

How to read the figure: time runs left-to-right in milliseconds; each row is one task (L bottom, M middle, H top). A green bar = L running while holding the lock; a yellow bar = M running; a blue bar = L running at boosted priority; a red bar = H blocked, waiting. The arrow marks the instant H finally acquires the mutex. The left panel is without inheritance (H waits to 130 ms); the right panel is with inheritance (H waits only to 30 ms). Watch how the yellow M bar disappears from H's critical path on the right — that is the whole fix.

(a) Without inheritance — trace the CPU owner over time:

• $t=0\to 5$ ms: only L is awake. L runs, holding the lock. It has now done 5 ms of its 30 ms of locked work.
• $t=5$ ms: H wakes and tries to take the mutex. L still holds it, so H blocks. L is still the only ready task, so L keeps running.
• $t=5\to 10$ ms: L runs another 5 ms → 10 ms of locked work done, 20 ms remaining.
• $t=10$ ms: M wakes. M's priority > L's, and M does not need the lock, so the scheduler preempts L and runs M.
• $t=10\to 110$ ms: M runs its full 100 ms. L is starved the entire time, still holding the lock, so H stays blocked.
• $t=110$ ms: M finishes. L resumes and runs its remaining 20 ms of locked work.
• $t=110+20=130$ ms: L releases the mutex. H finally acquires it at $t=130$ ms. This blocking is unbounded: add more medium tasks and H waits even longer.

(b) With inheritance — the same trace, one rule changed:

• $t=0\to 5$ ms: L runs holding the lock (5 ms done, 25 ms left).
• $t=5$ ms: H blocks on the mutex. The kernel now boosts L's priority to H's (priority inheritance) because L holds the lock H wants.
• $t=5\to 30$ ms: L, now at H's priority, runs its remaining 25 ms uninterrupted.
• $t=10$ ms: M wakes — but M's medium priority is below L's boosted priority, so M cannot preempt L. M waits.
• $t=30$ ms: L finishes the locked work and releases the mutex; its priority drops back to low. H acquires the mutex at $t=30$ ms, bounded only by L's critical-section length. This is the fix behind the Priority Inversion & the Mars Pathfinder bug.

• Send 10 → queue [10], returns pdTRUE.
• Send 20 → queue [10, 20] (full), returns pdTRUE.
• Send 30 → queue is full and timeout is 0, so it does not block; returns pdFALSE. 30 is dropped.
• Receiver reads FIFO → 10 first, then 20. Lesson: with xTicksToWait = 0, a full queue makes xQueueSend fail immediately (return value pdFALSE) rather than block — you must check the return value.

• Queue q_samples (float, length ≈ 8): ISR → filter task data transfer. Copy-by-value keeps each sample lifetime-safe; the length absorbs jitter. Use xQueueSendFromISR in the ISR.
• Mutex m_display: both the filter task and the clock task write the shared I²C display; a mutex gives exclusive turns and priority inheritance so a low-priority writer can't indefinitely block a high-priority one.
• (Optional) binary semaphore could replace the queue only if the ISR passed no data — but here it passes a float, so a queue is required. Why not a mutex ISR→filter? ISRs can't own mutexes; use the queue (which has ...FromISR variants) for the hand-off.

• Counting semaphore, xSemaphoreCreateCounting(maxCount, 0) with maxCount ≥ 4 (pick the worst-case burst, e.g. 8 for margin).
• ISR does xSemaphoreGiveFromISR each event; the worker loops xSemaphoreTake(sem, portMAX_DELAY); handle_one();.
• Why counting, not binary: a binary semaphore saturates at 1 — 4 events during one busy stretch collapse to a single wake-up, losing 3. A counting semaphore remembers the backlog up to its max.
• Trade-off: if the real burst can exceed maxCount, events beyond it are still lost — you must size maxCount to the true worst case, at the cost of a slightly larger control block.

• Critical section for the 3-instruction increment: correct. taskENTER_CRITICAL disables the scheduler/interrupts for a handful of cycles — cheap, and no blocking object is needed for something this short. See Critical Sections & taskENTER_CRITICAL.
• Mutex for the 5 ms I²C transaction: correct. Disabling interrupts for 5 ms would wreck real-time latency (no ISR could run). A mutex blocks the waiting task instead — the CPU keeps doing other work — and priority inheritance bounds the wait.
• The rule: guard very short, deterministic sequences with a critical section; guard long or blocking operations with a mutex. Wrong swap (critical section around 5 ms) would freeze the whole system's interrupts for 5 ms.

Model the binary semaphore as a queue of length 1, itemSize 0. Its count is $c\in \{0,1\}$, and every Give does the saturating update $c\leftarrow \min (c+1,1)$.

• Start $c=0$. Give #1: $c=\min (0+1,1)=1$.
• Gives #2 … #N: each computes $c=\min (1+1,1)=1$ — the count is already saturated, so all $N-1$ of these are no-ops. That is exactly $N-1$ lost events.
• When the worker finally Takes: $c=1\to$ one successful wake-up, then $c=0$. So out of $N$ events, exactly 1 produces work and $N-1$ are lost — the claim.

With a counting semaphore, $\text{maxCount}\ge N$: the update $c\leftarrow \min (c+1,\text{maxCount})$ never saturates during the burst, so after $N$ gives $c=N$. The worker then Takes $N$ times, doing all $N$ units of work with 0 losses. This is the concrete justification for L4.2's sizing rule: set $\text{maxCount}$ to the worst-case burst.

A semaphore is implemented as a queue of itemSize ::: 0 (zero bytes). Only the task that took a mutex may give it back — this property is called ::: ownership. While a high-priority task waits on a mutex, the kernel boosts the holder's priority — this is ::: priority inheritance. pdMS_TO_TICKS(50) at a 100 Hz tick rate equals ::: 5 ticks. A counting semaphore's count saturates at its ::: maximum count. The event-group mask WIFI_BIT | CFG_BIT with bits 0 and 1 equals numerically ::: 3.