release/src-rt-6.x.4708/linux/linux-2.6.36/arch/arm/mach-bcmring/include/mach/dma.h

   1 /*****************************************************************************
   2 * Copyright 2004 - 2008 Broadcom Corporation.  All rights reserved.
   3 *
   4 * Unless you and Broadcom execute a separate written software license
   5 * agreement governing use of this software, this software is licensed to you
   6 * under the terms of the GNU General Public License version 2, available at
   7 * http://www.broadcom.com/licenses/GPLv2.php (the "GPL").
   8 *
   9 * Notwithstanding the above, under no circumstances may you combine this
  10 * software in any way with any other Broadcom software provided under a
  11 * license other than the GPL, without Broadcom's express prior written
  12 * consent.
  13 *****************************************************************************/
  14
  15 /****************************************************************************/
  16 /**
  17 *   @file   dma.h
  18 *
  19 *   @brief  API definitions for the linux DMA interface.
  20 */
  21 /****************************************************************************/
  22
  23 #if !defined(ASM_ARM_ARCH_BCMRING_DMA_H)
  24 #define ASM_ARM_ARCH_BCMRING_DMA_H
  25
  26 /* ---- Include Files ---------------------------------------------------- */
  27
  28 #include <linux/kernel.h>
  29 #include <linux/wait.h>
  30 #include <linux/semaphore.h>
  31 #include <csp/dmacHw.h>
  32 #include <mach/timer.h>
  33 #include <linux/scatterlist.h>
  34 #include <linux/dma-mapping.h>
  35 #include <linux/mm.h>
  36 #include <linux/vmalloc.h>
  37 #include <linux/pagemap.h>
  38
  39 /* ---- Constants and Types ---------------------------------------------- */
  40
  41 /* If DMA_DEBUG_TRACK_RESERVATION is set to a non-zero value, then the filename */
  42 /* and line number of the reservation request will be recorded in the channel table */
  43
  44 #define DMA_DEBUG_TRACK_RESERVATION   1
  45
  46 #define DMA_NUM_CONTROLLERS     2
  47 #define DMA_NUM_CHANNELS        8       /* per controller */
  48
  49 typedef enum {
  50         DMA_DEVICE_MEM_TO_MEM,  /* For memory to memory transfers */
  51         DMA_DEVICE_I2S0_DEV_TO_MEM,
  52         DMA_DEVICE_I2S0_MEM_TO_DEV,
  53         DMA_DEVICE_I2S1_DEV_TO_MEM,
  54         DMA_DEVICE_I2S1_MEM_TO_DEV,
  55         DMA_DEVICE_APM_CODEC_A_DEV_TO_MEM,
  56         DMA_DEVICE_APM_CODEC_A_MEM_TO_DEV,
  57         DMA_DEVICE_APM_CODEC_B_DEV_TO_MEM,
  58         DMA_DEVICE_APM_CODEC_B_MEM_TO_DEV,
  59         DMA_DEVICE_APM_CODEC_C_DEV_TO_MEM,      /* Additional mic input for beam-forming */
  60         DMA_DEVICE_APM_PCM0_DEV_TO_MEM,
  61         DMA_DEVICE_APM_PCM0_MEM_TO_DEV,
  62         DMA_DEVICE_APM_PCM1_DEV_TO_MEM,
  63         DMA_DEVICE_APM_PCM1_MEM_TO_DEV,
  64         DMA_DEVICE_SPUM_DEV_TO_MEM,
  65         DMA_DEVICE_SPUM_MEM_TO_DEV,
  66         DMA_DEVICE_SPIH_DEV_TO_MEM,
  67         DMA_DEVICE_SPIH_MEM_TO_DEV,
  68         DMA_DEVICE_UART_A_DEV_TO_MEM,
  69         DMA_DEVICE_UART_A_MEM_TO_DEV,
  70         DMA_DEVICE_UART_B_DEV_TO_MEM,
  71         DMA_DEVICE_UART_B_MEM_TO_DEV,
  72         DMA_DEVICE_PIF_MEM_TO_DEV,
  73         DMA_DEVICE_PIF_DEV_TO_MEM,
  74         DMA_DEVICE_ESW_DEV_TO_MEM,
  75         DMA_DEVICE_ESW_MEM_TO_DEV,
  76         DMA_DEVICE_VPM_MEM_TO_MEM,
  77         DMA_DEVICE_CLCD_MEM_TO_MEM,
  78         DMA_DEVICE_NAND_MEM_TO_MEM,
  79         DMA_DEVICE_MEM_TO_VRAM,
  80         DMA_DEVICE_VRAM_TO_MEM,
  81
  82         /* Add new entries before this line. */
  83
  84         DMA_NUM_DEVICE_ENTRIES,
  85         DMA_DEVICE_NONE = 0xff, /* Special value to indicate that no device is currently assigned. */
  86
  87 } DMA_Device_t;
  88
  89 /****************************************************************************
  90 *
  91 *   The DMA_Handle_t is the primary object used by callers of the API.
  92 *
  93 *****************************************************************************/
  94
  95 #define DMA_INVALID_HANDLE  ((DMA_Handle_t) -1)
  96
  97 typedef int DMA_Handle_t;
  98
  99 /****************************************************************************
 100 *
 101 *   The DMA_DescriptorRing_t contains a ring of descriptors which is used
 102 *   to point to regions of memory.
 103 *
 104 *****************************************************************************/
 105
 106 typedef struct {
 107         void *virtAddr;         /* Virtual Address of the descriptor ring */
 108         dma_addr_t physAddr;    /* Physical address of the descriptor ring */
 109         int descriptorsAllocated;       /* Number of descriptors allocated in the descriptor ring */
 110         size_t bytesAllocated;  /* Number of bytes allocated in the descriptor ring */
 111
 112 } DMA_DescriptorRing_t;
 113
 114 /****************************************************************************
 115 *
 116 *   The DMA_MemType_t and DMA_MemMap_t are helper structures used to setup
 117 *   DMA chains from a variety of memory sources.
 118 *
 119 *****************************************************************************/
 120
 121 #define DMA_MEM_MAP_MIN_SIZE    4096    /* Pages less than this size are better */
 122                                         /* off not being DMA'd. */
 123
 124 typedef enum {
 125         DMA_MEM_TYPE_NONE,      /* Not a valid setting */
 126         DMA_MEM_TYPE_VMALLOC,   /* Memory came from vmalloc call */
 127         DMA_MEM_TYPE_KMALLOC,   /* Memory came from kmalloc call */
 128         DMA_MEM_TYPE_DMA,       /* Memory came from dma_alloc_xxx call */
 129         DMA_MEM_TYPE_USER,      /* Memory came from user space. */
 130
 131 } DMA_MemType_t;
 132
 133 /* A segment represents a physically and virtually contiguous chunk of memory. */
 134 /* i.e. each segment can be DMA'd */
 135 /* A user of the DMA code will add memory regions. Each region may need to be */
 136 /* represented by one or more segments. */
 137
 138 typedef struct {
 139         void *virtAddr;         /* Virtual address used for this segment */
 140         dma_addr_t physAddr;    /* Physical address this segment maps to */
 141         size_t numBytes;        /* Size of the segment, in bytes */
 142
 143 } DMA_Segment_t;
 144
 145 /* A region represents a virtually contiguous chunk of memory, which may be */
 146 /* made up of multiple segments. */
 147
 148 typedef struct {
 149         DMA_MemType_t memType;
 150         void *virtAddr;
 151         size_t numBytes;
 152
 153         /* Each region (virtually contiguous) consists of one or more segments. Each */
 154         /* segment is virtually and physically contiguous. */
 155
 156         int numSegmentsUsed;
 157         int numSegmentsAllocated;
 158         DMA_Segment_t *segment;
 159
 160         /* When a region corresponds to user memory, we need to lock all of the pages */
 161         /* down before we can figure out the physical addresses. The lockedPage array contains */
 162         /* the pages that were locked, and which subsequently need to be unlocked once the */
 163         /* memory is unmapped. */
 164
 165         unsigned numLockedPages;
 166         struct page **lockedPages;
 167
 168 } DMA_Region_t;
 169
 170 typedef struct {
 171         int inUse;              /* Is this mapping currently being used? */
 172         struct semaphore lock;  /* Acquired when using this structure */
 173         enum dma_data_direction dir;    /* Direction this transfer is intended for */
 174
 175         /* In the event that we're mapping user memory, we need to know which task */
 176         /* the memory is for, so that we can obtain the correct mm locks. */
 177
 178         struct task_struct *userTask;
 179
 180         int numRegionsUsed;
 181         int numRegionsAllocated;
 182         DMA_Region_t *region;
 183
 184 } DMA_MemMap_t;
 185
 186 /****************************************************************************
 187 *
 188 *   The DMA_DeviceAttribute_t contains information which describes a
 189 *   particular DMA device (or peripheral).
 190 *
 191 *   It is anticipated that the arrary of DMA_DeviceAttribute_t's will be
 192 *   statically initialized.
 193 *
 194 *****************************************************************************/
 195
 196 /* The device handler is called whenever a DMA operation completes. The reaon */
 197 /* for it to be called will be a bitmask with one or more of the following bits */
 198 /* set. */
 199
 200 #define DMA_HANDLER_REASON_BLOCK_COMPLETE       dmacHw_INTERRUPT_STATUS_BLOCK
 201 #define DMA_HANDLER_REASON_TRANSFER_COMPLETE    dmacHw_INTERRUPT_STATUS_TRANS
 202 #define DMA_HANDLER_REASON_ERROR                dmacHw_INTERRUPT_STATUS_ERROR
 203
 204 typedef void (*DMA_DeviceHandler_t) (DMA_Device_t dev, int reason,
 205                                      void *userData);
 206
 207 #define DMA_DEVICE_FLAG_ON_DMA0             0x00000001
 208 #define DMA_DEVICE_FLAG_ON_DMA1             0x00000002
 209 #define DMA_DEVICE_FLAG_PORT_PER_DMAC       0x00000004  /* If set, it means that the port used on DMAC0 is different from the port used on DMAC1 */
 210 #define DMA_DEVICE_FLAG_ALLOC_DMA1_FIRST    0x00000008  /* If set, allocate from DMA1 before allocating from DMA0 */
 211 #define DMA_DEVICE_FLAG_IS_DEDICATED        0x00000100
 212 #define DMA_DEVICE_FLAG_NO_ISR              0x00000200
 213 #define DMA_DEVICE_FLAG_ALLOW_LARGE_FIFO    0x00000400
 214 #define DMA_DEVICE_FLAG_IN_USE              0x00000800  /* If set, device is in use on a channel */
 215
 216 /* Note: Some DMA devices can be used from multiple DMA Controllers. The bitmask is used to */
 217 /*       determine which DMA controllers a given device can be used from, and the interface */
 218 /*       array determeines the actual interface number to use for a given controller. */
 219
 220 typedef struct {
 221         uint32_t flags;         /* Bitmask of DMA_DEVICE_FLAG_xxx constants */
 222         uint8_t dedicatedController;    /* Controller number to use if DMA_DEVICE_FLAG_IS_DEDICATED is set. */
 223         uint8_t dedicatedChannel;       /* Channel number to use if DMA_DEVICE_FLAG_IS_DEDICATED is set. */
 224         const char *name;       /* Will show up in the /proc entry */
 225
 226         uint32_t dmacPort[DMA_NUM_CONTROLLERS]; /* Specifies the port number when DMA_DEVICE_FLAG_PORT_PER_DMAC flag is set */
 227
 228         dmacHw_CONFIG_t config; /* Configuration to use when DMA'ing using this device */
 229
 230         void *userData;         /* Passed to the devHandler */
 231         DMA_DeviceHandler_t devHandler; /* Called when DMA operations finish. */
 232
 233         timer_tick_count_t transferStartTime;   /* Time the current transfer was started */
 234
 235         /* The following statistical information will be collected and presented in a proc entry. */
 236         /* Note: With a contiuous bandwidth of 1 Gb/sec, it would take 584 years to overflow */
 237         /*       a 64 bit counter. */
 238
 239         uint64_t numTransfers;  /* Number of DMA transfers performed */
 240         uint64_t transferTicks; /* Total time spent doing DMA transfers (measured in timer_tick_count_t's) */
 241         uint64_t transferBytes; /* Total bytes transferred */
 242         uint32_t timesBlocked;  /* Number of times a channel was unavailable */
 243         uint32_t numBytes;      /* Last transfer size */
 244
 245         /* It's not possible to free memory which is allocated for the descriptors from within */
 246         /* the ISR. So make the presumption that a given device will tend to use the */
 247         /* same sized buffers over and over again, and we keep them around. */
 248
 249         DMA_DescriptorRing_t ring;      /* Ring of descriptors allocated for this device */
 250
 251         /* We stash away some of the information from the previous transfer. If back-to-back */
 252         /* transfers are performed from the same buffer, then we don't have to keep re-initializing */
 253         /* the descriptor buffers. */
 254
 255         uint32_t prevNumBytes;
 256         dma_addr_t prevSrcData;
 257         dma_addr_t prevDstData;
 258
 259 } DMA_DeviceAttribute_t;
 260
 261 /****************************************************************************
 262 *
 263 *   DMA_Channel_t, DMA_Controller_t, and DMA_State_t are really internal
 264 *   data structures and don't belong in this header file, but are included
 265 *   merely for discussion.
 266 *
 267 *   By the time this is implemented, these structures will be moved out into
 268 *   the appropriate C source file instead.
 269 *
 270 *****************************************************************************/
 271
 272 /****************************************************************************
 273 *
 274 *   The DMA_Channel_t contains state information about each DMA channel. Some
 275 *   of the channels are dedicated. Non-dedicated channels are shared
 276 *   amongst the other devices.
 277 *
 278 *****************************************************************************/
 279
 280 #define DMA_CHANNEL_FLAG_IN_USE         0x00000001
 281 #define DMA_CHANNEL_FLAG_IS_DEDICATED   0x00000002
 282 #define DMA_CHANNEL_FLAG_NO_ISR         0x00000004
 283 #define DMA_CHANNEL_FLAG_LARGE_FIFO     0x00000008
 284
 285 typedef struct {
 286         uint32_t flags;         /* bitmask of DMA_CHANNEL_FLAG_xxx constants */
 287         DMA_Device_t devType;   /* Device this channel is currently reserved for */
 288         DMA_Device_t lastDevType;       /* Device type that used this previously */
 289         char name[20];          /* Name passed onto request_irq */
 290
 291 #if DMA_DEBUG_TRACK_RESERVATION
 292         const char *fileName;   /* Place where channel reservation took place */
 293         int lineNum;            /* Place where channel reservation took place */
 294 #endif
 295         dmacHw_HANDLE_t dmacHwHandle;   /* low level channel handle. */
 296
 297 } DMA_Channel_t;
 298
 299 /****************************************************************************
 300 *
 301 *   The DMA_Controller_t contains state information about each DMA controller.
 302 *
 303 *   The freeChannelQ is stored in the controller data structure rather than
 304 *   the channel data structure since several of the devices are accessible
 305 *   from multiple controllers, and there is no way to know which controller
 306 *   will become available first.
 307 *
 308 *****************************************************************************/
 309
 310 typedef struct {
 311         DMA_Channel_t channel[DMA_NUM_CHANNELS];
 312
 313 } DMA_Controller_t;
 314
 315 /****************************************************************************
 316 *
 317 *   The DMA_Global_t contains all of the global state information used by
 318 *   the DMA code.
 319 *
 320 *   Callers which need to allocate a shared channel will be queued up
 321 *   on the freeChannelQ until a channel becomes available.
 322 *
 323 *****************************************************************************/
 324
 325 typedef struct {
 326         struct semaphore lock;  /* acquired when manipulating table entries */
 327         wait_queue_head_t freeChannelQ;
 328
 329         DMA_Controller_t controller[DMA_NUM_CONTROLLERS];
 330
 331 } DMA_Global_t;
 332
 333 /* ---- Variable Externs ------------------------------------------------- */
 334
 335 extern DMA_DeviceAttribute_t DMA_gDeviceAttribute[DMA_NUM_DEVICE_ENTRIES];
 336
 337 /* ---- Function Prototypes ---------------------------------------------- */
 338
 339 #if defined(__KERNEL__)
 340
 341 /****************************************************************************/
 342 /**
 343 *   Initializes the DMA module.
 344 *
 345 *   @return
 346 *       0       - Success
 347 *       < 0     - Error
 348 */
 349 /****************************************************************************/
 350
 351 int dma_init(void);
 352
 353 #if DMA_DEBUG_TRACK_RESERVATION
 354 DMA_Handle_t dma_request_channel_dbg(DMA_Device_t dev, const char *fileName,
 355                                      int lineNum);
 356 #define dma_request_channel(dev)  dma_request_channel_dbg(dev, __FILE__, __LINE__)
 357 #else
 358
 359 /****************************************************************************/
 360 /**
 361 *   Reserves a channel for use with @a dev. If the device is setup to use
 362 *   a shared channel, then this function will block until a free channel
 363 *   becomes available.
 364 *
 365 *   @return
 366 *       >= 0    - A valid DMA Handle.
 367 *       -EBUSY  - Device is currently being used.
 368 *       -ENODEV - Device handed in is invalid.
 369 */
 370 /****************************************************************************/
 371
 372 DMA_Handle_t dma_request_channel(DMA_Device_t dev       /* Device to use with the allocated channel. */
 373     );
 374 #endif
 375
 376 /****************************************************************************/
 377 /**
 378 *   Frees a previously allocated DMA Handle.
 379 *
 380 *   @return
 381 *        0      - DMA Handle was released successfully.
 382 *       -EINVAL - Invalid DMA handle
 383 */
 384 /****************************************************************************/
 385
 386 int dma_free_channel(DMA_Handle_t channel       /* DMA handle. */
 387     );
 388
 389 /****************************************************************************/
 390 /**
 391 *   Determines if a given device has been configured as using a shared
 392 *   channel.
 393 *
 394 *   @return boolean
 395 *       0           Device uses a dedicated channel
 396 *       non-zero    Device uses a shared channel
 397 */
 398 /****************************************************************************/
 399
 400 int dma_device_is_channel_shared(DMA_Device_t dev       /* Device to check. */
 401     );
 402
 403 /****************************************************************************/
 404 /**
 405 *   Allocates memory to hold a descriptor ring. The descriptor ring then
 406 *   needs to be populated by making one or more calls to
 407 *   dna_add_descriptors.
 408 *
 409 *   The returned descriptor ring will be automatically initialized.
 410 *
 411 *   @return
 412 *       0           Descriptor ring was allocated successfully
 413 *       -ENOMEM     Unable to allocate memory for the desired number of descriptors.
 414 */
 415 /****************************************************************************/
 416
 417 int dma_alloc_descriptor_ring(DMA_DescriptorRing_t *ring,       /* Descriptor ring to populate */
 418                               int numDescriptors        /* Number of descriptors that need to be allocated. */
 419     );
 420
 421 /****************************************************************************/
 422 /**
 423 *   Releases the memory which was previously allocated for a descriptor ring.
 424 */
 425 /****************************************************************************/
 426
 427 void dma_free_descriptor_ring(DMA_DescriptorRing_t *ring        /* Descriptor to release */
 428     );
 429
 430 /****************************************************************************/
 431 /**
 432 *   Initializes a descriptor ring, so that descriptors can be added to it.
 433 *   Once a descriptor ring has been allocated, it may be reinitialized for
 434 *   use with additional/different regions of memory.
 435 *
 436 *   Note that if 7 descriptors are allocated, it's perfectly acceptable to
 437 *   initialize the ring with a smaller number of descriptors. The amount
 438 *   of memory allocated for the descriptor ring will not be reduced, and
 439 *   the descriptor ring may be reinitialized later
 440 *
 441 *   @return
 442 *       0           Descriptor ring was initialized successfully
 443 *       -ENOMEM     The descriptor which was passed in has insufficient space
 444 *                   to hold the desired number of descriptors.
 445 */
 446 /****************************************************************************/
 447
 448 int dma_init_descriptor_ring(DMA_DescriptorRing_t *ring,        /* Descriptor ring to initialize */
 449                              int numDescriptors /* Number of descriptors to initialize. */
 450     );
 451
 452 /****************************************************************************/
 453 /**
 454 *   Determines the number of descriptors which would be required for a
 455 *   transfer of the indicated memory region.
 456 *
 457 *   This function also needs to know which DMA device this transfer will
 458 *   be destined for, so that the appropriate DMA configuration can be retrieved.
 459 *   DMA parameters such as transfer width, and whether this is a memory-to-memory
 460 *   or memory-to-peripheral, etc can all affect the actual number of descriptors
 461 *   required.
 462 *
 463 *   @return
 464 *       > 0     Returns the number of descriptors required for the indicated transfer
 465 *       -EINVAL Invalid device type for this kind of transfer
 466 *               (i.e. the device is _MEM_TO_DEV and not _DEV_TO_MEM)
 467 *       -ENOMEM Memory exhausted
 468 */
 469 /****************************************************************************/
 470
 471 int dma_calculate_descriptor_count(DMA_Device_t device, /* DMA Device that this will be associated with */
 472                                    dma_addr_t srcData,  /* Place to get data to write to device */
 473                                    dma_addr_t dstData,  /* Pointer to device data address */
 474                                    size_t numBytes      /* Number of bytes to transfer to the device */
 475     );
 476
 477 /****************************************************************************/
 478 /**
 479 *   Adds a region of memory to the descriptor ring. Note that it may take
 480 *   multiple descriptors for each region of memory. It is the callers
 481 *   responsibility to allocate a sufficiently large descriptor ring.
 482 *
 483 *   @return
 484 *       0       Descriptors were added successfully
 485 *       -EINVAL Invalid device type for this kind of transfer
 486 *               (i.e. the device is _MEM_TO_DEV and not _DEV_TO_MEM)
 487 *       -ENOMEM Memory exhausted
 488 */
 489 /****************************************************************************/
 490
 491 int dma_add_descriptors(DMA_DescriptorRing_t *ring,     /* Descriptor ring to add descriptors to */
 492                         DMA_Device_t device,    /* DMA Device that descriptors are for */
 493                         dma_addr_t srcData,     /* Place to get data (memory or device) */
 494                         dma_addr_t dstData,     /* Place to put data (memory or device) */
 495                         size_t numBytes /* Number of bytes to transfer to the device */
 496     );
 497
 498 /****************************************************************************/
 499 /**
 500 *   Sets the descriptor ring associated with a device.
 501 *
 502 *   Once set, the descriptor ring will be associated with the device, even
 503 *   across channel request/free calls. Passing in a NULL descriptor ring
 504 *   will release any descriptor ring currently associated with the device.
 505 *
 506 *   Note: If you call dma_transfer, or one of the other dma_alloc_ functions
 507 *         the descriptor ring may be released and reallocated.
 508 *
 509 *   Note: This function will release the descriptor memory for any current
 510 *         descriptor ring associated with this device.
 511 */
 512 /****************************************************************************/
 513
 514 int dma_set_device_descriptor_ring(DMA_Device_t device, /* Device to update the descriptor ring for. */
 515                                    DMA_DescriptorRing_t *ring   /* Descriptor ring to add descriptors to */
 516     );
 517
 518 /****************************************************************************/
 519 /**
 520 *   Retrieves the descriptor ring associated with a device.
 521 */
 522 /****************************************************************************/
 523
 524 int dma_get_device_descriptor_ring(DMA_Device_t device, /* Device to retrieve the descriptor ring for. */
 525                                    DMA_DescriptorRing_t *ring   /* Place to store retrieved ring */
 526     );
 527
 528 /****************************************************************************/
 529 /**
 530 *   Allocates buffers for the descriptors. This is normally done automatically
 531 *   but needs to be done explicitly when initiating a dma from interrupt
 532 *   context.
 533 *
 534 *   @return
 535 *       0       Descriptors were allocated successfully
 536 *       -EINVAL Invalid device type for this kind of transfer
 537 *               (i.e. the device is _MEM_TO_DEV and not _DEV_TO_MEM)
 538 *       -ENOMEM Memory exhausted
 539 */
 540 /****************************************************************************/
 541
 542 int dma_alloc_descriptors(DMA_Handle_t handle,  /* DMA Handle */
 543                           dmacHw_TRANSFER_TYPE_e transferType,  /* Type of transfer being performed */
 544                           dma_addr_t srcData,   /* Place to get data to write to device */
 545                           dma_addr_t dstData,   /* Pointer to device data address */
 546                           size_t numBytes       /* Number of bytes to transfer to the device */
 547     );
 548
 549 /****************************************************************************/
 550 /**
 551 *   Allocates and sets up descriptors for a double buffered circular buffer.
 552 *
 553 *   This is primarily intended to be used for things like the ingress samples
 554 *   from a microphone.
 555 *
 556 *   @return
 557 *       > 0     Number of descriptors actually allocated.
 558 *       -EINVAL Invalid device type for this kind of transfer
 559 *               (i.e. the device is _MEM_TO_DEV and not _DEV_TO_MEM)
 560 *       -ENOMEM Memory exhausted
 561 */
 562 /****************************************************************************/
 563
 564 int dma_alloc_double_dst_descriptors(DMA_Handle_t handle,       /* DMA Handle */
 565                                      dma_addr_t srcData,        /* Physical address of source data */
 566                                      dma_addr_t dstData1,       /* Physical address of first destination buffer */
 567                                      dma_addr_t dstData2,       /* Physical address of second destination buffer */
 568                                      size_t numBytes    /* Number of bytes in each destination buffer */
 569     );
 570
 571 /****************************************************************************/
 572 /**
 573 *   Initializes a DMA_MemMap_t data structure
 574 */
 575 /****************************************************************************/
 576
 577 int dma_init_mem_map(DMA_MemMap_t *memMap       /* Stores state information about the map */
 578     );
 579
 580 /****************************************************************************/
 581 /**
 582 *   Releases any memory currently being held by a memory mapping structure.
 583 */
 584 /****************************************************************************/
 585
 586 int dma_term_mem_map(DMA_MemMap_t *memMap       /* Stores state information about the map */
 587     );
 588
 589 /****************************************************************************/
 590 /**
 591 *   Looks at a memory address and categorizes it.
 592 *
 593 *   @return One of the values from the DMA_MemType_t enumeration.
 594 */
 595 /****************************************************************************/
 596
 597 DMA_MemType_t dma_mem_type(void *addr);
 598
 599 /****************************************************************************/
 600 /**
 601 *   Sets the process (aka userTask) associated with a mem map. This is
 602 *   required if user-mode segments will be added to the mapping.
 603 */
 604 /****************************************************************************/
 605
 606 static inline void dma_mem_map_set_user_task(DMA_MemMap_t *memMap,
 607                                              struct task_struct *task)
 608 {
 609         memMap->userTask = task;
 610 }
 611
 612 /****************************************************************************/
 613 /**
 614 *   Looks at a memory address and determines if we support DMA'ing to/from
 615 *   that type of memory.
 616 *
 617 *   @return boolean -
 618 *               return value != 0 means dma supported
 619 *               return value == 0 means dma not supported
 620 */
 621 /****************************************************************************/
 622
 623 int dma_mem_supports_dma(void *addr);
 624
 625 /****************************************************************************/
 626 /**
 627 *   Initializes a memory map for use. Since this function acquires a
 628 *   sempaphore within the memory map, it is VERY important that dma_unmap
 629 *   be called when you're finished using the map.
 630 */
 631 /****************************************************************************/
 632
 633 int dma_map_start(DMA_MemMap_t *memMap, /* Stores state information about the map */
 634                   enum dma_data_direction dir   /* Direction that the mapping will be going */
 635     );
 636
 637 /****************************************************************************/
 638 /**
 639 *   Adds a segment of memory to a memory map.
 640 *
 641 *   @return     0 on success, error code otherwise.
 642 */
 643 /****************************************************************************/
 644
 645 int dma_map_add_region(DMA_MemMap_t *memMap,    /* Stores state information about the map */
 646                        void *mem,       /* Virtual address that we want to get a map of */
 647                        size_t numBytes  /* Number of bytes being mapped */
 648     );
 649
 650 /****************************************************************************/
 651 /**
 652 *   Creates a descriptor ring from a memory mapping.
 653 *
 654 *   @return 0 on success, error code otherwise.
 655 */
 656 /****************************************************************************/
 657
 658 int dma_map_create_descriptor_ring(DMA_Device_t dev,    /* DMA device (where the ring is stored) */
 659                                    DMA_MemMap_t *memMap,        /* Memory map that will be used */
 660                                    dma_addr_t devPhysAddr       /* Physical address of device */
 661     );
 662
 663 /****************************************************************************/
 664 /**
 665 *   Maps in a memory region such that it can be used for performing a DMA.
 666 *
 667 *   @return
 668 */
 669 /****************************************************************************/
 670
 671 int dma_map_mem(DMA_MemMap_t *memMap,   /* Stores state information about the map */
 672                 void *addr,     /* Virtual address that we want to get a map of */
 673                 size_t count,   /* Number of bytes being mapped */
 674                 enum dma_data_direction dir     /* Direction that the mapping will be going */
 675     );
 676
 677 /****************************************************************************/
 678 /**
 679 *   Maps in a memory region such that it can be used for performing a DMA.
 680 *
 681 *   @return
 682 */
 683 /****************************************************************************/
 684
 685 int dma_unmap(DMA_MemMap_t *memMap,     /* Stores state information about the map */
 686               int dirtied       /* non-zero if any of the pages were modified */
 687     );
 688
 689 /****************************************************************************/
 690 /**
 691 *   Initiates a transfer when the descriptors have already been setup.
 692 *
 693 *   This is a special case, and normally, the dma_transfer_xxx functions should
 694 *   be used.
 695 *
 696 *   @return
 697 *       0       Transfer was started successfully
 698 *       -ENODEV Invalid handle
 699 */
 700 /****************************************************************************/
 701
 702 int dma_start_transfer(DMA_Handle_t handle);
 703
 704 /****************************************************************************/
 705 /**
 706 *   Stops a previously started DMA transfer.
 707 *
 708 *   @return
 709 *       0       Transfer was stopped successfully
 710 *       -ENODEV Invalid handle
 711 */
 712 /****************************************************************************/
 713
 714 int dma_stop_transfer(DMA_Handle_t handle);
 715
 716 /****************************************************************************/
 717 /**
 718 *   Waits for a DMA to complete by polling. This function is only intended
 719 *   to be used for testing. Interrupts should be used for most DMA operations.
 720 */
 721 /****************************************************************************/
 722
 723 int dma_wait_transfer_done(DMA_Handle_t handle);
 724
 725 /****************************************************************************/
 726 /**
 727 *   Initiates a DMA transfer
 728 *
 729 *   @return
 730 *       0       Transfer was started successfully
 731 *       -EINVAL Invalid device type for this kind of transfer
 732 *               (i.e. the device is _MEM_TO_DEV and not _DEV_TO_MEM)
 733 */
 734 /****************************************************************************/
 735
 736 int dma_transfer(DMA_Handle_t handle,   /* DMA Handle */
 737                  dmacHw_TRANSFER_TYPE_e transferType,   /* Type of transfer being performed */
 738                  dma_addr_t srcData,    /* Place to get data to write to device */
 739                  dma_addr_t dstData,    /* Pointer to device data address */
 740                  size_t numBytes        /* Number of bytes to transfer to the device */
 741     );
 742
 743 /****************************************************************************/
 744 /**
 745 *   Initiates a transfer from memory to a device.
 746 *
 747 *   @return
 748 *       0       Transfer was started successfully
 749 *       -EINVAL Invalid device type for this kind of transfer
 750 *               (i.e. the device is _DEV_TO_MEM and not _MEM_TO_DEV)
 751 */
 752 /****************************************************************************/
 753
 754 static inline int dma_transfer_to_device(DMA_Handle_t handle,   /* DMA Handle */
 755                                          dma_addr_t srcData,    /* Place to get data to write to device (physical address) */
 756                                          dma_addr_t dstData,    /* Pointer to device data address (physical address) */
 757                                          size_t numBytes        /* Number of bytes to transfer to the device */
 758     ) {
 759         return dma_transfer(handle,
 760                             dmacHw_TRANSFER_TYPE_MEM_TO_PERIPHERAL,
 761                             srcData, dstData, numBytes);
 762 }
 763
 764 /****************************************************************************/
 765 /**
 766 *   Initiates a transfer from a device to memory.
 767 *
 768 *   @return
 769 *       0       Transfer was started successfully
 770 *       -EINVAL Invalid device type for this kind of transfer
 771 *               (i.e. the device is _MEM_TO_DEV and not _DEV_TO_MEM)
 772 */
 773 /****************************************************************************/
 774
 775 static inline int dma_transfer_from_device(DMA_Handle_t handle, /* DMA Handle */
 776                                            dma_addr_t srcData,  /* Pointer to the device data address (physical address) */
 777                                            dma_addr_t dstData,  /* Place to store data retrieved from the device (physical address) */
 778                                            size_t numBytes      /* Number of bytes to retrieve from the device */
 779     ) {
 780         return dma_transfer(handle,
 781                             dmacHw_TRANSFER_TYPE_PERIPHERAL_TO_MEM,
 782                             srcData, dstData, numBytes);
 783 }
 784
 785 /****************************************************************************/
 786 /**
 787 *   Initiates a memory to memory transfer.
 788 *
 789 *   @return
 790 *       0       Transfer was started successfully
 791 *       -EINVAL Invalid device type for this kind of transfer
 792 *               (i.e. the device wasn't DMA_DEVICE_MEM_TO_MEM)
 793 */
 794 /****************************************************************************/
 795
 796 static inline int dma_transfer_mem_to_mem(DMA_Handle_t handle,  /* DMA Handle */
 797                                           dma_addr_t srcData,   /* Place to transfer data from (physical address) */
 798                                           dma_addr_t dstData,   /* Place to transfer data to (physical address) */
 799                                           size_t numBytes       /* Number of bytes to transfer */
 800     ) {
 801         return dma_transfer(handle,
 802                             dmacHw_TRANSFER_TYPE_MEM_TO_MEM,
 803                             srcData, dstData, numBytes);
 804 }
 805
 806 /****************************************************************************/
 807 /**
 808 *   Set the callback function which will be called when a transfer completes.
 809 *   If a NULL callback function is set, then no callback will occur.
 810 *
 811 *   @note   @a devHandler will be called from IRQ context.
 812 *
 813 *   @return
 814 *       0       - Success
 815 *       -ENODEV - Device handed in is invalid.
 816 */
 817 /****************************************************************************/
 818
 819 int dma_set_device_handler(DMA_Device_t dev,    /* Device to set the callback for. */
 820                            DMA_DeviceHandler_t devHandler,      /* Function to call when the DMA completes */
 821                            void *userData       /* Pointer which will be passed to devHandler. */
 822     );
 823
 824 #endif
 825
 826 #endif /* ASM_ARM_ARCH_BCMRING_DMA_H */