<?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-877EEB52-40C8-4880-87A0-9736A625F85F" xml:lang="en"><title>TDmaChannel Derived Class Implementation</title><shortdesc>Describes how to write a class describing a DMA channel.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The <xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita"><apiname>TDmaChannel</apiname></xref> class is part of the PSL implementation.

It is an abstract class with pure virtual functions which you must

derive in order to implement it. The implementation of a DMA channel

involves hardware-specific decisions such as the choice of DMA mode</p>

<p>The purpose of DMA is to transfer data such as streaming audio

produced by a client application. A typical transfer involves passing

the data from user side to kernel side via a shared chunk and then

a transfer from one memory location to another by DMA over a buffer.

If the amount of data to be transferred exceeds the maximum transfer

size supported by the controller or involves non-contiguous physical

memory, the data is fragmented and transmitted in a sequence of transfers

in one of three modes. </p>

<ul>

<li><p>In single buffer mode the hardware controller provides a single

set of transfer registers used alternately to perform an active transfer

and to set up a pending one: however this mode incurs overhead in

the form of significant periods of time when the driver is idle during

the pending phase. </p></li>

<li><p>In double buffer mode the hardware controller provides two

sets of transfer registers, one set for the active transfer and one

for the pending transfer.. </p></li>

<li><p>In scatter-gather mode, a single procedure call sequentially

writes data from multiple buffers to a single data  stream or from

a data stream to multiple buffers.</p></li>

</ul>

<p> The PIL supplies three derived classes corresponding to the DMA

modes:</p>

<ul>

<li><p><xref href="GUID-A8B4AD1B-770C-363E-A0DE-C78A9786CBDC.dita"><apiname>TDmaSbChannel</apiname></xref></p> for a single-buffer channel,</li>

<li><p><xref href="GUID-FD76AF08-6250-3054-8A06-16343E385B23.dita"><apiname>TDmaDbChannel </apiname></xref></p> for a double-buffer channel,

and</li>

<li><p><xref href="GUID-2D4CFBB1-8D64-3CF5-B6F0-B24D16D5BAD4.dita"><apiname>TDmaSgChannel</apiname></xref></p> for a scatter-gather channel.</li>

</ul>

<p>These three classes are defined in <filepath>dma_v1.h</filepath>. </p>

<p> You may simply use one of these classes or derive further classes

from them and implement those. For example, the template scatter-gather

implementation defines a <xref href="GUID-45CDD48A-6BB4-3409-AC03-E2E0D2B73592.dita"><apiname>TTemplateSgChannel</apiname></xref> class

derived from <xref href="GUID-2D4CFBB1-8D64-3CF5-B6F0-B24D16D5BAD4.dita"><apiname>TDmaSgChannel</apiname></xref> for storing data when

appending new descriptors to a running channel: </p>

<codeblock xml:space="preserve">class TTemplateSgChannel : public TDmaSgChannel

    {

public:

    TDmaDesc* iTmpDes;

    TPhysAddr iTmpDesPhysAddr;

    };

</codeblock>

<p>In general, design decisions are made at the level of implementation

in hardware and are subsequently reflected in the structure of the

derived classes.</p>

<p>There are two ways of extending the DMA Framework:</p>

<ul>

<li><p>to provide platform-specific functionality on a per-channel

basis, and</p></li>

<li><p>to provide platform-specific functionality on a channel independent

basis</p></li>

</ul>

<p>In the first case, <xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-2CF7498E-F5D2-3C4A-8E98-47504F9FC404"><apiname>TDmaChannel::Extension()</apiname></xref> calls <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-D6D011E9-9D75-3881-87D8-1986FFBBA106"><apiname>TDmac::Extension()</apiname></xref> and the PSL provides an implementation

of the virtual function <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-D6D011E9-9D75-3881-87D8-1986FFBBA106"><apiname>TDmac::Extension()</apiname></xref>. The

default implementation just returns <xref href="GUID-F89DA3F0-2A48-3F9B-8F08-29350E92D0E4.dita"><apiname>KErrNotSupported</apiname></xref>. In the second case, <xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-75562653-1F27-39D3-96D8-55A94BA9B68B"><apiname>TDmaChannel::StaticExtension()</apiname></xref> calls <xref href="GUID-176B8E0D-0422-341B-A134-7C85432E1303.dita#GUID-176B8E0D-0422-341B-A134-7C85432E1303/GUID-C733B302-4269-3391-8ADE-617CFF198B56"><apiname>DmaChannelMgr::StaticExtension()</apiname></xref> and the

PSL provides an implementation of the static function <xref href="GUID-176B8E0D-0422-341B-A134-7C85432E1303.dita#GUID-176B8E0D-0422-341B-A134-7C85432E1303/GUID-C733B302-4269-3391-8ADE-617CFF198B56"><apiname>DmaChannelMgr::StaticExtension()</apiname></xref>. The template PSL implementation just returns <xref href="GUID-F89DA3F0-2A48-3F9B-8F08-29350E92D0E4.dita"><apiname>KErrNotSupported</apiname></xref>. </p>

</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>