94 |
98 |
95 /** Each hardware or pseudo descriptor is associated with a header. Headers |
99 /** Each hardware or pseudo descriptor is associated with a header. Headers |
96 are needed because hardware descriptors can not easily be extended to store |
100 are needed because hardware descriptors can not easily be extended to store |
97 additional information. |
101 additional information. |
98 |
102 |
99 @publishedPartner |
|
100 @released |
103 @released |
101 */ |
104 */ |
102 struct SDmaDesHdr |
105 struct SDmaDesHdr |
103 { |
106 { |
104 SDmaDesHdr* iNext; |
107 SDmaDesHdr* iNext; |
105 }; |
108 }; |
106 |
109 |
|
110 |
107 /** Pointer to signature of the new extended callback function. |
111 /** Pointer to signature of the new extended callback function. |
108 |
112 |
109 TUint - bitmask of one or more TDmaCallbackType values |
113 TUint - bitmask of one or more TDmaCallbackType values |
110 TDmaResult - just that |
114 TDmaResult - just that |
111 TAny* - was provided by client in DDmaRequest constructor |
115 TAny* - was provided by client in DDmaRequest constructor |
112 SDmaDesHdr* - points to header (and thus descriptor) which caused a |
116 SDmaDesHdr* - points to header (and thus descriptor) which caused a |
113 'descriptor completed' or 'descriptor paused' event. |
117 'descriptor completed' or 'descriptor paused' event |
|
118 |
|
119 @released |
114 */ |
120 */ |
115 typedef void (*TDmaCallback)(TUint, TDmaResult, TAny*, SDmaDesHdr*); |
121 typedef void (*TDmaCallback)(TUint, TDmaResult, TAny*, SDmaDesHdr*); |
116 |
122 |
|
123 |
117 class TDmaChannel; |
124 class TDmaChannel; |
|
125 |
118 |
126 |
119 /** A DMA request is a list of fragments small enough to be transferred in one go |
127 /** A DMA request is a list of fragments small enough to be transferred in one go |
120 by the DMAC. |
128 by the DMAC. |
121 |
129 |
122 In general, fragmentation is done in the framework by calling Fragment() but |
130 In general, fragmentation is done in the framework by calling Fragment() but |
130 Multithreaded clients must implement their own locking scheme (via DMutex). |
138 Multithreaded clients must implement their own locking scheme (via DMutex). |
131 |
139 |
132 Mutexes are used internally to protect data structures accessed both by the |
140 Mutexes are used internally to protect data structures accessed both by the |
133 client thread and the DFC thread. Therefore no fast mutex can be held when |
141 client thread and the DFC thread. Therefore no fast mutex can be held when |
134 calling a request function. |
142 calling a request function. |
135 |
143 */ |
136 @publishedPartner |
|
137 @released |
|
138 */ |
|
139 class DDmaRequest : public DBase |
144 class DDmaRequest : public DBase |
140 { |
145 { |
141 friend class TDmaChannel; |
146 friend class TDmaChannel; |
142 |
147 |
143 public: |
148 public: |
144 /** The outcome of the transfer |
149 /** The outcome of the transfer |
145 |
150 |
|
151 @see TDmaResult |
|
152 |
146 @deprecated |
153 @deprecated |
147 @see TDmaResult |
|
148 */ |
154 */ |
149 enum TResult {EBadResult=0, EOk, EError}; |
155 enum TResult {EBadResult=0, EOk, EError}; |
|
156 |
150 /** The signature of the completion/failure callback function |
157 /** The signature of the completion/failure callback function |
151 |
158 |
|
159 @see TDmaCallback |
|
160 |
152 @deprecated |
161 @deprecated |
153 @see TDmaCallback |
|
154 */ |
162 */ |
155 typedef void (*TCallback)(TResult, TAny*); |
163 typedef void (*TCallback)(TResult, TAny*); |
156 |
164 |
157 public: |
165 public: |
158 /** Constructor. |
166 /** Constructor. |
181 failure (in channel DFC or ISR context). Can be NULL. |
189 failure (in channel DFC or ISR context). Can be NULL. |
182 @param aCbArg Argument passed to callback function. |
190 @param aCbArg Argument passed to callback function. |
183 @param aMaxTransferSize Maximum fragment size. If not specified, |
191 @param aMaxTransferSize Maximum fragment size. If not specified, |
184 defaults to the maximum size supported by the DMA controller for the |
192 defaults to the maximum size supported by the DMA controller for the |
185 type of transfer that is later scheduled. |
193 type of transfer that is later scheduled. |
186 */ |
194 |
187 IMPORT_C DDmaRequest(TDmaChannel& aChannel, TDmaCallback aDmaCb, TAny* aCbArg=NULL, |
195 @released |
188 TUint aMaxTransferSize=0); |
196 */ |
|
197 IMPORT_C DDmaRequest(TDmaChannel& aChannel, TDmaCallback aDmaCb, |
|
198 TAny* aCbArg=NULL, TUint aMaxTransferSize=0); |
189 |
199 |
190 |
200 |
191 /** Destructor. |
201 /** Destructor. |
192 |
202 |
193 Assume the request is not being transferred or pending. |
203 Assume the request is not being transferred or pending. |
194 */ |
204 |
|
205 @released |
|
206 */ |
195 IMPORT_C ~DDmaRequest(); |
207 IMPORT_C ~DDmaRequest(); |
196 |
208 |
197 |
209 |
198 /** Split request into a list of fragments small enough to be fed to the |
210 /** Split request into a list of fragments small enough to be fed to the |
199 DMAC. |
211 DMAC. |
209 magic cookie by the PIL and passed straight to the PSL. |
221 magic cookie by the PIL and passed straight to the PSL. |
210 |
222 |
211 The request can be uninitialised or may have been fragmented |
223 The request can be uninitialised or may have been fragmented |
212 previously. The previous configuration if any is lost whether or not |
224 previously. The previous configuration if any is lost whether or not |
213 the function succeeds. |
225 the function succeeds. |
|
226 |
|
227 The client must ensure that any memory buffers involved in the transfer |
|
228 have been suitably prepared for DMA. For memory allocated on the kernel |
|
229 side or in a shared chunk this amounts to ensuring cache consistency |
|
230 before Queue() is called. However for memory that was allocated on the |
|
231 user side the client must also ensure that the memory is protected from |
|
232 both data paging and RAM defragmentation before Fragment() is called |
|
233 @see Kern::MapAndPinMemory(). Note however, that this function is only |
|
234 available if the flexible memory model (FMM) is in use. |
214 |
235 |
215 @param aSrc Source memory buffer linear address or peripheral magic |
236 @param aSrc Source memory buffer linear address or peripheral magic |
216 cookie. |
237 cookie. |
217 @param aDest Destination memory buffer linear address or peripheral |
238 @param aDest Destination memory buffer linear address or peripheral |
218 magic cookie. |
239 magic cookie. |
235 IMPORT_C TInt Fragment(TUint32 aSrc, TUint32 aDest, TInt aCount, TUint aFlags, TUint32 aPslInfo); |
256 IMPORT_C TInt Fragment(TUint32 aSrc, TUint32 aDest, TInt aCount, TUint aFlags, TUint32 aPslInfo); |
236 |
257 |
237 |
258 |
238 /** New version of the DMA request fragment function, to be used with the |
259 /** New version of the DMA request fragment function, to be used with the |
239 TDmaTransferArgs structure. |
260 TDmaTransferArgs structure. |
|
261 |
|
262 Split request into a list of fragments small enough to be fed to the |
|
263 DMAC. |
|
264 |
|
265 The size of each fragment is smaller than or equal to the maximum |
|
266 transfer size supported by the DMAC. If the source and/or destination |
|
267 is memory, each fragment points to memory which is physically |
|
268 contiguous. |
|
269 |
|
270 The request can be uninitialised or may have been fragmented |
|
271 previously. Any previous configuration is lost whether or not the |
|
272 function succeeds. |
|
273 |
|
274 The client must ensure that any memory buffers involved in the transfer |
|
275 have been suitably prepared for DMA. For memory allocated on the kernel |
|
276 side or in a shared chunk this amounts to ensuring cache consistency |
|
277 before Queue() is called. However for memory that was allocated on the |
|
278 user side the client must also ensure that the memory is protected from |
|
279 both data paging and RAM defragmentation before Fragment() is called |
|
280 @see Kern::MapAndPinMemory(). Note however, that this function is only |
|
281 available if the flexible memory model (FMM) is in use. |
|
282 |
|
283 @param aTransferArgs Describes the transfer to be performed. |
|
284 |
|
285 @return KErrNone if success. KErrArgument if certain arguments are |
|
286 invalid. May also fail if running out of descriptors. |
|
287 |
|
288 @pre The request is not being transferred or pending. |
|
289 @pre The various parameters must be valid. The PIL or PSL will fault |
|
290 the kernel if not. |
|
291 |
|
292 @released |
240 */ |
293 */ |
241 IMPORT_C TInt Fragment(const TDmaTransferArgs& aTransferArgs); |
294 IMPORT_C TInt Fragment(const TDmaTransferArgs& aTransferArgs); |
242 |
295 |
243 |
296 |
244 /** Transfer asynchronously this request. |
297 /** Transfer asynchronously this request. |
304 true, otherwise it will just return KErrGeneral. |
363 true, otherwise it will just return KErrGeneral. |
305 |
364 |
306 @param aCount Number of descriptors to append. |
365 @param aCount Number of descriptors to append. |
307 |
366 |
308 @return KErrNone or standard error code. |
367 @return KErrNone or standard error code. |
309 */ |
368 |
|
369 @prototype |
|
370 */ |
310 IMPORT_C TInt ExpandDstDesList(TInt aCount=1); |
371 IMPORT_C TInt ExpandDstDesList(TInt aCount=1); |
311 |
372 |
312 |
373 |
313 /** Free resources associated with this request. |
374 /** Free resources associated with this request. |
314 |
375 |
315 Assume the request is not being transferred or pending. |
376 Assume the request is not being transferred or pending. |
316 */ |
377 |
|
378 @released |
|
379 */ |
317 IMPORT_C void FreeDesList(); |
380 IMPORT_C void FreeDesList(); |
318 |
381 |
319 |
382 |
320 /** Free resources associated with this request. This function variant |
383 /** Free resources associated with this request. This function variant |
321 operates on the source port descriptor chain. |
384 operates on the source port descriptor chain. |
322 |
385 |
323 @see FreeDesList |
386 @see FreeDesList |
324 |
387 |
325 This function can only be used if SDmacCaps::iAsymHwDescriptors is |
388 This function can only be used if SDmacCaps::iAsymHwDescriptors is |
326 true, otherwise it will do nothing. |
389 true, otherwise it will do nothing. |
327 */ |
390 |
|
391 @prototype |
|
392 */ |
328 IMPORT_C void FreeSrcDesList(); |
393 IMPORT_C void FreeSrcDesList(); |
329 |
394 |
330 |
395 |
331 /** Free resources associated with this request. This function variant |
396 /** Free resources associated with this request. This function variant |
332 operates on the destination port descriptor chain. |
397 operates on the destination port descriptor chain. |
333 |
398 |
334 @see FreeDesList |
399 @see FreeDesList |
335 |
400 |
336 This function can only be used if SDmacCaps::iAsymHwDescriptors is |
401 This function can only be used if SDmacCaps::iAsymHwDescriptors is |
337 true, otherwise it will do nothing. |
402 true, otherwise it will do nothing. |
338 */ |
403 |
|
404 @prototype |
|
405 */ |
339 IMPORT_C void FreeDstDesList(); |
406 IMPORT_C void FreeDstDesList(); |
340 |
407 |
341 |
408 |
342 /** Enables the functionality for counting the transferred source |
409 /** Enables the functionality for counting the transferred source |
343 elements. |
410 elements. |
541 This function can only be used if SDmacCaps::iAsymHwDescriptors is |
625 This function can only be used if SDmacCaps::iAsymHwDescriptors is |
542 true, otherwise it will always return 0. |
626 true, otherwise it will always return 0. |
543 |
627 |
544 @return The number of destination port fragments (descriptors) that |
628 @return The number of destination port fragments (descriptors) that |
545 this transfer request has been split into. |
629 this transfer request has been split into. |
546 */ |
630 |
|
631 @prototype |
|
632 */ |
547 IMPORT_C TInt DstFragmentCount(); |
633 IMPORT_C TInt DstFragmentCount(); |
548 |
634 |
549 private: |
635 private: |
550 inline void OnDeque(); |
636 inline void OnDeque(); |
551 TUint GetTransferCount(const TDmaTransferArgs& aTransferArgs); |
637 TInt CheckTransferConfig(const TDmaTransferConfig& aTarget, TUint aCount) const; |
|
638 TInt CheckMemFlags(const TDmaTransferConfig& aTarget, TUint aCount) const; |
|
639 TInt AdjustFragmentSize(TUint& aFragSize, TUint aElementSize, TUint aFrameSize); |
|
640 TUint GetTransferCount(const TDmaTransferArgs& aTransferArgs) const; |
|
641 TUint GetMaxTransferlength(const TDmaTransferArgs& aTransferArgs, TUint aCount) const; |
552 TInt Frag(TDmaTransferArgs& aTransferArgs); |
642 TInt Frag(TDmaTransferArgs& aTransferArgs); |
553 TInt FragSym(TDmaTransferArgs& aTransferArgs, TUint aCount, TUint aMaxTransferLen); |
643 TInt FragSym(TDmaTransferArgs& aTransferArgs, TUint aCount, TUint aMaxTransferLen); |
554 TInt FragAsym(TDmaTransferArgs& aTransferArgs, TUint aCount, TUint aMaxTransferLen); |
644 TInt FragAsym(TDmaTransferArgs& aTransferArgs, TUint aCount, TUint aMaxTransferLen); |
555 TInt FragAsymSrc(TDmaTransferArgs& aTransferArgs, TUint aCount, TUint aMaxTransferLen); |
645 TInt FragAsymSrc(TDmaTransferArgs& aTransferArgs, TUint aCount, TUint aMaxTransferLen); |
556 TInt FragAsymDst(TDmaTransferArgs& aTransferArgs, TUint aCount, TUint aMaxTransferLen); |
646 TInt FragAsymDst(TDmaTransferArgs& aTransferArgs, TUint aCount, TUint aMaxTransferLen); |
|
647 TInt FragBalancedAsym(TDmaTransferArgs& aTransferArgs, TUint aCount, TUint aMaxTransferLen); |
557 TInt ExpandDesList(TInt aCount, TInt& aDesCount, SDmaDesHdr*& aFirstHdr, |
648 TInt ExpandDesList(TInt aCount, TInt& aDesCount, SDmaDesHdr*& aFirstHdr, |
558 SDmaDesHdr*& aLastHdr); |
649 SDmaDesHdr*& aLastHdr); |
559 void FreeDesList(TInt& aDesCount, SDmaDesHdr*& aFirstHdr, SDmaDesHdr*& aLastHdr); |
650 void FreeDesList(TInt& aDesCount, SDmaDesHdr*& aFirstHdr, SDmaDesHdr*& aLastHdr); |
560 TInt FragmentCount(const SDmaDesHdr* aHdr); |
651 TInt FragmentCount(const SDmaDesHdr* aHdr); |
561 |
652 |
562 public: |
653 public: |
563 // WARNING: The following attributes are accessed both in client and DFC |
654 // WARNING: The following attributes are accessed both in client and DFC |
564 // context and so accesses must be protected with the channel lock. |
655 // thread context, so accesses must be protected with the channel lock. |
565 TDmaChannel& iChannel; /**< The channel this request is bound to */ |
656 TDmaChannel& iChannel; /**< The channel this request is bound to */ |
566 TCallback iCb; /**< Called on completion/failure (can be NULL) */ |
657 TCallback iCb; /**< Called on completion/failure (can be NULL) */ |
567 TAny* iCbArg; /**< Callback argument */ |
658 TAny* iCbArg; /**< Callback argument */ |
568 TDmaCallback iDmaCb; // the new-style callback function |
659 TDmaCallback iDmaCb; // the new-style callback function |
569 TAny* iDmaCbArg; // the new-style callback arg |
660 TAny* iDmaCbArg; // the new-style callback arg |
606 scheme (via DMutex). |
697 scheme (via DMutex). |
607 |
698 |
608 Mutexes are used internally to protect data structures accessed both by the |
699 Mutexes are used internally to protect data structures accessed both by the |
609 client thread and the DFC one. Therefore no fast mutex can be held when |
700 client thread and the DFC one. Therefore no fast mutex can be held when |
610 calling a channel function. |
701 calling a channel function. |
611 |
702 */ |
612 @publishedPartner |
|
613 @released |
|
614 */ |
|
615 class TDmaChannel |
703 class TDmaChannel |
616 { |
704 { |
617 friend class DDmaRequest; |
705 friend class DDmaRequest; |
618 friend class TDmac; |
706 friend class TDmac; |
619 friend class DmaChannelMgr; |
707 friend class DmaChannelMgr; |
|
708 |
620 public: |
709 public: |
621 |
710 /** Information passed by client when opening a channel. */ |
622 /** Information passed by client when opening a channel */ |
|
623 struct SCreateInfo |
711 struct SCreateInfo |
624 { |
712 { |
625 /** Default constructor. Initializes all fields with meaningful default |
713 /** Default constructor. Initializes all fields with meaningful default |
626 values. |
714 values. |
627 |
715 |
628 Must be inline (for now) because exporting it would break existing |
716 Must be inline (for now) because exporting it would break existing |
629 custom DMA libs as their clients would need the export which would |
717 custom DMA libs as their clients would need the export which would |
630 be missing from the custom .def files. |
718 be missing from the custom .def files. |
|
719 |
|
720 @released |
631 */ |
721 */ |
632 SCreateInfo() : iPriority(KDmaPriorityNone), iDynChannel(EFalse) {}; |
722 SCreateInfo() : iPriority(KDmaPriorityNone), iDynChannel(EFalse) {}; |
633 |
723 |
634 /** Identifier used by PSL to select channel to open */ |
724 /** Identifier used by PSL to select channel to open. |
|
725 |
|
726 @released |
|
727 */ |
635 TUint32 iCookie; |
728 TUint32 iCookie; |
636 /** Number of descriptors this channel can use. |
729 /** Number of descriptors this channel can maximally use. |
637 |
730 |
638 This number is not used in the upgraded version of the DMA |
731 This value will not be used in the fully implemented new version of |
639 framework and is kept there only for source compatibility. If the |
732 the DMA framework. Until then it is still required. |
640 client is certain that it will only ever use that version, then the |
733 |
641 value passed here doesn't matter - the framework will ignore it. |
734 @released |
642 |
735 */ |
643 @deprecated |
|
644 */ |
|
645 TInt iDesCount; |
736 TInt iDesCount; |
646 /** DFC queue used to service DMA interrupts. |
737 /** DFC queue used to service DMA interrupts. |
647 |
738 |
648 The DFC thread priority must be higher than any client thread |
739 The DFC thread priority must be higher than any client thread |
649 priority to avoid a situation where a transfer completes while |
740 priority to avoid a situation where a transfer completes while |
650 being cancelled and another transfer is started before the DFC |
741 being cancelled and another transfer is started before the DFC |
651 thread gets a chance to run. This would lead to a stray DFC. |
742 thread gets a chance to run. This would lead to a stray DFC. |
|
743 |
|
744 @released |
652 */ |
745 */ |
653 TDfcQue* iDfcQ; |
746 TDfcQue* iDfcQ; |
654 /** DFC priority */ |
747 /** DFC priority. |
|
748 |
|
749 @released |
|
750 */ |
655 TUint8 iDfcPriority; |
751 TUint8 iDfcPriority; |
656 /** Used by PSL to configure a channel priority (if possible). |
752 /** Used by PSL to configure a channel priority (if possible). |
657 |
753 |
658 The default is KDmaPriorityNone (the don't care value). |
754 The default is KDmaPriorityNone (the don't care value). |
659 |
755 |
660 @see TDmaPriority |
756 @see TDmaPriority |
|
757 |
|
758 @prototype |
661 */ |
759 */ |
662 TUint iPriority; |
760 TUint iPriority; |
663 /** Request a dynamic DMA channel. |
761 /** Request a dynamic DMA channel. |
664 |
762 |
665 If this is set to ETrue then the Open call is for a 'dynamic' as |
763 If this is set to ETrue then the Open call is for a 'dynamic' as |
666 opposed to a static and solely owned DMA channel. A number of |
764 opposed to a static and solely owned DMA channel. A number of |
667 properties of the opened TDmaChannel object will be different in |
765 properties of the opened TDmaChannel object will be different in |
668 that case. |
766 that case. |
669 |
767 |
670 The default value is EFalse. |
768 The default value is EFalse. |
|
769 |
|
770 @prototype |
671 */ |
771 */ |
672 TBool iDynChannel; |
772 TBool iDynChannel; |
673 }; |
773 }; |
674 |
774 |
675 public: |
775 public: |
676 /** Opens the DMA channel. |
776 /** Opens the DMA channel. |
677 |
777 |
678 Channel selection is done by the hardware-specific layer using a cookie |
778 Channel selection is done by the hardware-specific layer using a cookie |
679 passed in via aInfo. |
779 passed in via aInfo. |
680 |
780 |
681 The client should not delete the returned pointer as the framework owns |
781 The client should not delete the returned pointer as the framework owns |
731 successfully, KErrCompletion if this channel was already linked to |
835 successfully, KErrCompletion if this channel was already linked to |
732 aChannel or already unlinked, KErrNotSupported if the DMAC doesn't |
836 aChannel or already unlinked, KErrNotSupported if the DMAC doesn't |
733 support channel linking, KErrArgument if this channel was already |
837 support channel linking, KErrArgument if this channel was already |
734 linked to a different channel, KErrGeneral if a general error occurred |
838 linked to a different channel, KErrGeneral if a general error occurred |
735 preventing a successful outcome. |
839 preventing a successful outcome. |
736 */ |
840 |
|
841 @prototype |
|
842 */ |
737 IMPORT_C TInt LinkToChannel(TDmaChannel* aChannel); |
843 IMPORT_C TInt LinkToChannel(TDmaChannel* aChannel); |
|
844 |
738 |
845 |
739 /** Pauses an active transfer on this channel. |
846 /** Pauses an active transfer on this channel. |
740 |
847 |
741 A paused channel transfer can be resumed by calling Resume() or it can |
848 A paused channel transfer can be resumed by calling Resume() or it can |
742 be stopped altogether by calling CancelAll(). |
849 be stopped altogether by calling CancelAll(). |
765 @see TDmaCallbackType::EDmaCallbackLinkedListPaused |
874 @see TDmaCallbackType::EDmaCallbackLinkedListPaused |
766 |
875 |
767 Function can only be used if the DMAC supports this functionality. |
876 Function can only be used if the DMAC supports this functionality. |
768 |
877 |
769 @see SDmacCaps::iChannelPauseAndResume |
878 @see SDmacCaps::iChannelPauseAndResume |
|
879 @see SDmacCaps::iLinkedListPausedInterrupt |
770 |
880 |
771 @return KErrNone if a paused transfer has been resumed successfully, |
881 @return KErrNone if a paused transfer has been resumed successfully, |
772 KErrCompletion if there was no paused transfer, KErrNotSupported if the |
882 KErrCompletion if there was no paused transfer, KErrNotSupported if the |
773 DMAC doesn't support channel transfer pausing/resuming, KErrGeneral if |
883 DMAC doesn't support channel transfer pausing/resuming, KErrGeneral if |
774 a general error occurred preventing a successful outcome. |
884 a general error occurred preventing a successful outcome. |
775 */ |
885 |
|
886 @released |
|
887 */ |
776 IMPORT_C TInt Resume(); |
888 IMPORT_C TInt Resume(); |
777 |
889 |
778 |
890 |
779 /** Cancels the current request and all the pending ones. |
891 /** Cancels the current request and all the pending ones. |
780 */ |
892 |
|
893 @released |
|
894 */ |
781 IMPORT_C void CancelAll(); |
895 IMPORT_C void CancelAll(); |
782 |
896 |
783 |
897 |
784 /** Returns the channel's maximum transfer length based on the passed |
898 /** Returns the channel's maximum transfer length based on the passed |
785 arguments. |
899 arguments. |
817 @param aPslInfo Cookie passed to the PSL |
933 @param aPslInfo Cookie passed to the PSL |
818 @see TDmaTransferArgs::iPslRequestInfo |
934 @see TDmaTransferArgs::iPslRequestInfo |
819 |
935 |
820 @return A value representing the alignment mask (e.g. 3 if buffer must |
936 @return A value representing the alignment mask (e.g. 3 if buffer must |
821 be 4-byte aligned) |
937 be 4-byte aligned) |
822 */ |
938 |
|
939 @released |
|
940 */ |
823 IMPORT_C TUint AddressAlignMask(TUint aTargetFlags, TUint aElementSize, |
941 IMPORT_C TUint AddressAlignMask(TUint aTargetFlags, TUint aElementSize, |
824 TUint32 aPslInfo); |
942 TUint32 aPslInfo); |
825 |
943 |
826 |
944 |
827 /** Returns a reference to a structure containing the capabilities and |
945 /** Returns a reference to a structure containing the capabilities and |
828 features of the DMA controller associated with this channel. |
946 features of the DMA controller associated with this channel. |
829 |
947 |
830 @return A reference to a structure containing the capabilities and |
948 @return A reference to a structure containing the capabilities and |
831 features of the DMA controller associated with this channel. |
949 features of the DMA controller associated with this channel. |
832 */ |
950 |
|
951 @released |
|
952 */ |
833 IMPORT_C const SDmacCaps& DmacCaps(); |
953 IMPORT_C const SDmacCaps& DmacCaps(); |
834 |
954 |
835 |
955 |
836 /** Sets up once more the transfer request that has just completed, after |
956 /** Sets up once more the transfer request that has just completed, after |
837 optionally having adjusted the transfer parameters as specified. |
957 optionally having adjusted the transfer parameters as specified. |
874 @see DDmaRequest::DDmaRequest(TDmaChannel&, TDmaCallback, TAny*, TUint) |
994 @see DDmaRequest::DDmaRequest(TDmaChannel&, TDmaCallback, TAny*, TUint) |
875 @see TDmaCallbackType::EDmaCallbackRequestCompletion |
995 @see TDmaCallbackType::EDmaCallbackRequestCompletion |
876 @see TDmaPILFlags::KDmaRequestCallbackFromIsr |
996 @see TDmaPILFlags::KDmaRequestCallbackFromIsr |
877 |
997 |
878 @return KErrGeneral if there was an error, KErrNone otherwise. |
998 @return KErrGeneral if there was an error, KErrNone otherwise. |
879 */ |
999 |
|
1000 @released |
|
1001 */ |
880 IMPORT_C TInt IsrRedoRequest(TUint32 aSrcAddr=KPhysAddrInvalid, |
1002 IMPORT_C TInt IsrRedoRequest(TUint32 aSrcAddr=KPhysAddrInvalid, |
881 TUint32 aDstAddr=KPhysAddrInvalid, |
1003 TUint32 aDstAddr=KPhysAddrInvalid, |
882 TUint aTransferCount=0, |
1004 TUint aTransferCount=0, |
883 TUint32 aPslRequestInfo=0, |
1005 TUint32 aPslRequestInfo=0, |
884 TBool aIsrCb=ETrue); |
1006 TBool aIsrCb=ETrue); |
889 @return ETrue if channel is currently opened, EFalse otherwise. |
1011 @return ETrue if channel is currently opened, EFalse otherwise. |
890 |
1012 |
891 NB: This API should not be used any longer. |
1013 NB: This API should not be used any longer. |
892 |
1014 |
893 After calling TDmaChannel::Open() successfully the channel is |
1015 After calling TDmaChannel::Open() successfully the channel is |
894 guaranteed to be open. Therefore there seems no good reason for this |
1016 guaranteed to be open, hence there seems no good reason for this API to |
895 API to exist. |
1017 exist. |
896 |
1018 |
897 @deprecated |
1019 @deprecated |
898 */ |
1020 */ |
899 inline TBool IsOpened() const; |
1021 inline TBool IsOpened() const; |
900 |
1022 |
901 |
1023 |
902 /** Tests whether the channel's request queue is currently empty. |
1024 /** Tests whether the channel's request queue is currently empty. |
903 |
1025 |
904 @return ETrue if request queue is currently empty, EFalse otherwise. |
1026 @return ETrue if request queue is currently empty, EFalse otherwise. |
905 */ |
1027 |
|
1028 @released |
|
1029 */ |
906 inline TBool IsQueueEmpty() const; |
1030 inline TBool IsQueueEmpty() const; |
907 |
1031 |
908 |
1032 |
909 /** Returns a PSL-specific value which uniquely identifies this channel - |
1033 /** Returns a PSL-specific value which uniquely identifies this channel - |
910 it is used for debug tracing by the PIL. |
1034 it is used for debug tracing by the PIL. |
911 |
1035 |
912 @return PSL-specific value which uniquely identifies this channel. |
1036 @return PSL-specific value which uniquely identifies this channel. |
913 */ |
1037 |
|
1038 @released |
|
1039 */ |
914 inline TUint32 PslId() const; |
1040 inline TUint32 PslId() const; |
915 |
1041 |
916 |
1042 |
917 /** Called by a test harness to force an error when the next fragment is |
1043 /** Called by a test harness to force an error when the next fragment is |
918 transferred. |
1044 transferred. |
919 |
1045 |
920 @param aFragmentCount The number of consecutive fragments to fail |
1046 @param aFragmentCount The number of consecutive fragments to fail |
921 */ |
1047 |
|
1048 @released |
|
1049 */ |
922 IMPORT_C TInt FailNext(TInt aFragmentCount); |
1050 IMPORT_C TInt FailNext(TInt aFragmentCount); |
923 |
1051 |
924 |
1052 |
925 /** Called by a test harness to force the DMA controller to miss one or |
1053 /** Called by a test harness to force the DMA controller to miss one or |
926 more interrupts. |
1054 more interrupts. |
927 |
1055 |
928 @param aInterruptCount The number of consecutive interrupts to miss |
1056 @param aInterruptCount The number of consecutive interrupts to miss |
929 */ |
1057 |
|
1058 @released |
|
1059 */ |
930 IMPORT_C TInt MissNextInterrupts(TInt aInterruptCount); |
1060 IMPORT_C TInt MissNextInterrupts(TInt aInterruptCount); |
931 |
1061 |
932 |
1062 |
933 /** Function allowing platform-specific layer to extend channel API with |
1063 /** Function allowing platform-specific layer to extend channel API with |
934 new channel-specific operations. |
1064 new channel-specific operations. |
935 |
1065 |
936 @param aCmd Command identifier. Negative values are reserved for use by |
1066 @param aCmd Command identifier. |
937 Nokia. |
|
938 @param aArg PSL-specific argument |
1067 @param aArg PSL-specific argument |
939 |
1068 |
940 @return KErrNotSupported if aCmd is not supported. PSL-specific value |
1069 @return KErrNotSupported if aCmd is not supported. PSL-specific value |
941 otherwise. |
1070 otherwise. |
942 */ |
1071 |
|
1072 @released |
|
1073 */ |
943 IMPORT_C TInt Extension(TInt aCmd, TAny* aArg); |
1074 IMPORT_C TInt Extension(TInt aCmd, TAny* aArg); |
944 |
1075 |
945 |
1076 |
946 /** This is a function that allows the Platform Specific Layer (PSL) to |
1077 /** This is a function that allows the Platform Specific Layer (PSL) to |
947 extend the DMA API with new channel-independent operations. |
1078 extend the DMA API with new channel-independent operations. |
948 |
1079 |
949 @param aCmd Command identifier. Negative values are reserved for |
1080 @param aCmd Command identifier. |
950 Symbian use. |
|
951 @param aArg PSL-specific. |
1081 @param aArg PSL-specific. |
952 |
1082 |
953 @return KErrNotSupported if aCmd is not supported; a PSL specific value |
1083 @return KErrNotSupported if aCmd is not supported; a PSL specific value |
954 otherwise. |
1084 otherwise. |
|
1085 |
|
1086 @released |
955 */ |
1087 */ |
956 IMPORT_C TInt StaticExtension(TInt aCmd, TAny* aArg); |
1088 IMPORT_C TInt StaticExtension(TInt aCmd, TAny* aArg); |
957 |
1089 |
958 |
1090 |
959 /** @deprecated |
1091 /** @see DmacCaps() |
960 @see DmacCaps() |
1092 |
961 */ |
1093 @deprecated |
|
1094 */ |
962 inline const TDmac* Controller() const; |
1095 inline const TDmac* Controller() const; |
963 |
1096 |
964 /** @deprecated |
1097 /** @see MaxTransferLength() |
965 @see MaxTransferLength() |
1098 |
966 */ |
1099 @deprecated |
|
1100 */ |
967 inline TInt MaxTransferSize(TUint aFlags, TUint32 aPslInfo); |
1101 inline TInt MaxTransferSize(TUint aFlags, TUint32 aPslInfo); |
968 |
1102 |
969 /** @deprecated |
1103 /** @see AddressAlignMask() |
970 @see AddressAlignMask() |
1104 |
971 */ |
1105 @deprecated |
|
1106 */ |
972 inline TUint MemAlignMask(TUint aFlags, TUint32 aPslInfo); |
1107 inline TUint MemAlignMask(TUint aFlags, TUint32 aPslInfo); |
973 |
1108 |
974 protected: |
1109 protected: |
975 // Interface with state machines |
1110 // Interface with state machines |
|
1111 |
|
1112 /** Constructor. |
|
1113 |
|
1114 @released |
|
1115 */ |
976 TDmaChannel(); |
1116 TDmaChannel(); |
977 |
1117 |
978 /** Called by the PIL when adding a new request to the channel's queue. |
1118 /** Called by the PIL when adding a new request to the channel's queue. |
979 The implementation should update the channel's state as appropriate |
1119 The implementation should update the channel's state as appropriate |
980 and begin transfer of aReq if possible. |
1120 and begin transfer of aReq if possible. |
981 |
1121 |
982 @param aReq The request which has been added to the queue |
1122 @param aReq The request which has been added to the queue |
|
1123 |
|
1124 @released |
983 */ |
1125 */ |
984 virtual void DoQueue(const DDmaRequest& aReq); |
1126 virtual void DoQueue(const DDmaRequest& aReq); |
985 |
1127 |
986 /** Called by the PIL in response to a CancelAll call. It should update |
1128 /** Called by the PIL in response to a CancelAll call. It should update |
987 the channel state appropriately. |
1129 the channel state appropriately. |
|
1130 |
|
1131 @released |
988 */ |
1132 */ |
989 virtual void DoCancelAll() = 0; |
1133 virtual void DoCancelAll() = 0; |
990 |
1134 |
991 /** This is called by the PIL when a DDmaRequest is removed from the |
1135 /** This is called by the PIL when a DDmaRequest is removed from the |
992 channel's queue. In general the implementation simply needs to unlink |
1136 channel's queue. In general the implementation simply needs to unlink |
1078 TBool iDynChannel; // this is a dynamically allocated channel |
1228 TBool iDynChannel; // this is a dynamically allocated channel |
1079 TUint iPriority; // hardware priority of this channel |
1229 TUint iPriority; // hardware priority of this channel |
1080 NFastMutex iLock; // for data accessed in both client & DFC context |
1230 NFastMutex iLock; // for data accessed in both client & DFC context |
1081 SDmaDesHdr* iCurHdr; // fragment being transferred or NULL |
1231 SDmaDesHdr* iCurHdr; // fragment being transferred or NULL |
1082 SDmaDesHdr** iNullPtr; // Pointer to NULL pointer following last fragment |
1232 SDmaDesHdr** iNullPtr; // Pointer to NULL pointer following last fragment |
1083 TDfc iDfc; // transfer completion/failure DFC |
1233 TDfc iDfc; // transfer completion/failure DFC |
1084 TInt iMaxDesCount; // maximum number of allocable descriptors |
1234 TInt iMaxDesCount; // maximum number of allocable descriptors |
1085 TInt iAvailDesCount; // available number of descriptors |
1235 TInt iAvailDesCount; // available number of descriptors |
1086 volatile TUint32 iIsrDfc; // Interface between ISR and DFC: |
1236 volatile TUint32 iIsrDfc; // Interface between ISR and DFC: |
1087 enum {KErrorFlagMask = 0x80000000}; // bit 31 - error flag |
1237 enum {KErrorFlagMask = 0x80000000}; // bit 31 - error flag |
1088 enum {KCancelFlagMask = 0x40000000}; // bit 30 - cancel flag |
1238 enum {KCancelFlagMask = 0x40000000}; // bit 30 - cancel flag |
1089 enum {KDfcCountMask = 0x3FFFFFFF}; // bits 0-29 - number of queued DFCs |
1239 enum {KDfcCountMask = 0x3FFFFFFF}; // bits 0-29 - number of queued DFCs |
1090 SDblQue iReqQ; // being/about to be transferred request queue |
1240 SDblQue iReqQ; // being/about to be transferred request queue |
1091 TInt iReqCount; // number of requests attached to this channel |
1241 TInt iReqCount; // number of requests attached to this channel |
1092 TInt iQueuedRequests; // number of requests currently queued on this channel |
1242 TInt iQueuedRequests; // number of requests currently queued on this channel |
|
1243 |
1093 private: |
1244 private: |
1094 TDmaCancelInfo* iCancelInfo; // ... |
1245 TDmaCancelInfo* iCancelInfo; // ... |
1095 TBool iRedoRequest; // client ISR callback wants a redo of request |
1246 TBool iRedoRequest; // client ISR callback wants a redo of request |
1096 TBool iIsrCbRequest; // request on queue using ISR callback |
1247 TBool iIsrCbRequest; // request on queue using ISR callback |
1097 |
1248 |
1098 __DMA_DECLARE_INVARIANT |
1249 __DMA_DECLARE_INVARIANT |
1099 }; |
1250 }; |
1100 |
1251 |
1101 |
1252 |
1102 ////////////////////////////////////////////////////////////////////////////// |
1253 ////////////////////////////////////////////////////////////////////////////// |
1103 // INTERFACE WITH TEST HARNESS |
1254 // INTERFACE WITH TEST HARNESS |
1104 ////////////////////////////////////////////////////////////////////////////// |
1255 ////////////////////////////////////////////////////////////////////////////// |
1105 |
1256 |
1106 /** Set of information used by test harness. |
|
1107 |
|
1108 @publishedPartner |
|
1109 @released |
|
1110 */ |
|
1111 struct TDmaTestInfo |
|
1112 { |
|
1113 /** Maximum transfer size in bytes for all channels (ie. the minimum of all channels' maximum size)*/ |
|
1114 TUint iMaxTransferSize; |
|
1115 /** 3->Memory buffers must be 4-byte aligned, 7->8-byte aligned, ... */ |
|
1116 TUint iMemAlignMask; |
|
1117 /** Cookie to pass to DDmaRequest::Fragment for memory-memory transfer*/ |
|
1118 TUint32 iMemMemPslInfo; |
|
1119 /** Number of test single-buffer channels */ |
|
1120 TInt iMaxSbChannels; |
|
1121 /** Pointer to array containing single-buffer test channel ids */ |
|
1122 TUint32* iSbChannels; |
|
1123 /** Number of test double-buffer channels */ |
|
1124 TInt iMaxDbChannels; |
|
1125 /** Pointer to array containing double-buffer test channel ids */ |
|
1126 TUint32* iDbChannels; |
|
1127 /** Number of test scatter-gather channels */ |
|
1128 TInt iMaxSgChannels; |
|
1129 /** Pointer to array containing scatter-gather test channel ids */ |
|
1130 TUint32* iSgChannels; |
|
1131 }; |
|
1132 |
|
1133 |
|
1134 /** Provides access to test information structure stored in the PSL. |
1257 /** Provides access to test information structure stored in the PSL. |
1135 |
1258 |
1136 Must be implemented by the PSL. |
1259 Must be implemented by the PSL (v1). |
1137 |
1260 |
1138 @publishedPartner |
1261 @deprecated |
1139 @released |
|
1140 */ |
1262 */ |
1141 IMPORT_C const TDmaTestInfo& DmaTestInfo(); |
1263 IMPORT_C const TDmaTestInfo& DmaTestInfo(); |
1142 |
1264 |
|
1265 |
1143 /** Provides access to test information structure stored in the PSL. |
1266 /** Provides access to test information structure stored in the PSL. |
1144 |
1267 |
1145 Must be implemented by the PSL. |
1268 Must be implemented by the PSL (v2). |
1146 |
1269 |
1147 @publishedPartner |
|
1148 @released |
1270 @released |
1149 */ |
1271 */ |
1150 IMPORT_C const TDmaV2TestInfo& DmaTestInfoV2(); |
1272 IMPORT_C const TDmaV2TestInfo& DmaTestInfoV2(); |
1151 |
1273 |
1152 |
1274 |
1153 |
|
1154 ////////////////////////////////////////////////////////////////////////////// |
1275 ////////////////////////////////////////////////////////////////////////////// |
1155 |
1276 |
1156 |
1277 |
1157 #include <drivers/dma_compat.inl> |
1278 #include <drivers/dma_compat.inl> |
1158 #include <drivers/dma_v2.inl> |
1279 #include <drivers/dma_v2.inl> |