IntelFrameworkModulePkg/Include/Protocol/IsaIo.h

   1 /** @file
   2   ISA I/O Protocol is used to perform ISA device Io/Mem operations.
   3
   4 Copyright (c) 2006 - 2009, Intel Corporation
   5 All rights reserved. This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef _EFI_ISA_IO_H_
  16 #define _EFI_ISA_IO_H_
  17
  18
  19 #include <Protocol/IsaAcpi.h>
  20
  21 //
  22 // Global GUID for the ISA I/O Protocol
  23 //
  24 #define EFI_ISA_IO_PROTOCOL_GUID \
  25   { 0x7ee2bd44, 0x3da0, 0x11d4, { 0x9a, 0x38, 0x0, 0x90, 0x27, 0x3f, 0xc1, 0x4d } }
  26
  27 typedef struct _EFI_ISA_IO_PROTOCOL EFI_ISA_IO_PROTOCOL;
  28
  29 //
  30 // Width of ISA Io/Mem operation
  31 //
  32 typedef enum {
  33   EfiIsaIoWidthUint8,
  34   EfiIsaIoWidthUint16,
  35   EfiIsaIoWidthUint32,
  36   EfiIsaIoWidthReserved,
  37   EfiIsaIoWidthFifoUint8,
  38   EfiIsaIoWidthFifoUint16,
  39   EfiIsaIoWidthFifoUint32,
  40   EfiIsaIoWidthFifoReserved,
  41   EfiIsaIoWidthFillUint8,
  42   EfiIsaIoWidthFillUint16,
  43   EfiIsaIoWidthFillUint32,
  44   EfiIsaIoWidthFillReserved,
  45   EfiIsaIoWidthMaximum
  46 } EFI_ISA_IO_PROTOCOL_WIDTH;
  47
  48 //
  49 // Attributes for common buffer allocations
  50 //
  51 #define EFI_ISA_IO_ATTRIBUTE_MEMORY_WRITE_COMBINE  0x080    ///< Map a memory range so write are combined
  52 #define EFI_ISA_IO_ATTRIBUTE_MEMORY_CACHED         0x800    ///< Map a memory range so all r/w accesses are cached
  53 #define EFI_ISA_IO_ATTRIBUTE_MEMORY_DISABLE        0x1000   ///< Disable a memory range
  54
  55 //
  56 // Channel attribute for DMA operations
  57 //
  58 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_COMPATIBLE  0x001
  59 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_A           0x002
  60 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_B           0x004
  61 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_C           0x008
  62 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_WIDTH_8           0x010
  63 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_WIDTH_16          0x020
  64 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SINGLE_MODE       0x040
  65 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_DEMAND_MODE       0x080
  66 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_AUTO_INITIALIZE   0x100
  67
  68 typedef enum {
  69   EfiIsaIoOperationBusMasterRead,
  70   EfiIsaIoOperationBusMasterWrite,
  71   EfiIsaIoOperationBusMasterCommonBuffer,
  72   EfiIsaIoOperationSlaveRead,
  73   EfiIsaIoOperationSlaveWrite,
  74   EfiIsaIoOperationMaximum
  75 } EFI_ISA_IO_PROTOCOL_OPERATION;
  76
  77 /**
  78   Performs an ISA Io/Memory Read/Write Cycle
  79
  80   @param This                    A pointer to the EFI_ISA_IO_PROTOCOL instance.
  81   @param Width                   Signifies the width of the Io/Memory operation.
  82   @param Offset                  The offset in ISA Io/Memory space to start the Io/Memory operation.
  83   @param Count                   The number of Io/Memory operations to perform.
  84   @param Buffer                  [OUT] The destination buffer to store the results.
  85                                  [IN] The source buffer to write data to the device.
  86
  87   @retval EFI_SUCCESS             The data was read from / written to the device sucessfully.
  88   @retval EFI_UNSUPPORTED         The Offset is not valid for this device.
  89   @retval EFI_INVALID_PARAMETER   Width or Count, or both, were invalid.
  90   @retval EFI_OUT_OF_RESOURCES    The request could not be completed due to a lack of resources.
  91
  92 **/
  93 typedef
  94 EFI_STATUS
  95 (EFIAPI *EFI_ISA_IO_PROTOCOL_IO_MEM) (
  96   IN     EFI_ISA_IO_PROTOCOL          *This,
  97   IN     EFI_ISA_IO_PROTOCOL_WIDTH    Width,
  98   IN     UINT32                       Offset,
  99   IN     UINTN                        Count,
 100   IN OUT VOID                         *Buffer
 101   );
 102
 103 typedef struct {
 104   EFI_ISA_IO_PROTOCOL_IO_MEM  Read;
 105   EFI_ISA_IO_PROTOCOL_IO_MEM  Write;
 106 } EFI_ISA_IO_PROTOCOL_ACCESS;
 107
 108 /**
 109   Performs an ISA I/O Copy Memory
 110
 111   @param This                    A pointer to the EFI_ISA_IO_PROTOCOL instance.
 112   @param Width                   Signifies the width of the memory copy operation.
 113   @param DestOffset              The offset of the destination
 114   @param SrcOffset               The offset of the source
 115   @param Count                   The number of memory copy  operations to perform
 116
 117   @retval EFI_SUCCESS             The data was copied sucessfully.
 118   @retval EFI_UNSUPPORTED         The DestOffset or SrcOffset is not valid for this device.
 119   @retval EFI_INVALID_PARAMETER   Width or Count, or both, were invalid.
 120   @retval EFI_OUT_OF_RESOURCES    The request could not be completed due to a lack of resources.
 121
 122 **/
 123 typedef
 124 EFI_STATUS
 125 (EFIAPI *EFI_ISA_IO_PROTOCOL_COPY_MEM) (
 126   IN     EFI_ISA_IO_PROTOCOL          *This,
 127   IN     EFI_ISA_IO_PROTOCOL_WIDTH    Width,
 128   IN     UINT32                       DestOffset,
 129   IN     UINT32                       SrcOffset,
 130   IN     UINTN                        Count
 131   );
 132
 133 /**
 134   Maps a memory region for DMA
 135
 136   @param This                    A pointer to the EFI_ISA_IO_PROTOCOL instance.
 137   @param Operation               Indicates the type of DMA (slave or bus master), and if
 138                                  the DMA operation is going to read or write to system memory.
 139   @param ChannelNumber           The slave channel number to use for this DMA operation.
 140                                  If Operation and ChannelAttributes shows that this device
 141                                  performs bus mastering DMA, then this field is ignored.
 142                                  The legal range for this field is 0..7.
 143   @param ChannelAttributes       The attributes of the DMA channel to use for this DMA operation
 144   @param HostAddress             The system memory address to map to the device.
 145   @param NumberOfBytes           On input the number of bytes to map.  On output the number
 146                                  of bytes that were mapped.
 147   @param DeviceAddress           The resulting map address for the bus master device to use
 148                                  to access the hosts HostAddress.
 149   @param Mapping                 A resulting value to pass to EFI_ISA_IO.Unmap().
 150
 151
 152   @retval EFI_SUCCESS             The range was mapped for the returned NumberOfBytes.
 153   @retval EFI_INVALID_PARAMETER   The Operation or HostAddress is undefined.
 154   @retval EFI_UNSUPPORTED         The HostAddress can not be mapped as a common buffer.
 155   @retval EFI_DEVICE_ERROR        The system hardware could not map the requested address.
 156   @retval EFI_OUT_OF_RESOURCES    The memory pages could not be allocated.
 157
 158 **/
 159 typedef
 160 EFI_STATUS
 161 (EFIAPI *EFI_ISA_IO_PROTOCOL_MAP) (
 162   IN     EFI_ISA_IO_PROTOCOL            *This,
 163   IN     EFI_ISA_IO_PROTOCOL_OPERATION  Operation,
 164   IN     UINT8                          ChannelNumber      OPTIONAL,
 165   IN     UINT32                         ChannelAttributes,
 166   IN     VOID                           *HostAddress,
 167   IN OUT UINTN                          *NumberOfBytes,
 168   OUT    EFI_PHYSICAL_ADDRESS           *DeviceAddress,
 169   OUT    VOID                           **Mapping
 170   );
 171
 172 /**
 173   Unmaps a memory region for DMA
 174
 175   @param This               A pointer to the EFI_ISA_IO_PROTOCOL instance.
 176   @param Mapping            The mapping value returned from EFI_ISA_IO.Map().
 177
 178   @retval EFI_SUCCESS        The range was unmapped.
 179   @retval EFI_DEVICE_ERROR   The data was not committed to the target system memory.
 180
 181 **/
 182 typedef
 183 EFI_STATUS
 184 (EFIAPI *EFI_ISA_IO_PROTOCOL_UNMAP) (
 185   IN  EFI_ISA_IO_PROTOCOL          *This,
 186   IN  VOID                         *Mapping
 187   );
 188
 189 /**
 190   Allocates a common buffer for DMA
 191
 192   @param This                    A pointer to the EFI_ISA_IO_PROTOCOL instance.
 193   @param Type                    The type allocation to perform.
 194   @param MemoryType              The type of memory to allocate.
 195   @param Pages                   The number of pages to allocate.
 196   @param HostAddress             A pointer to store the base address of the allocated range.
 197   @param Attributes              The requested bit mask of attributes for the allocated range.
 198
 199   @retval EFI_SUCCESS             The requested memory pages were allocated.
 200   @retval EFI_INVALID_PARAMETER   Type is invalid or MemoryType is invalid or HostAddress is NULL
 201   @retval EFI_UNSUPPORTED         Attributes is unsupported or the memory range specified
 202                                   by HostAddress, Pages, and Type is not available for common buffer use.
 203   @retval EFI_OUT_OF_RESOURCES    The memory pages could not be allocated.
 204
 205 **/
 206 typedef
 207 EFI_STATUS
 208 (EFIAPI *EFI_ISA_IO_PROTOCOL_ALLOCATE_BUFFER) (
 209   IN  EFI_ISA_IO_PROTOCOL          *This,
 210   IN  EFI_ALLOCATE_TYPE            Type,
 211   IN  EFI_MEMORY_TYPE              MemoryType,
 212   IN  UINTN                        Pages,
 213   OUT VOID                         **HostAddress,
 214   IN  UINT64                       Attributes
 215   );
 216
 217 /**
 218   Frees a common buffer
 219
 220   @param This                    A pointer to the EFI_ISA_IO_PROTOCOL instance.
 221   @param Pages                   The number of pages to free.
 222   @param HostAddress             The base address of the allocated range.
 223
 224
 225   @retval EFI_SUCCESS             The requested memory pages were freed.
 226   @retval EFI_INVALID_PARAMETER   The memory was not allocated with EFI_ISA_IO.AllocateBufer().
 227
 228 **/
 229 typedef
 230 EFI_STATUS
 231 (EFIAPI *EFI_ISA_IO_PROTOCOL_FREE_BUFFER) (
 232   IN  EFI_ISA_IO_PROTOCOL          *This,
 233   IN  UINTN                        Pages,
 234   IN  VOID                         *HostAddress
 235   );
 236
 237 /**
 238   Flushes a DMA buffer
 239
 240   @param This                 A pointer to the EFI_ISA_IO_PROTOCOL instance.
 241
 242   @retval  EFI_SUCCESS        The buffers were flushed.
 243   @retval  EFI_DEVICE_ERROR   The buffers were not flushed due to a hardware error.
 244
 245 **/
 246 typedef
 247 EFI_STATUS
 248 (EFIAPI *EFI_ISA_IO_PROTOCOL_FLUSH) (
 249   IN EFI_ISA_IO_PROTOCOL                  *This
 250   );
 251
 252 //
 253 // Interface structure for the ISA I/O Protocol
 254 //
 255 struct _EFI_ISA_IO_PROTOCOL {
 256   EFI_ISA_IO_PROTOCOL_ACCESS           Mem;
 257   EFI_ISA_IO_PROTOCOL_ACCESS           Io;
 258   EFI_ISA_IO_PROTOCOL_COPY_MEM         CopyMem;
 259   EFI_ISA_IO_PROTOCOL_MAP              Map;
 260   EFI_ISA_IO_PROTOCOL_UNMAP            Unmap;
 261   EFI_ISA_IO_PROTOCOL_ALLOCATE_BUFFER  AllocateBuffer;
 262   EFI_ISA_IO_PROTOCOL_FREE_BUFFER      FreeBuffer;
 263   EFI_ISA_IO_PROTOCOL_FLUSH            Flush;
 264   EFI_ISA_ACPI_RESOURCE_LIST           *ResourceList;
 265   UINT32                               RomSize;
 266   VOID                                 *RomImage;
 267 };
 268
 269 extern EFI_GUID gEfiIsaIoProtocolGuid;
 270
 271 #endif