]>
Commit | Line | Data |
---|---|---|
81eb669b DC |
1 | /* Cypress West Bridge API header file (cyasdma.h) |
2 | ## =========================== | |
3 | ## Copyright (C) 2010 Cypress Semiconductor | |
4 | ## | |
5 | ## This program is free software; you can redistribute it and/or | |
6 | ## modify it under the terms of the GNU General Public License | |
7 | ## as published by the Free Software Foundation; either version 2 | |
8 | ## of the License, or (at your option) any later version. | |
9 | ## | |
10 | ## This program is distributed in the hope that it will be useful, | |
11 | ## but WITHOUT ANY WARRANTY; without even the implied warranty of | |
12 | ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
13 | ## GNU General Public License for more details. | |
14 | ## | |
15 | ## You should have received a copy of the GNU General Public License | |
16 | ## along with this program; if not, write to the Free Software | |
17 | ## Foundation, Inc., 51 Franklin Street | |
18 | ## Fifth Floor, Boston, MA 02110-1301, USA. | |
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 | |
33 | device. The DMA module maintains a DMA queue for each endpoint | |
34 | so multiple DMA requests may be queued and they will complete | |
35 | at some future time. | |
36 | ||
37 | The DMA module must be started before it can be used. It is | |
d9fed669 | 38 | started by calling CyAsDmaStart(). This function initializes |
81eb669b DC |
39 | all of the endpoint data structures. |
40 | ||
41 | In order to perform DMA on a particular endpoint, the endpoint | |
42 | must be enabled by calling CyAsDmaEnableEndPoint(). In addition | |
43 | to enabling or disabling the endpoint, this function also sets | |
44 | the direction for a given endpoint. Direction is given in USB | |
45 | terms. For P port to West Bridge traffic, the endpoint is a | |
46 | CyAsDirectionIn endpoint. For West Bridge to P port traffic, | |
47 | the endpoint is a CyAsDirectionOut endpoint. | |
48 | ||
49 | Once DMA is started and an endpoint is enabled, DMA requests | |
50 | are issued by calling CyAsDmaQueueRequest(). This function | |
51 | queue either a DMA read or DMA write request. The callback | |
52 | associated with the request is called once the request has been | |
53 | fulfilled. | |
54 | ||
55 | See Also | |
56 | * CyAsDmaStart | |
57 | * CyAsDmaEnableEndPoint | |
58 | * CyAsDmaDirection | |
59 | * CyAsDmaQueueRequest | |
60 | */ | |
61 | ||
62 | /************************ | |
63 | * West Bridge Constants | |
64 | ************************/ | |
65 | #define CY_AS_DMA_MAX_SIZE_HW_SIZE (0xffffffff) | |
66 | ||
67 | /************************ | |
68 | * West Bridge Data Structures | |
69 | ************************/ | |
70 | ||
71 | /* Summary | |
72 | This type specifies the direction of an endpoint to the | |
73 | CyAsDmaEnableEndPoint function. | |
74 | ||
75 | Description | |
76 | When an endpoint is enabled, the direction of the endpoint | |
77 | can also be set. This type is used to specify the endpoint | |
78 | type. Note that the direction is specified in USB terms. | |
79 | Therefore, if the DMA is from the P port to West Bridge, | |
80 | the direction is IN. | |
81 | ||
82 | See Also | |
83 | * CyAsDmaEnableEndPoint | |
84 | */ | |
85 | typedef enum cy_as_dma_direction { | |
86 | /* Set the endpoint to type IN (P -> West Bridge) */ | |
87 | cy_as_direction_in = 0, | |
88 | /* Set the endpoint to type OUT (West Bridge -> P) */ | |
89 | cy_as_direction_out = 1, | |
90 | /* Only valid for EP 0 */ | |
91 | cy_as_direction_in_out = 2, | |
92 | /* Do no change the endpoint type */ | |
93 | cy_as_direction_dont_change = 3 | |
0769c38d | 94 | } cy_as_dma_direction; |
81eb669b DC |
95 | |
96 | /********************************* | |
97 | * West Bridge Functions | |
98 | *********************************/ | |
99 | ||
100 | /* Summary | |
101 | Initialize the DMA module and ready the module for receiving data | |
102 | ||
103 | Description | |
104 | This function initializes the DMA module by initializing all of | |
105 | the endpoint data structures associated with the device given. | |
106 | This function also register a DMA complete callback with the HAL | |
107 | DMA code. This callback is called whenever the HAL DMA subsystem | |
108 | completes a requested DMA operation. | |
109 | ||
110 | Returns | |
25985edc | 111 | CY_AS_ERROR_SUCCESS - the module initialized successfully |
81eb669b DC |
112 | CY_AS_ERROR_OUT_OF_MEMORY - memory allocation failed during |
113 | initialization | |
114 | CY_AS_ERROR_ALREADY_RUNNING - the DMA module was already running | |
115 | ||
116 | See Also | |
117 | * CyAsDmaStop | |
118 | */ | |
119 | extern cy_as_return_status_t | |
120 | cy_as_dma_start( | |
121 | /* The device to start */ | |
122 | cy_as_device *dev_p | |
0769c38d | 123 | ); |
81eb669b DC |
124 | |
125 | /* Summary | |
126 | Shutdown the DMA module | |
127 | ||
128 | Description | |
129 | This function shuts down the DMA module for this device by | |
130 | canceling any DMA requests associated with each endpoint and | |
131 | then freeing the resources associated with each DMA endpoint. | |
132 | ||
133 | Returns | |
25985edc | 134 | CY_AS_ERROR_SUCCESS - the module shutdown successfully |
81eb669b DC |
135 | CY_AS_ERROR_NOT_RUNNING - the DMA module was not running |
136 | ||
137 | See Also | |
138 | * CyAsDmaStart | |
139 | * CyAsDmaCancel | |
140 | */ | |
141 | extern cy_as_return_status_t | |
142 | cy_as_dma_stop( | |
143 | /* The device to stop */ | |
144 | cy_as_device *dev_p | |
0769c38d | 145 | ); |
81eb669b DC |
146 | |
147 | /* Summary | |
148 | This function cancels all outstanding DMA requests on a given endpoint | |
149 | ||
150 | Description | |
151 | This function cancels any DMA requests outstanding on a given endpoint | |
152 | by disabling the transfer of DMA requests from the queue to the HAL | |
153 | layer and then removing any pending DMA requests from the queue. The | |
154 | callback associated with any DMA requests that are being removed is | |
155 | called with an error code of CY_AS_ERROR_CANCELED. | |
156 | ||
157 | Notes | |
158 | If a request has already been sent to the HAL layer it will be | |
159 | completed and not canceled. Only requests that have not been sent to | |
160 | the HAL layer will be cancelled. | |
161 | ||
162 | Returns | |
163 | CY_AS_ERROR_SUCCESS - the traffic on the endpoint is canceled | |
25985edc | 164 | successfully |
81eb669b DC |
165 | |
166 | See Also | |
167 | */ | |
168 | extern cy_as_return_status_t | |
169 | cy_as_dma_cancel( | |
170 | /* The device of interest */ | |
171 | cy_as_device *dev_p, | |
172 | /* The endpoint to cancel */ | |
173 | cy_as_end_point_number_t ep, | |
174 | cy_as_return_status_t err | |
0769c38d | 175 | ); |
81eb669b DC |
176 | |
177 | /* Summary | |
178 | This function enables a single endpoint for DMA operations | |
179 | ||
180 | Description | |
181 | In order to enable the queuing of DMA requests on a given | |
182 | endpoint, the endpoint must be enabled for DMA. This function | |
183 | enables a given endpoint. In addition, this function sets the | |
184 | direction of the DMA operation. | |
185 | ||
186 | Returns | |
187 | * CY_AS_ERROR_INVALID_ENDPOINT - invalid endpoint number | |
188 | * CY_AS_ERROR_SUCCESS - endpoint was enabled or disabled | |
189 | * successfully | |
190 | ||
191 | See Also | |
192 | * CyAsDmaQueueRequest | |
193 | */ | |
194 | extern cy_as_return_status_t | |
195 | cy_as_dma_enable_end_point( | |
196 | /* The device of interest */ | |
197 | cy_as_device *dev_p, | |
198 | /* The endpoint to enable or disable */ | |
199 | cy_as_end_point_number_t ep, | |
200 | /* CyTrue to enable, CyFalse to disable */ | |
201 | cy_bool enable, | |
202 | /* The direction of the endpoint */ | |
203 | cy_as_dma_direction dir | |
0769c38d | 204 | ); |
81eb669b DC |
205 | |
206 | /* Summary | |
207 | This function queue a DMA request for a given endpoint | |
208 | ||
209 | Description | |
210 | When an West Bridge API module wishes to do a DMA operation, | |
211 | this function is called on the associated endpoint to queue | |
212 | a DMA request. When the DMA request has been fulfilled, the | |
213 | callback associated with the DMA operation is called. | |
214 | ||
215 | Notes | |
216 | The buffer associated with the DMA request, must remain valid | |
217 | until after the callback function is calld. | |
218 | ||
219 | Returns | |
220 | * CY_AS_ERROR_SUCCESS - the DMA operation was queued successfully | |
221 | * CY_AS_ERROR_INVALID_ENDPOINT - the endpoint number was invalid | |
222 | * CY_AS_ERROR_ENDPOINT_DISABLED - the endpoint was disabled | |
223 | * CY_AS_ERROR_OUT_OF_MEMORY - out of memory processing the request | |
224 | ||
225 | See Also | |
226 | * CyAsDmaEnableEndPoint | |
227 | * CyAsDmaCancel | |
228 | */ | |
229 | extern cy_as_return_status_t | |
230 | cy_as_dma_queue_request( | |
231 | /* The device of interest */ | |
232 | cy_as_device *dev_p, | |
233 | /* The endpoint to receive a new request */ | |
234 | cy_as_end_point_number_t ep, | |
235 | /* The memory buffer for the DMA request - | |
236 | * must be valid until after the callback has been called */ | |
237 | void *mem_p, | |
238 | /* The size of the DMA request in bytes */ | |
239 | uint32_t size, | |
240 | /* If true and a DMA read request, return the next packet | |
241 | * regardless of size */ | |
242 | cy_bool packet, | |
243 | /* If true, this is a read request, | |
244 | * otherwise it is a write request */ | |
245 | cy_bool readreq, | |
246 | /* The callback to call when the DMA request is complete, | |
247 | * either successfully or via an error */ | |
248 | cy_as_dma_callback cb | |
0769c38d | 249 | ); |
81eb669b DC |
250 | |
251 | /* Summary | |
252 | This function waits until all DMA requests on a given endpoint | |
253 | have been processed and then return | |
254 | ||
255 | Description | |
256 | There are times when a module in the West Bridge API needs to | |
257 | wait until the DMA operations have been queued. This function | |
258 | sleeps until all DMA requests have been fulfilled and only then | |
259 | returns to the caller. | |
260 | ||
261 | Notes | |
262 | I don't think we will need a list of sleeping clients to support | |
263 | multiple parallel client modules sleeping on a single endpoint, | |
264 | but if we do instead of having a single sleep channel in the | |
265 | endpoint, each client will have to supply a sleep channel and we | |
266 | will have to maintain a list of sleep channels to wake. | |
267 | ||
268 | Returns | |
25985edc | 269 | * CY_AS_ERROR_SUCCESS - the queue has drained successfully |
81eb669b DC |
270 | * CY_AS_ERROR_INVALID_ENDPOINT - the endpoint given is not valid |
271 | * CY_AS_ERROR_NESTED_SLEEP - CyAsDmaQueueRequest() was requested | |
272 | * on an endpoint where CyAsDmaQueueRequest was already called | |
273 | */ | |
274 | extern cy_as_return_status_t | |
275 | cy_as_dma_drain_queue( | |
276 | /* The device of interest */ | |
277 | cy_as_device *dev_p, | |
278 | /* The endpoint to drain */ | |
279 | cy_as_end_point_number_t ep, | |
280 | /* If CyTrue, call kickstart to start the DMA process, | |
281 | if cy_false, west bridge will start the DMA process */ | |
282 | cy_bool kickstart | |
0769c38d | 283 | ); |
81eb669b DC |
284 | |
285 | /* Summary | |
286 | Sets the maximum amount of data West Bridge can accept in a single | |
287 | DMA Operation for the given endpoint | |
288 | ||
289 | Description | |
290 | Depending on the configuration of the West Bridge device endpoint, | |
291 | the amount of data that can be accepted varies. This function | |
292 | sets the maximum amount of data West Bridge can accept in a single | |
293 | DMA operation. The value is stored with the endpoint and passed | |
294 | to the HAL layer in the CyAsHalDmaSetupWrite() and | |
295 | CyAsHalDmaSetupRead() functoins. | |
296 | ||
297 | Returns | |
25985edc | 298 | * CY_AS_ERROR_SUCCESS - the value was set successfully |
81eb669b DC |
299 | * CY_AS_ERROR_INVALID_SIZE - the size value was not valid |
300 | */ | |
301 | extern cy_as_return_status_t | |
302 | cy_as_dma_set_max_dma_size( | |
303 | /* The device of interest */ | |
304 | cy_as_device *dev_p, | |
305 | /* The endpoint to change */ | |
306 | cy_as_end_point_number_t ep, | |
307 | /* The max size of this endpoint in bytes */ | |
308 | uint32_t size | |
0769c38d | 309 | ); |
81eb669b DC |
310 | |
311 | /* Summary | |
312 | This function starts the DMA process on a given channel. | |
313 | ||
314 | Description | |
315 | When transferring data from the P port processor to West | |
316 | Bridge, the DMA operation must be initiated P Port software | |
317 | for the first transfer. Subsequent transferrs will be | |
318 | handled at the interrupt level. | |
319 | ||
320 | Returns | |
321 | * CY_AS_ERROR_SUCCESS | |
322 | */ | |
323 | extern cy_as_return_status_t | |
324 | cy_as_dma_kick_start( | |
325 | /* The device of interest */ | |
326 | cy_as_device *dev_p, | |
327 | /* The endpoint to change */ | |
328 | cy_as_end_point_number_t ep | |
0769c38d | 329 | ); |
81eb669b DC |
330 | |
331 | /* Summary | |
332 | This function receives endpoint data from a request. | |
333 | ||
334 | Description | |
335 | For endpoint 0 and 1 the endpoint data is transferred from | |
336 | the West Bridge device to the DMA via a lowlevel | |
337 | requests (via the mailbox registers). | |
338 | ||
339 | Returns | |
340 | * CY_AS_ERROR_SUCCESS | |
341 | */ | |
342 | extern cy_as_return_status_t | |
343 | cy_as_dma_received_data( | |
344 | /* The device of interest */ | |
345 | cy_as_device *dev_p, | |
346 | /* The endpoint that received data */ | |
347 | cy_as_end_point_number_t ep, | |
348 | /* The data size */ | |
349 | uint32_t dsize, | |
350 | /* The data buffer */ | |
351 | void *data | |
352 | ); | |
353 | ||
354 | /* Summary | |
355 | This function is called when the DMA operation on | |
356 | an endpoint has been completed. | |
357 | ||
358 | Returns | |
359 | * void | |
360 | */ | |
361 | extern void | |
362 | cy_as_dma_completed_callback( | |
363 | /* Tag to HAL completing the DMA operation. */ | |
364 | cy_as_hal_device_tag tag, | |
365 | /* Endpoint on which DMA has been completed. */ | |
366 | cy_as_end_point_number_t ep, | |
367 | /* Length of data received. */ | |
368 | uint32_t length, | |
369 | /* Status of DMA operation. */ | |
370 | cy_as_return_status_t status | |
0769c38d | 371 | ); |
81eb669b DC |
372 | |
373 | #include "cyas_cplus_end.h" | |
374 | ||
375 | #endif /* _INCLUDED_CYASDMA_H_ */ |