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 (new in the 5.0 kernel)::
  48
  49     % modprobe dmatest
  50     % echo 2000 > /sys/module/dmatest/parameters/timeout
  51     % echo 1 > /sys/module/dmatest/parameters/iterations
  52     % echo dma0chan0 > /sys/module/dmatest/parameters/channel
  53     % echo dma0chan1 > /sys/module/dmatest/parameters/channel
  54     % echo dma0chan2 > /sys/module/dmatest/parameters/channel
  55     % echo 1 > /sys/module/dmatest/parameters/run
  56
  57 .. note::
  58   For all tests, starting in the 5.0 kernel, either single- or multi-channel,
  59   the channel parameter(s) must be set after all other parameters. It is at
  60   that time that the existing parameter values are acquired for use by the
  61   thread(s). All other parameters are shared. Therefore, if changes are made
  62   to any of the other parameters, and an additional channel specified, the
  63   (shared) parameters used for all threads will use the new values.
  64   After the channels are specified, each thread is set as pending. All threads
  65   begin execution when the run parameter is set to 1.
  66
  67 .. hint::
  68   A list of available channels can be found by running the following command::
  69
  70     % ls -1 /sys/class/dma/
  71
  72 Once started a message like " dmatest: Added 1 threads using dma0chan0" is
  73 emitted. A thread for that specific channel is created and is now pending, the
  74 pending thread is started once run is to 1.
  75
  76 Note that running a new test will not stop any in progress test.
  77
  78 The following command returns the state of the test. ::
  79
  80     % cat /sys/module/dmatest/parameters/run
  81
  82 To wait for test completion userpace can poll 'run' until it is false, or use
  83 the wait parameter. Specifying 'wait=1' when loading the module causes module
  84 initialization to pause until a test run has completed, while reading
  85 /sys/module/dmatest/parameters/wait waits for any running test to complete
  86 before returning. For example, the following scripts wait for 42 tests
  87 to complete before exiting. Note that if 'iterations' is set to 'infinite' then
  88 waiting is disabled.
  89
  90 Example::
  91
  92     % modprobe dmatest run=1 iterations=42 wait=1
  93     % modprobe -r dmatest
  94
  95 ...or::
  96
  97     % modprobe dmatest run=1 iterations=42
  98     % cat /sys/module/dmatest/parameters/wait
  99     % modprobe -r dmatest
 100
 101 Part 3 - When built-in in the kernel
 102 ====================================
 103
 104 The module parameters that is supplied to the kernel command line will be used
 105 for the first performed test. After user gets a control, the test could be
 106 re-run with the same or different parameters. For the details see the above
 107 section `Part 2 - When dmatest is built as a module`_.
 108
 109 In both cases the module parameters are used as the actual values for the test
 110 case. You always could check them at run-time by running ::
 111
 112     % grep -H . /sys/module/dmatest/parameters/*
 113
 114 Part 4 - Gathering the test results
 115 ===================================
 116
 117 Test results are printed to the kernel log buffer with the format::
 118
 119     "dmatest: result <channel>: <test id>: '<error msg>' with src_off=<val> dst_off=<val> len=<val> (<err code>)"
 120
 121 Example of output::
 122
 123     % dmesg | tail -n 1
 124     dmatest: result dma0chan0-copy0: #1: No errors with src_off=0x7bf dst_off=0x8ad len=0x3fea (0)
 125
 126 The message format is unified across the different types of errors. A
 127 number in the parentheses represents additional information, e.g. error
 128 code, error counter, or status. A test thread also emits a summary line at
 129 completion listing the number of tests executed, number that failed, and a
 130 result code.
 131
 132 Example::
 133
 134     % dmesg | tail -n 1
 135     dmatest: dma0chan0-copy0: summary 1 test, 0 failures 1000 iops 100000 KB/s (0)
 136
 137 The details of a data miscompare error are also emitted, but do not follow the
 138 above format.
 139
 140 Part 5 - Handling channel allocation
 141 ====================================
 142
 143 Allocating Channels
 144 -------------------
 145
 146 Channels do not need to be configured prior to starting a test run. Attempting
 147 to run the test without configuring the channels will result in testing any
 148 channels that are available.
 149
 150 Example::
 151
 152     % echo 1 > /sys/module/dmatest/parameters/run
 153     dmatest: No channels configured, continue with any
 154
 155 Channels are registered using the "channel" parameter. Channels can be requested by their
 156 name, once requested, the channel is registered and a pending thread is added to the test list.
 157
 158 Example::
 159
 160     % echo dma0chan2 > /sys/module/dmatest/parameters/channel
 161     dmatest: Added 1 threads using dma0chan2
 162
 163 More channels can be added by repeating the example above.
 164 Reading back the channel parameter will return the name of last channel that was added successfully.
 165
 166 Example::
 167
 168     % echo dma0chan1 > /sys/module/dmatest/parameters/channel
 169     dmatest: Added 1 threads using dma0chan1
 170     % echo dma0chan2 > /sys/module/dmatest/parameters/channel
 171     dmatest: Added 1 threads using dma0chan2
 172     % cat /sys/module/dmatest/parameters/channel
 173     dma0chan2
 174
 175 Another method of requesting channels is to request a channel with an empty string, Doing so
 176 will request all channels available to be tested:
 177
 178 Example::
 179
 180     % echo "" > /sys/module/dmatest/parameters/channel
 181     dmatest: Added 1 threads using dma0chan0
 182     dmatest: Added 1 threads using dma0chan3
 183     dmatest: Added 1 threads using dma0chan4
 184     dmatest: Added 1 threads using dma0chan5
 185     dmatest: Added 1 threads using dma0chan6
 186     dmatest: Added 1 threads using dma0chan7
 187     dmatest: Added 1 threads using dma0chan8
 188
 189 At any point during the test configuration, reading the "test_list" parameter will
 190 print the list of currently pending tests.
 191
 192 Example::
 193
 194     % cat /sys/module/dmatest/parameters/test_list
 195     dmatest: 1 threads using dma0chan0
 196     dmatest: 1 threads using dma0chan3
 197     dmatest: 1 threads using dma0chan4
 198     dmatest: 1 threads using dma0chan5
 199     dmatest: 1 threads using dma0chan6
 200     dmatest: 1 threads using dma0chan7
 201     dmatest: 1 threads using dma0chan8
 202
 203 Note: Channels will have to be configured for each test run as channel configurations do not
 204 carry across to the next test run.
 205
 206 Releasing Channels
 207 -------------------
 208
 209 Channels can be freed by setting run to 0.
 210
 211 Example::
 212
 213     % echo dma0chan1 > /sys/module/dmatest/parameters/channel
 214     dmatest: Added 1 threads using dma0chan1
 215     % cat /sys/class/dma/dma0chan1/in_use
 216     1
 217     % echo 0 > /sys/module/dmatest/parameters/run
 218     % cat /sys/class/dma/dma0chan1/in_use
 219     0
 220
 221 Channels allocated by previous test runs are automatically freed when a new
 222 channel is requested after completing a successful test run.