/* 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_ */