[PATCH 0/2] Documentation: dmaengine: Tweak dmatest docs

[PATCH 0/2] Documentation: dmaengine: Tweak dmatest docs

[Daniel Thompson]

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

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

[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.

Signed-off-by: Haavard Skinnemoen <hskinnemoen@atmel.com>
Signed-off-by: Daniel Thompson <daniel.thompson@linaro.org>
---
 Documentation/driver-api/dmaengine/dmatest.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)

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 <andriy.shevchenko@linux.intel.com>
 
 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

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

[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")
Signed-off-by: Daniel Thompson <daniel.thompson@linaro.org>
---
 Documentation/driver-api/dmaengine/dmatest.rst | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

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.
-- 
2.30.2

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

[Andy Shevchenko]

On Wed, Aug 18, 2021 at 6:15 PM Daniel Thompson
<daniel.thompson@linaro.org> wrote:
>
> 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.

> Signed-off-by: Haavard Skinnemoen <hskinnemoen@atmel.com>

Not sure if you can use it like this (I mean the above SoB)
Otherwise it's a good idea, thanks!
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>

> Signed-off-by: Daniel Thompson <daniel.thompson@linaro.org>
> ---
>  Documentation/driver-api/dmaengine/dmatest.rst | 10 ++++++++++
>  1 file changed, 10 insertions(+)
>
> 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 <andriy.shevchenko@linux.intel.com>
>
>  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
>


-- 
With Best Regards,
Andy Shevchenko

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

[Daniel Thompson]

On Wed, Aug 18, 2021 at 06:27:52PM +0300, Andy Shevchenko wrote:
> On Wed, Aug 18, 2021 at 6:15 PM Daniel Thompson
> <daniel.thompson@linaro.org> wrote:
> >
> > 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.
> 
> > Signed-off-by: Haavard Skinnemoen <hskinnemoen@atmel.com>
> 
> 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.

> Otherwise it's a good idea, thanks!
> Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>

Thanks!


Daniel.


> 
> > Signed-off-by: Daniel Thompson <daniel.thompson@linaro.org>
> > ---
> >  Documentation/driver-api/dmaengine/dmatest.rst | 10 ++++++++++
> >  1 file changed, 10 insertions(+)
> >
> > 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 <andriy.shevchenko@linux.intel.com>
> >
> >  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
> >
> 
> 
> -- 
> With Best Regards,
> Andy Shevchenko

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

[Vinod Koul]

On 19-08-21, 10:13, Daniel Thompson wrote:
> On Wed, Aug 18, 2021 at 06:27:52PM +0300, Andy Shevchenko wrote:
> > On Wed, Aug 18, 2021 at 6:15 PM Daniel Thompson
> > <daniel.thompson@linaro.org> wrote:
> > >
> > > 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.
> > 
> > > Signed-off-by: Haavard Skinnemoen <hskinnemoen@atmel.com>
> > 
> > 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.

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 :)

-- 
~Vinod

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

[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").
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 <daniel.thompson@linaro.org>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
---
 Documentation/driver-api/dmaengine/dmatest.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)

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 <andriy.shevchenko@linux.intel.com>
 
 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.33.0