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 are required to be configured prior to starting the test run.
 147 Attempting to run the test without configuring the channels will fail.
 148
 149 Example::
 150
 151     % echo 1 > /sys/module/dmatest/parameters/run
 152     dmatest: Could not start test, no channels configured
 153
 154 Channels are registered using the "channel" parameter. Channels can be requested by their
 155 name, once requested, the channel is registered and a pending thread is added to the test list.
 156
 157 Example::
 158
 159     % echo dma0chan2 > /sys/module/dmatest/parameters/channel
 160     dmatest: Added 1 threads using dma0chan2
 161
 162 More channels can be added by repeating the example above.
 163 Reading back the channel parameter will return the name of last channel that was added successfully.
 164
 165 Example::
 166
 167     % echo dma0chan1 > /sys/module/dmatest/parameters/channel
 168     dmatest: Added 1 threads using dma0chan1
 169     % echo dma0chan2 > /sys/module/dmatest/parameters/channel
 170     dmatest: Added 1 threads using dma0chan2
 171     % cat /sys/module/dmatest/parameters/channel
 172     dma0chan2
 173
 174 Another method of requesting channels is to request a channel with an empty string, Doing so
 175 will request all channels available to be tested:
 176
 177 Example::
 178
 179     % echo "" > /sys/module/dmatest/parameters/channel
 180     dmatest: Added 1 threads using dma0chan0
 181     dmatest: Added 1 threads using dma0chan3
 182     dmatest: Added 1 threads using dma0chan4
 183     dmatest: Added 1 threads using dma0chan5
 184     dmatest: Added 1 threads using dma0chan6
 185     dmatest: Added 1 threads using dma0chan7
 186     dmatest: Added 1 threads using dma0chan8
 187
 188 At any point during the test configuration, reading the "test_list" parameter will
 189 print the list of currently pending tests.
 190
 191 Example::
 192
 193     % cat /sys/module/dmatest/parameters/test_list
 194     dmatest: 1 threads using dma0chan0
 195     dmatest: 1 threads using dma0chan3
 196     dmatest: 1 threads using dma0chan4
 197     dmatest: 1 threads using dma0chan5
 198     dmatest: 1 threads using dma0chan6
 199     dmatest: 1 threads using dma0chan7
 200     dmatest: 1 threads using dma0chan8
 201
 202 Note: Channels will have to be configured for each test run as channel configurations do not
 203 carry across to the next test run.
 204
 205 Releasing Channels
 206 -------------------
 207
 208 Channels can be freed by setting run to 0.
 209
 210 Example::
 211
 212     % echo dma0chan1 > /sys/module/dmatest/parameters/channel
 213     dmatest: Added 1 threads using dma0chan1
 214     % cat /sys/class/dma/dma0chan1/in_use
 215     1
 216     % echo 0 > /sys/module/dmatest/parameters/run
 217     % cat /sys/class/dma/dma0chan1/in_use
 218     0
 219
 220 Channels allocated by previous test runs are automatically freed when a new
 221 channel is requested after completing a successful test run.