<?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-D5ED62EB-744D-42EB-B8CF-D5623BDA5B38" xml:lang="en"><title>DMA Client Interface Guide</title><shortdesc>Explains how to use the interface between the DMA platform
service and the Symbian platform.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>The DMA client interface specifies the connection between the Symbian
platform and the DMA platform service. This document describes how
to open and close a DMA channel along with how to use the DMA client
interface to perform a DMA transfer.</p>
<section id="GUID-C917EAE6-BB3F-436A-BBF4-612FCCB837DB"><title>Interface
classes</title><p>The classes that process a DMA transfer are:</p><table id="GUID-32AF43CB-8D2F-427A-984F-B577280905F0">
<tgroup cols="2"><colspec colname="col1" colwidth="0.43*"/><colspec colname="col2" colwidth="1.57*"/>
<thead>
<row>
<entry align="center" valign="top"><p><b>Name</b></p></entry>
<entry align="center" valign="top"><p><b>Description</b></p></entry>
</row>
</thead>
<tbody>
<row>
<entry><p><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita"><apiname>DDmaRequest</apiname></xref></p></entry>
<entry><p>This class is used to handle transfer requests. It carries
out the configuration and initialization of the DMA transfer, along
with tracking the state of the transfer to the client. Communication
with the rest of the Symbian platform is carried out with the aid
of a callback function.</p></entry>
</row>
<row>
<entry><p><xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita"><apiname>TDmaChannel</apiname></xref></p></entry>
<entry><p>This class is used to open and close DMA channels.</p></entry>
</row>
</tbody>
</tgroup>
</table><p>The steps involved in performing a DMA transfer are described
below.</p></section>
<section id="GUID-96B6E82F-85C1-4AB0-96EF-F2E7AA705973"><title>Using
the DMA client interface</title><p>The sequence diagram of a DMA transfer
is:</p><fig id="GUID-6A4644F2-62A7-4821-9C13-DFF13793CAE0">
<title>The sequence diagram of a DMA transfer</title>
<image href="GUID-DDD883A2-6784-4851-8E36-227EC564452A_d0e90311_href.png" placement="inline"/>
</fig><p><b>Initialization</b></p><p>Before any DMA operations can
be carried out, the data structure that holds the configuration of
the DMA channel must be initialized. An example of this is shown below:</p><codeblock xml:space="preserve"> TDmaChannel::SCreateInfo info;
 
 info.iCookie = iDMAChannelNumber;
 info.iDesCount = 3;
 info.iDfcPriority = 3;
 info.iDfcQ = iDfcQue;</codeblock><p>The <codeph>iCookie</codeph> parameter
is used to provide a unique ID for the channel. Its value is application
specific.</p><p>The <codeph>iDesCount</codeph> element is used to
specify how many descriptors this channel can use.</p><p>The <codeph>iDfcPriority</codeph> element is used to specify the priority of
the DMA callback relative to all the other callbacks on its DFC queue.</p><p>The <codeph>iDfcQ</codeph> element is used to specify which DFC
queue is to be used by this DMA channel.</p><p><b>Open a DMA channel</b></p><p>Next the DMA channel is opened and configured. An example
of this is show below: </p><codeblock xml:space="preserve">r = TDmaChannel::Open(info, iDMAChannel);

if (r)
{
      // [...] handle the error
      return r;
}</codeblock><p>The first parameter for the open method holds the
channel configuration details. The second parameter is the DMA channel
handle. In this example, if an error occurs during the open operation,
then the error code is returned to the rest of the system and the
transfer is aborted.</p><p>The first parameter contains the DMA channel
configuration information. The second parameter points to the instance
of the DMA channel class that is to be used. This class must be declared
before this method call can be made.</p><p><b>Create a request object</b></p><p>The next task is to create a request object, specifying the
channel it will be queued on and the callback when it completes. An
example of this is shown below:</p><codeblock xml:space="preserve">new (iDMARequest) DDmaRequest(*iDMAChannel, DmaCallback, this);</codeblock><p>The above line creates a new instance of the DDmaRequest class
which will be queued on the DMA channel specified in the first parameter.
The callback function (<codeph>DmaCallback</codeph>) that will process
the result of an operation is specified in the second parameter and
is optional. The third parameter specifies the argument passed to
the callback function.</p><p><b>Transfer</b></p><p>Once the DMA channel
has been setup, the DMA transfer can be carried out. Executing a DMA
transfer consists of two parts:</p><ol>
<li id="GUID-FEBFEA0C-A6A3-4920-B62B-5F011F1FA571"><p>Specifying the
details of the DMA transfer.</p></li>
<li id="GUID-AD469BD7-94F4-4F79-91E0-2CB6CD988F97"><p>Placing the
transfer onto the DMA transfer queue.</p></li>
</ol><p>Once a successful transfer has been completed, the specified
DMA callback function is executed.</p><p>An example of the use of
the fragment method call is:</p><codeblock xml:space="preserve"> retval = iDMARequest-&gt;Fragment(EDmaSDMMC, aDest, aCount, KDmaMemDest | KDmaIncDest, 0);
 
 if (retval) 
{
     // [...] handle the error
     return retval;
}</codeblock><p>In this code snippet, the details of the DMA transfer
are specified. If an error is returned by the fragment method, then
the error code is passed on to the rest of the system and the transfer does
not take place. The first parameter specifies the data source. The
second specified the destination of the data. The third specifies
the number of bytes that are to be sent. The fourth parameter consists
of flags. The final parameter specifies any DMA PSL specific settings
(there are none in the example).</p><p>A code snippet that shows the
DMA transfer request being placed onto the DMA queue is:</p><codeblock xml:space="preserve"> iDMARequest-&gt;Queue();</codeblock><p><b>Close a DMA channel</b></p><p>Finally, once the DMA functionality is no longer required, the
DMA channel is closed. A code snippet that shows this is:</p><codeblock xml:space="preserve">iDMAChannel-&gt;Close();</codeblock><p>Where <codeph>iDMAChannel</codeph> is the instance of the DMA channel that was being used.</p></section>
</conbody></concept>