<?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-58AA7257-0951-42AB-9B6E-AAF63343FEFA-GENID-1-2-1-10-1-5-1-5-1-1-7-1-9-1-5-1" xml:lang="en"><title>DMA Channel Operations</title><shortdesc>Describes how a device driver should open and close a DMA

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

<section id="GUID-C4241738-D4C3-4171-87B2-5EDFFACE4002-GENID-1-2-1-10-1-5-1-5-1-1-7-1-9-1-5-1-3-1"><title>Open</title><p>To use a DMA channel it has to be opened. <xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-514BA285-3563-3C24-A067-F360098A6ADF"><apiname>TDmaChannel::Open()</apiname></xref> must be called to open the channel, and the required information

provided in a <xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-6B973278-8BE7-3CE5-97D8-60E8D3F4D473"><apiname>TDmaChannel::SCreateInfo</apiname></xref> structure.

The actual DMA channel selection is done by the hardware specific

layer. </p> <codeblock id="GUID-A1CA8DBA-1378-502B-8CC8-6D83F13DD151-GENID-1-2-1-10-1-5-1-5-1-1-7-1-9-1-5-1-3-1-3" xml:space="preserve">/**

 Initializes the DMA for transmit. This function does all the 

 required generic initialization to use the DMA framework. This 

 function does not have any variant specific initialization. 

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

 */

TInt DExDriverUartTxDma::Init()

    {

    ...

    // Initialize the channel information to select and configure the DMA     

    // channel

    TDmaChannel::SCreateInfo info;

    info.iCookie = (TUint);

    info.iDesCount = 1; // For single buffered transfers

    info.iDfcPriority = 4; // Set the priority of this DFC for DMA

    info.iDfcQ = iUartComm->DfcQ(); // DFCQ onto which this request

 // has to be queued    

    // DMA channel has to be opened before doing any operations on 

    // the channel. TDmaChannel::Open() opens the DMA channel as 

    // set by info passed and selected by the hardware-specific layer. 

    r = TDmaChannel::Open(info, iTxDmaChannel);

    if (r!=KErrNone)

        {

        return r;

        }

    ...

    }</codeblock> </section>

<section id="GUID-5E09A55C-A2B9-4E02-9BCF-F23558357B70-GENID-1-2-1-10-1-5-1-5-1-1-7-1-9-1-5-1-3-2"><title>Close</title> <p>A DMA channel has to be closed after completing all the DMA operations.

This releases the DMA channel for other resources and peripherals.

To close a previously opened channel, the channel should be idle,

with no pending requests. So, before closing, call <xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-0A98D2DC-2A61-3FBD-AB7A-623FE926A183"><apiname>TDmaChannel::CancelAll()</apiname></xref>, which cancels the current request and any pending DMA requests.

This should then be followed by closing the channel using <xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-8204AFBD-2A60-372E-B626-35BD19851FF7"><apiname>TDmaChannel::Close()</apiname></xref>. </p> <codeblock id="GUID-4BA5CDD2-6BD3-5179-89B8-7337ED5809AA-GENID-1-2-1-10-1-5-1-5-1-1-7-1-9-1-5-1-3-2-3" xml:space="preserve">/**

 Destructor. Deinitializes the member variables, cancels any 

 requests, closes the channel, deletes the DMA requests, frees the 

 hardware chunks allocated.

 */    

DExDriverUartTxDma::~DExDriverUarttxDma()

    {

    ...

    // if DMA channel is existing, cancel all requests on it.    

    //

    if (iTxDmaChannel)

        {

        // TDmaChannel::CancelAll() cancels the current request and 

        // any pending requests on the DMA channel

        //     

        iTxDmaChannel->CancelAll();

        }

    ...

    if(iTxDmaChannel)

        {

        // Close the DMA channel. TDmaChannel::Close() closes a 

        // previously opened channel. All the requests on this 

        // channel should have been cancelled prior to this, i.e. 

        // TDmaChannel::CancelAll() should have been called before 

        // this call.

        //

        iTxDmaChannel->Close();

        }

    ...

    }</codeblock> <p>To stop DMA without closing the channel, simply

cancel the request. </p></section>

</conbody><related-links>

<link href="GUID-C649DB97-F138-4C90-B177-16590F2E3F19-GENID-1-2-1-9-1-6-1-8-1-7-1-3-1.dita"><linktext>DMA

Channels</linktext></link>

</related-links></concept>