Circular Buffers and Producer-Consumer Flow

A normal transfer stops when its count reaches zero. For a continuous stream the channel must instead write round and round the same buffer:

• circular mode (STM32 DMA_CIRCULAR): at the end of the buffer the stream goes back to its start and carries on, and keeps interrupting at half and full if asked;
• address wrapping (the RP2040’s RING_SIZE): only the low $n$ bits of the write address change, so it wraps every $2^n$ bytes. The transfer count still runs down, so it is set very large, or the channel is re-armed (by a chained channel or its completion interrupt) before it runs out;
• chaining two channels or re-triggering one from its completion interrupt (lesson 5).

The buffer now has the same two indices as unit 9’s ring buffer, with the difference that one side is hardware:

• the head, where the next byte will be written, belongs to the DMA. The program reads it from the channel: on the RP2040, WRITE_ADDR minus the buffer’s address; on an STM32 in circular mode, the buffer length minus the remaining count NDTR (__HAL_DMA_GET_COUNTER()); Zephyr reports a write_position where the driver supports it;
• the tail, where the next unread byte is, belongs to the program.

#define N 1024                                          /* power of two: RING_SIZE = 10 */
static uint8_t rx[N] __attribute__((aligned(N)));       /* aligned to its own size (below) */
static uint32_t tail;                                   /* owned by the reader */

size_t rx_read(uint8_t *out, size_t max) {
    uint32_t head = (dma_hw->ch[rx_chan].write_addr - (uintptr_t)rx) % N;   /* next byte the DMA writes */
    __compiler_memory_barrier();                        /* read the data only after reading head */
    size_t n = 0;
    while (tail != head && n < max) { out[n++] = rx[tail]; tail = (tail + 1) % N; }
    return n;
}

The crucial difference from unit 9: an interrupt handler can check for a full buffer and drop the new byte. The DMA never looks at the tail. If the reader falls a whole buffer behind, the DMA simply overwrites bytes that were never read, and the head appears to have moved only a little.

↑ This step uses the figure at the top of the page.

The reader must come back before the DMA has written a full buffer’s worth. For a buffer of $N$ bytes filled at $R$ bytes/s, and a longest gap $T_{\text{read}}$ between reads:

$T_{\text{read}}$ is the worst case, not the average: the longest pass of the main loop (unit 7, lesson 6), plus the longest time higher-priority handlers or tasks can keep the reader from running (unit 9, lesson 6). Leave a margin, because a gap that is only just short enough fails on the next slow path nobody measured.

• Periodically, from the main loop or a timer, as in the example above. Simple, but a message waits up to one period.
• Half and complete interrupts: STM32 circular mode can interrupt at half transfer and transfer complete; Zephyr reports the end of the buffer or a “water mark”. They bound the latency for a full stream but say nothing about a short message that stops mid-buffer.
• An idle line: the UART can detect that the line has gone quiet after a message. The STM32 HAL’s HAL_UARTEx_ReceiveToIdle_DMA() combines DMA reception with half, complete and idle events, and reports how many bytes have arrived.

At 921 600 baud with 8N1 framing the DMA writes $R$ = 92 160 bytes/s. A 256-byte ring fills in 256 / 92 160 = 2.78 ms. Reading every 2 ms keeps up (at most 185 bytes unread, 72 % of the buffer). But the main loop occasionally takes 5 ms when it redraws a display: then about 461 bytes arrive between reads and roughly 205 are overwritten each time. Worse, the reader computes the new head modulo 256 and receives only 461 mod 256 = 205 bytes: a whole buffer’s worth is lost per slow pass and the stream is spliced without any sign of it.

A 1024-byte ring fills in 11.1 ms, more than twice the 5 ms worst case, and costs 1 KiB of RAM. On the RP2040 it is declared aligned(1024) with RING_SIZE = 10. The channel’s TRANS_COUNT still counts down: set to its maximum, 2³² − 1 transfers, it runs out after (2³² − 1) / 92 160 ≈ 46 600 s, about 13 hours. A device that runs for weeks must re-arm the channel before then, for example from a second channel chained to it or from its completion interrupt.