<?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-95A33491-17AC-4F12-948E-A1352ADDA483" xml:lang="en"><title>DMA Implementation Guide</title><shortdesc>Explains how to implement the DMA Platform Specific Layer
(PSL) for your platform.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>The DMA Framework is made of a PIL and a PSL. You have to write
a new Platform specific implementation code whenever your hardware
changes, but the PIL and the platform service API do not change. </p>
<section id="GUID-C443CD88-0894-444D-BC7D-E65698AF46E4"><title>Prerequisites</title><p>You should be familiar with the <xref href="GUID-4E3C086B-25BE-4DAC-9E21-CFC4F8B792A5.dita">DMA Technology Guide</xref> and with the specifications of your hardware DMA controller.</p></section>
<section id="GUID-F8827A6B-234A-4358-9720-15AD7ABE4AC9"><title>Architecture</title><p>In the diagram below, the classes in green provide the platform
service API and the classes in blue implement the Platform-specific
functions (PSL).</p><fig id="GUID-61388066-2B2B-4DEF-8FEC-D07D71E4DFAF">
<title>PSL class diagram</title>
<image href="GUID-F7ABA3C6-60DD-4AE1-916B-BE2BCF6285CE_d0e91217_href.png" placement="inline"/>
</fig></section>
<section id="GUID-1460340B-DF92-45A4-AC7A-7238CBD63199"><title>Implementation
files</title><p>The following table lists the important files of the
DMA Framework and what you should do with each of them.<table id="GUID-54A82958-4168-42CD-81DE-466CEA0FEEFC-GENID-1-2-1-10-1-5-1-5-1-1-8-1-4-1-3-4-2-1">
<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry valign="top">File</entry>
<entry valign="top">Usage</entry>
</row>
</thead>
<tbody>
<row>
<entry><filepath>/os/kernelhwsrv/kernel/eka/include/drivers/dma.h</filepath></entry>
<entry><p>This file is the main header file for DMA. </p><p>Include
it in the PSL implementation.</p></entry>
</row>
<row>
<entry><filepath>/os/kernelhwsrv/kernel/eka/include/drivers/dma_v1.h</filepath></entry>
<entry><p>This file contains the definitions of the PSL classes. </p><p>Refer to this file for the signature of the PSL functions. </p></entry>
</row>
<row>
<entry><filepath>/os/kernelhwsrv/kernel/eka/drivers/dma/dmapil.cpp</filepath></entry>
<entry>This file is for information only: it contains the source code
for the generic implementation.</entry>
</row>
<row>
<entry><filepath>/os/kernelhwsrv/kernel/eka/drivers/dma/dma_lib.mmp</filepath></entry>
<entry><p>This file is the MMP for the PIL. </p><p>Use it to build
the .LIB file for the PIL.</p></entry>
</row>
<row>
<entry><filepath>/os/kernelhwsrv/bsptemplate/asspandvariant/template_assp/dmapsl.cpp</filepath></entry>
<entry><p>This file contains the template code for the PSL implementation. </p><p>Copy it to your variant directory and modify it.</p></entry>
</row>
<row>
<entry><filepath>/os/kernelhwsrv/bsptemplate/asspandvariant/template_assp/dma.mmp</filepath></entry>
<entry><p>This file is the template MMP for the PSL implementation. </p><p>Copy it to your variant directory and modify it. </p><p>Use the
new file to build the DMA Framework (PIL and PSL).</p></entry>
</row>
</tbody>
</tgroup>
</table></p></section>
<section id="GUID-04C86903-0899-4A0F-8A38-777DD7D71D8F"><title>Implementation
process</title><p>To write the PSL for the DMA Framework, do the following:<ol>
<li id="GUID-A9CAA850-23C5-4F3C-8FDF-2041CDF432A2"><p>Copy the template
listed in the above section to your own variant directory (at chip
level or at board level depending on where the DMA hardware is located).</p></li>
<li id="GUID-BB62C00E-1B93-4771-AA18-0AB1188279AF"><p>Implement the <xref href="GUID-176B8E0D-0422-341B-A134-7C85432E1303.dita"><apiname>DmaChannelMgr</apiname></xref> functions.</p></li>
<li id="GUID-65626C78-F06B-4694-A819-5C1BAD7AB467"><p>Derive the <xref href="GUID-25398075-927B-36E4-B953-16785EC4086C.dita"><apiname>TDmac</apiname></xref> class and implement its controller-specific functions.</p></li>
<li id="GUID-D427EEA9-A434-4012-B680-0B2F70B0122D"><p>If necessary,
derive the <xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita"><apiname>TDmaChannel</apiname></xref> class or one of its sub-classes
to store channel-specific data.</p></li>
<li id="GUID-1587F0CF-1A85-4C9E-8AAB-4D05E5CDC8EA"><p>Test the PSL
implementation.</p></li>

</ol></p></section>
</conbody><related-links>
<link href="GUID-D5ED62EB-744D-42EB-B8CF-D5623BDA5B38.dita"><linktext>DMA
Client Interface Guide</linktext></link>
<link href="GUID-C2114C7B-705C-4527-836A-C6E72227111A.dita"><linktext>DMA
Testing Guide</linktext></link>
</related-links></concept>