Commit 58fe1076 authored by Adrian Larumbe's avatar Adrian Larumbe Committed by Vinod Koul
Browse files

dmaengine: Add documentation for new memcpy scatter-gather function 



Documentation describes semantics, limitations and a typical use case
scenario.

Signed-off-by: default avatarAdrian Larumbe <adrianml@alumnos.upm.es>
Link: https://lore.kernel.org/r/20211101180825.241048-2-adrianml@alumnos.upm.es


Signed-off-by: default avatarVinod Koul <vkoul@kernel.org>
parent 56fc39f5

Documentation/driver-api/dmaengine/provider.rst

+23 −0
Original line number Diff line number Diff line
@@ -162,6 +162,29 @@ Currently, the types available are: 


  - The device is able to do memory to memory copies



- - DMA_MEMCPY_SG



  - The device supports memory to memory scatter-gather transfers.



  - Even though a plain memcpy can look like a particular case of a

    scatter-gather transfer, with a single chunk to copy, it's a distinct

    transaction type in the mem2mem transfer case. This is because some very

    simple devices might be able to do contiguous single-chunk memory copies,

    but have no support for more complex SG transfers.



  - No matter what the overall size of the combined chunks for source and

    destination is, only as many bytes as the smallest of the two will be

    transmitted. That means the number and size of the scatter-gather buffers in

    both lists need not be the same, and that the operation functionally is

    equivalent to a ``strncpy`` where the ``count`` argument equals the smallest

    total size of the two scatter-gather list buffers.



  - It's usually used for copying pixel data between host memory and

    memory-mapped GPU device memory, such as found on modern PCI video graphics

    cards. The most immediate example is the OpenGL API function

    ``glReadPielx()``, which might require a verbatim copy of a huge framebuffer

    from local device memory onto host memory.



- DMA_XOR



  - The device is able to perform XOR operations on memory areas