1 // Copyright (c) 2002-2010 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // include/drivers/dma_hai.h |
|
15 // DMA Framework - Symbian Hardware Abstraction Interface (SHAI). |
|
16 // |
|
17 // |
|
18 |
|
19 #ifndef __DMA_HAI_H__ |
|
20 #define __DMA_HAI_H__ |
|
21 |
|
22 |
|
23 #include <kernel/kern_priv.h> |
|
24 |
|
25 |
|
26 ////////////////////////////////////////////////////////////////////////////// |
|
27 |
|
28 |
|
29 /** Interface used by PIL to open and close DMA channels. |
|
30 |
|
31 Must be implemented by the PSL. |
|
32 |
|
33 @publishedPartner |
|
34 @released |
|
35 */ |
|
36 class DmaChannelMgr |
|
37 { |
|
38 public: |
|
39 /** Opens a channel using a client-provided identifier. |
|
40 |
|
41 This function must be implemented by the PSL. |
|
42 |
|
43 @param aOpenId PSL-specific magic cookie passed by client. This could |
|
44 identify the channel exactly (by being just the channel number), or at |
|
45 least sufficiently (for example for use with a certain peripheral), or |
|
46 it may indicate some properties which the channel must possess. It may |
|
47 be set to zero always if all channels are equivalent. |
|
48 |
|
49 @param aDynChannel ETrue if the Open call is for a dynamic channel. A |
|
50 dynamic channel is not exclusively reserved for just one client, and |
|
51 further Open calls for more dynamic channels should succeed as long as |
|
52 certain resources (but not including the number of available physical |
|
53 channels) are not exceeded. Different transfer requests on this dynamic |
|
54 channel may be serviced using different actual channels. |
|
55 |
|
56 @param aPriority The desired channel priority as requested by the |
|
57 client. This may be an actual hardware priority or a |
|
58 platform-independent value. Not being able to satisfy the requested |
|
59 value is not a reason for the PSL to return NULL. This parameter may be |
|
60 ignored if aDynChannel is passed as ETrue. An overriding per-transfer |
|
61 priority may be requested by a client later via |
|
62 TDmaTransferArgs::iChannelPriority. |
|
63 @see SDmacCaps::iChannelPriorities |
|
64 @see TDmaPriority |
|
65 |
|
66 @return Pointer to channel if available, NULL otherwise. It should not |
|
67 be NULL if the Open call was for a dynamic channel unless a processing |
|
68 error occurred. |
|
69 |
|
70 @pre The PIL calls this function with a global fast mutex held to avoid |
|
71 race conditions. |
|
72 |
|
73 @post If a non-NULL pointer is returned, the object pointed to has its |
|
74 iController, iDmacCaps, iPslId, iDynChannel and iPriority members set |
|
75 to valid states. |
|
76 |
|
77 iController should point to the controller handling the |
|
78 channel. |
|
79 |
|
80 iDmacCaps should point to a SDmacCaps structure containing values |
|
81 relating to this particular channel. |
|
82 |
|
83 iPslId should contain a value uniquely identifying the channel - the |
|
84 PIL assigns this value later during request fragmentation to |
|
85 TDmaTransferArgs::iChannelCookie. It can be given any convenient value |
|
86 by the PSL (channel index, I/O port address, etc.). |
|
87 |
|
88 iDynChannel should be set to ETrue by the PSL if a dynamic channel was |
|
89 requested and has been opened. |
|
90 |
|
91 If applicable, iPriority should contain the actual hardware priority |
|
92 that has been configured or reserved. Otherwise it may be left at its |
|
93 default value TDmaPriority::KDmaPriorityNone. |
|
94 */ |
|
95 static TDmaChannel* Open(TUint32 aOpenId, TBool aDynChannel, TUint aPriority); |
|
96 |
|
97 /** Performs platform-specific operations when a channel is closed. |
|
98 |
|
99 If aChannel was opened as a dynamic channel then this call is a sign |
|
100 that there is a client which does not intend to queue any further |
|
101 transfer requests via this channel. |
|
102 |
|
103 This function must be implemented by the PSL but the implementation can |
|
104 be a no-op. |
|
105 |
|
106 @param aChannel The channel to close |
|
107 |
|
108 @pre The PIL calls this function with a global fast mutex held to avoid |
|
109 race conditions. |
|
110 */ |
|
111 static void Close(TDmaChannel* aChannel); |
|
112 |
|
113 /** Function allowing PSL to extend DMA API with new channel-independent |
|
114 operations. |
|
115 |
|
116 This function must be implemented by the PSL. |
|
117 |
|
118 @param aCmd Command identifier. Negative values are reserved for FW |
|
119 internal use. |
|
120 |
|
121 @param aArg PSL-specific |
|
122 |
|
123 @return KErrNotSupported if aCmd is not supported. PSL-specific value |
|
124 otherwise. |
|
125 */ |
|
126 static TInt StaticExtension(TInt aCmd, TAny* aArg); |
|
127 |
|
128 /** Acquires the channel manager lock. Called by the PIL before opening and |
|
129 closing a channel. |
|
130 */ |
|
131 static void Wait(); |
|
132 |
|
133 /** Releases the channel manager lock. Called by the PIL after opening and |
|
134 closing a channel. |
|
135 */ |
|
136 static void Signal(); |
|
137 |
|
138 private: |
|
139 /** Declared, defined, and called by PSL's DECLARE_STANDARD_EXTENSION(). */ |
|
140 friend TInt InitExtension(); |
|
141 |
|
142 /** Must be called in the DMA DLL entry point. */ |
|
143 static TInt Initialise(); |
|
144 |
|
145 static NFastMutex Lock; |
|
146 }; |
|
147 |
|
148 |
|
149 ////////////////////////////////////////////////////////////////////////////// |
|
150 |
|
151 |
|
152 /** Abstract base class representing a DMA controller. |
|
153 |
|
154 The class has two purposes. |
|
155 |
|
156 First, it is a container for channels, descriptors and descriptor headers. |
|
157 |
|
158 Second, it exposes a set of virtual functions implemented by the PSL |
|
159 (platform-specific layer). |
|
160 |
|
161 These functions are the main interfaces between the PIL |
|
162 (platform-independent layer) and PSL. |
|
163 |
|
164 @publishedPartner |
|
165 @released |
|
166 */ |
|
167 class TDmac |
|
168 { |
|
169 friend class DmaChannelMgr; |
|
170 |
|
171 protected: |
|
172 /** Data required for creating a new instance */ |
|
173 struct SCreateInfo |
|
174 { |
|
175 /** True if DMAC uses hardware descriptors (i.e. supports |
|
176 scatter/gather mode). |
|
177 */ |
|
178 TBool iCapsHwDes; |
|
179 /** Initial maximum number of descriptors and headers (shared by all |
|
180 channels) to be allocated by the PIL. If at run time more |
|
181 descriptors are needed then they will be dynamically allocated and |
|
182 added to the available pool. |
|
183 |
|
184 The PSL may consider a number of factors when providing this |
|
185 initial value, such as the number of channels on this controller, |
|
186 the maximum transfer size per descriptor and also likely usage |
|
187 scenarios for the platform or device (number of drivers using DMA, |
|
188 their traffic patterns, simultaneity of operations, etc.). |
|
189 */ |
|
190 TInt iDesCount; |
|
191 /** Size of individual descriptors. Use sizeof(TDmaTransferArgs) for |
|
192 single-buffer and double-buffer (i.e. non-s/g) controllers. |
|
193 */ |
|
194 TInt iDesSize; |
|
195 /** Bitmask used when creating the memory chunk storing the descriptor |
|
196 pool. Used only for hardware descriptors. |
|
197 |
|
198 The access part must be EMapAttrSupRw. If the chunk is cached |
|
199 and/or buffered, the PSL must flush the data cache and/or drain the |
|
200 write buffer in InitHwDes() and related functions. |
|
201 |
|
202 The physical start address of the chunk will always be MMU page |
|
203 size aligned. |
|
204 |
|
205 @see TMappingAttributes |
|
206 */ |
|
207 TUint iDesChunkAttribs; |
|
208 }; |
|
209 |
|
210 /** Base class constructor. */ |
|
211 TDmac(const SCreateInfo& aInfo); |
|
212 |
|
213 /** Base class 2nd-phase constructor. */ |
|
214 TInt Create(const SCreateInfo& aInfo); |
|
215 |
|
216 public: |
|
217 /** Base class virtual destructor. */ |
|
218 virtual ~TDmac(); |
|
219 |
|
220 /** Allocates a number of headers (and hence also descriptors) from the |
|
221 header/descriptor pools. Called by the PIL but may also be used by the |
|
222 PSL. |
|
223 */ |
|
224 TInt ReserveSetOfDes(TInt aCount); |
|
225 |
|
226 /** Returns previously allocated headers (and hence also descriptors) to |
|
227 the header/descriptor pools. Called by the PIL but may also be used by |
|
228 the PSL. |
|
229 */ |
|
230 void ReleaseSetOfDes(TInt aCount); |
|
231 |
|
232 /** Called by the PIL during request fragmentation to fill a descriptor or |
|
233 pseudo descriptor with transfer arguments. |
|
234 */ |
|
235 TInt InitDes(const SDmaDesHdr& aHdr, const TDmaTransferArgs& aTransferArgs); |
|
236 |
|
237 /** Called by the PIL in TDmaChannel::IsrRedoRequest() if any of the |
|
238 latter's arguments is non-zero. |
|
239 */ |
|
240 TInt UpdateDes(const SDmaDesHdr& aHdr, TUint32 aSrcAddr, TUint32 aDstAddr, |
|
241 TUint aTransferCount, TUint32 aPslRequestInfo); |
|
242 |
|
243 /** Returns a reference to the associated pseudo descriptor for a given |
|
244 descriptor header. For use by PIL and PSL. |
|
245 */ |
|
246 inline TDmaTransferArgs& HdrToDes(const SDmaDesHdr& aHdr) const; |
|
247 |
|
248 /** Returns a reference to the associated hardware descriptor for a given |
|
249 descriptor header. For use by PIL and PSL. |
|
250 */ |
|
251 inline TAny* HdrToHwDes(const SDmaDesHdr& aHdr) const; |
|
252 |
|
253 /** Returns the physical address of the hardware descriptor |
|
254 pointed to by aDes. For use by PIL and PSL. |
|
255 */ |
|
256 inline TUint32 HwDesLinToPhys(TAny* aDes) const; |
|
257 |
|
258 /** Called by the PIL to acquire the controller lock which protects the |
|
259 header and descriptor pools. |
|
260 */ |
|
261 inline void Wait(); |
|
262 |
|
263 /** Called by the PIL to release the controller lock which protects the |
|
264 header and descriptor pools. |
|
265 */ |
|
266 inline void Signal(); |
|
267 |
|
268 public: |
|
269 /** Called by PIL when one fragment (single-buffer and double-buffer DMACs) |
|
270 or list of fragments (scatter/gather DMAC) is to be transferred. |
|
271 |
|
272 Called when initiating a new transfer and also, for double-buffer |
|
273 DMACs, for configuring the next fragment to transfer while the current |
|
274 one is ongoing. |
|
275 |
|
276 The function must be implemented by the PSL if |
|
277 SCreateInfo::iCaps::iAsymHwDescriptors is reported as false. |
|
278 |
|
279 @note This function may be called in thread or ISR context by the PIL |
|
280 |
|
281 @param aChannel The channel to use. |
|
282 @param aHdr Header associated with fragment to transfer. |
|
283 */ |
|
284 virtual void Transfer(const TDmaChannel& aChannel, const SDmaDesHdr& aHdr); |
|
285 |
|
286 /** Called by PIL when two lists of fragments (scatter/gather DMAC with |
|
287 asymmetrical linked-list capability) are to be transferred. |
|
288 |
|
289 Called when initiating a new transfer. |
|
290 |
|
291 The function must be implemented by the PSL if |
|
292 SDmaCaps::iAsymHwDescriptors is reported as true. |
|
293 |
|
294 @note This function may be called in thread or ISR context by the PIL |
|
295 |
|
296 @param aChannel The channel to use. |
|
297 @param aSrcHdr Header associated with descriptor to transfer on the |
|
298 source side. |
|
299 @param aDstHdr Header associated with descriptor to transfer on the |
|
300 destination side. |
|
301 */ |
|
302 virtual void Transfer(const TDmaChannel& aChannel, const SDmaDesHdr& aSrcHdr, |
|
303 const SDmaDesHdr& aDstHdr); |
|
304 |
|
305 /** Called by PIL to stop a transfer on a given channel. |
|
306 |
|
307 The stopping must occur synchronously as the PIL assumes the channel |
|
308 is halted after calling this function. A channel stopped via this |
|
309 function is not intended to be resumed. Function must always be |
|
310 implemented by the PSL. |
|
311 |
|
312 @param aChannel The channel to stop |
|
313 @post The channel will be idle |
|
314 @post No interrupt will occur from this channel until a new |
|
315 request is queued. |
|
316 */ |
|
317 virtual void StopTransfer(const TDmaChannel& aChannel) = 0; |
|
318 |
|
319 /** Called by PIL to pause (suspend) a transfer on a given channel. |
|
320 |
|
321 A paused channel transfer must be able to be resumed by calling |
|
322 ResumeTransfer(). |
|
323 |
|
324 The function must be implemented by the PSL if |
|
325 SDmacCaps::iChannelPauseAndResume is reported as true. |
|
326 |
|
327 @return KErrNone if the transfer has been paused successfully, |
|
328 KErrCompletion if the transfer was already paused, KErrGeneral |
|
329 if a general error occurred preventing a successful outcome. |
|
330 |
|
331 @post No interrupt will occur from this channel until it is |
|
332 resumed. |
|
333 */ |
|
334 virtual TInt PauseTransfer(const TDmaChannel& aChannel); |
|
335 |
|
336 /** Called by PIL to resume a paused (suspended) transfer on a given |
|
337 channel. |
|
338 |
|
339 Resume() can be called when the transfer is paused as a result of a |
|
340 previous call to PauseTransfer() or because the DMAC has encountered a |
|
341 Pause bit in a H/W descriptor. |
|
342 |
|
343 The function must be implemented by the PSL if |
|
344 SDmacCaps::iChannelPauseAndResume is reported as true. |
|
345 |
|
346 @return KErrNone if the transfer has been resumed successfully, |
|
347 KErrCompletion if there was no paused transfer, KErrGeneral |
|
348 if a general error occurred preventing a successful outcome. |
|
349 */ |
|
350 virtual TInt ResumeTransfer(const TDmaChannel& aChannel); |
|
351 |
|
352 /** Called by PIL to check whether a DMA channel is idle. |
|
353 |
|
354 'Idle' here means that the channel is ultimately stopped, for example |
|
355 because the transfer has finished, or an error was encountered, or it |
|
356 was manually stopped, but not because it was manually suspended (aka |
|
357 'paused'), or it is waiting for a request line assertion to start the |
|
358 transfer. |
|
359 |
|
360 @param aChannel The channel to test |
|
361 |
|
362 @return ETrue if channel idle, EFalse if transferring. |
|
363 */ |
|
364 virtual TBool IsIdle(const TDmaChannel& aChannel) = 0; |
|
365 |
|
366 /** Called by PIL to retrieve from the PSL the maximum transfer length |
|
367 based on the parameters passed. |
|
368 |
|
369 @param aChannel Channel to be used for the transfer |
|
370 @param aSrcFlags Bitmask characterising transfer source |
|
371 @see TDmaTransferArgs::iSrcConfig::iFlags |
|
372 @param aDstFlags Bitmask characterising transfer destination |
|
373 @see TDmaTransferArgs::iDstConfig::iFlags |
|
374 @param aPslInfo Cookie passed by client and used by the PSL |
|
375 @see TDmaTransferArgs::iPslRequestInfo |
|
376 |
|
377 @return 0 if transfer length is not limited, the maximum transfer |
|
378 length in bytes otherwise. |
|
379 */ |
|
380 virtual TUint MaxTransferLength(TDmaChannel& aChannel, TUint aSrcFlags, |
|
381 TUint aDstFlags, TUint32 aPslInfo) = 0; |
|
382 |
|
383 /** Called by PIL to retrieve from the PSL the memory alignment mask based |
|
384 on the parameters passed. Some DMA controllers impose alignment |
|
385 constraints on the base address of memory buffers. This mask is AND'ed |
|
386 against memory addresses computed during fragmentation. |
|
387 |
|
388 The PIL will call this function separately for source and destination. |
|
389 |
|
390 An assumption is that the PSL doesn't need to know if a call to this |
|
391 function is for the source or the destination side, i.e. both ports |
|
392 are, as far as the alignment is concerned, equivalent. All that matters |
|
393 are the values of the relevant configuration parameters. |
|
394 |
|
395 Another assumption is that the alignment requirement for a port on a |
|
396 DMAC with potentially different values for source and destination does |
|
397 not depend on the configuration of the respective other port. |
|
398 |
|
399 @param aChannel Channel used for the transfer |
|
400 @param aTargetFlags Bitmask characterising transfer source or |
|
401 destination |
|
402 @see TDmaTransferArgs::iSrcConfig::iFlags |
|
403 @see TDmaTransferArgs::iDstConfig::iFlags |
|
404 @param aElementSize Element size used for the transfer. May be zero if |
|
405 not known or 'don't care'. |
|
406 @param aPslInfo Cookie passed by client and used by the PSL |
|
407 @see TDmaTransferArgs::iPslRequestInfo |
|
408 |
|
409 @return A value representing the alignment mask (e.g. 3 if buffer must |
|
410 be 4-byte aligned) |
|
411 */ |
|
412 virtual TUint AddressAlignMask(TDmaChannel& aChannel, TUint aTargetFlags, |
|
413 TUint aElementSize, TUint32 aPslInfo) = 0; |
|
414 |
|
415 /** Called by PIL during fragmentation to initialise a hardware descriptor. |
|
416 |
|
417 The PSL must assume the descriptor is the last in the chain and so set |
|
418 the interrupt bit and set the next descriptor field to an end of chain |
|
419 marker. |
|
420 |
|
421 The function must be implemented by the PSL if and only if the DMAC |
|
422 supports hardware descriptors and SDmaCaps::iAsymHwDescriptors is |
|
423 reported as false. |
|
424 |
|
425 @param aHdr Header associated with the hardware descriptor to |
|
426 initialise |
|
427 @param aTransferArgs The transfer parameters for this descriptor |
|
428 |
|
429 @return KErrNone if the descriptor was successfully initialized, |
|
430 KErrArgument if any of the transfer arguments were detected to be |
|
431 invalid, KErrGeneral if a general error occurred preventing a |
|
432 successful outcome. |
|
433 */ |
|
434 virtual TInt InitHwDes(const SDmaDesHdr& aHdr, const TDmaTransferArgs& aTransferArgs); |
|
435 |
|
436 /** Called by PIL during fragmentation to initialise a hardware descriptor |
|
437 on the source side of an asymmetric linked list. |
|
438 |
|
439 The function must be implemented by the PSL if |
|
440 SDmaCaps::iAsymHwDescriptors is reported as true. |
|
441 |
|
442 @param aHdr Header associated with the hardware descriptor to |
|
443 initialise |
|
444 @param aTransferArgs The transfer parameters for this descriptor. Only |
|
445 the elements relating to the source side should be relevant to the |
|
446 implementation. |
|
447 |
|
448 @return KErrNone if the descriptor was successfully initialized, |
|
449 KErrArgument if any of the transfer arguments were detected to be |
|
450 invalid, KErrGeneral if a general error occurred preventing a |
|
451 successful outcome. |
|
452 */ |
|
453 virtual TInt InitSrcHwDes(const SDmaDesHdr& aHdr, const TDmaTransferArgs& aTransferArgs); |
|
454 |
|
455 /** Called by PIL during fragmentation to initialise a hardware descriptor |
|
456 on the destination side of an asymmetric linked list. |
|
457 |
|
458 The function must be implemented by the PSL if |
|
459 SDmaCaps::iAsymHwDescriptors is reported as true. |
|
460 |
|
461 @param aHdr Header associated with the hardware descriptor to |
|
462 initialise |
|
463 @param aTransferArgs The transfer parameters for this descriptor. Only |
|
464 the elements relating to the destination side should be relevant to the |
|
465 implementation. |
|
466 |
|
467 @return KErrNone if the descriptor was successfully initialized, |
|
468 KErrArgument if any of the transfer arguments were detected to be |
|
469 invalid, KErrGeneral if a general error occurred preventing a |
|
470 successful outcome. |
|
471 */ |
|
472 virtual TInt InitDstHwDes(const SDmaDesHdr& aHdr, const TDmaTransferArgs& aTransferArgs); |
|
473 |
|
474 /** Called by the PIL in ISR context to change specific fields in a |
|
475 hardware descriptor. |
|
476 |
|
477 The function must be implemented by the PSL if and only if the DMAC |
|
478 supports hardware descriptors and SDmaCaps::iAsymHwDescriptors is |
|
479 reported as false. |
|
480 |
|
481 @param aHdr Header associated with the hardware descriptor to be |
|
482 updated |
|
483 @param aSrcAddr @see TDmaTransferArgs::iSrcConfig::iAddr |
|
484 @param aDstAddr @see TDmaTransferArgs::iDstConfig::iAddr |
|
485 @param aTransferCount @see TDmaTransferArgs::iTransferCount |
|
486 @param aPslRequestInfo @see TDmaTransferArgs::iPslRequestInfo |
|
487 |
|
488 Since Epoc::LinearToPhysical() cannot be called in ISR context the |
|
489 addresses passed into this function are always physical ones, i.e. |
|
490 TDmaTransferFlags::KDmaPhysAddr is implied. |
|
491 |
|
492 @return KErrNone if the descriptor was successfully modified, |
|
493 KErrArgument if any of the transfer arguments were detected to be |
|
494 invalid, KErrGeneral if a general error occurred preventing a |
|
495 successful outcome. |
|
496 */ |
|
497 virtual TInt UpdateHwDes(const SDmaDesHdr& aHdr, TUint32 aSrcAddr, TUint32 aDstAddr, |
|
498 TUint aTransferCount, TUint32 aPslRequestInfo); |
|
499 |
|
500 /** Called by the PIL in ISR context to change specific fields in a |
|
501 hardware descriptor. |
|
502 |
|
503 The function must be implemented by the PSL if |
|
504 SDmaCaps::iAsymHwDescriptors is reported as true. |
|
505 |
|
506 @param aHdr Header associated with the hardware descriptor to be |
|
507 updated |
|
508 @param aSrcAddr @see TDmaTransferArgs::iSrcConfig::iAddr |
|
509 @param aTransferCount @see TDmaTransferArgs::iTransferCount |
|
510 @param aPslRequestInfo @see TDmaTransferArgs::iPslRequestInfo |
|
511 |
|
512 Since Epoc::LinearToPhysical() cannot be called in ISR context the |
|
513 address passed into this function is always a physical ones, i.e. |
|
514 TDmaTransferFlags::KDmaPhysAddr is implied. |
|
515 |
|
516 @return KErrNone if the descriptor was successfully modified, |
|
517 KErrArgument if any of the transfer arguments were detected to be |
|
518 invalid, KErrGeneral if a general error occurred preventing a |
|
519 successful outcome. |
|
520 */ |
|
521 virtual TInt UpdateSrcHwDes(const SDmaDesHdr& aHdr, TUint32 aSrcAddr, |
|
522 TUint aTransferCount, TUint32 aPslRequestInfo); |
|
523 |
|
524 /** Called by the PIL in ISR context to change specific fields in a |
|
525 hardware descriptor. |
|
526 |
|
527 The function must be implemented by the PSL if |
|
528 SDmaCaps::iAsymHwDescriptors is reported as true. |
|
529 |
|
530 @param aHdr Header associated with the hardware descriptor to be |
|
531 updated |
|
532 @param aDstAddr @see TDmaTransferArgs::iDstConfig::iAddr |
|
533 @param aTransferCount @see TDmaTransferArgs::iTransferCount |
|
534 @param aPslRequestInfo @see TDmaTransferArgs::iPslRequestInfo |
|
535 |
|
536 Since Epoc::LinearToPhysical() cannot be called in ISR context the |
|
537 address passed into this function is always a physical ones, i.e. |
|
538 TDmaTransferFlags::KDmaPhysAddr is implied. |
|
539 |
|
540 @return KErrNone if the descriptor was successfully modified, |
|
541 KErrArgument if any of the transfer arguments were detected to be |
|
542 invalid, KErrGeneral if a general error occurred preventing a |
|
543 successful outcome. |
|
544 */ |
|
545 virtual TInt UpdateDstHwDes(const SDmaDesHdr& aHdr, TUint32 aDstAddr, |
|
546 TUint aTransferCount, TUint32 aPslRequestInfo); |
|
547 |
|
548 /** Called by PIL, when fragmenting a request, to append a new hardware |
|
549 descriptor to an existing descriptor chain. May also be called by |
|
550 clients who wish to create their own descriptor chains. |
|
551 |
|
552 Must clear the interrupt bit of the descriptor associated with aHdr. |
|
553 |
|
554 The function must be implemented by the PSL if and only if the DMAC |
|
555 supports hardware descriptors. |
|
556 |
|
557 @param aHdr Header associated with last fragment in chain |
|
558 @param aNextHdr Header associated with fragment to append |
|
559 */ |
|
560 virtual void ChainHwDes(const SDmaDesHdr& aHdr, const SDmaDesHdr& aNextHdr); |
|
561 |
|
562 /** Called by PIL when queuing a new request while the channel is running. |
|
563 |
|
564 Must append the first hardware descriptor of the new request to the |
|
565 last descriptor in the existing chain. |
|
566 |
|
567 The function must be implemented by the PSL if and only if the DMAC |
|
568 supports hardware descriptors. |
|
569 |
|
570 @param aChannel The channel where the transfer takes place |
|
571 @param aLastHdr Header associated with last hardware descriptor in |
|
572 chain |
|
573 @param aNewHdr Header associated with first hardware descriptor in new |
|
574 request |
|
575 */ |
|
576 virtual void AppendHwDes(const TDmaChannel& aChannel, const SDmaDesHdr& aLastHdr, |
|
577 const SDmaDesHdr& aNewHdr); |
|
578 |
|
579 /** Called by PIL when queuing a new request while the channel is running. |
|
580 |
|
581 Must append the first hardware descriptor of the new request to the |
|
582 last descriptor in the existing chain. |
|
583 |
|
584 The function must be implemented by the PSL if |
|
585 SDmaCaps::iAsymHwDescriptors is reported as true. |
|
586 |
|
587 @param aChannel The channel where the transfer takes place |
|
588 @param aSrcLastHdr Header associated with the last descriptor in the |
|
589 source side chain |
|
590 @param aSrcNewHdr Header associated with the first source side |
|
591 descriptor of the new request |
|
592 @param aDstLastHdr Header associated with the last descriptor in the |
|
593 destination side chain |
|
594 @param aDstNewHdr Header associated with the first destination side |
|
595 descriptor of the new request |
|
596 */ |
|
597 virtual void AppendHwDes(const TDmaChannel& aChannel, |
|
598 const SDmaDesHdr& aSrcLastHdr, const SDmaDesHdr& aSrcNewHdr, |
|
599 const SDmaDesHdr& aDstLastHdr, const SDmaDesHdr& aDstNewHdr); |
|
600 |
|
601 /** Called by PIL when completing or cancelling a request to cause the PSL |
|
602 to unlink the last item in the h/w descriptor chain from a subsequent |
|
603 chain that it was possibly linked to. |
|
604 |
|
605 The function must be implemented by the PSL if and only if the DMAC |
|
606 supports hardware descriptors. |
|
607 |
|
608 @param aChannel The channel where the request (and thus the descriptor) |
|
609 was queued |
|
610 @param aHdr Header associated with last h/w descriptor in |
|
611 completed / cancelled chain |
|
612 */ |
|
613 virtual void UnlinkHwDes(const TDmaChannel& aChannel, SDmaDesHdr& aHdr); |
|
614 |
|
615 /** Called by PIL when freeing descriptors back to the shared pool in |
|
616 FreeDesList(). The PSL inside ClearHwDes() can clear the contents of |
|
617 the h/w descriptor. |
|
618 |
|
619 This may be necessary if the PSL implementation uses the h/w descriptor |
|
620 as another header which in turn points to the actual DMA h/w descriptor |
|
621 (aka LLI). |
|
622 |
|
623 The function may be implemented by the PSL if the DMAC supports |
|
624 hardware descriptors. |
|
625 |
|
626 @param aHdr Header associated with the h/w descriptor being freed. |
|
627 */ |
|
628 virtual void ClearHwDes(const SDmaDesHdr& aHdr); |
|
629 |
|
630 /** Called by PIL to logically link two physical channels. |
|
631 |
|
632 The function must be implemented by the PSL if the DMAC supports |
|
633 logical channel linking. |
|
634 |
|
635 @see SDmacCaps::iChannelLinking |
|
636 |
|
637 @param a1stChannel The channel which is to be linked to another channel |
|
638 @param a2ndChannel The channel the first one is to be linked to |
|
639 |
|
640 @return KErrNone if the two channels have been linked successfully, |
|
641 KErrCompletion if a1stChannel was already linked to a2ndChannel, |
|
642 KErrArgument if a1stChannel was already linked to a different channel, |
|
643 KErrGeneral if a general error occurred preventing a successful |
|
644 outcome. The default PIL implementation returns KErrNotSupported. |
|
645 */ |
|
646 virtual TInt LinkChannels(TDmaChannel& a1stChannel, TDmaChannel& a2ndChannel); |
|
647 |
|
648 /** Called by PIL to logically unlink a physical channel from its linked-to |
|
649 successor. |
|
650 |
|
651 The function must be implemented by the PSL if the DMAC supports |
|
652 logical channel linking. |
|
653 |
|
654 @see SDmacCaps::iChannelLinking |
|
655 |
|
656 @param aChannel The channel which is to be unlinked from its successor |
|
657 |
|
658 @return KErrNone if the channel has been unlinked successfully, |
|
659 KErrCompletion if the channel was not linked to another channel, |
|
660 KErrGeneral if a general error occurred preventing a successful |
|
661 outcome. The default PIL implementation returns KErrNotSupported. |
|
662 */ |
|
663 virtual TInt UnlinkChannel(TDmaChannel& aChannel); |
|
664 |
|
665 /** Called by a test harness to force an error when the next fragment is |
|
666 transferred. |
|
667 |
|
668 Must be implemented by the PSL only if possible. |
|
669 |
|
670 @param aChannel The channel where the error is to occur. |
|
671 |
|
672 @return KErrNone if implemented. The default PIL implementation |
|
673 returns KErrNotSupported. |
|
674 */ |
|
675 virtual TInt FailNext(const TDmaChannel& aChannel); |
|
676 |
|
677 /** Called by a test harness to force the DMA controller to miss one or |
|
678 more interrupts. |
|
679 |
|
680 The function must be implemented by the PSL only if possible. |
|
681 |
|
682 @param aChannel The channel where the error is to occur |
|
683 @param aInterruptCount The number of interrupt to miss. |
|
684 |
|
685 @return KErrNone if implemented. The default PIL implementation |
|
686 returns KErrNotSupported. |
|
687 */ |
|
688 virtual TInt MissNextInterrupts(const TDmaChannel& aChannel, TInt aInterruptCount); |
|
689 |
|
690 /** Function allowing platform-specific layer to extend channel API with |
|
691 new channel-specific operations. |
|
692 |
|
693 @see TDmaChannel::ChannelExtension |
|
694 |
|
695 @param aChannel Channel to operate on |
|
696 @param aCmd Command identifier. Negative values are reserved for use by |
|
697 Nokia. |
|
698 @param aArg PSL-specific argument |
|
699 |
|
700 @return KErrNotSupported if aCmd is not supported. PSL-specific value |
|
701 otherwise. |
|
702 */ |
|
703 virtual TInt Extension(TDmaChannel& aChannel, TInt aCmd, TAny* aArg); |
|
704 |
|
705 /** Called by the PIL to query the number of elements that have so far been |
|
706 transferred by the hardware descriptor associated with aHdr at the |
|
707 source port. |
|
708 |
|
709 If SDmacCaps::iAsymHwDescriptors is true then the PIL will call this |
|
710 function only for source-side descriptors, and the PSL should fault the |
|
711 kernel if this is not the case. |
|
712 |
|
713 The function must be implemented (i.e. overridden) by the PSL if and |
|
714 only if the DMAC supports hardware descriptors. |
|
715 |
|
716 @param aHdr Descriptor header associated with the hardware descriptor |
|
717 to be queried |
|
718 |
|
719 @return The number of elements that have been transferred by the |
|
720 hardware descriptor associated with aHdr at the source port |
|
721 */ |
|
722 virtual TUint32 HwDesNumSrcElementsTransferred(const SDmaDesHdr& aHdr); |
|
723 |
|
724 /** Called by the PIL to query the number of elements that have so far been |
|
725 transferred by the hardware descriptor associated with aHdr at the |
|
726 destination port. |
|
727 |
|
728 If SDmacCaps::iAsymHwDescriptors is true then the PIL will call this |
|
729 function only for destination-side descriptors, and the PSL should |
|
730 panic if this is not the case. |
|
731 |
|
732 The function must be implemented (i.e. overridden) by the PSL if and |
|
733 only if the DMAC supports hardware descriptors. |
|
734 |
|
735 @param aHdr Descriptor header associated with the hardware descriptor |
|
736 to be queried |
|
737 |
|
738 @return The number of elements that have been transferred by the |
|
739 hardware descriptor associated with aHdr at the destination port |
|
740 */ |
|
741 virtual TUint32 HwDesNumDstElementsTransferred(const SDmaDesHdr& aHdr); |
|
742 |
|
743 protected: |
|
744 /** Called by the PSL in interrupt context upon a channel interrupt event. |
|
745 |
|
746 @param aChannel The channel the ISR relates to |
|
747 @param aEventMask Bitmask of one or more TDmaCallbackType values |
|
748 @param aIsComplete Set to ETrue if no error was encountered |
|
749 */ |
|
750 static void HandleIsr(TDmaChannel& aChannel, TUint aEventMask, TBool aIsComplete); |
|
751 |
|
752 private: |
|
753 /** Called in Create() */ |
|
754 TInt AllocDesPool(TUint aAttribs); |
|
755 |
|
756 /** Called in ~TDmac() */ |
|
757 void FreeDesPool(); |
|
758 |
|
759 private: |
|
760 NFastMutex iLock; // protect descriptor reservation and allocation |
|
761 const TInt iMaxDesCount; // initial number of descriptors and headers |
|
762 TInt iAvailDesCount; // current available number of descriptors and headers |
|
763 SDmaDesHdr* iHdrPool; // descriptor header dynamic array |
|
764 #ifndef __WINS__ |
|
765 DPlatChunkHw* iHwDesChunk; // chunk for hardware descriptor pool |
|
766 #endif |
|
767 TAny* iDesPool; // hardware or pseudo descriptor dynamic array |
|
768 const TInt iDesSize; // descriptor size in bytes |
|
769 |
|
770 public: |
|
771 const TBool iCapsHwDes; /*< True if DMAC uses h/w descriptors */ |
|
772 SDmaDesHdr* iFreeHdr; /*< head of unallocated descriptors linked list */ |
|
773 |
|
774 #ifdef _DEBUG |
|
775 /** Tests whether aHdr points into the descriptor header array. */ |
|
776 TBool IsValidHdr(const SDmaDesHdr* aHdr); |
|
777 #endif |
|
778 __DMA_DECLARE_INVARIANT |
|
779 }; |
|
780 |
|
781 |
|
782 ////////////////////////////////////////////////////////////////////////////// |
|
783 |
|
784 |
|
785 /** Single-buffer DMA channel. |
|
786 |
|
787 Can be instantiated or further derived by the PSL. |
|
788 |
|
789 @publishedPartner |
|
790 @released |
|
791 */ |
|
792 class TDmaSbChannel : public TDmaChannel |
|
793 { |
|
794 private: |
|
795 virtual void DoQueue(const DDmaRequest& aReq); |
|
796 virtual void DoCancelAll(); |
|
797 virtual void DoDfc(const DDmaRequest& aCurReq, SDmaDesHdr*& aCompletedHdr); |
|
798 private: |
|
799 enum {EIdle = 0, ETransferring} iState; |
|
800 }; |
|
801 |
|
802 |
|
803 /** Double-buffer DMA channel. |
|
804 |
|
805 Can be instantiated or further derived by the PSL. |
|
806 |
|
807 @publishedPartner |
|
808 @released |
|
809 */ |
|
810 class TDmaDbChannel : public TDmaChannel |
|
811 { |
|
812 private: |
|
813 virtual void DoQueue(const DDmaRequest& aReq); |
|
814 virtual void DoCancelAll(); |
|
815 virtual void DoDfc(const DDmaRequest& aCurReq, SDmaDesHdr*& aCompletedHdr); |
|
816 private: |
|
817 enum {EIdle = 0, ETransferring, ETransferringLast} iState; |
|
818 }; |
|
819 |
|
820 |
|
821 /** Scatter-gather DMA channel. |
|
822 |
|
823 Can be instantiated or further derived by the PSL. |
|
824 |
|
825 @publishedPartner |
|
826 @released |
|
827 */ |
|
828 class TDmaSgChannel : public TDmaChannel |
|
829 { |
|
830 private: |
|
831 virtual void DoQueue(const DDmaRequest& aReq); |
|
832 virtual void DoCancelAll(); |
|
833 virtual void DoUnlink(SDmaDesHdr& aHdr); |
|
834 virtual void DoDfc(const DDmaRequest& aCurReq, SDmaDesHdr*& aCompletedHdr); |
|
835 private: |
|
836 enum {EIdle = 0, ETransferring} iState; |
|
837 }; |
|
838 |
|
839 |
|
840 /** Scatter-gather DMA channel with asymmetric linked-lists. |
|
841 |
|
842 Can be instantiated or further derived by the PSL. |
|
843 |
|
844 @publishedPartner |
|
845 @released |
|
846 */ |
|
847 class TDmaAsymSgChannel : public TDmaChannel |
|
848 { |
|
849 private: |
|
850 virtual void DoQueue(const DDmaRequest& aReq); |
|
851 virtual void DoCancelAll(); |
|
852 virtual void DoUnlink(SDmaDesHdr& aHdr); |
|
853 virtual void DoDfc(const DDmaRequest& aCurReq, SDmaDesHdr*& aSrcCompletedHdr, |
|
854 SDmaDesHdr*& aDstCompletedHdr); |
|
855 private: |
|
856 SDmaDesHdr* iSrcCurHdr; // source fragment being transferred or NULL |
|
857 SDmaDesHdr** iSrcNullPtr; // Pointer to NULL pointer following last source fragment |
|
858 SDmaDesHdr* iDstCurHdr; // destination fragment being transferred or NULL |
|
859 SDmaDesHdr** iDstNullPtr; // Pointer to NULL pointer following last destination fragment |
|
860 enum {EIdle = 0, ETransferring} iState; |
|
861 }; |
|
862 |
|
863 |
|
864 ////////////////////////////////////////////////////////////////////////////// |
|
865 |
|
866 // Trace macros intended for use by the DMA PSL |
|
867 #define DMA_PRINTF(MSG) __KTRACE_OPT(KDMA, Kern::Printf((MSG))) |
|
868 #define DMA_PRINTF1(MSG, ARG1) __KTRACE_OPT(KDMA, Kern::Printf((MSG), (ARG1))) |
|
869 #define DMA_PRINTF2(MSG, ARG1, ARG2) __KTRACE_OPT(KDMA, Kern::Printf((MSG), (ARG1), (ARG2))) |
|
870 |
|
871 #define DMA_PSL_MESG "DMA PSL: " |
|
872 |
|
873 // General PSL tracing |
|
874 #define DMA_PSL_TRACE(MSG) DMA_PRINTF(DMA_PSL_MESG MSG) |
|
875 #define DMA_PSL_TRACE1(MSG, ARG1) DMA_PRINTF1(DMA_PSL_MESG MSG, (ARG1)) |
|
876 #define DMA_PSL_TRACE2(MSG, ARG1, ARG2) DMA_PRINTF2(DMA_PSL_MESG MSG, (ARG1), (ARG2)) |
|
877 |
|
878 |
|
879 #define DMA_PSL_CHAN_MESG DMA_PSL_MESG "ChanId %d: " |
|
880 #define DMA_PSL_CHAN_ARGS(CHAN) ((CHAN).PslId()) |
|
881 |
|
882 // For channel specific tracing (where CHAN is a TDmaChannel) |
|
883 #define DMA_PSL_CHAN_TRACE_STATIC(CHAN, MSG) DMA_PRINTF1(DMA_PSL_CHAN_MESG MSG, DMA_PSL_CHAN_ARGS(CHAN)) |
|
884 #define DMA_PSL_CHAN_TRACE_STATIC1(CHAN, MSG, ARG1) DMA_PRINTF2(DMA_PSL_CHAN_MESG MSG, DMA_PSL_CHAN_ARGS(CHAN), (ARG1)) |
|
885 |
|
886 // For channel specific tracing, for use within methods of TDmaChannel derived |
|
887 // class |
|
888 #define DMA_PSL_CHAN_TRACE(MSG) DMA_PSL_CHAN_TRACE_STATIC(*this, MSG) |
|
889 #define DMA_PSL_CHAN_TRACE1(MSG, ARG1) DMA_PSL_CHAN_TRACE_STATIC1(*this, MSG, (ARG1)) |
|
890 |
|
891 |
|
892 |
|
893 #include <drivers/dma_hai.inl> |
|
894 |
|
895 |
|
896 #endif // #ifndef __DMA_HAI_H__ |
|