DMA Client Interface Guide

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.

Using +the DMA client interface

The sequence diagram of a DMA transfer +is:

+The sequence diagram of a DMA transfer + +

Initialization

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:

TDmaChannel::SCreateInfo info; + + info.iCookie = iDMAChannelNumber; + info.iDesCount = 3; + info.iDfcPriority = 3; + info.iDfcQ = iDfcQue;

The iCookie parameter +is used to provide a unique ID for the channel. Its value is application +specific.

The iDesCount element is used to +specify how many descriptors this channel can use.

The iDfcPriority element is used to specify the priority of +the DMA callback relative to all the other callbacks on its DFC queue.

The iDfcQ element is used to specify which DFC +queue is to be used by this DMA channel.

Open a DMA channel

Next the DMA channel is opened and configured. An example +of this is show below:

r = TDmaChannel::Open(info, iDMAChannel); + +if (r) +{ + // [...] handle the error + return r; +}

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.

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.

Create a request object

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:

new (iDMARequest) DDmaRequest(*iDMAChannel, DmaCallback, this);

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 (DmaCallback) 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.

Transfer

Once the DMA channel +has been setup, the DMA transfer can be carried out. Executing a DMA +transfer consists of two parts:

Specifying the +details of the DMA transfer.
Placing the +transfer onto the DMA transfer queue.

Once a successful transfer has been completed, the specified +DMA callback function is executed.

An example of the use of +the fragment method call is:

retval = iDMARequest->Fragment(EDmaSDMMC, aDest, aCount, KDmaMemDest | KDmaIncDest, 0); + + if (retval) +{ + // [...] handle the error + return retval; +}

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).

A code snippet that shows the +DMA transfer request being placed onto the DMA queue is:

iDMARequest->Queue();

Close a DMA channel

Finally, once the DMA functionality is no longer required, the +DMA channel is closed. A code snippet that shows this is:

iDMAChannel->Close();

Where iDMAChannel is the instance of the DMA channel that was being used.