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