Bug 1996 - Contribution for West Bridge Astoria Symbian Storage Driver
this storage driver is for the West Bridge Astoria chipset. This device
has a USB, SD and processor port for communication with a baseband processor.
In our port, we connected this device DVK to the Beagleboard through the SPI
interface of the OMAP3. After driver installation, the Symbian OS can see an
external device or D: drive represented by the SD card. In this driver, the USB
interface is not used directly, though this may be the subject of future
contributions. The appropriate way to test the driver is to access the external
volume and do file read and write to it, pretty much the same way you would
test a thumb drive on your PC
/* 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_ */