Documentation/driver-api/dmaengine/dmatest.rst

   1 ==============
   2 DMA Test Guide
   3 ==============
   4
   5 Andy Shevchenko <andriy.shevchenko@linux.intel.com>
   6
   7 This 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 Part 1 - How to build the test module
  15 =====================================
  16
  17 The menuconfig contains an option that could be found by following path:
  18
  19         Device Drivers -> DMA Engine support -> DMA Test client
  20
  21 In the configuration file the option called CONFIG_DMATEST. The dmatest could
  22 be built as module or inside kernel. Let's consider those cases.
  23
  24 Part 2 - When dmatest is built as a module
  25 ==========================================
  26
  27 Example of usage::
  28
  29     % modprobe dmatest channel=dma0chan0 timeout=2000 iterations=1 run=1
  30
  31 ...or::
  32
  33     % modprobe dmatest
  34     % echo dma0chan0 > /sys/module/dmatest/parameters/channel
  35     % echo 2000 > /sys/module/dmatest/parameters/timeout
  36     % echo 1 > /sys/module/dmatest/parameters/iterations
  37     % echo 1 > /sys/module/dmatest/parameters/run
  38
  39 ...or on the kernel command line::
  40
  41     dmatest.channel=dma0chan0 dmatest.timeout=2000 dmatest.iterations=1 dmatest.run=1
  42
  43 .. hint::
  44   available channel list could be extracted by running the following command::
  45
  46     % ls -1 /sys/class/dma/
  47
  48 Once started a message like "dmatest: Started 1 threads using dma0chan0" is
  49 emitted. After that only test failure messages are reported until the test
  50 stops.
  51
  52 Note that running a new test will not stop any in progress test.
  53
  54 The following command returns the state of the test. ::
  55
  56     % cat /sys/module/dmatest/parameters/run
  57
  58 To wait for test completion userpace can poll 'run' until it is false, or use
  59 the wait parameter. Specifying 'wait=1' when loading the module causes module
  60 initialization to pause until a test run has completed, while reading
  61 /sys/module/dmatest/parameters/wait waits for any running test to complete
  62 before returning. For example, the following scripts wait for 42 tests
  63 to complete before exiting. Note that if 'iterations' is set to 'infinite' then
  64 waiting is disabled.
  65
  66 Example::
  67
  68     % modprobe dmatest run=1 iterations=42 wait=1
  69     % modprobe -r dmatest
  70
  71 ...or::
  72
  73     % modprobe dmatest run=1 iterations=42
  74     % cat /sys/module/dmatest/parameters/wait
  75     % modprobe -r dmatest
  76
  77 Part 3 - When built-in in the kernel
  78 ====================================
  79
  80 The module parameters that is supplied to the kernel command line will be used
  81 for the first performed test. After user gets a control, the test could be
  82 re-run with the same or different parameters. For the details see the above
  83 section `Part 2 - When dmatest is built as a module`_.
  84
  85 In both cases the module parameters are used as the actual values for the test
  86 case. You always could check them at run-time by running ::
  87
  88     % grep -H . /sys/module/dmatest/parameters/*
  89
  90 Part 4 - Gathering the test results
  91 ===================================
  92
  93 Test results are printed to the kernel log buffer with the format::
  94
  95     "dmatest: result <channel>: <test id>: '<error msg>' with src_off=<val> dst_off=<val> len=<val> (<err code>)"
  96
  97 Example of output::
  98
  99     % dmesg | tail -n 1
 100     dmatest: result dma0chan0-copy0: #1: No errors with src_off=0x7bf dst_off=0x8ad len=0x3fea (0)
 101
 102 The message format is unified across the different types of errors. A
 103 number in the parentheses represents additional information, e.g. error
 104 code, error counter, or status. A test thread also emits a summary line at
 105 completion listing the number of tests executed, number that failed, and a
 106 result code.
 107
 108 Example::
 109
 110     % dmesg | tail -n 1
 111     dmatest: dma0chan0-copy0: summary 1 test, 0 failures 1000 iops 100000 KB/s (0)
 112
 113 The details of a data miscompare error are also emitted, but do not follow the
 114 above format.