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