|
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-D5ED62EB-744D-42EB-B8CF-D5623BDA5B38" xml:lang="en"><title>DMA Client Interface Guide</title><shortdesc>Explains how to use the interface between the DMA platform |
|
13 service and the Symbian platform.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>The DMA client interface specifies the connection between the Symbian |
|
15 platform and the DMA platform service. This document describes how |
|
16 to open and close a DMA channel along with how to use the DMA client |
|
17 interface to perform a DMA transfer.</p> |
|
18 <section id="GUID-C917EAE6-BB3F-436A-BBF4-612FCCB837DB"><title>Interface |
|
19 classes</title><p>The classes that process a DMA transfer are:</p><table id="GUID-32AF43CB-8D2F-427A-984F-B577280905F0"> |
|
20 <tgroup cols="2"><colspec colname="col1" colwidth="0.43*"/><colspec colname="col2" colwidth="1.57*"/> |
|
21 <thead> |
|
22 <row> |
|
23 <entry align="center" valign="top"><p><b>Name</b></p></entry> |
|
24 <entry align="center" valign="top"><p><b>Description</b></p></entry> |
|
25 </row> |
|
26 </thead> |
|
27 <tbody> |
|
28 <row> |
|
29 <entry><p><xref href="GUID-780F4D53-5546-3B69-B328-0226C70EBDE2.dita"><apiname>DDmaRequest</apiname></xref></p></entry> |
|
30 <entry><p>This class is used to handle transfer requests. It carries |
|
31 out the configuration and initialization of the DMA transfer, along |
|
32 with tracking the state of the transfer to the client. Communication |
|
33 with the rest of the Symbian platform is carried out with the aid |
|
34 of a callback function.</p></entry> |
|
35 </row> |
|
36 <row> |
|
37 <entry><p><xref href="GUID-83882548-FAC5-3EFF-92ED-14D1D9A85D37.dita"><apiname>TDmaChannel</apiname></xref></p></entry> |
|
38 <entry><p>This class is used to open and close DMA channels.</p></entry> |
|
39 </row> |
|
40 </tbody> |
|
41 </tgroup> |
|
42 </table><p>The steps involved in performing a DMA transfer are described |
|
43 below.</p></section> |
|
44 <section id="GUID-96B6E82F-85C1-4AB0-96EF-F2E7AA705973"><title>Using |
|
45 the DMA client interface</title><p>The sequence diagram of a DMA transfer |
|
46 is:</p><fig id="GUID-6A4644F2-62A7-4821-9C13-DFF13793CAE0"> |
|
47 <title>The sequence diagram of a DMA transfer</title> |
|
48 <image href="GUID-DDD883A2-6784-4851-8E36-227EC564452A_d0e90311_href.png" placement="inline"/> |
|
49 </fig><p><b>Initialization</b></p><p>Before any DMA operations can |
|
50 be carried out, the data structure that holds the configuration of |
|
51 the DMA channel must be initialized. An example of this is shown below:</p><codeblock xml:space="preserve"> TDmaChannel::SCreateInfo info; |
|
52 |
|
53 info.iCookie = iDMAChannelNumber; |
|
54 info.iDesCount = 3; |
|
55 info.iDfcPriority = 3; |
|
56 info.iDfcQ = iDfcQue;</codeblock><p>The <codeph>iCookie</codeph> parameter |
|
57 is used to provide a unique ID for the channel. Its value is application |
|
58 specific.</p><p>The <codeph>iDesCount</codeph> element is used to |
|
59 specify how many descriptors this channel can use.</p><p>The <codeph>iDfcPriority</codeph> element is used to specify the priority of |
|
60 the DMA callback relative to all the other callbacks on its DFC queue.</p><p>The <codeph>iDfcQ</codeph> element is used to specify which DFC |
|
61 queue is to be used by this DMA channel.</p><p><b>Open a DMA channel</b></p><p>Next the DMA channel is opened and configured. An example |
|
62 of this is show below: </p><codeblock xml:space="preserve">r = TDmaChannel::Open(info, iDMAChannel); |
|
63 |
|
64 if (r) |
|
65 { |
|
66 // [...] handle the error |
|
67 return r; |
|
68 }</codeblock><p>The first parameter for the open method holds the |
|
69 channel configuration details. The second parameter is the DMA channel |
|
70 handle. In this example, if an error occurs during the open operation, |
|
71 then the error code is returned to the rest of the system and the |
|
72 transfer is aborted.</p><p>The first parameter contains the DMA channel |
|
73 configuration information. The second parameter points to the instance |
|
74 of the DMA channel class that is to be used. This class must be declared |
|
75 before this method call can be made.</p><p><b>Create a request object</b></p><p>The next task is to create a request object, specifying the |
|
76 channel it will be queued on and the callback when it completes. An |
|
77 example of this is shown below:</p><codeblock xml:space="preserve">new (iDMARequest) DDmaRequest(*iDMAChannel, DmaCallback, this);</codeblock><p>The above line creates a new instance of the DDmaRequest class |
|
78 which will be queued on the DMA channel specified in the first parameter. |
|
79 The callback function (<codeph>DmaCallback</codeph>) that will process |
|
80 the result of an operation is specified in the second parameter and |
|
81 is optional. The third parameter specifies the argument passed to |
|
82 the callback function.</p><p><b>Transfer</b></p><p>Once the DMA channel |
|
83 has been setup, the DMA transfer can be carried out. Executing a DMA |
|
84 transfer consists of two parts:</p><ol> |
|
85 <li id="GUID-FEBFEA0C-A6A3-4920-B62B-5F011F1FA571"><p>Specifying the |
|
86 details of the DMA transfer.</p></li> |
|
87 <li id="GUID-AD469BD7-94F4-4F79-91E0-2CB6CD988F97"><p>Placing the |
|
88 transfer onto the DMA transfer queue.</p></li> |
|
89 </ol><p>Once a successful transfer has been completed, the specified |
|
90 DMA callback function is executed.</p><p>An example of the use of |
|
91 the fragment method call is:</p><codeblock xml:space="preserve"> retval = iDMARequest->Fragment(EDmaSDMMC, aDest, aCount, KDmaMemDest | KDmaIncDest, 0); |
|
92 |
|
93 if (retval) |
|
94 { |
|
95 // [...] handle the error |
|
96 return retval; |
|
97 }</codeblock><p>In this code snippet, the details of the DMA transfer |
|
98 are specified. If an error is returned by the fragment method, then |
|
99 the error code is passed on to the rest of the system and the transfer does |
|
100 not take place. The first parameter specifies the data source. The |
|
101 second specified the destination of the data. The third specifies |
|
102 the number of bytes that are to be sent. The fourth parameter consists |
|
103 of flags. The final parameter specifies any DMA PSL specific settings |
|
104 (there are none in the example).</p><p>A code snippet that shows the |
|
105 DMA transfer request being placed onto the DMA queue is:</p><codeblock xml:space="preserve"> iDMARequest->Queue();</codeblock><p><b>Close a DMA channel</b></p><p>Finally, once the DMA functionality is no longer required, the |
|
106 DMA channel is closed. A code snippet that shows this is:</p><codeblock xml:space="preserve">iDMAChannel->Close();</codeblock><p>Where <codeph>iDMAChannel</codeph> is the instance of the DMA channel that was being used.</p></section> |
|
107 </conbody></concept> |