0001 ==============
0002 DMA Test Guide
0003 ==============
0004
0005 Andy Shevchenko <andriy.shevchenko@linux.intel.com>
0006
0007 This small document introduces how to test DMA drivers using dmatest module.
0008
0009 The dmatest module tests DMA memcpy, memset, XOR and RAID6 P+Q operations using
0010 various lengths and various offsets into the source and destination buffers. It
0011 will initialize both buffers with a repeatable pattern and verify that the DMA
0012 engine copies the requested region and nothing more. It will also verify that
0013 the bytes aren't swapped around, and that the source buffer isn't modified.
0014
0015 The dmatest module can be configured to test a specific channel. It can also
0016 test multiple channels at the same time, and it can start multiple threads
0017 competing for the same channel.
0018
0019 .. note::
0020 The test suite works only on the channels that have at least one
0021 capability of the following: DMA_MEMCPY (memory-to-memory), DMA_MEMSET
0022 (const-to-memory or memory-to-memory, when emulated), DMA_XOR, DMA_PQ.
0023
0024 .. note::
0025 In case of any related questions use the official mailing list
0026 dmaengine@vger.kernel.org.
0027
0028 Part 1 - How to build the test module
0029 =====================================
0030
0031 The menuconfig contains an option that could be found by following path:
0032
0033 Device Drivers -> DMA Engine support -> DMA Test client
0034
0035 In the configuration file the option called CONFIG_DMATEST. The dmatest could
0036 be built as module or inside kernel. Let's consider those cases.
0037
0038 Part 2 - When dmatest is built as a module
0039 ==========================================
0040
0041 Example of usage::
0042
0043 % modprobe dmatest timeout=2000 iterations=1 channel=dma0chan0 run=1
0044
0045 ...or::
0046
0047 % modprobe dmatest
0048 % echo 2000 > /sys/module/dmatest/parameters/timeout
0049 % echo 1 > /sys/module/dmatest/parameters/iterations
0050 % echo dma0chan0 > /sys/module/dmatest/parameters/channel
0051 % echo 1 > /sys/module/dmatest/parameters/run
0052
0053 ...or on the kernel command line::
0054
0055 dmatest.timeout=2000 dmatest.iterations=1 dmatest.channel=dma0chan0 dmatest.run=1
0056
0057 Example of multi-channel test usage (new in the 5.0 kernel)::
0058
0059 % modprobe dmatest
0060 % echo 2000 > /sys/module/dmatest/parameters/timeout
0061 % echo 1 > /sys/module/dmatest/parameters/iterations
0062 % echo dma0chan0 > /sys/module/dmatest/parameters/channel
0063 % echo dma0chan1 > /sys/module/dmatest/parameters/channel
0064 % echo dma0chan2 > /sys/module/dmatest/parameters/channel
0065 % echo 1 > /sys/module/dmatest/parameters/run
0066
0067 .. note::
0068 For all tests, starting in the 5.0 kernel, either single- or multi-channel,
0069 the channel parameter(s) must be set after all other parameters. It is at
0070 that time that the existing parameter values are acquired for use by the
0071 thread(s). All other parameters are shared. Therefore, if changes are made
0072 to any of the other parameters, and an additional channel specified, the
0073 (shared) parameters used for all threads will use the new values.
0074 After the channels are specified, each thread is set as pending. All threads
0075 begin execution when the run parameter is set to 1.
0076
0077 .. hint::
0078 A list of available channels can be found by running the following command::
0079
0080 % ls -1 /sys/class/dma/
0081
0082 Once started a message like " dmatest: Added 1 threads using dma0chan0" is
0083 emitted. A thread for that specific channel is created and is now pending, the
0084 pending thread is started once run is to 1.
0085
0086 Note that running a new test will not stop any in progress test.
0087
0088 The following command returns the state of the test. ::
0089
0090 % cat /sys/module/dmatest/parameters/run
0091
0092 To wait for test completion userpace can poll 'run' until it is false, or use
0093 the wait parameter. Specifying 'wait=1' when loading the module causes module
0094 initialization to pause until a test run has completed, while reading
0095 /sys/module/dmatest/parameters/wait waits for any running test to complete
0096 before returning. For example, the following scripts wait for 42 tests
0097 to complete before exiting. Note that if 'iterations' is set to 'infinite' then
0098 waiting is disabled.
0099
0100 Example::
0101
0102 % modprobe dmatest run=1 iterations=42 wait=1
0103 % modprobe -r dmatest
0104
0105 ...or::
0106
0107 % modprobe dmatest run=1 iterations=42
0108 % cat /sys/module/dmatest/parameters/wait
0109 % modprobe -r dmatest
0110
0111 Part 3 - When built-in in the kernel
0112 ====================================
0113
0114 The module parameters that is supplied to the kernel command line will be used
0115 for the first performed test. After user gets a control, the test could be
0116 re-run with the same or different parameters. For the details see the above
0117 section `Part 2 - When dmatest is built as a module`_.
0118
0119 In both cases the module parameters are used as the actual values for the test
0120 case. You always could check them at run-time by running ::
0121
0122 % grep -H . /sys/module/dmatest/parameters/*
0123
0124 Part 4 - Gathering the test results
0125 ===================================
0126
0127 Test results are printed to the kernel log buffer with the format::
0128
0129 "dmatest: result <channel>: <test id>: '<error msg>' with src_off=<val> dst_off=<val> len=<val> (<err code>)"
0130
0131 Example of output::
0132
0133 % dmesg | tail -n 1
0134 dmatest: result dma0chan0-copy0: #1: No errors with src_off=0x7bf dst_off=0x8ad len=0x3fea (0)
0135
0136 The message format is unified across the different types of errors. A
0137 number in the parentheses represents additional information, e.g. error
0138 code, error counter, or status. A test thread also emits a summary line at
0139 completion listing the number of tests executed, number that failed, and a
0140 result code.
0141
0142 Example::
0143
0144 % dmesg | tail -n 1
0145 dmatest: dma0chan0-copy0: summary 1 test, 0 failures 1000 iops 100000 KB/s (0)
0146
0147 The details of a data miscompare error are also emitted, but do not follow the
0148 above format.
0149
0150 Part 5 - Handling channel allocation
0151 ====================================
0152
0153 Allocating Channels
0154 -------------------
0155
0156 Channels do not need to be configured prior to starting a test run. Attempting
0157 to run the test without configuring the channels will result in testing any
0158 channels that are available.
0159
0160 Example::
0161
0162 % echo 1 > /sys/module/dmatest/parameters/run
0163 dmatest: No channels configured, continue with any
0164
0165 Channels are registered using the "channel" parameter. Channels can be requested by their
0166 name, once requested, the channel is registered and a pending thread is added to the test list.
0167
0168 Example::
0169
0170 % echo dma0chan2 > /sys/module/dmatest/parameters/channel
0171 dmatest: Added 1 threads using dma0chan2
0172
0173 More channels can be added by repeating the example above.
0174 Reading back the channel parameter will return the name of last channel that was added successfully.
0175
0176 Example::
0177
0178 % echo dma0chan1 > /sys/module/dmatest/parameters/channel
0179 dmatest: Added 1 threads using dma0chan1
0180 % echo dma0chan2 > /sys/module/dmatest/parameters/channel
0181 dmatest: Added 1 threads using dma0chan2
0182 % cat /sys/module/dmatest/parameters/channel
0183 dma0chan2
0184
0185 Another method of requesting channels is to request a channel with an empty string, Doing so
0186 will request all channels available to be tested:
0187
0188 Example::
0189
0190 % echo "" > /sys/module/dmatest/parameters/channel
0191 dmatest: Added 1 threads using dma0chan0
0192 dmatest: Added 1 threads using dma0chan3
0193 dmatest: Added 1 threads using dma0chan4
0194 dmatest: Added 1 threads using dma0chan5
0195 dmatest: Added 1 threads using dma0chan6
0196 dmatest: Added 1 threads using dma0chan7
0197 dmatest: Added 1 threads using dma0chan8
0198
0199 At any point during the test configuration, reading the "test_list" parameter will
0200 print the list of currently pending tests.
0201
0202 Example::
0203
0204 % cat /sys/module/dmatest/parameters/test_list
0205 dmatest: 1 threads using dma0chan0
0206 dmatest: 1 threads using dma0chan3
0207 dmatest: 1 threads using dma0chan4
0208 dmatest: 1 threads using dma0chan5
0209 dmatest: 1 threads using dma0chan6
0210 dmatest: 1 threads using dma0chan7
0211 dmatest: 1 threads using dma0chan8
0212
0213 Note: Channels will have to be configured for each test run as channel configurations do not
0214 carry across to the next test run.
0215
0216 Releasing Channels
0217 -------------------
0218
0219 Channels can be freed by setting run to 0.
0220
0221 Example::
0222
0223 % echo dma0chan1 > /sys/module/dmatest/parameters/channel
0224 dmatest: Added 1 threads using dma0chan1
0225 % cat /sys/class/dma/dma0chan1/in_use
0226 1
0227 % echo 0 > /sys/module/dmatest/parameters/run
0228 % cat /sys/class/dma/dma0chan1/in_use
0229 0
0230
0231 Channels allocated by previous test runs are automatically freed when a new
0232 channel is requested after completing a successful test run.
