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