1 /* Cypress West Bridge API header file (cyasdma.h)
2 ## ===========================
3 ## Copyright (C) 2010 Cypress Semiconductor
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.
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.
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 ## ===========================
22 #ifndef _INCLUDED_CYASDMA_H_
23 #define _INCLUDED_CYASDMA_H_
26 #include "cyasdevice.h"
28 #include "cyas_cplus_start.h"
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
37 The DMA module must be started before it can be used. It is
38 started by calling CyAsDmaStart(). This function initializes
39 all of the endpoint data structures.
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.
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
57 * CyAsDmaEnableEndPoint
62 /************************
63 * West Bridge Constants
64 ************************/
65 #define CY_AS_DMA_MAX_SIZE_HW_SIZE (0xffffffff)
67 /************************
68 * West Bridge Data Structures
69 ************************/
72 This type specifies the direction of an endpoint to the
73 CyAsDmaEnableEndPoint function.
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,
83 * CyAsDmaEnableEndPoint
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
94 } cy_as_dma_direction;
96 /*********************************
97 * West Bridge Functions
98 *********************************/
101 Initialize the DMA module and ready the module for receiving data
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.
111 CY_AS_ERROR_SUCCESS - the module initialized successfully
112 CY_AS_ERROR_OUT_OF_MEMORY - memory allocation failed during
114 CY_AS_ERROR_ALREADY_RUNNING - the DMA module was already running
119 extern cy_as_return_status_t
121 /* The device to start */
126 Shutdown the DMA module
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.
134 CY_AS_ERROR_SUCCESS - the module shutdown successfully
135 CY_AS_ERROR_NOT_RUNNING - the DMA module was not running
141 extern cy_as_return_status_t
143 /* The device to stop */
148 This function cancels all outstanding DMA requests on a given endpoint
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.
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.
163 CY_AS_ERROR_SUCCESS - the traffic on the endpoint is canceled
168 extern cy_as_return_status_t
170 /* The device of interest */
172 /* The endpoint to cancel */
173 cy_as_end_point_number_t ep,
174 cy_as_return_status_t err
178 This function enables a single endpoint for DMA operations
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.
187 * CY_AS_ERROR_INVALID_ENDPOINT - invalid endpoint number
188 * CY_AS_ERROR_SUCCESS - endpoint was enabled or disabled
192 * CyAsDmaQueueRequest
194 extern cy_as_return_status_t
195 cy_as_dma_enable_end_point(
196 /* The device of interest */
198 /* The endpoint to enable or disable */
199 cy_as_end_point_number_t ep,
200 /* CyTrue to enable, CyFalse to disable */
202 /* The direction of the endpoint */
203 cy_as_dma_direction dir
207 This function queue a DMA request for a given endpoint
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.
216 The buffer associated with the DMA request, must remain valid
217 until after the callback function is calld.
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
226 * CyAsDmaEnableEndPoint
229 extern cy_as_return_status_t
230 cy_as_dma_queue_request(
231 /* The device of interest */
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 */
238 /* The size of the DMA request in bytes */
240 /* If true and a DMA read request, return the next packet
241 * regardless of size */
243 /* If true, this is a read request,
244 * otherwise it is a write request */
246 /* The callback to call when the DMA request is complete,
247 * either successfully or via an error */
248 cy_as_dma_callback cb
252 This function waits until all DMA requests on a given endpoint
253 have been processed and then return
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.
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.
269 * CY_AS_ERROR_SUCCESS - the queue has drained successfully
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
274 extern cy_as_return_status_t
275 cy_as_dma_drain_queue(
276 /* The device of interest */
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 */
286 Sets the maximum amount of data West Bridge can accept in a single
287 DMA Operation for the given endpoint
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.
298 * CY_AS_ERROR_SUCCESS - the value was set successfully
299 * CY_AS_ERROR_INVALID_SIZE - the size value was not valid
301 extern cy_as_return_status_t
302 cy_as_dma_set_max_dma_size(
303 /* The device of interest */
305 /* The endpoint to change */
306 cy_as_end_point_number_t ep,
307 /* The max size of this endpoint in bytes */
312 This function starts the DMA process on a given channel.
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.
321 * CY_AS_ERROR_SUCCESS
323 extern cy_as_return_status_t
324 cy_as_dma_kick_start(
325 /* The device of interest */
327 /* The endpoint to change */
328 cy_as_end_point_number_t ep
332 This function receives endpoint data from a request.
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).
340 * CY_AS_ERROR_SUCCESS
342 extern cy_as_return_status_t
343 cy_as_dma_received_data(
344 /* The device of interest */
346 /* The endpoint that received data */
347 cy_as_end_point_number_t ep,
350 /* The data buffer */
355 This function is called when the DMA operation on
356 an endpoint has been completed.
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. */
369 /* Status of DMA operation. */
370 cy_as_return_status_t status
373 #include "cyas_cplus_end.h"
375 #endif /* _INCLUDED_CYASDMA_H_ */