[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

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

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

v2: Remove Haavard's SoB: from the first patch (Andy S., Vinod K.).

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: fa55b7dcdc43c1aa1ba12bca9d2dd4318c2a0dbf
--
2.33.0

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