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