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