/* Cypress West Bridge API header file (cyasdma.h)
## ===========================
## Copyright (C) 2010  Cypress Semiconductor
##
## This program is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License
## as published by the Free Software Foundation; either version 2
## of the License, or (at your option) any later version.
##
## This program is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
## GNU General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with this program; if not, write to the Free Software
## Foundation, Inc., 51 Franklin Street
## Fifth Floor, Boston, MA  02110-1301, USA.
## ===========================
*/

#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 cy_as_dma_direction {
	/* Set the endpoint to type IN (P -> West Bridge) */
	cy_as_direction_in = 0,
	/* Set the endpoint to type OUT (West Bridge -> P) */
	cy_as_direction_out = 1,
	/* Only valid for EP 0 */
	cy_as_direction_in_out = 2,
	/* Do no change the endpoint type */
	cy_as_direction_dont_change = 3
} cy_as_dma_direction;

/*********************************
 * 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 cy_as_return_status_t
cy_as_dma_start(
	/* The device to start */
	cy_as_device *dev_p
	);

/* 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 cy_as_return_status_t
cy_as_dma_stop(
	/* The device to stop */
	cy_as_device *dev_p
	);

/* 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 cancelled.

   Returns
   CY_AS_ERROR_SUCCESS - the traffic on the endpoint is canceled
	sucessfully

   See Also
*/
extern cy_as_return_status_t
cy_as_dma_cancel(
	/* The device of interest */
	cy_as_device *dev_p,
	/* The endpoint to cancel */
	cy_as_end_point_number_t ep,
	cy_as_return_status_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 cy_as_return_status_t
cy_as_dma_enable_end_point(
	/* The device of interest */
	cy_as_device *dev_p,
	/* The endpoint to enable or disable */
	cy_as_end_point_number_t ep,
	/* CyTrue to enable, CyFalse to disable */
	cy_bool	enable,
	/* The direction of the endpoint */
	cy_as_dma_direction	dir
);

/* 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 cy_as_return_status_t
cy_as_dma_queue_request(
	/* The device of interest */
	cy_as_device *dev_p,
	/* The endpoint to receive a new request */
	cy_as_end_point_number_t ep,
	/* The memory buffer for the DMA request -
	 * must be valid until after the callback has been called */
	void *mem_p,
	/* The size of the DMA request in bytes */
	uint32_t size,
	/* If true and a DMA read request, return the next packet
	 * regardless of size */
	cy_bool	packet,
	/* If true, this is a read request,
	 * otherwise it is a write request */
	cy_bool	readreq,
	/* The callback to call when the DMA request is complete,
	 * either successfully or via an error */
	cy_as_dma_callback cb
	);

/* 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 cy_as_return_status_t
cy_as_dma_drain_queue(
	/* The device of interest */
	cy_as_device *dev_p,
	/* The endpoint to drain */
	cy_as_end_point_number_t ep,
	/* If CyTrue, call kickstart to start the DMA process,
	if cy_false, west bridge will start the DMA process */
	cy_bool kickstart
	);

/* 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 cy_as_return_status_t
cy_as_dma_set_max_dma_size(
	/* The device of interest */
	cy_as_device *dev_p,
	/* The endpoint to change */
	cy_as_end_point_number_t ep,
	/* The max size of this endpoint in bytes */
	uint32_t size
	);

/* 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 cy_as_return_status_t
cy_as_dma_kick_start(
	/* The device of interest */
	cy_as_device *dev_p,
	/* The endpoint to change */
	cy_as_end_point_number_t ep
	);

/* 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 cy_as_return_status_t
cy_as_dma_received_data(
	/* The device of interest */
	cy_as_device *dev_p,
	/* The endpoint that received data */
	cy_as_end_point_number_t ep,
	/* The data size */
	uint32_t dsize,
	/* The data buffer */
	void *data
	);

/* Summary
   This function is called when the DMA operation on
   an endpoint has been completed.

   Returns
   * void
 */
extern void
cy_as_dma_completed_callback(
	/* Tag to HAL completing the DMA operation. */
	cy_as_hal_device_tag	 tag,
	/* Endpoint on which DMA has been completed. */
	cy_as_end_point_number_t ep,
	/* Length of data received. */
	uint32_t			 length,
	/* Status of DMA operation. */
	cy_as_return_status_t   status
	);

#include "cyas_cplus_end.h"

#endif		  /* _INCLUDED_CYASDMA_H_ */