--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/omap3530/beagle_drivers/wb/api/src/cyasdma.h Wed Mar 03 13:10:32 2010 +0000
@@ -0,0 +1,312 @@
+/* Cypress West Bridge API header file (cyasdma.h)
+ ## ===========================
+ ##
+ ## Copyright Cypress Semiconductor Corporation, 2006-2009,
+ ## All Rights Reserved
+ ## UNPUBLISHED, LICENSED SOFTWARE.
+ ##
+ ## CONFIDENTIAL AND PROPRIETARY INFORMATION
+ ## WHICH IS THE PROPERTY OF CYPRESS.
+ ##
+ ## Use of this file is governed
+ ## by the license agreement included in the file
+ ##
+ ## <install>/license/license.txt
+ ##
+ ## where <install> is the Cypress software
+ ## installation root directory path.
+ ##
+ ## ===========================
+*/
+
+#ifndef _INCLUDED_CYASDMA_H_
+#define _INCLUDED_CYASDMA_H_
+
+#include "cyashal.h"
+#include "cyasdevice.h"
+
+#include "cyas_cplus_start.h"
+
+
+/*@@DMA Overview
+ This module manages the DMA operations to/from the West Bridge device. The
+ DMA module maintains a DMA queue for each endpoint so multiple DMA requests
+ may be queued and they will complete at some future time.
+
+ The DMA module must be started before it can be used. It is started by
+ calling CyAsDmaStart(). This function intializes all of the endpoint
+ data structures.
+
+ In order to perform DMA on a particular endpoint, the endpoint must be
+ enabled by calling CyAsDmaEnableEndPoint(). In addition to enabling or
+ disabling the endpoint, this function also sets the direction for a
+ given endpoint. Direction is given in USB terms. For P port to West Bridge
+ traffic, the endpoint is a CyAsDirectionIn endpoint. For West Bridge to P
+ port traffic, the endpoint is a CyAsDirectionOut endpoint.
+
+ Once DMA is started and an endpoint is enabled, DMA requests are issued by
+ calling CyAsDmaQueueRequest(). This function queue either a DMA read or
+ DMA write request. The callback associated with the request is called once
+ the request has been fulfilled.
+
+ See Also
+ * CyAsDmaStart
+ * CyAsDmaEnableEndPoint
+ * CyAsDmaDirection
+ * CyAsDmaQueueRequest
+ */
+
+/*****************************************************************************
+ * West Bridge Constants
+ ****************************************************************************/
+#define CY_AS_DMA_MAX_SIZE_HW_SIZE (0xffffffff)
+
+/*****************************************************************************
+ * West Bridge Data Structures
+ ****************************************************************************/
+
+/* Summary
+ This type specifies the direction of an endpoint to the CyAsDmaEnableEndPoint function.
+
+ Description
+ When an endpoint is enabled, the direction of the endpoint can also be set.
+ This type is used to specify the endpoint type. Note that the direction is specified in
+ USB terms. Therefore, if the DMA is from the P port to West Bridge, the direction is IN.
+
+ See Also
+ * CyAsDmaEnableEndPoint
+*/
+typedef enum CyAsDmaDirection
+{
+ CyAsDirectionIn = 0, /* Set the endpoint to type IN (P -> West Bridge) */
+ CyAsDirectionOut = 1, /* Set the endpoint to type OUT (West Bridge -> P) */
+ CyAsDirectionInOut = 2, /* Only valid for EP 0 */
+ CyAsDirectionDontChange = 3 /* Do no change the endpoint type */
+} CyAsDmaDirection ;
+
+/*****************************************************************************
+ * West Bridge Functions
+ ****************************************************************************/
+
+/* Summary
+ Initialize the DMA module and ready the module for receiving data
+
+ Description
+ This function initializes the DMA module by initializing all of the endpoint data
+ structures associated with the device given. This function also register a DMA
+ complete callback with the HAL DMA code. This callback is called whenever the
+ HAL DMA subsystem completes a requested DMA operation.
+
+ Returns
+ CY_AS_ERROR_SUCCESS - the module initialized sucessfully
+ CY_AS_ERROR_OUT_OF_MEMORY - memory allocation failed during initialization
+ CY_AS_ERROR_ALREADY_RUNNING - the DMA module was already running
+
+ See Also
+ * CyAsDmaStop
+*/
+extern CyAsReturnStatus_t
+CyAsDmaStart(
+ CyAsDevice * dev_p /* The device to start */
+ ) ;
+
+/* Summary
+ Shutdown the DMA module
+
+ Description
+ This function shuts down the DMA module for this device by canceling any DMA requests
+ associated with each endpoint and then freeing the resources associated with each DMA
+ endpoint.
+
+ Returns
+ CY_AS_ERROR_SUCCESS - the module shutdown sucessfully
+ CY_AS_ERROR_NOT_RUNNING - the DMA module was not running
+
+ See Also
+ * CyAsDmaStart
+ * CyAsDmaCancel
+*/
+extern CyAsReturnStatus_t
+CyAsDmaStop(
+ CyAsDevice * dev_p /* The device to stop */
+ ) ;
+
+/* Summary
+ This function cancels all outstanding DMA requests on a given endpoint
+
+ Description
+ This function cancels any DMA requests outstanding on a given endpoint by
+ disabling the transfer of DMA requests from the queue to the HAL layer and
+ then removing any pending DMA requests from the queue. The callback associated
+ with any DMA requests that are being removed is called with an error code of
+ CY_AS_ERROR_CANCELED.
+
+ Notes
+ If a request has already been sent to the HAL layer it will be completed and
+ not canceled. Only requests that have not been sent to the HAL layer will be
+ canceled.
+
+ Returns
+ CY_AS_ERROR_SUCCESS - the traffic on the endpoint is canceled sucessfully
+
+ See Also
+*/
+extern CyAsReturnStatus_t
+CyAsDmaCancel(
+ CyAsDevice * dev_p, /* The device of interest */
+ CyAsEndPointNumber_t ep, /* The endpoint to cancel */
+ CyAsReturnStatus_t err
+ ) ;
+
+/* Summary
+ This function enables a single endpoint for DMA operations
+
+ Description
+ In order to enable the queuing of DMA requests on a given endpoint, the endpoint
+ must be enabled for DMA. This function enables a given endpoint. In addition, this
+ function sets the direction of the DMA operation.
+
+ Returns
+ * CY_AS_ERROR_INVALID_ENDPOINT - invalid endpoint number
+ * CY_AS_ERROR_SUCCESS - endpoint was enabled or disabled successfully
+
+ See Also
+ * CyAsDmaQueueRequest
+*/
+extern CyAsReturnStatus_t
+CyAsDmaEnableEndPoint(
+ CyAsDevice * dev_p, /* The device of interest */
+ CyAsEndPointNumber_t ep, /* The endpoint to enable or disable */
+ CyBool enable, /* CyTrue to enable, CyFalse to disable */
+ CyAsDmaDirection dir /* The direction of the endpoint */
+ ) ;
+
+/* Summary
+ This function queue a DMA request for a given endpoint
+
+ Description
+ When an West Bridge API module wishes to do a DMA operation, this function is called on the
+ associated endpoint to queue a DMA request. When the DMA request has been fulfilled, the
+ callback associated with the DMA operation is called.
+
+ Notes
+ The buffer associated with the DMA request, must remain valid until after the callback
+ function is calld.
+
+ Returns
+ * CY_AS_ERROR_SUCCESS - the DMA operation was queued successfully
+ * CY_AS_ERROR_INVALID_ENDPOINT - the endpoint number was invalid
+ * CY_AS_ERROR_ENDPOINT_DISABLED - the endpoint was disabled
+ * CY_AS_ERROR_OUT_OF_MEMORY - out of memory processing the request
+
+ See Also
+ * CyAsDmaEnableEndPoint
+ * CyAsDmaCancel
+*/
+extern CyAsReturnStatus_t
+CyAsDmaQueueRequest(
+ CyAsDevice * dev_p, /* The device of interest */
+ CyAsEndPointNumber_t ep, /* The endpoint to receive a new request */
+ void * mem_p, /* The memory buffer for the DMA request - must be valid until after the callback has been called */
+ uint32_t size, /* The size of the DMA request in bytes */
+ CyBool packet, /* If true and a DMA read request, return the next packet regardless of size */
+ CyBool readreq, /* If true, this is a read request, otherwise it is a write request */
+ CyAsDmaCallback cb /* The callback to call when the DMA request is complete, either successfully or via an error */
+ ) ;
+
+/* Summary
+ This function waits until all DMA requests on a given endpoint have been processed and then return
+
+ Description
+ There are times when a module in the West Bridge API needs to wait until the DMA operations have been
+ queued. This function sleeps until all DMA requests have been fulfilled and only then returns to the caller.
+
+ Notes
+ I don't think we will need a list of sleeping clients to support multiple parallel client modules
+ sleeping on a single endpoint, but if we do instead of having a single sleep channel in the endpoint, each
+ client will have to supply a sleep channel and we will have to maintain a list of sleep channels to wake.
+
+ Returns
+ * CY_AS_ERROR_SUCCESS - the queue has drained sucessfully
+ * CY_AS_ERROR_INVALID_ENDPOINT - the endpoint given is not valid
+ * CY_AS_ERROR_NESTED_SLEEP - CyAsDmaQueueRequest() was requested on an endpoint where CyAsDmaQueueRequest was already called
+*/
+extern CyAsReturnStatus_t
+CyAsDmaDrainQueue(
+ CyAsDevice * dev_p, /* The device of interest */
+ CyAsEndPointNumber_t ep, /* The endpoint to drain */
+ CyBool kickstart /* If CyTrue, call kickstart to start the DMA process,
+ If CyFalse, West Bridge will start the DMA process */
+ ) ;
+
+/* Summary
+ Sets the maximum amount of data West Bridge can accept in a single DMA Operation for the given endpoint
+
+ Description
+ Depending on the configuration of the West Bridge device endpoint, the amount of data that can be
+ accepted varies. This function sets the maximum amount of data West Bridge can accept in a single
+ DMA operation. The value is stored with the endpoint and passed to the HAL layer in the
+ CyAsHalDmaSetupWrite() and CyAsHalDmaSetupRead() functoins.
+
+ Returns
+ * CY_AS_ERROR_SUCCESS - the value was set sucessfully
+ * CY_AS_ERROR_INVALID_SIZE - the size value was not valid
+*/
+extern CyAsReturnStatus_t
+CyAsDmaSetMaxDmaSize(
+ CyAsDevice * dev_p, /* The device of interest */
+ CyAsEndPointNumber_t ep, /* The endpoint to change */
+ uint32_t size /* The max size of this endpoint in bytes */
+ ) ;
+
+/* Summary
+ This function starts the DMA process on a given channel.
+
+ Description
+ When transferring data from the P port processor to West Bridge, the DMA operation must be initiated
+ P Port software for the first transfer. Subsequent transferrs will be handled at the interrupt level.
+
+ Returns
+ * CY_AS_ERROR_SUCCESS
+*/
+extern CyAsReturnStatus_t
+CyAsDmaKickStart(
+ CyAsDevice * dev_p, /* The device of interest */
+ CyAsEndPointNumber_t ep /* The endpoint to change */
+ ) ;
+
+/* Summary
+ This function receives endpoint data from a request.
+
+ Description
+ For endpoint 0 and 1 the endpoint data is transferred from the West Bridge device to the DMA via a lowlevel
+ requests (via the mailbox registers).
+
+ Returns
+ * CY_AS_ERROR_SUCCESS
+*/
+extern CyAsReturnStatus_t
+CyAsDmaReceivedData(
+ CyAsDevice * dev_p, /* The device of interest */
+ CyAsEndPointNumber_t ep, /* The endpoint that received data */
+ uint32_t dsize, /* The data size */
+ void * data /* The data buffer */
+ );
+
+/* Summary
+ This function is called when the DMA operation on an endpoint has been completed.
+
+ Returns
+ * void
+ */
+extern void
+CyAsDmaCompletedCallback (
+ CyAsHalDeviceTag tag, /* Tag to HAL completing the DMA operation. */
+ CyAsEndPointNumber_t ep, /* Endpoint on which DMA has been completed. */
+ uint32_t length, /* Length of data received. */
+ CyAsReturnStatus_t status /* Status of DMA operation. */
+ ) ;
+
+#include "cyas_cplus_end.h"
+
+#endif /* _INCLUDED_CYASDMA_H_ */