<?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-6114133F-E738-4DF1-8308-B09C02B9CEEA" xml:lang="en"><title>DMAv2 Interface Overview</title><shortdesc>Describes the interfaces provided by the DMAv2 platform
service.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-37ADE1EE-C4AB-41FD-B639-DE447AA4BD53"><title>Client
functions</title><p>The clients that require to use the DMA framework
functionality use the <xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita"><apiname>DDmaRequest</apiname></xref> class functions
to request DMA transfers. The clients should not set any parameters
directly but use functions of the <xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita"><apiname>DDmaRequest</apiname></xref> class.</p><table id="GUID-B53C9C8A-C5D5-4CA2-A81B-85D5EF9F86EA">
<tgroup cols="2"><colspec colname="col1" colwidth="1.00*"/><colspec colname="col2" colwidth="1.00*"/>
<thead>
<row>
<entry>API</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-311897BE-5079-3945-A299-333B9B8E4071"><apiname>DDmaRequest::DDmaRequest(TDmaChannel&amp; aChannel,
TCallback, TAny*, TInt)</apiname></xref></entry>
<entry>The constructor for the <codeph>DDmaRequest</codeph> class. </entry>
</row>
<row>
<entry><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-55E31857-CCA8-3463-BB72-D45A8952A39F"><apiname>DDmaRequest::Fragment(const TDmaTransferArgs&amp;
aTransferArgs)</apiname></xref></entry>
<entry>Split request into a list of fragments small enough to be fed
to the DMA Controller. The size of the fragment should be less than
or equal to the maximum transfer size supported by the DMA controller.</entry>
</row>
<row>
<entry><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></entry>
<entry>Asynchronous transfer request.</entry>
</row>
<row>
<entry><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-E91276AA-EC8A-39C7-802F-22F713E2BBAC"><apiname>DDmaRequest::ExpandDesList(TInt)</apiname></xref></entry>
<entry>Add new descriptors to the existing list. The function is to
be used by the clients that require to build a custom descriptor list.</entry>
</row>
<row>
<entry><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-8A34A869-3593-308E-93CC-36951C8B310B"><apiname>DDmaRequest::ExpandSrcDesList(TInt)</apiname></xref></entry>
<entry>Add new descriptors to the existing source port descriptor
list.</entry>
</row>
<row>
<entry><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-6A9CE3CA-BECF-3A8C-802A-D53FBB152627"><apiname>DDmaRequest::ExpandDstDesList(TInt)</apiname></xref></entry>
<entry>Add new descriptors to the existing destination port descriptor
list.</entry>
</row>
<row>
<entry><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-6E1A6759-E6E0-3C04-BEED-318AF42A892F"><apiname>DDmaRequest::FreeDesList()</apiname></xref></entry>
<entry>Free resources associated with this request.</entry>
</row>
<row>
<entry><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-57047E56-CEC0-364D-A276-6F66AC2B2F3F"><apiname>DDmaRequest::FreeSrcDesList()</apiname></xref></entry>
<entry>Free resources associated with this request from the source
port descriptor chain.</entry>
</row>
<row>
<entry><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-1826EE8C-817B-3086-B524-CEC9329007DC"><apiname>DDmaRequest::FreeDstDesList()</apiname></xref></entry>
<entry>Free resources associated with this request from the destination
port descriptor chain.</entry>
</row>
<row>
<entry><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-C5CFD281-7E51-3366-8BAE-1D702F9BD142"><apiname>DDmaRequest::EnableSrcElementCounting(TBool)</apiname></xref></entry>
<entry>Enables the functionality for counting the transferred source
elements.</entry>
</row>
<row>
<entry><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-7C978E94-20B0-3445-9785-4135FAEFAFE3"><apiname>DDmaRequest::EnableDstElementCounting(TBool)</apiname></xref></entry>
<entry>Enables the functionality for counting the transferred destination
elements.</entry>
</row>
<row>
<entry><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-ED613C3E-CD72-342B-B8A1-F26F4B3319A8"><apiname>DDmaRequest::DisableSrcElementCounting()</apiname></xref></entry>
<entry>Disables  the functionality for counting the transferred source
elements.</entry>
</row>
<row>
<entry><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-021492C7-B778-3F58-A097-376A414B40B6"><apiname>DDmaRequest::DisableDstElementCounting()</apiname></xref></entry>
<entry>Disables the functionality for counting the transferred destination
elements.</entry>
</row>
<row>
<entry><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-6613A1DA-1E18-34A8-9FD8-4DE9269FA2B9"><apiname>DDmaRequest::TotalNumSrcElementsTransferred()</apiname></xref></entry>
<entry>Get the number of transferred elements at the source port.
This function can only be used if the counting is enabled.</entry>
</row>
<row>
<entry><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-5B1350AB-FFF6-3172-BB08-B50925CB89E9"><apiname>DDmaRequest::TotalNumDstElementsTransferred()</apiname></xref></entry>
<entry>Get the number of transferred elements at the destination port.
This function can only be used if the counting is enabled.</entry>
</row>
<row>
<entry><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-A43A6A70-EEA7-31B1-A9FB-A75865D64FC4"><apiname>DDmaRequest::FragmentCount()</apiname></xref></entry>
<entry>Returns the number of fragments that are created by this transfer
request. </entry>
</row>
<row>
<entry><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-F2B9B9ED-A2DF-3E43-A080-323CC67CD9DD"><apiname>DDmaRequest::SrcFragmentCount()</apiname></xref></entry>
<entry>Returns the number of source port fragments that are created
by this transfer request.</entry>
</row>
<row>
<entry><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita#GUID-780F4D53-5546-3B69-B328-0226C70EBDE2/GUID-74BEEB4D-04B6-3722-A7CD-8ED9EE3267AC"><apiname>DDmaRequest::DstFragmentCount()</apiname></xref></entry>
<entry>Returns the number of destination port fragments that are created
by this transfer request.</entry>
</row>
<row>
<entry><xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-C10135FD-8CCB-3032-9865-F86A8428A54D"><apiname>TDmaChannel::Open(const SCreateInfo&amp; aInfo, TDmaChannel*&amp;
aChannel)</apiname></xref></entry>
<entry>Open a specified channel.</entry>
</row>
<row>
<entry><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></entry>
<entry>Close a previously opened channel.</entry>
</row>
<row>
<entry><xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-0588547C-300B-3558-8173-E7581956D8DB"><apiname>TDmaChannel::LinkToChannel(TDmaChannel* aChannel)</apiname></xref></entry>
<entry>Logically link a channel with the specified argument. When
the argument is NULL the channel is unlinked.</entry>
</row>
<row>
<entry><xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-39306527-CBB8-3C89-90F5-BB21A7F34A0F"><apiname>TDmaChannel::Pause()</apiname></xref></entry>
<entry>Pause an active transfer.</entry>
</row>
<row>
<entry><xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-5BC3DDA2-D6EB-375D-9FFC-DD40F26BD01C"><apiname>TDmaChannel::Resume()</apiname></xref></entry>
<entry>Resume transfer on this channel.</entry>
</row>
<row>
<entry><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></entry>
<entry>Cancel current and all pending requests.</entry>
</row>
<row>
<entry><xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-FC57221E-0C3D-3150-80DC-B3532725607F"><apiname>TDmaChannel::MaxTransferLength(TUint aSrcFlags, TUint
aDstFlags, TUint32 aPslInfo)</apiname></xref></entry>
<entry>Get the maximum transfer length of the current channel.</entry>
</row>
<row>
<entry><xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-F53A4F88-971E-37E9-973E-33DF9AD4847A"><apiname>TDmaChannel::AddressAlignMask(TUint aTargetFlags,
TUint aElementSize, TUint32 aPslInfo)</apiname></xref></entry>
<entry>Get the address or memory alignment mask.</entry>
</row>
<row>
<entry><xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-4DCC8674-E4C7-365B-AE19-244F62C2273D"><apiname>TDmaChannel::DmacCaps()</apiname></xref></entry>
<entry>Get the reference to the structure that contains the features
and the capabilities of the DMAC associated with the current channel.</entry>
</row>
<row>
<entry><xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-5C1CB8FB-31BC-3968-A5BD-B187EE0051D0"><apiname>TDmaChannel::IsrRedoRequest(TUint32 aSrcAddr=KPhysAddrInvalid,
TUint32 aDstAddr=KPhysAddrInvalid, TUint aTransferCount=0, TUint32
aPslRequestInfo=0, TBool aIsrCb=ETrue)</apiname></xref></entry>
<entry>Repeat the current transfer request with modified parameters.</entry>
</row>
<row>
<entry><xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-B3887AA6-FEB6-3109-A98A-2854ED903628"><apiname>TDmaChannel::IsQueueEmpty()</apiname></xref></entry>
<entry>Check if the current transfer queue is empty.</entry>
</row>
<row>
<entry><xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-A84A0711-4573-3ED1-A20E-759215F21255"><apiname>TDmaChannel::PslId()</apiname></xref></entry>
<entry>Get the PSL specific ID of the current channel. This function
is used for debugging by the PIL.</entry>
</row>
<row>
<entry><xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-B65DAEB8-C389-33DC-AD46-EFB0D34C42FC"><apiname>TDmaChannel::FailNext(TInt)</apiname></xref></entry>
<entry>Force to fail the next transfer request. This function is for
testing purpose only.</entry>
</row>
<row>
<entry><xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-640C7397-434C-3EB4-9931-9E462CE0FB22"><apiname>TDmaChannel::MissNextInterrupts(TInt)</apiname></xref></entry>
<entry>Force the DMAC to miss one or more interrupts.</entry>
</row>
<row>
<entry><xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-DEABB054-CAF1-3FC4-BC14-87581AFD5370"><apiname>TDmaChannel::Extension(TInt aCmd, TAny* aArg)</apiname></xref></entry>
<entry>Allows PSL to extend the DMA API with a channel specific functionality.</entry>
</row>
<row>
<entry><xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita#GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37/GUID-89BD759C-7269-3C93-ABE2-34E6DA087DA6"><apiname>TDmaChannel::StaticExtension(TInt aCmd, TAny* aArg)</apiname></xref></entry>
<entry>Allows PSL to extend the DMA API with a channel independent
functionality.</entry>
</row>
</tbody>
</tgroup>
</table></section>
<section id="GUID-827B3A45-FB7F-4E4E-901A-BB50C2D19EC3"><title>DMA
controller implementation</title>The <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita"><apiname>TDmac</apiname></xref> class
provides the functions of a DMA controller:<table id="GUID-FCA888C8-F648-4A9F-8595-1ABF8AE305C5">
<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry valign="top">API</entry>
<entry valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-5B418CE9-7050-3301-927E-059C55B2FC0F"><apiname>TDmac::Transfer(const TDmaChannel&amp; aChannel, const
SDmaDesHdr&amp; aHdr)</apiname></xref></entry>
<entry>Initiate a transfer request on a specified channel.</entry>
</row>
<row>
<entry><xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-5191C7E1-A805-3BD1-9743-76B94A457538"><apiname>TDmac::StopTransfer(const TDmaChannel&amp; aChannel)</apiname></xref></entry>
<entry>Stop a data transfer on a specified channel.</entry>
</row>
<row>
<entry><xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita#GUID-25398075-927B-36E4-B953-16785EC4086C/GUID-216083D9-6506-3DD0-B884-80AB16A929A2"><apiname>TDmac::IsIdle(const TDmaChannel&amp; aChannel)</apiname></xref></entry>
<entry>Get the state of a specified channel.</entry>
</row>
<row>
<entry><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></entry>
<entry>Implement a platform specific functionality per channel.</entry>
</row>
</tbody>
</tgroup>
</table></section>
<section id="GUID-FD5756CA-CAA7-4259-8508-2F37E2D30C42"><title>Channel
manager implementation</title><p>The <xref href="GUID-176B8E0D-0422-341B-A134-7C85432E1303.dita"><apiname>DmaChannelMgr</apiname></xref> class provides functions to open and close the channels by the PIL.
Implement the following functions in the PSL:</p><table id="GUID-965FE251-FE92-4D1A-B35D-92E5104CBB6F">
<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry valign="top">API</entry>
<entry valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><xref href="GUID-176B8E0D-0422-341B-A134-7C85432E1303.dita#GUID-176B8E0D-0422-341B-A134-7C85432E1303/GUID-23FE411E-A058-3C6F-957C-BB36F0EBE3E6"><apiname>DmaChannelMgr::Open(TUint32 aOpenId, TBool aDynChannel,
TUint aPriority)</apiname></xref></entry>
<entry>Open a channel with a specified channel ID.</entry>
</row>
<row>
<entry><xref href="GUID-176B8E0D-0422-341B-A134-7C85432E1303.dita#GUID-176B8E0D-0422-341B-A134-7C85432E1303/GUID-909D795A-7303-3A76-9C8E-3B07A97DD716"><apiname>DmaChannelMgr::Close() </apiname></xref></entry>
<entry>Close a channel.</entry>
</row>
</tbody>
</tgroup>
</table></section>
<section id="GUID-868DC865-577F-43F2-A8F2-E5649804F1AD"><title>DMA
channel implementation</title><p>The <xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita"><apiname>TDmaChannel</apiname></xref> class provides the functions to implement a DMA channel. There are
three types of DMA channels that be can be implemented as described
below.</p> <table id="GUID-7EDF7986-AA5A-456C-8BF4-0ADE3E348F65">
<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry valign="top">Class</entry>
<entry valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><xref href="GUID-A8B4AD1B-770C-363E-A0DE-C78A9786CBDC.dita"><apiname>TDmaSbChannel</apiname></xref></entry>
<entry>Class to implement a single buffer channel.</entry>
</row>
<row>
<entry><xref href="GUID-FD76AF08-6250-3054-8A06-16343E385B23.dita"><apiname>TDmaDbChannel</apiname></xref></entry>
<entry>Class to implement a double buffer channel.</entry>
</row>
<row>
<entry><xref href="GUID-2D4CFBB1-8D64-3CF5-B6F0-B24D16D5BAD4.dita"><apiname>TDmaSgChannel</apiname></xref></entry>
<entry>Class to implement a scatter-gather channel.</entry>
</row>
<row>
<entry><xref href="GUID-B0100F2B-6C01-3429-8B48-DFFB96EA85D0.dita"><apiname>TDmaAsymSgChannel</apiname></xref></entry>
<entry>Channel class for controllers using asymmetric descriptor lists.</entry>
</row>
</tbody>
</tgroup>
</table></section>
</conbody></concept>