Documentation/dmatest.txt

				DMA Test Guide
				==============

		Andy Shevchenko <andriy.shevchenko@linux.intel.com>

This small document introduces how to test DMA drivers using dmatest module.

	Part 1 - How to build the test module

The menuconfig contains an option that could be found by following path:
	Device Drivers -> DMA Engine support -> DMA Test client

In the configuration file the option called CONFIG_DMATEST. The dmatest could
be built as module or inside kernel. Let's consider those cases.

	Part 2 - When dmatest is built as a module...

Example of usage:
	% modprobe dmatest channel=dma0chan0 timeout=2000 iterations=1 run=1

...or:
	% modprobe dmatest
	% echo dma0chan0 > /sys/module/dmatest/parameters/channel
	% echo 2000 > /sys/module/dmatest/parameters/timeout
	% echo 1 > /sys/module/dmatest/parameters/iterations
	% echo 1 > /sys/module/dmatest/parameters/run

...or on the kernel command line:

	dmatest.channel=dma0chan0 dmatest.timeout=2000 dmatest.iterations=1 dmatest.run=1

Hint: available channel list could be extracted by running the following
command:
	% ls -1 /sys/class/dma/

Once started a message like "dmatest: Started 1 threads using dma0chan0" is
emitted.  After that only test failure messages are reported until the test
stops.

Note that running a new test will not stop any in progress test.

The following command should return actual state of the test.
	% cat /sys/kernel/debug/dmatest/run

To wait for test done the user may perform a busy loop that checks the state.

	% while [ $(cat /sys/module/dmatest/parameters/run) = "Y" ]
	> do
	> 	echo -n "."
	> 	sleep 1
	> done
	> echo

	Part 3 - When built-in in the kernel...

The module parameters that is supplied to the kernel command line will be used
for the first performed test. After user gets a control, the test could be
re-run with the same or different parameters. For the details see the above
section "Part 2 - When dmatest is built as a module..."

In both cases the module parameters are used as the actual values for the test
case. You always could check them at run-time by running
	% grep -H . /sys/module/dmatest/parameters/*

	Part 4 - Gathering the test results

Test results are printed to the kernel log buffer with the format:

"dmatest: result <channel>: <test id>: '<error msg>' with src_off=<val> dst_off=<val> len=<val> (<err code>)"

Example of output:
	% dmesg | tail -n 1
	dmatest: result dma0chan0-copy0: #1: No errors with src_off=0x7bf dst_off=0x8ad len=0x3fea (0)

The message format is unified across the different types of errors. A number in
the parens represents additional information, e.g. error code, error counter,
or status.  A test thread also emits a summary line at completion listing the
number of tests executed, number that failed, and a result code.

Example:
	% dmesg | tail -n 1
	dmatest: dma3chan0-copy0: summary 400000 tests, 0 failures iops: 61524 KB/s 246098 (0)

The details of a data miscompare error are also emitted, but do not follow the
above format.