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 (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
72Once started a message like " dmatest: Added 1 threads using dma0chan0" is
73emitted. A thread for that specific channel is created and is now pending, the
74pending thread is started once run is to 1.
75
76Note that running a new test will not stop any in progress test.
77
78The following command returns the state of the test. ::
79
80    % cat /sys/module/dmatest/parameters/run
81
82To wait for test completion userpace can poll 'run' until it is false, or use
83the wait parameter. Specifying 'wait=1' when loading the module causes module
84initialization to pause until a test run has completed, while reading
85/sys/module/dmatest/parameters/wait waits for any running test to complete
86before returning. For example, the following scripts wait for 42 tests
87to complete before exiting. Note that if 'iterations' is set to 'infinite' then
88waiting is disabled.
89
90Example::
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
101Part 3 - When built-in in the kernel
102====================================
103
104The module parameters that is supplied to the kernel command line will be used
105for the first performed test. After user gets a control, the test could be
106re-run with the same or different parameters. For the details see the above
107section `Part 2 - When dmatest is built as a module`_.
108
109In both cases the module parameters are used as the actual values for the test
110case. You always could check them at run-time by running ::
111
112    % grep -H . /sys/module/dmatest/parameters/*
113
114Part 4 - Gathering the test results
115===================================
116
117Test 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
121Example 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
126The message format is unified across the different types of errors. A
127number in the parentheses represents additional information, e.g. error
128code, error counter, or status. A test thread also emits a summary line at
129completion listing the number of tests executed, number that failed, and a
130result code.
131
132Example::
133
134    % dmesg | tail -n 1
135    dmatest: dma0chan0-copy0: summary 1 test, 0 failures 1000 iops 100000 KB/s (0)
136
137The details of a data miscompare error are also emitted, but do not follow the
138above format.
139
140Part 5 - Handling channel allocation
141====================================
142
143Allocating Channels
144-------------------
145
146Channels are required to be configured prior to starting the test run.
147Attempting to run the test without configuring the channels will fail.
148
149Example::
150
151    % echo 1 > /sys/module/dmatest/parameters/run
152    dmatest: Could not start test, no channels configured
153
154Channels are registered using the "channel" parameter. Channels can be requested by their
155name, once requested, the channel is registered and a pending thread is added to the test list.
156
157Example::
158
159    % echo dma0chan2 > /sys/module/dmatest/parameters/channel
160    dmatest: Added 1 threads using dma0chan2
161
162More channels can be added by repeating the example above.
163Reading back the channel parameter will return the name of last channel that was added successfully.
164
165Example::
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
174Another method of requesting channels is to request a channel with an empty string, Doing so
175will request all channels available to be tested:
176
177Example::
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
188At any point during the test configuration, reading the "test_list" parameter will
189print the list of currently pending tests.
190
191Example::
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
202Note: Channels will have to be configured for each test run as channel configurations do not
203carry across to the next test run.
204
205Releasing Channels
206-------------------
207
208Channels can be freed by setting run to 0.
209
210Example::
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
220Channels allocated by previous test runs are automatically freed when a new
221channel is requested after completing a successful test run.
222