From patchwork Fri Nov 3 04:49:40 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Vinod Koul X-Patchwork-Id: 10039527 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id EC52C600C5 for ; Fri, 3 Nov 2017 04:46:56 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id DDFD5286B3 for ; Fri, 3 Nov 2017 04:46:56 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id D28B228992; Fri, 3 Nov 2017 04:46:56 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 49604294B0 for ; Fri, 3 Nov 2017 04:46:56 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752196AbdKCEqz (ORCPT ); Fri, 3 Nov 2017 00:46:55 -0400 Received: from mga07.intel.com ([134.134.136.100]:2369 "EHLO mga07.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750794AbdKCEqz (ORCPT ); Fri, 3 Nov 2017 00:46:55 -0400 Received: from fmsmga002.fm.intel.com ([10.253.24.26]) by orsmga105.jf.intel.com with ESMTP; 02 Nov 2017 21:46:54 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.44,336,1505804400"; d="scan'208";a="1239135590" Received: from vkoul-udesk7.iind.intel.com ([10.223.84.143]) by fmsmga002.fm.intel.com with ESMTP; 02 Nov 2017 21:46:53 -0700 From: Vinod Koul To: dmaengine@vger.kernel.org Cc: linux-doc@vger.kernel.org, Jonathan Corbet , Vinod Koul Subject: [PATCH v2 4/6] dmaengine: doc: ReSTize dmatest doc Date: Fri, 3 Nov 2017 10:19:40 +0530 Message-Id: <1509684582-11930-5-git-send-email-vinod.koul@intel.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1509684582-11930-1-git-send-email-vinod.koul@intel.com> References: <1509684582-11930-1-git-send-email-vinod.koul@intel.com> Sender: dmaengine-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: dmaengine@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP This converts and moves dmatest file with some format changes for RST style Signed-off-by: Vinod Koul --- .../dmaengine/dmatest.rst} | 96 +++++++++++++--------- Documentation/driver-api/dmaengine/index.rst | 10 +++ 2 files changed, 67 insertions(+), 39 deletions(-) rename Documentation/{dmaengine/dmatest.txt => driver-api/dmaengine/dmatest.rst} (50%) diff --git a/Documentation/dmaengine/dmatest.txt b/Documentation/driver-api/dmaengine/dmatest.rst similarity index 50% rename from Documentation/dmaengine/dmatest.txt rename to Documentation/driver-api/dmaengine/dmatest.rst index fb683c72dea8..3922c0a3f0c0 100644 --- a/Documentation/dmaengine/dmatest.txt +++ b/Documentation/driver-api/dmaengine/dmatest.rst @@ -1,11 +1,13 @@ - DMA Test Guide - ============== +============== +DMA Test Guide +============== - Andy Shevchenko +Andy Shevchenko This small document introduces how to test DMA drivers using dmatest module. - Part 1 - How to build the test 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 @@ -13,25 +15,31 @@ The menuconfig contains an option that could be found by following path: 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... +Part 2 - When dmatest is built as a module +========================================== -Example of usage: - % modprobe dmatest channel=dma0chan0 timeout=2000 iterations=1 run=1 +Example of usage: :: -...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 + % modprobe dmatest channel=dma0chan0 timeout=2000 iterations=1 run=1 -...or on the kernel command line: +...or: :: - dmatest.channel=dma0chan0 dmatest.timeout=2000 dmatest.iterations=1 dmatest.run=1 + % 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 -Hint: available channel list could be extracted by running the following -command: - % ls -1 /sys/class/dma/ +...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 @@ -39,8 +47,9 @@ stops. Note that running a new test will not stop any in progress test. -The following command returns the state of the test. - % cat /sys/module/dmatest/parameters/run +The following command returns the state of the test. :: + + % cat /sys/module/dmatest/parameters/run To wait for test completion userpace can poll 'run' until it is false, or use the wait parameter. Specifying 'wait=1' when loading the module causes module @@ -50,15 +59,19 @@ before returning. For example, the following scripts wait for 42 tests to complete before exiting. Note that if 'iterations' is set to 'infinite' then waiting is disabled. -Example: - % modprobe dmatest run=1 iterations=42 wait=1 - % modprobe -r dmatest -...or: - % modprobe dmatest run=1 iterations=42 - % cat /sys/module/dmatest/parameters/wait - % modprobe -r dmatest +Example: :: + + % modprobe dmatest run=1 iterations=42 wait=1 + % modprobe -r dmatest - Part 3 - When built-in in the kernel... +...or: :: + + % modprobe dmatest run=1 iterations=42 + % cat /sys/module/dmatest/parameters/wait + % modprobe -r dmatest + +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 @@ -66,27 +79,32 @@ 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/* +case. You always could check them at run-time by running :: + + % grep -H . /sys/module/dmatest/parameters/* - Part 4 - Gathering the test results +Part 4 - Gathering the test results +=================================== -Test results are printed to the kernel log buffer with the format: +Test results are printed to the kernel log buffer with the format: :: -"dmatest: result : : '' with src_off= dst_off= len= ()" + "dmatest: result : : '' with src_off= dst_off= len= ()" -Example of output: - % dmesg | tail -n 1 - dmatest: result dma0chan0-copy0: #1: No errors with src_off=0x7bf dst_off=0x8ad len=0x3fea (0) +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: dma0chan0-copy0: summary 1 test, 0 failures 1000 iops 100000 KB/s (0) +Example: :: + + % dmesg | tail -n 1 + dmatest: dma0chan0-copy0: summary 1 test, 0 failures 1000 iops 100000 KB/s (0) The details of a data miscompare error are also emitted, but do not follow the above format. diff --git a/Documentation/driver-api/dmaengine/index.rst b/Documentation/driver-api/dmaengine/index.rst index ffc2b797938c..fae852922a49 100644 --- a/Documentation/driver-api/dmaengine/index.rst +++ b/Documentation/driver-api/dmaengine/index.rst @@ -27,6 +27,16 @@ API of the DMAEngine. This is applicable only for slave DMA usage only. client +DMA Test documentation +---------------------- + +This book introduces how to test DMA drivers using dmatest module. + +.. toctree:: + :maxdepth: 1 + + dmatest + .. only:: subproject Indices