diff -r b7e488c49d0d -r 117faf51deac omap3530/beagle_drivers/wb/api/src/cyasdma.h --- /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 + ## + ## /license/license.txt + ## + ## where 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_ */