On 05.01.2026 09:22, Michael S. Tsirkin wrote: > Document the __dma_from_device_group_begin()/end() annotations. > > Signed-off-by: Michael S. Tsirkin <[email protected]> > --- > Documentation/core-api/dma-api-howto.rst | 52 ++++++++++++++++++++++++ > 1 file changed, 52 insertions(+)
Acked-by: Marek Szyprowski <[email protected]> > diff --git a/Documentation/core-api/dma-api-howto.rst > b/Documentation/core-api/dma-api-howto.rst > index 96fce2a9aa90..e97743ab0f26 100644 > --- a/Documentation/core-api/dma-api-howto.rst > +++ b/Documentation/core-api/dma-api-howto.rst > @@ -146,6 +146,58 @@ What about block I/O and networking buffers? The block > I/O and > networking subsystems make sure that the buffers they use are valid > for you to DMA from/to. > > +__dma_from_device_group_begin/end annotations > +============================================= > + > +As explained previously, when a structure contains a DMA_FROM_DEVICE / > +DMA_BIDIRECTIONAL buffer (device writes to memory) alongside fields that the > +CPU writes to, cache line sharing between the DMA buffer and CPU-written > fields > +can cause data corruption on CPUs with DMA-incoherent caches. > + > +The > ``__dma_from_device_group_begin(GROUP)/__dma_from_device_group_end(GROUP)`` > +macros ensure proper alignment to prevent this:: > + > + struct my_device { > + spinlock_t lock1; > + __dma_from_device_group_begin(); > + char dma_buffer1[16]; > + char dma_buffer2[16]; > + __dma_from_device_group_end(); > + spinlock_t lock2; > + }; > + > +To isolate a DMA buffer from adjacent fields, use > +``__dma_from_device_group_begin(GROUP)`` before the first DMA buffer > +field and ``__dma_from_device_group_end(GROUP)`` after the last DMA > +buffer field (with the same GROUP name). This protects both the head > +and tail of the buffer from cache line sharing. > + > +The GROUP parameter is an optional identifier that names the DMA buffer group > +(in case you have several in the same structure):: > + > + struct my_device { > + spinlock_t lock1; > + __dma_from_device_group_begin(buffer1); > + char dma_buffer1[16]; > + __dma_from_device_group_end(buffer1); > + spinlock_t lock2; > + __dma_from_device_group_begin(buffer2); > + char dma_buffer2[16]; > + __dma_from_device_group_end(buffer2); > + }; > + > +On cache-coherent platforms these macros expand to zero-length array markers. > +On non-coherent platforms, they also ensure the minimal DMA alignment, which > +can be as large as 128 bytes. > + > +.. note:: > + > + It is allowed (though somewhat fragile) to include extra fields, not > + intended for DMA from the device, within the group (in order to pack > the > + structure tightly) - but only as long as the CPU does not write these > + fields while any fields in the group are mapped for DMA_FROM_DEVICE > or > + DMA_BIDIRECTIONAL. > + > DMA addressing capabilities > =========================== > Best regards -- Marek Szyprowski, PhD Samsung R&D Institute Poland
