<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-C2114C7B-705C-4527-836A-C6E72227111A" xml:lang="en"><title>DMA Testing Guide</title><shortdesc>Describes the required and optional testing for the DMA

framework.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>You can use the same set of source code to build the following

DMA test harnesses: </p>

<ol>

<li id="GUID-95B78247-5B32-479A-B013-A3FD4D04477E"><p><b>Simulation

PSL</b>: T_DMASIM.EXE, D_DMASIM.LDD, and DMASIM.DLL. This is a software-simulated

implementation of DMA that is used mainly for debugging and validating

the PIL (platform-independent layer), as it simulates all types of

DMA controller. </p></li>

<li id="GUID-4090D5D9-7D03-4E68-9870-FA035058F50B"><p><b>User-side

harness</b>: T_DMA.EXE. </p></li>

</ol>

<section id="GUID-34FD4B72-0481-46A3-9EB7-50CA55D01FF9">       <title>DMA test source files</title>       <p>The following test code are

available to test a DMA port.</p><table id="GUID-999C6533-DEEA-42DA-AAAD-5F9F2E3DB794">

<tgroup cols="4"><colspec colname="col1"/><colspec colname="col2"/>

<colspec colname="col3"/><colspec colname="COLSPEC0" colwidth="1.00*"/>

<thead>

<row>

<entry valign="top">File</entry>

<entry valign="top">Description</entry>

<entry valign="top">Location</entry>

<entry valign="top">Usage</entry>

</row>

</thead>

<tbody>

<row>

<entry>t_dma.exe</entry>

<entry>User-side test harness to test the DMA framework</entry>

<entry><filepath>/e32test/dma/t_dma.cpp</filepath></entry>

<entry>Mandatory</entry>

</row>

<row>

<entry>d_dma.ldd</entry>

<entry>Simulation PSL to test the DMA framework</entry>

<entry><filepath>/e32test/dma/d_dma.cpp</filepath></entry>

<entry>Mandatory</entry>

</row>

<row>

<entry>dmasim.dll</entry>

<entry>Software simulation of DMA controller and the SHAI implemetation</entry>

<entry><filepath>e32test/dma/dmasim.cpp</filepath></entry>

<entry>Optional, only used to test software simulated DMA controller.</entry>

</row>

<row>

<entry>t_dmasim.exe</entry>

<entry>User-side test harness to test the simulated DMA controller</entry>

<entry><filepath>/e32test/dma/t_dma.cpp</filepath></entry>

<entry>Optional, only used to test software simulated DMA controller.</entry>

</row>

<row>

<entry>d_dmasim.ldd</entry>

<entry>Kernel-side test harness to test the simulated DMA controller</entry>

<entry><filepath>/e32test/dma/d_dma.cpp</filepath></entry>

<entry>Optional, only used to test software simulated DMA controller.</entry>

</row>

</tbody>

</tgroup>

</table>     <p><filepath>T_DMA.EXE</filepath> is a user-side harness,

and is an automatic test included in the <codeph>E32TEST</codeph> suite.

It assumes that the underlying DMA controller supports memory to memory

transfers. This executable delegates most of the work to <filepath>D_DMA.LDD</filepath> , a logical device driver that acts as a client

for the DMA Framework. <filepath>D_DMA.LDD</filepath> links statically

against <filepath>DMA.DLL</filepath>, the DMA Framework kernel extension

must be built from the variant.</p><p><filepath>T_DMA.EXE</filepath> delegates most of the work to <filepath>D_DMA.LDD</filepath>, which

is a logical device driver that acts as a client for the DMA Framework.

D_DMA.LDD links statically against DMA.DLL, the DMA Framework kernel

extension must be built from the variant. In practice, this means

that D_DMA.LDD must be specified in the test <codeph>bld.inf</codeph> for the variant being ported. For an example of this, see <filepath>...\template_variant\test\bld.inf</filepath>. </p><p><filepath>D_DMA.LDD</filepath> calls the <xref href="GUID-3D0A9A03-E210-30EE-A1A1-7DA06E668CAA.dita"><apiname>DmaTestInfo()</apiname></xref> function in the PSL to

obtain the information on which channels are available to be used

by T_DMA to allow it to run multiple DMA channels simultaneously.

This is the template implementation: </p><codeblock xml:space="preserve">struct TDmaTestInfo

     {

     /** Maximum transfer size in bytes for all channels (ie. the minimum of all channels' maximum size)*/

     TInt iMaxTransferSize;

     /** 3->Memory buffers must be 4-byte aligned, 7->8-byte aligned, ... */

     TUint iMemAlignMask;

     /** Cookie to pass to DDmaRequest::Fragment for memory-memory transfer*/

     TUint32 iMemMemPslInfo;

     /** Number of test single-buffer channels */

     TInt iMaxSbChannels;

     /** Pointer to array containing single-buffer test channel ids */

     TUint32* iSbChannels;

     /** Number of test double-buffer channels */

     TInt iMaxDbChannels;

     /** Pointer to array containing double-buffer test channel ids */

     TUint32* iDbChannels;

     /** Number of test scatter-gather channels */

     TInt iMaxSgChannels;

     /** Pointer to array containing scatter-gather test channel ids */

     TUint32* iSgChannels;

     };

TDmaTestInfo TestInfo = {0, 0, 0, 0, NULL, 0, NULL, 0, NULL};

EXPORT_C const TDmaTestInfo& DmaTestInfo()

//...

    {

    return TestInfo;

    }

</codeblock></section>

<section id="GUID-A4207DD8-1DE4-4F4C-8EAB-BDEBF2D2A7F0"><title>Test

application use cases</title><p>The DMA test application is used to

test:</p><ul>

<li><p>one shot single buffer transfer</p></li>

<li><p>one shot double buffer transfer</p></li>

<li><p>one shot scatter/gather transfer</p></li>

<li><p>streaming single buffer transfer</p></li>

<li><p>streaming double buffer transfer</p></li>

<li><p>streaming scatter/gather transfer</p></li>

</ul><p>The DMA test application can be used on both reference hardware

platform and software simulated DMA.</p></section>

<section id="GUID-DA97B733-2449-4A74-B4A9-0682C8A4DCE0"><title>Limitations</title><p>The DMA test application has the following known limitations:</p><ul>

<li><p> only supports one shot and streaming data transfer</p></li>

<li><p>many parameters such as the number of buffers, the transfer

size and the number of fragments are fixed</p></li>

<li><p>does not support performance measurements like CPU usage, setup

time and transfer time</p></li>

<li><p>does not support memory to peripheral data transfer</p></li>

<li><p>does not support SMP related testing like allocating DFC on

same core or different core.</p></li>

</ul></section>

</conbody><related-links>

<link href="GUID-95A33491-17AC-4F12-948E-A1352ADDA483.dita"><linktext>DMA

Implementation Guide</linktext></link>

</related-links></concept>