diff options
Diffstat (limited to 'drivers/staging/westbridge/astoria/include/linux/westbridge/cyasdma.h')
| -rw-r--r-- | drivers/staging/westbridge/astoria/include/linux/westbridge/cyasdma.h | 375 |
1 files changed, 375 insertions, 0 deletions
diff --git a/drivers/staging/westbridge/astoria/include/linux/westbridge/cyasdma.h b/drivers/staging/westbridge/astoria/include/linux/westbridge/cyasdma.h new file mode 100644 index 0000000..6efb8b8 --- /dev/null +++ b/drivers/staging/westbridge/astoria/include/linux/westbridge/cyasdma.h @@ -0,0 +1,375 @@ +/* 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_ */ |
