drivers/staging/westbridge/astoria/include/linux/westbridge/cyasdma.h

   1 /* Cypress West Bridge API header file (cyasdma.h)
   2 ## ===========================
   3 ## Copyright (C) 2010  Cypress Semiconductor
   4 ##
   5 ## This program is free software; you can redistribute it and/or
   6 ## modify it under the terms of the GNU General Public License
   7 ## as published by the Free Software Foundation; either version 2
   8 ## of the License, or (at your option) any later version.
   9 ##
  10 ## This program is distributed in the hope that it will be useful,
  11 ## but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 ## GNU General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with this program; if not, write to the Free Software
  17 ## Foundation, Inc., 51 Franklin Street
  18 ## Fifth Floor, Boston, MA  02110-1301, USA.
  19 ## ===========================
  20 */
  21
  22 #ifndef _INCLUDED_CYASDMA_H_
  23 #define _INCLUDED_CYASDMA_H_
  24
  25 #include "cyashal.h"
  26 #include "cyasdevice.h"
  27
  28 #include "cyas_cplus_start.h"
  29
  30
  31 /*@@DMA Overview
  32         This module manages the DMA operations to/from the West Bridge
  33         device.  The DMA module maintains a DMA queue for each endpoint
  34         so multiple DMA requests may be queued and they will complete
  35         at some future time.
  36
  37         The DMA module must be started before it can be used.  It is
  38         started by calling CyAsDmaStart().  This function initializes
  39         all of the endpoint data structures.
  40
  41         In order to perform DMA on a particular endpoint, the endpoint
  42         must be enabled by calling CyAsDmaEnableEndPoint(). In addition
  43         to enabling or disabling the endpoint, this function also sets
  44         the direction for a given endpoint.  Direction is given in USB
  45         terms.  For P port to West Bridge traffic, the endpoint is a
  46         CyAsDirectionIn endpoint.  For West Bridge to P port traffic,
  47         the endpoint is a CyAsDirectionOut endpoint.
  48
  49         Once DMA is started and an endpoint is enabled, DMA requests
  50         are issued by calling CyAsDmaQueueRequest().  This function
  51         queue either a DMA read or DMA write request.  The callback
  52         associated with the request is called once the request has been
  53         fulfilled.
  54
  55         See Also
  56         * CyAsDmaStart
  57         * CyAsDmaEnableEndPoint
  58         * CyAsDmaDirection
  59         * CyAsDmaQueueRequest
  60  */
  61
  62 /************************
  63  * West Bridge Constants
  64  ************************/
  65 #define CY_AS_DMA_MAX_SIZE_HW_SIZE (0xffffffff)
  66
  67 /************************
  68  * West Bridge Data Structures
  69  ************************/
  70
  71 /* Summary
  72    This type specifies the direction of an endpoint to the
  73    CyAsDmaEnableEndPoint function.
  74
  75    Description
  76    When an endpoint is enabled, the direction of the endpoint
  77    can also be set. This type is used to specify the endpoint
  78    type.  Note that the direction is specified in USB terms.
  79    Therefore, if the DMA is from the P port to West Bridge,
  80    the direction is IN.
  81
  82    See Also
  83    * CyAsDmaEnableEndPoint
  84 */
  85 typedef enum cy_as_dma_direction {
  86         /* Set the endpoint to type IN (P -> West Bridge) */
  87         cy_as_direction_in = 0,
  88         /* Set the endpoint to type OUT (West Bridge -> P) */
  89         cy_as_direction_out = 1,
  90         /* Only valid for EP 0 */
  91         cy_as_direction_in_out = 2,
  92         /* Do no change the endpoint type */
  93         cy_as_direction_dont_change = 3
  94 } cy_as_dma_direction;
  95
  96 /*********************************
  97  * West Bridge Functions
  98  *********************************/
  99
 100 /* Summary
 101    Initialize the DMA module and ready the module for receiving data
 102
 103    Description
 104    This function initializes the DMA module by initializing all of
 105    the endpoint data structures associated with the device given.
 106    This function also register a DMA complete callback with the HAL
 107    DMA code.  This callback is called whenever the HAL DMA subsystem
 108    completes a requested DMA operation.
 109
 110    Returns
 111    CY_AS_ERROR_SUCCESS - the module initialized successfully
 112    CY_AS_ERROR_OUT_OF_MEMORY - memory allocation failed during
 113                 initialization
 114    CY_AS_ERROR_ALREADY_RUNNING - the DMA module was already running
 115
 116    See Also
 117    * CyAsDmaStop
 118 */
 119 extern cy_as_return_status_t
 120 cy_as_dma_start(
 121         /* The device to start */
 122         cy_as_device *dev_p
 123         );
 124
 125 /* Summary
 126    Shutdown the DMA module
 127
 128    Description
 129    This function shuts down the DMA module for this device by
 130    canceling any DMA requests associated with each endpoint and
 131    then freeing the resources associated with each DMA endpoint.
 132
 133    Returns
 134    CY_AS_ERROR_SUCCESS - the module shutdown successfully
 135    CY_AS_ERROR_NOT_RUNNING - the DMA module was not running
 136
 137    See Also
 138    * CyAsDmaStart
 139    * CyAsDmaCancel
 140 */
 141 extern cy_as_return_status_t
 142 cy_as_dma_stop(
 143         /* The device to stop */
 144         cy_as_device *dev_p
 145         );
 146
 147 /* Summary
 148    This function cancels all outstanding DMA requests on a given endpoint
 149
 150    Description
 151    This function cancels any DMA requests outstanding on a given endpoint
 152    by disabling the transfer of DMA requests from the queue to the HAL
 153    layer and then removing any pending DMA requests from the queue. The
 154    callback associated with any DMA requests that are being removed is
 155    called with an error code of CY_AS_ERROR_CANCELED.
 156
 157    Notes
 158    If a request has already been sent to the HAL layer it will be
 159    completed and not canceled. Only requests that have not been sent to
 160    the HAL layer will be cancelled.
 161
 162    Returns
 163    CY_AS_ERROR_SUCCESS - the traffic on the endpoint is canceled
 164         successfully
 165
 166    See Also
 167 */
 168 extern cy_as_return_status_t
 169 cy_as_dma_cancel(
 170         /* The device of interest */
 171         cy_as_device *dev_p,
 172         /* The endpoint to cancel */
 173         cy_as_end_point_number_t ep,
 174         cy_as_return_status_t err
 175         );
 176
 177 /* Summary
 178    This function enables a single endpoint for DMA operations
 179
 180    Description
 181    In order to enable the queuing of DMA requests on a given
 182    endpoint, the endpoint must be enabled for DMA.  This function
 183    enables a given endpoint.  In addition, this function sets the
 184    direction of the DMA operation.
 185
 186    Returns
 187    * CY_AS_ERROR_INVALID_ENDPOINT - invalid endpoint number
 188    * CY_AS_ERROR_SUCCESS - endpoint was enabled or disabled
 189    *    successfully
 190
 191    See Also
 192    * CyAsDmaQueueRequest
 193 */
 194 extern cy_as_return_status_t
 195 cy_as_dma_enable_end_point(
 196         /* The device of interest */
 197         cy_as_device *dev_p,
 198         /* The endpoint to enable or disable */
 199         cy_as_end_point_number_t ep,
 200         /* CyTrue to enable, CyFalse to disable */
 201         cy_bool enable,
 202         /* The direction of the endpoint */
 203         cy_as_dma_direction     dir
 204 );
 205
 206 /* Summary
 207    This function queue a DMA request for a given endpoint
 208
 209    Description
 210    When an West Bridge API module wishes to do a DMA operation,
 211    this function is called on the associated endpoint to queue
 212    a DMA request.  When the DMA request has been fulfilled, the
 213    callback associated with the DMA operation is called.
 214
 215    Notes
 216    The buffer associated with the DMA request, must remain valid
 217    until after the callback function is calld.
 218
 219    Returns
 220    * CY_AS_ERROR_SUCCESS - the DMA operation was queued successfully
 221    * CY_AS_ERROR_INVALID_ENDPOINT - the endpoint number was invalid
 222    * CY_AS_ERROR_ENDPOINT_DISABLED - the endpoint was disabled
 223    * CY_AS_ERROR_OUT_OF_MEMORY - out of memory processing the request
 224
 225    See Also
 226    * CyAsDmaEnableEndPoint
 227    * CyAsDmaCancel
 228 */
 229 extern cy_as_return_status_t
 230 cy_as_dma_queue_request(
 231         /* The device of interest */
 232         cy_as_device *dev_p,
 233         /* The endpoint to receive a new request */
 234         cy_as_end_point_number_t ep,
 235         /* The memory buffer for the DMA request -
 236          * must be valid until after the callback has been called */
 237         void *mem_p,
 238         /* The size of the DMA request in bytes */
 239         uint32_t size,
 240         /* If true and a DMA read request, return the next packet
 241          * regardless of size */
 242         cy_bool packet,
 243         /* If true, this is a read request,
 244          * otherwise it is a write request */
 245         cy_bool readreq,
 246         /* The callback to call when the DMA request is complete,
 247          * either successfully or via an error */
 248         cy_as_dma_callback cb
 249         );
 250
 251 /* Summary
 252    This function waits until all DMA requests on a given endpoint
 253    have been processed and then return
 254
 255    Description
 256    There are times when a module in the West Bridge API needs to
 257    wait until the DMA operations have been queued.  This function
 258    sleeps until all DMA requests have been fulfilled and only then
 259    returns to the caller.
 260
 261    Notes
 262    I don't think we will need a list of sleeping clients to support
 263    multiple parallel client modules sleeping on a single endpoint,
 264    but if we do instead of having a single sleep channel in the
 265    endpoint, each client will have to supply a sleep channel and we
 266    will have to maintain a list of sleep channels to wake.
 267
 268    Returns
 269    * CY_AS_ERROR_SUCCESS - the queue has drained successfully
 270    * CY_AS_ERROR_INVALID_ENDPOINT - the endpoint given is not valid
 271    * CY_AS_ERROR_NESTED_SLEEP - CyAsDmaQueueRequest() was requested
 272    *    on an endpoint where CyAsDmaQueueRequest was already called
 273 */
 274 extern cy_as_return_status_t
 275 cy_as_dma_drain_queue(
 276         /* The device of interest */
 277         cy_as_device *dev_p,
 278         /* The endpoint to drain */
 279         cy_as_end_point_number_t ep,
 280         /* If CyTrue, call kickstart to start the DMA process,
 281         if cy_false, west bridge will start the DMA process */
 282         cy_bool kickstart
 283         );
 284
 285 /* Summary
 286    Sets the maximum amount of data West Bridge can accept in a single
 287    DMA Operation for the given endpoint
 288
 289    Description
 290    Depending on the configuration of the West Bridge device endpoint,
 291    the amount of data that can be accepted varies.  This function
 292    sets the maximum amount of data West Bridge can accept in a single
 293    DMA operation.  The value is stored with the endpoint and passed
 294    to the HAL layer in the CyAsHalDmaSetupWrite() and
 295    CyAsHalDmaSetupRead() functoins.
 296
 297    Returns
 298    * CY_AS_ERROR_SUCCESS - the value was set successfully
 299    * CY_AS_ERROR_INVALID_SIZE - the size value was not valid
 300 */
 301 extern cy_as_return_status_t
 302 cy_as_dma_set_max_dma_size(
 303         /* The device of interest */
 304         cy_as_device *dev_p,
 305         /* The endpoint to change */
 306         cy_as_end_point_number_t ep,
 307         /* The max size of this endpoint in bytes */
 308         uint32_t size
 309         );
 310
 311 /* Summary
 312    This function starts the DMA process on a given channel.
 313
 314    Description
 315    When transferring data from the P port processor to West
 316    Bridge, the DMA operation must be initiated P Port software
 317    for the first transfer.  Subsequent transferrs will be
 318    handled at the interrupt level.
 319
 320    Returns
 321    * CY_AS_ERROR_SUCCESS
 322 */
 323 extern cy_as_return_status_t
 324 cy_as_dma_kick_start(
 325         /* The device of interest */
 326         cy_as_device *dev_p,
 327         /* The endpoint to change */
 328         cy_as_end_point_number_t ep
 329         );
 330
 331 /* Summary
 332    This function receives endpoint data from a request.
 333
 334    Description
 335    For endpoint 0 and 1 the endpoint data is transferred from
 336    the West Bridge device to the DMA via a lowlevel
 337    requests (via the mailbox registers).
 338
 339    Returns
 340    * CY_AS_ERROR_SUCCESS
 341 */
 342 extern cy_as_return_status_t
 343 cy_as_dma_received_data(
 344         /* The device of interest */
 345         cy_as_device *dev_p,
 346         /* The endpoint that received data */
 347         cy_as_end_point_number_t ep,
 348         /* The data size */
 349         uint32_t dsize,
 350         /* The data buffer */
 351         void *data
 352         );
 353
 354 /* Summary
 355    This function is called when the DMA operation on
 356    an endpoint has been completed.
 357
 358    Returns
 359    * void
 360  */
 361 extern void
 362 cy_as_dma_completed_callback(
 363         /* Tag to HAL completing the DMA operation. */
 364         cy_as_hal_device_tag     tag,
 365         /* Endpoint on which DMA has been completed. */
 366         cy_as_end_point_number_t ep,
 367         /* Length of data received. */
 368         uint32_t                         length,
 369         /* Status of DMA operation. */
 370         cy_as_return_status_t   status
 371         );
 372
 373 #include "cyas_cplus_end.h"
 374
 375 #endif            /* _INCLUDED_CYASDMA_H_ */