Skip to contentSkip to conversation

Documentation: dmaengine: Tweak dmatest docs

PATCH In review Daniel Thompson 3 participants 6 messages Aug 18, 2021 – Aug 26, 2021

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

cover Documentation: dmaengine: Tweak dmatest docs

A couple of small improvements to the dmatest documentation.

The first provides a description of what the test actually does. The second corrects the description of how the test behaves if the channel parameter is not configured.

Daniel Thompson (2):
Documentation: dmaengine: Add a description of what dmatest does
Documentation: dmaengine: Correctly describe dmatest with channel
unset

 Documentation/driver-api/dmaengine/dmatest.rst | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

base-commit: 7c60610d476766e128cc4284bb6349732cbd6606 --
2.30.2

#1 lore raw

PATCH 1/2 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") although it has been edited and updated slightly.

---
 Documentation/driver-api/dmaengine/dmatest.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)
Documentation/driver-api/dmaengine/dmatest.rst +10 -0
index ee268d445d38..529cc2cbbb1b 100644
@@ -6,6 +6,16 @@ Andy Shevchenko <[email protected]>
 
 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
Signature · 1 line
2.30.2
Reviewed-by on v1 1/2
#2 lore raw

Re: [PATCH 1/2] Documentation: dmaengine: Add a description of what dmatest does

Quoted 9 lines · Daniel Thompson

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") although it has been edited and updated slightly.

Not sure if you can use it like this (I mean the above SoB) Otherwise it's a good idea, thanks!

Quoted 29 lines
---
 Documentation/driver-api/dmaengine/dmatest.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)
Documentation/driver-api/dmaengine/dmatest.rst +10 -1
index ee268d445d38..529cc2cbbb1b 100644
@@ -6,6 +6,16 @@ Andy Shevchenko <[email protected]>
 
 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
--

2.30.2

Signature · 2 lines
With Best Regards,
Andy Shevchenko
#3 lore raw

Re: [PATCH 1/2] Documentation: dmaengine: Add a description of what dmatest does

Quoted 6 lines · Andy Shevchenko
Quoted 4 lines · Daniel Thompson

Currently it can difficult to determine what dmatest does without reading the source code. Let's add a description.

Quoted 7 lines
Quoted 5 lines

The description is taken mostly from the patch header of commit 4a776f0aa922 ("dmatest: Simple DMA memcpy test client") although it has been edited and updated slightly.

Not sure if you can use it like this (I mean the above SoB)

I wondered about that.

In the end I concluded that if I had picked up code from an old patch and edited to this degree then I would probably consider it a new patch but be clear about credit and preserve the original SoB. I saw no real reason to treat the contents of a patch header much different.

However, I'm very happy to make the credit more informal if needed.

Quoted 2 lines

Otherwise it's a good idea, thanks!

Thanks!

Daniel.

Quoted 35 lines
Quoted 30 lines
---
 Documentation/driver-api/dmaengine/dmatest.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)
Documentation/driver-api/dmaengine/dmatest.rst +10 -1
index ee268d445d38..529cc2cbbb1b 100644
@@ -6,6 +6,16 @@ Andy Shevchenko <[email protected]>
 
 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
--

2.30.2

Signature · 2 lines
With Best Regards,
Andy Shevchenko
maintainer
#4 lore raw

Re: [PATCH 1/2] Documentation: dmaengine: Add a description of what dmatest does

Quoted 15 lines · Daniel Thompson
Quoted 6 lines · Andy Shevchenko
Quoted 4 lines · Daniel Thompson

Currently it can difficult to determine what dmatest does without reading the source code. Let's add a description.

Quoted 7 lines
Quoted 5 lines

The description is taken mostly from the patch header of commit 4a776f0aa922 ("dmatest: Simple DMA memcpy test client") although it has been edited and updated slightly.

Not sure if you can use it like this (I mean the above SoB)

Quoted 8 lines

I wondered about that.

In the end I concluded that if I had picked up code from an old patch and edited to this degree then I would probably consider it a new patch but be clear about credit and preserve the original SoB. I saw no real reason to treat the contents of a patch header much different.

However, I'm very happy to make the credit more informal if needed.

It would be better if we be formal when giving credit. I am okay with sob by Haavard if he acks it...
Daniel, Yes the intention is very noble, but I would have Haavard ack before applying a patch with his sob, if not lets drop it and give credit in changelog :)

Signature · 1 line
~Vinod
#5 lore raw

PATCH 2/2 Documentation: dmaengine: Correctly describe dmatest with channel unset

In reply to Daniel Thompson

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")
---
 Documentation/driver-api/dmaengine/dmatest.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
Documentation/driver-api/dmaengine/dmatest.rst +4 -3
index 529cc2cbbb1b..cf9859cd0b43 100644
@@ -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.
Signature · 1 line
2.30.2