Documentation/driver-api/dmaengine/dmatest.rst

   1 ==============
   2 DMA Test Guide
   3 ==============
   4
   5 Andy Shevchenko <andriy.shevchenko@linux.intel.com>
   6
   7 This small document introduces how to test DMA drivers using dmatest module.
   8
   9 .. note::
  10   The test suite works only on the channels that have at least one
  11   capability of the following: DMA_MEMCPY (memory-to-memory), DMA_MEMSET
  12   (const-to-memory or memory-to-memory, when emulated), DMA_XOR, DMA_PQ.
  13
  14 .. note::
  15   In case of any related questions use the official mailing list
  16   dmaengine@vger.kernel.org.
  17
  18 Part 1 - How to build the test module
  19 =====================================
  20
  21 The menuconfig contains an option that could be found by following path:
  22
  23         Device Drivers -> DMA Engine support -> DMA Test client
  24
  25 In the configuration file the option called CONFIG_DMATEST. The dmatest could
  26 be built as module or inside kernel. Let's consider those cases.
  27
  28 Part 2 - When dmatest is built as a module
  29 ==========================================
  30
  31 Example of usage::
  32
  33     % modprobe dmatest timeout=2000 iterations=1 channel=dma0chan0 run=1
  34
  35 ...or::
  36
  37     % modprobe dmatest
  38     % echo 2000 > /sys/module/dmatest/parameters/timeout
  39     % echo 1 > /sys/module/dmatest/parameters/iterations
  40     % echo dma0chan0 > /sys/module/dmatest/parameters/channel
  41     % echo 1 > /sys/module/dmatest/parameters/run
  42
  43 ...or on the kernel command line::
  44
  45     dmatest.timeout=2000 dmatest.iterations=1 dmatest.channel=dma0chan0 dmatest.run=1
  46
  47 Example of multi-channel test usage:
  48     % modprobe dmatest
  49     % echo 2000 > /sys/module/dmatest/parameters/timeout
  50     % echo 1 > /sys/module/dmatest/parameters/iterations
  51     % echo dma0chan0 > /sys/module/dmatest/parameters/channel
  52     % echo dma0chan1 > /sys/module/dmatest/parameters/channel
  53     % echo dma0chan2 > /sys/module/dmatest/parameters/channel
  54     % echo 1 > /sys/module/dmatest/parameters/run
  55
  56 Note: the channel parameter should always be the last parameter set prior to
  57 running the test (setting run=1), this is because upon setting the channel
  58 parameter, that specific channel is requested using the dmaengine and a thread
  59 is created with the existing parameters. This thread is set as pending
  60 and will be executed once run is set to 1. Any parameters set after the thread
  61 is created are not applied.
  62 .. hint::
  63   available channel list could be extracted by running the following command::
  64
  65     % ls -1 /sys/class/dma/
  66
  67 Once started a message like " dmatest: Added 1 threads using dma0chan0" is
  68 emitted. A thread for that specific channel is created and is now pending, the
  69 pending thread is started once run is to 1.
  70
  71 Note that running a new test will not stop any in progress test.
  72
  73 The following command returns the state of the test. ::
  74
  75     % cat /sys/module/dmatest/parameters/run
  76
  77 To wait for test completion userpace can poll 'run' until it is false, or use
  78 the wait parameter. Specifying 'wait=1' when loading the module causes module
  79 initialization to pause until a test run has completed, while reading
  80 /sys/module/dmatest/parameters/wait waits for any running test to complete
  81 before returning. For example, the following scripts wait for 42 tests
  82 to complete before exiting. Note that if 'iterations' is set to 'infinite' then
  83 waiting is disabled.
  84
  85 Example::
  86
  87     % modprobe dmatest run=1 iterations=42 wait=1
  88     % modprobe -r dmatest
  89
  90 ...or::
  91
  92     % modprobe dmatest run=1 iterations=42
  93     % cat /sys/module/dmatest/parameters/wait
  94     % modprobe -r dmatest
  95
  96 Part 3 - When built-in in the kernel
  97 ====================================
  98
  99 The module parameters that is supplied to the kernel command line will be used
 100 for the first performed test. After user gets a control, the test could be
 101 re-run with the same or different parameters. For the details see the above
 102 section `Part 2 - When dmatest is built as a module`_.
 103
 104 In both cases the module parameters are used as the actual values for the test
 105 case. You always could check them at run-time by running ::
 106
 107     % grep -H . /sys/module/dmatest/parameters/*
 108
 109 Part 4 - Gathering the test results
 110 ===================================
 111
 112 Test results are printed to the kernel log buffer with the format::
 113
 114     "dmatest: result <channel>: <test id>: '<error msg>' with src_off=<val> dst_off=<val> len=<val> (<err code>)"
 115
 116 Example of output::
 117
 118     % dmesg | tail -n 1
 119     dmatest: result dma0chan0-copy0: #1: No errors with src_off=0x7bf dst_off=0x8ad len=0x3fea (0)
 120
 121 The message format is unified across the different types of errors. A
 122 number in the parentheses represents additional information, e.g. error
 123 code, error counter, or status. A test thread also emits a summary line at
 124 completion listing the number of tests executed, number that failed, and a
 125 result code.
 126
 127 Example::
 128
 129     % dmesg | tail -n 1
 130     dmatest: dma0chan0-copy0: summary 1 test, 0 failures 1000 iops 100000 KB/s (0)
 131
 132 The details of a data miscompare error are also emitted, but do not follow the
 133 above format.
 134
 135 Part 5 - Handling channel allocation
 136 ====================================
 137
 138 Allocating Channels
 139 -------------------
 140
 141 Channels are required to be configured prior to starting the test run.
 142 Attempting to run the test without configuring the channels will fail.
 143
 144 Example::
 145
 146     % echo 1 > /sys/module/dmatest/parameters/run
 147     dmatest: Could not start test, no channels configured
 148
 149 Channels are registered using the "channel" parameter. Channels can be requested by their
 150 name, once requested, the channel is registered and a pending thread is added to the test list.
 151
 152 Example::
 153
 154     % echo dma0chan2 > /sys/module/dmatest/parameters/channel
 155     dmatest: Added 1 threads using dma0chan2
 156
 157 More channels can be added by repeating the example above.
 158 Reading back the channel parameter will return the name of last channel that was added successfully.
 159
 160 Example::
 161
 162     % echo dma0chan1 > /sys/module/dmatest/parameters/channel
 163     dmatest: Added 1 threads using dma0chan1
 164     % echo dma0chan2 > /sys/module/dmatest/parameters/channel
 165     dmatest: Added 1 threads using dma0chan2
 166     % cat /sys/module/dmatest/parameters/channel
 167     dma0chan2
 168
 169 Another method of requesting channels is to request a channel with an empty string, Doing so
 170 will request all channels available to be tested:
 171
 172 Example::
 173
 174     % echo "" > /sys/module/dmatest/parameters/channel
 175     dmatest: Added 1 threads using dma0chan0
 176     dmatest: Added 1 threads using dma0chan3
 177     dmatest: Added 1 threads using dma0chan4
 178     dmatest: Added 1 threads using dma0chan5
 179     dmatest: Added 1 threads using dma0chan6
 180     dmatest: Added 1 threads using dma0chan7
 181     dmatest: Added 1 threads using dma0chan8
 182
 183 At any point during the test configuration, reading the "test_list" parameter will
 184 print the list of currently pending tests.
 185
 186 Example::
 187
 188     % cat /sys/module/dmatest/parameters/test_list
 189     dmatest: 1 threads using dma0chan0
 190     dmatest: 1 threads using dma0chan3
 191     dmatest: 1 threads using dma0chan4
 192     dmatest: 1 threads using dma0chan5
 193     dmatest: 1 threads using dma0chan6
 194     dmatest: 1 threads using dma0chan7
 195     dmatest: 1 threads using dma0chan8
 196
 197 Note: Channels will have to be configured for each test run as channel configurations do not
 198 carry across to the next test run.
 199
 200 Releasing Channels
 201 -------------------
 202
 203 Channels can be freed by setting run to 0.
 204
 205 Example::
 206     % echo dma0chan1 > /sys/module/dmatest/parameters/channel
 207     dmatest: Added 1 threads using dma0chan1
 208     % cat /sys/class/dma/dma0chan1/in_use
 209     1
 210     % echo 0 > /sys/module/dmatest/parameters/run
 211     % cat /sys/class/dma/dma0chan1/in_use
 212     0
 213
 214 Channels allocated by previous test runs are automatically freed when a new
 215 channel is requested after completing a successful test run.