|
1 /* Cypress West Bridge API header file (cyasdma.h) |
|
2 ## =========================== |
|
3 ## |
|
4 ## Copyright Cypress Semiconductor Corporation, 2006-2009, |
|
5 ## All Rights Reserved |
|
6 ## UNPUBLISHED, LICENSED SOFTWARE. |
|
7 ## |
|
8 ## CONFIDENTIAL AND PROPRIETARY INFORMATION |
|
9 ## WHICH IS THE PROPERTY OF CYPRESS. |
|
10 ## |
|
11 ## Use of this file is governed |
|
12 ## by the license agreement included in the file |
|
13 ## |
|
14 ## <install>/license/license.txt |
|
15 ## |
|
16 ## where <install> is the Cypress software |
|
17 ## installation root directory path. |
|
18 ## |
|
19 ## =========================== |
|
20 */ |
|
21 |
|
22 #ifndef _INCLUDED_CYASDMA_H_ |
|
23 #define _INCLUDED_CYASDMA_H_ |
|
24 |
|
25 #include "cyashal.h" |
|
26 #include "cyasdevice.h" |
|
27 |
|
28 #include "cyas_cplus_start.h" |
|
29 |
|
30 |
|
31 /*@@DMA Overview |
|
32 This module manages the DMA operations to/from the West Bridge device. The |
|
33 DMA module maintains a DMA queue for each endpoint so multiple DMA requests |
|
34 may be queued and they will complete at some future time. |
|
35 |
|
36 The DMA module must be started before it can be used. It is started by |
|
37 calling CyAsDmaStart(). This function intializes all of the endpoint |
|
38 data structures. |
|
39 |
|
40 In order to perform DMA on a particular endpoint, the endpoint must be |
|
41 enabled by calling CyAsDmaEnableEndPoint(). In addition to enabling or |
|
42 disabling the endpoint, this function also sets the direction for a |
|
43 given endpoint. Direction is given in USB terms. For P port to West Bridge |
|
44 traffic, the endpoint is a CyAsDirectionIn endpoint. For West Bridge to P |
|
45 port traffic, the endpoint is a CyAsDirectionOut endpoint. |
|
46 |
|
47 Once DMA is started and an endpoint is enabled, DMA requests are issued by |
|
48 calling CyAsDmaQueueRequest(). This function queue either a DMA read or |
|
49 DMA write request. The callback associated with the request is called once |
|
50 the request has been fulfilled. |
|
51 |
|
52 See Also |
|
53 * CyAsDmaStart |
|
54 * CyAsDmaEnableEndPoint |
|
55 * CyAsDmaDirection |
|
56 * CyAsDmaQueueRequest |
|
57 */ |
|
58 |
|
59 /***************************************************************************** |
|
60 * West Bridge Constants |
|
61 ****************************************************************************/ |
|
62 #define CY_AS_DMA_MAX_SIZE_HW_SIZE (0xffffffff) |
|
63 |
|
64 /***************************************************************************** |
|
65 * West Bridge Data Structures |
|
66 ****************************************************************************/ |
|
67 |
|
68 /* Summary |
|
69 This type specifies the direction of an endpoint to the CyAsDmaEnableEndPoint function. |
|
70 |
|
71 Description |
|
72 When an endpoint is enabled, the direction of the endpoint can also be set. |
|
73 This type is used to specify the endpoint type. Note that the direction is specified in |
|
74 USB terms. Therefore, if the DMA is from the P port to West Bridge, the direction is IN. |
|
75 |
|
76 See Also |
|
77 * CyAsDmaEnableEndPoint |
|
78 */ |
|
79 typedef enum CyAsDmaDirection |
|
80 { |
|
81 CyAsDirectionIn = 0, /* Set the endpoint to type IN (P -> West Bridge) */ |
|
82 CyAsDirectionOut = 1, /* Set the endpoint to type OUT (West Bridge -> P) */ |
|
83 CyAsDirectionInOut = 2, /* Only valid for EP 0 */ |
|
84 CyAsDirectionDontChange = 3 /* Do no change the endpoint type */ |
|
85 } CyAsDmaDirection ; |
|
86 |
|
87 /***************************************************************************** |
|
88 * West Bridge Functions |
|
89 ****************************************************************************/ |
|
90 |
|
91 /* Summary |
|
92 Initialize the DMA module and ready the module for receiving data |
|
93 |
|
94 Description |
|
95 This function initializes the DMA module by initializing all of the endpoint data |
|
96 structures associated with the device given. This function also register a DMA |
|
97 complete callback with the HAL DMA code. This callback is called whenever the |
|
98 HAL DMA subsystem completes a requested DMA operation. |
|
99 |
|
100 Returns |
|
101 CY_AS_ERROR_SUCCESS - the module initialized sucessfully |
|
102 CY_AS_ERROR_OUT_OF_MEMORY - memory allocation failed during initialization |
|
103 CY_AS_ERROR_ALREADY_RUNNING - the DMA module was already running |
|
104 |
|
105 See Also |
|
106 * CyAsDmaStop |
|
107 */ |
|
108 extern CyAsReturnStatus_t |
|
109 CyAsDmaStart( |
|
110 CyAsDevice * dev_p /* The device to start */ |
|
111 ) ; |
|
112 |
|
113 /* Summary |
|
114 Shutdown the DMA module |
|
115 |
|
116 Description |
|
117 This function shuts down the DMA module for this device by canceling any DMA requests |
|
118 associated with each endpoint and then freeing the resources associated with each DMA |
|
119 endpoint. |
|
120 |
|
121 Returns |
|
122 CY_AS_ERROR_SUCCESS - the module shutdown sucessfully |
|
123 CY_AS_ERROR_NOT_RUNNING - the DMA module was not running |
|
124 |
|
125 See Also |
|
126 * CyAsDmaStart |
|
127 * CyAsDmaCancel |
|
128 */ |
|
129 extern CyAsReturnStatus_t |
|
130 CyAsDmaStop( |
|
131 CyAsDevice * dev_p /* The device to stop */ |
|
132 ) ; |
|
133 |
|
134 /* Summary |
|
135 This function cancels all outstanding DMA requests on a given endpoint |
|
136 |
|
137 Description |
|
138 This function cancels any DMA requests outstanding on a given endpoint by |
|
139 disabling the transfer of DMA requests from the queue to the HAL layer and |
|
140 then removing any pending DMA requests from the queue. The callback associated |
|
141 with any DMA requests that are being removed is called with an error code of |
|
142 CY_AS_ERROR_CANCELED. |
|
143 |
|
144 Notes |
|
145 If a request has already been sent to the HAL layer it will be completed and |
|
146 not canceled. Only requests that have not been sent to the HAL layer will be |
|
147 canceled. |
|
148 |
|
149 Returns |
|
150 CY_AS_ERROR_SUCCESS - the traffic on the endpoint is canceled sucessfully |
|
151 |
|
152 See Also |
|
153 */ |
|
154 extern CyAsReturnStatus_t |
|
155 CyAsDmaCancel( |
|
156 CyAsDevice * dev_p, /* The device of interest */ |
|
157 CyAsEndPointNumber_t ep, /* The endpoint to cancel */ |
|
158 CyAsReturnStatus_t err |
|
159 ) ; |
|
160 |
|
161 /* Summary |
|
162 This function enables a single endpoint for DMA operations |
|
163 |
|
164 Description |
|
165 In order to enable the queuing of DMA requests on a given endpoint, the endpoint |
|
166 must be enabled for DMA. This function enables a given endpoint. In addition, this |
|
167 function sets the direction of the DMA operation. |
|
168 |
|
169 Returns |
|
170 * CY_AS_ERROR_INVALID_ENDPOINT - invalid endpoint number |
|
171 * CY_AS_ERROR_SUCCESS - endpoint was enabled or disabled successfully |
|
172 |
|
173 See Also |
|
174 * CyAsDmaQueueRequest |
|
175 */ |
|
176 extern CyAsReturnStatus_t |
|
177 CyAsDmaEnableEndPoint( |
|
178 CyAsDevice * dev_p, /* The device of interest */ |
|
179 CyAsEndPointNumber_t ep, /* The endpoint to enable or disable */ |
|
180 CyBool enable, /* CyTrue to enable, CyFalse to disable */ |
|
181 CyAsDmaDirection dir /* The direction of the endpoint */ |
|
182 ) ; |
|
183 |
|
184 /* Summary |
|
185 This function queue a DMA request for a given endpoint |
|
186 |
|
187 Description |
|
188 When an West Bridge API module wishes to do a DMA operation, this function is called on the |
|
189 associated endpoint to queue a DMA request. When the DMA request has been fulfilled, the |
|
190 callback associated with the DMA operation is called. |
|
191 |
|
192 Notes |
|
193 The buffer associated with the DMA request, must remain valid until after the callback |
|
194 function is calld. |
|
195 |
|
196 Returns |
|
197 * CY_AS_ERROR_SUCCESS - the DMA operation was queued successfully |
|
198 * CY_AS_ERROR_INVALID_ENDPOINT - the endpoint number was invalid |
|
199 * CY_AS_ERROR_ENDPOINT_DISABLED - the endpoint was disabled |
|
200 * CY_AS_ERROR_OUT_OF_MEMORY - out of memory processing the request |
|
201 |
|
202 See Also |
|
203 * CyAsDmaEnableEndPoint |
|
204 * CyAsDmaCancel |
|
205 */ |
|
206 extern CyAsReturnStatus_t |
|
207 CyAsDmaQueueRequest( |
|
208 CyAsDevice * dev_p, /* The device of interest */ |
|
209 CyAsEndPointNumber_t ep, /* The endpoint to receive a new request */ |
|
210 void * mem_p, /* The memory buffer for the DMA request - must be valid until after the callback has been called */ |
|
211 uint32_t size, /* The size of the DMA request in bytes */ |
|
212 CyBool packet, /* If true and a DMA read request, return the next packet regardless of size */ |
|
213 CyBool readreq, /* If true, this is a read request, otherwise it is a write request */ |
|
214 CyAsDmaCallback cb /* The callback to call when the DMA request is complete, either successfully or via an error */ |
|
215 ) ; |
|
216 |
|
217 /* Summary |
|
218 This function waits until all DMA requests on a given endpoint have been processed and then return |
|
219 |
|
220 Description |
|
221 There are times when a module in the West Bridge API needs to wait until the DMA operations have been |
|
222 queued. This function sleeps until all DMA requests have been fulfilled and only then returns to the caller. |
|
223 |
|
224 Notes |
|
225 I don't think we will need a list of sleeping clients to support multiple parallel client modules |
|
226 sleeping on a single endpoint, but if we do instead of having a single sleep channel in the endpoint, each |
|
227 client will have to supply a sleep channel and we will have to maintain a list of sleep channels to wake. |
|
228 |
|
229 Returns |
|
230 * CY_AS_ERROR_SUCCESS - the queue has drained sucessfully |
|
231 * CY_AS_ERROR_INVALID_ENDPOINT - the endpoint given is not valid |
|
232 * CY_AS_ERROR_NESTED_SLEEP - CyAsDmaQueueRequest() was requested on an endpoint where CyAsDmaQueueRequest was already called |
|
233 */ |
|
234 extern CyAsReturnStatus_t |
|
235 CyAsDmaDrainQueue( |
|
236 CyAsDevice * dev_p, /* The device of interest */ |
|
237 CyAsEndPointNumber_t ep, /* The endpoint to drain */ |
|
238 CyBool kickstart /* If CyTrue, call kickstart to start the DMA process, |
|
239 If CyFalse, West Bridge will start the DMA process */ |
|
240 ) ; |
|
241 |
|
242 /* Summary |
|
243 Sets the maximum amount of data West Bridge can accept in a single DMA Operation for the given endpoint |
|
244 |
|
245 Description |
|
246 Depending on the configuration of the West Bridge device endpoint, the amount of data that can be |
|
247 accepted varies. This function sets the maximum amount of data West Bridge can accept in a single |
|
248 DMA operation. The value is stored with the endpoint and passed to the HAL layer in the |
|
249 CyAsHalDmaSetupWrite() and CyAsHalDmaSetupRead() functoins. |
|
250 |
|
251 Returns |
|
252 * CY_AS_ERROR_SUCCESS - the value was set sucessfully |
|
253 * CY_AS_ERROR_INVALID_SIZE - the size value was not valid |
|
254 */ |
|
255 extern CyAsReturnStatus_t |
|
256 CyAsDmaSetMaxDmaSize( |
|
257 CyAsDevice * dev_p, /* The device of interest */ |
|
258 CyAsEndPointNumber_t ep, /* The endpoint to change */ |
|
259 uint32_t size /* The max size of this endpoint in bytes */ |
|
260 ) ; |
|
261 |
|
262 /* Summary |
|
263 This function starts the DMA process on a given channel. |
|
264 |
|
265 Description |
|
266 When transferring data from the P port processor to West Bridge, the DMA operation must be initiated |
|
267 P Port software for the first transfer. Subsequent transferrs will be handled at the interrupt level. |
|
268 |
|
269 Returns |
|
270 * CY_AS_ERROR_SUCCESS |
|
271 */ |
|
272 extern CyAsReturnStatus_t |
|
273 CyAsDmaKickStart( |
|
274 CyAsDevice * dev_p, /* The device of interest */ |
|
275 CyAsEndPointNumber_t ep /* The endpoint to change */ |
|
276 ) ; |
|
277 |
|
278 /* Summary |
|
279 This function receives endpoint data from a request. |
|
280 |
|
281 Description |
|
282 For endpoint 0 and 1 the endpoint data is transferred from the West Bridge device to the DMA via a lowlevel |
|
283 requests (via the mailbox registers). |
|
284 |
|
285 Returns |
|
286 * CY_AS_ERROR_SUCCESS |
|
287 */ |
|
288 extern CyAsReturnStatus_t |
|
289 CyAsDmaReceivedData( |
|
290 CyAsDevice * dev_p, /* The device of interest */ |
|
291 CyAsEndPointNumber_t ep, /* The endpoint that received data */ |
|
292 uint32_t dsize, /* The data size */ |
|
293 void * data /* The data buffer */ |
|
294 ); |
|
295 |
|
296 /* Summary |
|
297 This function is called when the DMA operation on an endpoint has been completed. |
|
298 |
|
299 Returns |
|
300 * void |
|
301 */ |
|
302 extern void |
|
303 CyAsDmaCompletedCallback ( |
|
304 CyAsHalDeviceTag tag, /* Tag to HAL completing the DMA operation. */ |
|
305 CyAsEndPointNumber_t ep, /* Endpoint on which DMA has been completed. */ |
|
306 uint32_t length, /* Length of data received. */ |
|
307 CyAsReturnStatus_t status /* Status of DMA operation. */ |
|
308 ) ; |
|
309 |
|
310 #include "cyas_cplus_end.h" |
|
311 |
|
312 #endif /* _INCLUDED_CYASDMA_H_ */ |