Omap35xxPkg/Include/Library/OmapDmaLib.h

   1 /** @file
   2
   3   Abstractions for simple OMAP DMA. The DMA functions are modeled on
   4   the PCI IO protocol and follow the same rules as outlined in the UEFI specification.
   5   OMAP_DMA4 structure elements are described in the OMAP35xx TRM. Currently
   6   there is no PCI'less DMA protocol, if one existed it could be used to
   7   replace this library.
   8
   9   Copyright (c) 2008 - 2010, Apple Inc. All rights reserved.<BR>
  10
  11   This program and the accompanying materials
  12   are licensed and made available under the terms and conditions of the BSD License
  13   which accompanies this distribution.  The full text of the license may be found at
  14   http://opensource.org/licenses/bsd-license.php
  15
  16   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  17   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  18
  19 **/
  20
  21 #ifndef __OMAP_DMA_LIB_H__
  22 #define __OMAP_DMA_LIB_H__
  23
  24 typedef enum {
  25   ///
  26   /// A read operation from system memory by a bus master.
  27   ///
  28   MapOperationBusMasterRead,
  29   ///
  30   /// A write operation from system memory by a bus master.
  31   ///
  32   MapOperationBusMasterWrite,
  33   ///
  34   /// Provides both read and write access to system memory by both the processor and a
  35   /// bus master. The buffer is coherent from both the processor's and the bus master's point of view.
  36   ///
  37   MapOperationBusMasterCommonBuffer,
  38   MapOperationMaximum
  39 } DMA_MAP_OPERATION;
  40
  41
  42 // Example from DMA chapter of the OMAP35xx spec
  43 typedef struct {
  44   UINT8     DataType;                      // DMA4_CSDPi[1:0]
  45   UINT8     ReadPortAccessType;            // DMA4_CSDPi[8:7]
  46   UINT8     WritePortAccessType;           // DMA4_CSDPi[15:14]
  47   UINT8     SourceEndiansim;               // DMA4_CSDPi[21]
  48   UINT8     DestinationEndianism;          // DMA4_CSDPi[19]
  49   UINT8     WriteMode;                     // DMA4_CSDPi[17:16]
  50   UINT8     SourcePacked;                  // DMA4_CSDPi[6]
  51   UINT8     DestinationPacked;             // DMA4_CSDPi[13]
  52   UINT32    NumberOfElementPerFrame;       // DMA4_CENi
  53   UINT32    NumberOfFramePerTransferBlock; // DMA4_CFNi
  54   UINT32    SourceStartAddress;            // DMA4_CSSAi
  55   UINT32    DestinationStartAddress;       // DMA4_CDSAi
  56   UINT32    SourceElementIndex;            // DMA4_CSEi
  57   UINT32    SourceFrameIndex;              // DMA4_CSFi
  58   UINT32    DestinationElementIndex;       // DMA4_CDEi
  59   UINT32    DestinationFrameIndex;         // DMA4_CDFi
  60   UINT8     ReadPortAccessMode;            // DMA4_CCRi[13:12]
  61   UINT8     WritePortAccessMode;           // DMA4_CCRi[15:14]
  62   UINT8     ReadPriority;                  // DMA4_CCRi[6]
  63   UINT8     WritePriority;                 // DMA4_CCRi[23]
  64   UINT8     ReadRequestNumber;             // DMA4_CCRi[4:0]
  65   UINT8     WriteRequestNumber;            // DMA4_CCRi[20:19]
  66 } OMAP_DMA4;
  67
  68
  69 /**
  70   Configure OMAP DMA Channel
  71
  72   @param  Channel               DMA Channel to configure
  73   @param  Dma4                  Pointer to structure used to initialize DMA registers for the Channel
  74
  75   @retval EFI_SUCCESS           The range was mapped for the returned NumberOfBytes.
  76   @retval EFI_INVALID_PARAMETER Channel is not valid
  77   @retval EFI_DEVICE_ERROR      The system hardware could not map the requested information.
  78
  79 **/
  80 EFI_STATUS
  81 EFIAPI
  82 EnableDmaChannel (
  83   IN  UINTN       Channel,
  84   IN  OMAP_DMA4   *Dma4
  85   );
  86
  87 /**
  88   Turn of DMA channel configured by EnableDma().
  89
  90   @param  Channel               DMA Channel to configure
  91   @param  SuccesMask            Bits in DMA4_CSR register indicate EFI_SUCCESS
  92   @param  ErrorMask             Bits in DMA4_CSR register indicate EFI_DEVICE_ERROR
  93
  94   @retval EFI_SUCCESS           DMA hardware disabled
  95   @retval EFI_INVALID_PARAMETER Channel is not valid
  96   @retval EFI_DEVICE_ERROR      The system hardware could not map the requested information.
  97
  98 **/
  99 EFI_STATUS
 100 EFIAPI
 101 DisableDmaChannel (
 102   IN  UINTN       Channel,
 103   IN  UINT32      SuccessMask,
 104   IN  UINT32      ErrorMask
 105   );
 106
 107
 108 /**
 109   Provides the DMA controller-specific addresses needed to access system memory.
 110
 111   Operation is relative to the DMA bus master.
 112
 113   @param  Operation             Indicates if the bus master is going to read or write to system memory.
 114   @param  HostAddress           The system memory address to map to the DMA controller.
 115   @param  NumberOfBytes         On input the number of bytes to map. On output the number of bytes
 116                                 that were mapped.
 117   @param  DeviceAddress         The resulting map address for the bus master controller to use to
 118                                 access the hosts HostAddress.
 119   @param  Mapping               A resulting value to pass to Unmap().
 120
 121   @retval EFI_SUCCESS           The range was mapped for the returned NumberOfBytes.
 122   @retval EFI_UNSUPPORTED       The HostAddress cannot be mapped as a common buffer.
 123   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 124   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
 125   @retval EFI_DEVICE_ERROR      The system hardware could not map the requested address.
 126
 127 **/
 128 EFI_STATUS
 129 EFIAPI
 130 DmaMap (
 131   IN     DMA_MAP_OPERATION              Operation,
 132   IN     VOID                           *HostAddress,
 133   IN OUT UINTN                          *NumberOfBytes,
 134   OUT    PHYSICAL_ADDRESS               *DeviceAddress,
 135   OUT    VOID                           **Mapping
 136   );
 137
 138
 139
 140
 141 /**
 142   Completes the DmaMapBusMasterRead(), DmaMapBusMasterWrite(), or DmaMapBusMasterCommonBuffer()
 143   operation and releases any corresponding resources.
 144
 145   @param  Mapping               The mapping value returned from DmaMap*().
 146
 147   @retval EFI_SUCCESS           The range was unmapped.
 148   @retval EFI_DEVICE_ERROR      The data was not committed to the target system memory.
 149
 150 **/
 151 EFI_STATUS
 152 EFIAPI
 153 DmaUnmap (
 154   IN  VOID                         *Mapping
 155   );
 156
 157
 158 /**
 159   Allocates pages that are suitable for an DmaMap() of type MapOperationBusMasterCommonBuffer.
 160   mapping.
 161
 162   @param  MemoryType            The type of memory to allocate, EfiBootServicesData or
 163                                 EfiRuntimeServicesData.
 164   @param  Pages                 The number of pages to allocate.
 165   @param  HostAddress           A pointer to store the base system memory address of the
 166                                 allocated range.
 167
 168                                 @retval EFI_SUCCESS           The requested memory pages were allocated.
 169   @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are
 170                                 MEMORY_WRITE_COMBINE and MEMORY_CACHED.
 171   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 172   @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.
 173
 174 **/
 175 EFI_STATUS
 176 EFIAPI
 177 DmaAllocateBuffer (
 178   IN  EFI_MEMORY_TYPE              MemoryType,
 179   IN  UINTN                        Pages,
 180   OUT VOID                         **HostAddress
 181   );
 182
 183
 184 /**
 185   Frees memory that was allocated with DmaAllocateBuffer().
 186
 187   @param  Pages                 The number of pages to free.
 188   @param  HostAddress           The base system memory address of the allocated range.
 189
 190   @retval EFI_SUCCESS           The requested memory pages were freed.
 191   @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
 192                                 was not allocated with DmaAllocateBuffer().
 193
 194 **/
 195 EFI_STATUS
 196 EFIAPI
 197 DmaFreeBuffer (
 198   IN  UINTN                        Pages,
 199   IN  VOID                         *HostAddress
 200   );
 201
 202
 203 #endif
 204