From 58fe107660483138a7a77acd673b911016e4ad31 Mon Sep 17 00:00:00 2001 From: Adrian Larumbe Date: Mon, 1 Nov 2021 18:08:23 +0000 Subject: dmaengine: Add documentation for new memcpy scatter-gather function Documentation describes semantics, limitations and a typical use case scenario. Signed-off-by: Adrian Larumbe Link: https://lore.kernel.org/r/20211101180825.241048-2-adrianml@alumnos.upm.es Signed-off-by: Vinod Koul --- Documentation/driver-api/dmaengine/provider.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'Documentation/driver-api') diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst index ddb0a81a796c..0072c9c7efd3 100644 --- a/Documentation/driver-api/dmaengine/provider.rst +++ b/Documentation/driver-api/dmaengine/provider.rst @@ -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 -- cgit v1.2.3 From 37829227f04247125894a7857e3299e8764c2d6f Mon Sep 17 00:00:00 2001 From: Daniel Thompson Date: Thu, 18 Nov 2021 10:09:51 +0000 Subject: Documentation: dmaengine: Add a description of what dmatest does Currently it can difficult to determine what dmatest does without reading the source code. Let's add a description. The description is taken mostly from the patch header of commit 4a776f0aa922 ("dmatest: Simple DMA memcpy test client"). It has been edited and updated slightly. Nevertheless the new text was largely written by Haarvard Skinnemoen and was copied from another patch, already committed to the kernel, which has Haarvard's SoB: attached to it. Signed-off-by: Daniel Thompson Reviewed-by: Andy Shevchenko Link: https://lore.kernel.org/r/20211118100952.27268-2-daniel.thompson@linaro.org Signed-off-by: Vinod Koul --- Documentation/driver-api/dmaengine/dmatest.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'Documentation/driver-api') diff --git a/Documentation/driver-api/dmaengine/dmatest.rst b/Documentation/driver-api/dmaengine/dmatest.rst index ee268d445d38..529cc2cbbb1b 100644 --- a/Documentation/driver-api/dmaengine/dmatest.rst +++ b/Documentation/driver-api/dmaengine/dmatest.rst @@ -6,6 +6,16 @@ Andy Shevchenko This small document introduces how to test DMA drivers using dmatest module. +The dmatest module tests DMA memcpy, memset, XOR and RAID6 P+Q operations using +various lengths and various offsets into the source and destination buffers. It +will initialize both buffers with a repeatable pattern and verify that the DMA +engine copies the requested region and nothing more. It will also verify that +the bytes aren't swapped around, and that the source buffer isn't modified. + +The dmatest module can be configured to test a specific channel. It can also +test multiple channels at the same time, and it can start multiple threads +competing for the same channel. + .. note:: The test suite works only on the channels that have at least one capability of the following: DMA_MEMCPY (memory-to-memory), DMA_MEMSET -- cgit v1.2.3 From c61d7b2ef141abf81140756b45860a2306f395a2 Mon Sep 17 00:00:00 2001 From: Daniel Thompson Date: Thu, 18 Nov 2021 10:09:52 +0000 Subject: Documentation: dmaengine: Correctly describe dmatest with channel unset Currently the documentation states that channels must be configured before running the dmatest. This has not been true since commit 6b41030fdc79 ("dmaengine: dmatest: Restore default for channel"). Fix accordingly. Fixes: 6b41030fdc79 ("dmaengine: dmatest: Restore default for channel") Signed-off-by: Daniel Thompson Link: https://lore.kernel.org/r/20211118100952.27268-3-daniel.thompson@linaro.org Signed-off-by: Vinod Koul --- Documentation/driver-api/dmaengine/dmatest.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'Documentation/driver-api') diff --git a/Documentation/driver-api/dmaengine/dmatest.rst b/Documentation/driver-api/dmaengine/dmatest.rst index 529cc2cbbb1b..cf9859cd0b43 100644 --- a/Documentation/driver-api/dmaengine/dmatest.rst +++ b/Documentation/driver-api/dmaengine/dmatest.rst @@ -153,13 +153,14 @@ Part 5 - Handling channel allocation Allocating Channels ------------------- -Channels are required to be configured prior to starting the test run. -Attempting to run the test without configuring the channels will fail. +Channels do not need to be configured prior to starting a test run. Attempting +to run the test without configuring the channels will result in testing any +channels that are available. Example:: % echo 1 > /sys/module/dmatest/parameters/run - dmatest: Could not start test, no channels configured + dmatest: No channels configured, continue with any Channels are registered using the "channel" parameter. Channels can be requested by their name, once requested, the channel is registered and a pending thread is added to the test list. -- cgit v1.2.3