Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 179a214e authored by Vinod Koul's avatar Vinod Koul Committed by Jonathan Corbet
Browse files

dmaengine: doc: ReSTize dmatest doc 



This converts and moves dmatest file with some format
changes for RST style

Signed-off-by: default avatarVinod Koul <vinod.koul@intel.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent eeb1c643

Documentation/dmaengine/dmatest.txt→Documentation/driver-api/dmaengine/dmatest.rst

+57 −39
Original line number Original line Diff line number Diff line 
==============

DMA Test Guide

DMA Test Guide

==============

==============
@@ -6,6 +7,7 @@ 
This small document introduces how to test DMA drivers using dmatest module.

This small document introduces how to test DMA drivers using dmatest module.





Part 1 - How to build the test module

Part 1 - How to build the test module

=====================================





The menuconfig contains an option that could be found by following path:

The menuconfig contains an option that could be found by following path:

	Device Drivers -> DMA Engine support -> DMA Test client

	Device Drivers -> DMA Engine support -> DMA Test client
@@ -13,24 +15,30 @@ The menuconfig contains an option that could be found by following path: 
In the configuration file the option called CONFIG_DMATEST. The dmatest could

In the configuration file the option called CONFIG_DMATEST. The dmatest could

be built as module or inside kernel. Let's consider those cases.

be built as module or inside kernel. Let's consider those cases.





	Part 2 - When dmatest is built as a module...

Part 2 - When dmatest is built as a module

==========================================



Example of usage: ::





Example of usage:

    % modprobe dmatest channel=dma0chan0 timeout=2000 iterations=1 run=1

    % modprobe dmatest channel=dma0chan0 timeout=2000 iterations=1 run=1





...or:

...or: ::



    % modprobe dmatest

    % modprobe dmatest

    % echo dma0chan0 > /sys/module/dmatest/parameters/channel

    % echo dma0chan0 > /sys/module/dmatest/parameters/channel

    % echo 2000 > /sys/module/dmatest/parameters/timeout

    % echo 2000 > /sys/module/dmatest/parameters/timeout

    % echo 1 > /sys/module/dmatest/parameters/iterations

    % echo 1 > /sys/module/dmatest/parameters/iterations

    % echo 1 > /sys/module/dmatest/parameters/run

    % echo 1 > /sys/module/dmatest/parameters/run





...or on the kernel command line:

...or on the kernel command line: ::





    dmatest.channel=dma0chan0 dmatest.timeout=2000 dmatest.iterations=1 dmatest.run=1

    dmatest.channel=dma0chan0 dmatest.timeout=2000 dmatest.iterations=1 dmatest.run=1





Hint: available channel list could be extracted by running the following

..hint:: available channel list could be extracted by running the following

         command:

         command:



::



    % ls -1 /sys/class/dma/

    % ls -1 /sys/class/dma/





Once started a message like "dmatest: Started 1 threads using dma0chan0" is

Once started a message like "dmatest: Started 1 threads using dma0chan0" is
@@ -39,7 +47,8 @@ stops. 




Note that running a new test will not stop any in progress test.

Note that running a new test will not stop any in progress test.





The following command returns the state of the test.

The following command returns the state of the test. ::



    % cat /sys/module/dmatest/parameters/run

    % cat /sys/module/dmatest/parameters/run





To wait for test completion userpace can poll 'run' until it is false, or use

To wait for test completion userpace can poll 'run' until it is false, or use
@@ -50,15 +59,19 @@ before returning. For example, the following scripts wait for 42 tests 
to complete before exiting. Note that if 'iterations' is set to 'infinite' then

to complete before exiting. Note that if 'iterations' is set to 'infinite' then

waiting is disabled.

waiting is disabled.





Example:

Example: ::



    % modprobe dmatest run=1 iterations=42 wait=1

    % modprobe dmatest run=1 iterations=42 wait=1

    % modprobe -r dmatest

    % modprobe -r dmatest

...or:



...or: ::



    % modprobe dmatest run=1 iterations=42

    % modprobe dmatest run=1 iterations=42

    % cat /sys/module/dmatest/parameters/wait

    % cat /sys/module/dmatest/parameters/wait

    % modprobe -r dmatest

    % modprobe -r dmatest





	Part 3 - When built-in in the kernel...

Part 3 - When built-in in the kernel

====================================





The module parameters that is supplied to the kernel command line will be used

The module parameters that is supplied to the kernel command line will be used

for the first performed test. After user gets a control, the test could be

for the first performed test. After user gets a control, the test could be
@@ -66,16 +79,20 @@ re-run with the same or different parameters. For the details see the above 
section "Part 2 - When dmatest is built as a module..."

section "Part 2 - When dmatest is built as a module..."





In both cases the module parameters are used as the actual values for the test

In both cases the module parameters are used as the actual values for the test

case. You always could check them at run-time by running

case. You always could check them at run-time by running ::



    % grep -H . /sys/module/dmatest/parameters/*

    % grep -H . /sys/module/dmatest/parameters/*





Part 4 - Gathering the test results

Part 4 - Gathering the test results

===================================





Test results are printed to the kernel log buffer with the format:

Test results are printed to the kernel log buffer with the format: ::





    "dmatest: result <channel>: <test id>: '<error msg>' with src_off=<val> dst_off=<val> len=<val> (<err code>)"

    "dmatest: result <channel>: <test id>: '<error msg>' with src_off=<val> dst_off=<val> len=<val> (<err code>)"





Example of output:

Example of output: ::





    % dmesg | tail -n 1

    % dmesg | tail -n 1

    dmatest: result dma0chan0-copy0: #1: No errors with src_off=0x7bf dst_off=0x8ad len=0x3fea (0)

    dmatest: result dma0chan0-copy0: #1: No errors with src_off=0x7bf dst_off=0x8ad len=0x3fea (0)
@@ -84,7 +101,8 @@ the parens represents additional information, e.g. error code, error counter, 
or status. A test thread also emits a summary line at completion listing the

or status. A test thread also emits a summary line at completion listing the

number of tests executed, number that failed, and a result code.

number of tests executed, number that failed, and a result code.





Example:

Example: ::



    % dmesg | tail -n 1

    % dmesg | tail -n 1

    dmatest: dma0chan0-copy0: summary 1 test, 0 failures 1000 iops 100000 KB/s (0)

    dmatest: dma0chan0-copy0: summary 1 test, 0 failures 1000 iops 100000 KB/s (0)

Documentation/driver-api/dmaengine/index.rst

+10 −0
Original line number Original line Diff line number Diff line
@@ -27,6 +27,16 @@ API of the DMAEngine. This is applicable only for slave DMA usage only. 




   client

   client





DMA Test documentation

----------------------



This book introduces how to test DMA drivers using dmatest module.



.. toctree::

   :maxdepth: 1



   dmatest



.. only::  subproject

.. only::  subproject





   Indices

   Indices