<?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-C74770A5-ADD4-4AB1-946F-77105E2B8C10" xml:lang="en"><title>DMA

Request Operations</title><shortdesc>This document describes the operations which a device driver performs

on a DMA request.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>After doing the required DMA initialisation, a driver can start a DMA operation.

To do this, the driver fragments the request and then queues the request. </p>

<section id="GUID-24567A76-814B-4E1C-81CA-61D9142B442B"><title>Fragment</title> <p>A

DMA request can be split into different fragments that are small enough to

be sent to DMAC. The size of each fragment is smaller than or equal to the

maximum transfer size supported by the DMAC. To fragment a DMA request, a

source and destination address, and the size of data to be transferred, must

be provided. If the source and/or destination is in memory, each fragment

points to memory which is physically contiguous. </p> <p>The kind of transfer

to perform is specified using a set of flags and hardware-specific information.

The flags can be: </p> <table id="GUID-52098463-21DE-5D42-8F35-9B6D67CE93BC">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p> <xref href="GUID-F607BDD4-4ED7-3841-B355-C5099C42612A.dita"><apiname>KDmaMemSrc</apiname></xref>  </p> </entry>

<entry><p>Source is the address of a memory buffer </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-B9018464-BBE0-3CF6-9B15-94E9658D1821.dita"><apiname>KDmaMmeDest </apiname></xref>  </p> </entry>

<entry><p>Destination is the address of a memory buffer </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-018CF7EC-55F3-38CB-9AC5-31ADE568F20B.dita"><apiname>KDmaIncSrc</apiname></xref>  </p> </entry>

<entry><p>Source address must be post-incremented during transfer </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-74D836AD-5A93-3971-9C73-583B4471AB18.dita"><apiname>KDmaIncDest</apiname></xref>  </p> </entry>

<entry><p>Destination address must be post-incremented during transfer </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-45E60D7F-0309-3EC0-B621-A1DF4A3358B9.dita"><apiname>KDmaPhysAddrSrc</apiname></xref>  </p> </entry>

<entry><p>Source address is a physical address (as opposed to a linear one) </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-82B3046B-F41C-3C99-8EAD-2F072D210BEF.dita"><apiname>KDmaPhysAddrDest</apiname></xref>  </p> </entry>

<entry><p>Destination address is a physical address (as opposed to a linear

one) </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>The following shows an example of fragmenting a DMA request: </p> <codeblock id="GUID-E2DE10F1-7E22-5EA6-A05C-1A76B98D1F91" xml:space="preserve">/**

 Start the DMA transfer. This function fragments the DMA request and 

 queues it for processing and actually triggers the DMA transfer.

 @param    aSource

        Source address for DMA transfer

    @param    aCount

         Size of data to be transferred            

 @return    KErrNone on success, else standard error code on failure

 */    

TInt DExDriverUartTxDma::Start(const TUint8* aSource, TInt aCount)

    {

    ...

    // Fragment the DMA request. DDmaRequest::Fragment() creates 

    // the DMA descriptor with source, destination address, size 

    // and attributes.

    // 

    // Flags KDmaMemSrc|KDmaIncSrc or KDmaMemDest|KDmaIncDest 

    // should be set if the source/destination is a memory buffer, 

    // or cleared if the source/destination is a peripheral. If the address 

    // specified is physical address instead of linear, 

    // then specify KDmaPhysAddrSrc or KDmaPhysAddrDest accordingly.

    //

    TInt retval = iTxDmaRequest->Fragment((TUint32)buf,

            (TUint32)(iUartComm->iPortAddr + KHoUART_THR), aCount,

            KDmaMemSrc |KDmaIncSrc, // source is a buffer

            0 ); // no HW Flags    

    if(retval != KErrNone)

        {

        return retval;

        }

    ...

    }</codeblock> </section>

<section id="GUID-72984A7F-C2C4-48E5-8656-638D472A2ACD"><title>Queue</title> <p>DMA transfer is initiated by queuing the

DMA request. A device driver queues the request by calling <xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-0A83F782-DB62-39ED-8D32-DBD5949C8D3F"><apiname>DDmaRequest::Queue()</apiname></xref> after

fragmenting the DMA request. This is an asynchronous call and the transfer

of DMA will actually start once the request is scheduled. </p> <codeblock id="GUID-FD225A28-4AFA-5CE0-A341-2261C97E7D1A" xml:space="preserve">/**

 Start the DMA transfer. This function fragments the DMA request and 

 queues it for processing and actually triggers the DMA transfer.

 @param    aSource Source address for DMA transfer

 @param    aCount Size of data to be transferred            

 @return    KErrNone on success, else standard error code on failure

 */

TInt DExDriverUartTxDma::Start(const TUint8* aSource, TInt aCount)

    {

    ...

    // Queue the DMA request. DDmaRequest::Queue() queues the 

    // request on the DFCQ. When it is processed, the SDMAC driver calls 

    // the helper ChannelTransfer() to start the transfer on the 

    // device. DMA operation starts at this point.

    //

    iTxDmaRequest->Queue();

    ...

    }</codeblock> <p>If the request channel is idle when a request is queued,

the request is transferred immediately. Otherwise, it is queued and transferred

later. The client is responsible for ensuring cache consistency before and/or

after the transfer if necessary. </p></section>

<section id="GUID-FA035D89-F593-49C5-84EC-BC5019C63F0B"><title>Completion notification</title> <p>Once the DMA request is

handled by the DMAC, the DMA service callback function is called by the DMA

driver. This runs in a DFC context, that is scheduled from a DMA interrupt

service routine. </p> <p>The DMA service callback function pointer must be

provided while creating the DMA request: </p> <codeblock id="GUID-0A15F944-F066-52E2-BFB6-D008DF690BA6" xml:space="preserve">iTxDmaRequest = new DDmaRequest(*iTxDmaChannel, TxDmaService, this);</codeblock> <p>The DMA callback function is called for both success and failure of the

request, so it needs to check the request result. On success, the function

should either initiate another DMA request, or stop DMA and close the request.

On failure, the function should stop DMA by cancelling the request. </p> <codeblock id="GUID-BD28E559-FA5B-564E-BC00-3BD98C61F201" xml:space="preserve">/**

 DMA service callback function for transmit. This static function is 

 called on the completion of DMA transfer request. This function 

 pointer is provided while creating the DMA request, i.e. in     

 DDmaRequest(). After the request is queued, the System DMA controller 

 completes the request and calls this service function. Here, we do 

 the processing that needs to be done post the DMA request  

 completion.

 This function shall be called both when the DMA request succeeds or fails, 

    so both must be handled appropriately.

 @param    aResult    

     DMA result, can be DDmaRequest::EOk in case of success, else error

 @param    aArg pointer passed at time of registration, typically <this> 

        pointer

 @return    none 

 */

static void TxDmaService(DDmaRequest::TResult aResult, TAny* aArg)

    {

    // Check the result of DMA service function call. It can be 

    // either of the DDmaRequest::TResult enumerated values.

    //

    if ( aResult != DDmaRequest::EOk)

        {

        // DMA request failed, so stop the DMA. 

        Stop ();

        // Notify request completion with an error result

        ...

        }

    else

        {

        // DMA request was successful. 

     // The program can start another DMA request, or stop 

        // the DMA, if no more DMA requests are needed.

        // Notify request operation complete with success.

        ...

        }

    }</codeblock></section>