|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <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 |
|
13 (PSL) for your platform.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>The DMA Framework is made of a PIL and a PSL. You have to write |
|
15 a new Platform specific implementation code whenever your hardware |
|
16 changes, but the PIL and the platform service API do not change. </p> |
|
17 <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> |
|
18 <section id="GUID-F8827A6B-234A-4358-9720-15AD7ABE4AC9"><title>Architecture</title><p>In the diagram below, the classes in green provide the platform |
|
19 service API and the classes in blue implement the Platform-specific |
|
20 functions (PSL).</p><fig id="GUID-61388066-2B2B-4DEF-8FEC-D07D71E4DFAF"> |
|
21 <title>PSL class diagram</title> |
|
22 <image href="GUID-F7ABA3C6-60DD-4AE1-916B-BE2BCF6285CE_d0e91217_href.png" placement="inline"/> |
|
23 </fig></section> |
|
24 <section id="GUID-1460340B-DF92-45A4-AC7A-7238CBD63199"><title>Implementation |
|
25 files</title><p>The following table lists the important files of the |
|
26 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"> |
|
27 <tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/> |
|
28 <thead> |
|
29 <row> |
|
30 <entry valign="top">File</entry> |
|
31 <entry valign="top">Usage</entry> |
|
32 </row> |
|
33 </thead> |
|
34 <tbody> |
|
35 <row> |
|
36 <entry><filepath>/os/kernelhwsrv/kernel/eka/include/drivers/dma.h</filepath></entry> |
|
37 <entry><p>This file is the main header file for DMA. </p><p>Include |
|
38 it in the PSL implementation.</p></entry> |
|
39 </row> |
|
40 <row> |
|
41 <entry><filepath>/os/kernelhwsrv/kernel/eka/include/drivers/dma_v1.h</filepath></entry> |
|
42 <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> |
|
43 </row> |
|
44 <row> |
|
45 <entry><filepath>/os/kernelhwsrv/kernel/eka/drivers/dma/dmapil.cpp</filepath></entry> |
|
46 <entry>This file is for information only: it contains the source code |
|
47 for the generic implementation.</entry> |
|
48 </row> |
|
49 <row> |
|
50 <entry><filepath>/os/kernelhwsrv/kernel/eka/drivers/dma/dma_lib.mmp</filepath></entry> |
|
51 <entry><p>This file is the MMP for the PIL. </p><p>Use it to build |
|
52 the .LIB file for the PIL.</p></entry> |
|
53 </row> |
|
54 <row> |
|
55 <entry><filepath>/os/kernelhwsrv/bsptemplate/asspandvariant/template_assp/dmapsl.cpp</filepath></entry> |
|
56 <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> |
|
57 </row> |
|
58 <row> |
|
59 <entry><filepath>/os/kernelhwsrv/bsptemplate/asspandvariant/template_assp/dma.mmp</filepath></entry> |
|
60 <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 |
|
61 new file to build the DMA Framework (PIL and PSL).</p></entry> |
|
62 </row> |
|
63 </tbody> |
|
64 </tgroup> |
|
65 </table></p></section> |
|
66 <section id="GUID-04C86903-0899-4A0F-8A38-777DD7D71D8F"><title>Implementation |
|
67 process</title><p>To write the PSL for the DMA Framework, do the following:<ol> |
|
68 <li id="GUID-A9CAA850-23C5-4F3C-8FDF-2041CDF432A2"><p>Copy the template |
|
69 listed in the above section to your own variant directory (at chip |
|
70 level or at board level depending on where the DMA hardware is located).</p></li> |
|
71 <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> |
|
72 <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> |
|
73 <li id="GUID-D427EEA9-A434-4012-B680-0B2F70B0122D"><p>If necessary, |
|
74 derive the <xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita"><apiname>TDmaChannel</apiname></xref> class or one of its sub-classes |
|
75 to store channel-specific data.</p></li> |
|
76 <li id="GUID-1587F0CF-1A85-4C9E-8AAB-4D05E5CDC8EA"><p>Test the PSL |
|
77 implementation.</p></li> |
|
78 |
|
79 </ol></p></section> |
|
80 </conbody><related-links> |
|
81 <link href="GUID-D5ED62EB-744D-42EB-B8CF-D5623BDA5B38.dita"><linktext>DMA |
|
82 Client Interface Guide</linktext></link> |
|
83 <link href="GUID-C2114C7B-705C-4527-836A-C6E72227111A.dita"><linktext>DMA |
|
84 Testing Guide</linktext></link> |
|
85 </related-links></concept> |