dma.h File Reference

DMA peripheral ingest / egress (DETWS_ENABLE_DMA) - the v5 high-throughput hardware-ingest path. More...

#include "ServerConfig.h"

Go to the source code of this file.

Detailed Description

DMA peripheral ingest / egress (DETWS_ENABLE_DMA) - the v5 high-throughput hardware-ingest path.

A DMA channel moves bytes between a peripheral (UART / I2C / SPI) and a static buffer while the CPU is free, then a DMA-complete event carries the result up. Two directions:

• RX (ingress): peripheral -> DMA -> buffer. On completion the channel emits a det_dma_event whose data/len point at the just-filled buffer. RX is double-buffered (ping-pong): the completed buffer is handed to the callback while the engine fills the other, so there is a full transfer of headroom to consume it before it is reused.
• TX (egress): buffer -> DMA -> peripheral. The caller submits bytes; on completion the channel emits a TX event (data == nullptr) so the producer knows the buffer is free to refill.

The completion callback runs in ISR context on real silicon, so keep it tiny - the intended pattern is to post the event into the preempting work queue (services/preempt_queue) with detws_pq_post_from_isr(), letting a high-priority task do the real work off the interrupt. det_dma stays decoupled from the queue: it just hands you the event.

Simulator (DETWS_DMA_SIMULATE, default on). With no physical loopback wire the transfers run through an in-memory model of the peripheral: det_dma_sim_feed() injects bytes as if they arrived on the RX line, det_dma_sim_capture() reads back what egress DMA "transmitted", and a channel opened with loopback feeds its own TX egress into its RX ingress (an internal jumper). det_dma_poll() advances the engine and fires the completions. This exercises the entire ingress -> event -> (queue) -> handler and produce -> egress pipeline identically on the host bench and on-device. It is the shipped, tested backend; a real silicon driver plugs into det_dma_hw_* when the flag is 0 (see docs/KNOWN_LIMITATIONS.md).

Zero-heap: DETWS_DMA_CHANNELS channels, each with 2x DETWS_DMA_BUF_SIZE RX + one TX buffer + the simulator's ingress/egress staging, all static and compile-time sized. Fail-closed: a submit onto a busy channel or a feed past the staging capacity returns false rather than blocking or overrunning.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file dma.h.