Module zero_copy 

Zero-copy residual source trait for DMA buffer integration. Enables tap into memory-mapped IQ buffers without CPU copy overhead. Zero-copy residual source trait for DMA buffer integration.

Motivation

On embedded RF platforms (Zynq UltraScale+ RFSoC, USRP E310), the IQ sample stream arrives in DMA buffers mapped into the processor’s address space. Copying these samples into an intermediate buffer adds latency and CPU overhead that is unacceptable in high-throughput pipelines.

The ResidualSource trait allows the DSFB engine to tap directly into a DMA buffer — or any other memory-mapped IQ source — without copying. The engine reads residual norms from the source via an immutable borrow, maintaining the non-intrusion contract (no write path, no mutation of upstream data).

Non-Intrusion Guarantee

The trait requires only &self access to the source. The engine never takes a mutable reference to the DMA buffer. This is enforced at the type level: ResidualSource::residual_norms() returns &[f32], an immutable slice. The Rust borrow checker prevents any write path from being introduced without a compilation error.

Design

• no_std, no_alloc, zero unsafe
• Trait-based: implementors provide platform-specific DMA access
• Engine accepts &dyn ResidualSource or &impl ResidualSource
• Compatible with volatile memory-mapped I/O via safe wrappers

Structs

RingSource

A fixed-capacity ring buffer residual source for embedded/bare-metal.

SliceSource

A simple owned-slice residual source for testing and host-side pipelines.

Traits

ResidualSource

A source of residual norm observations.