IntelFrameworkModulePkg/Include/Protocol/IsaIo.h

   1 /** @file
   2   ISA I/O Protocol is used by ISA device drivers to perform I/O, MMIO and DMA
   3   operations on the ISA controllers they manage.
   4
   5   Copyright (c) 2006 - 2009, Intel Corporation
   6   All rights reserved. This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef _EFI_ISA_IO_H_
  17 #define _EFI_ISA_IO_H_
  18
  19 #include <Protocol/IsaAcpi.h>
  20
  21 ///
  22 /// Global ID for the EFI_ISA_IO_PROTOCOL
  23 ///
  24 #define EFI_ISA_IO_PROTOCOL_GUID \
  25   { \
  26     0x7ee2bd44, 0x3da0, 0x11d4, { 0x9a, 0x38, 0x0, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \
  27   }
  28
  29 ///
  30 /// Forward declaration for the EFI_ISA_IO_PROTOCOL
  31 ///
  32 typedef struct _EFI_ISA_IO_PROTOCOL EFI_ISA_IO_PROTOCOL;
  33
  34 ///
  35 /// Width of EFI_ISA_IO_PROTOCOL I/O Port and MMIO operations
  36 ///
  37 typedef enum {
  38   EfiIsaIoWidthUint8 = 0,      ///< 8-bit operation
  39   EfiIsaIoWidthUint16,         ///< 16-bit operation
  40   EfiIsaIoWidthUint32,         ///< 32-bit operation
  41   EfiIsaIoWidthReserved,
  42   EfiIsaIoWidthFifoUint8,      ///< 8-bit FIFO operation
  43   EfiIsaIoWidthFifoUint16,     ///< 16-bit FIFO operation
  44   EfiIsaIoWidthFifoUint32,     ///< 32-bit FIFO operation
  45   EfiIsaIoWidthFifoReserved,
  46   EfiIsaIoWidthFillUint8,      ///< 8-bit Fill operation
  47   EfiIsaIoWidthFillUint16,     ///< 16-bit Fill operation
  48   EfiIsaIoWidthFillUint32,     ///< 32-bit Fill operation
  49   EfiIsaIoWidthFillReserved,
  50   EfiIsaIoWidthMaximum
  51 } EFI_ISA_IO_PROTOCOL_WIDTH;
  52
  53 ///
  54 /// Attributes for the EFI_ISA_IO_PROTOCOL common DMA buffer allocations
  55 ///
  56 #define EFI_ISA_IO_ATTRIBUTE_MEMORY_WRITE_COMBINE  0x080    ///< Map a memory range so write are combined
  57 #define EFI_ISA_IO_ATTRIBUTE_MEMORY_CACHED         0x800    ///< Map a memory range so all read and write accesses are cached
  58 #define EFI_ISA_IO_ATTRIBUTE_MEMORY_DISABLE        0x1000   ///< Disable a memory range
  59
  60 ///
  61 /// Channel attribute for EFI_ISA_IO_PROTOCOL slave DMA requests
  62 ///
  63 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_COMPATIBLE  0x001   ///< Set the speed of the DMA transfer in compatible mode
  64 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_A           0x002   ///< Not supported
  65 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_B           0x004   ///< Not supported
  66 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SPEED_C           0x008   ///< Not supported
  67 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_WIDTH_8           0x010   ///< Request 8-bit DMA transfers.  Only available on channels 0..3
  68 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_WIDTH_16          0x020   ///< Request 16-bit DMA transfers.  Only available on channels 4..7
  69 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_SINGLE_MODE       0x040   ///< Request a single DMA transfer
  70 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_DEMAND_MODE       0x080   ///< Request multiple DMA transfers until TC (Terminal Count) or EOP (End of Process)
  71 #define EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_AUTO_INITIALIZE   0x100   ///< Automatically reload base and count at the end of the DMA transfer
  72
  73 ///
  74 /// The DMA opreration type for EFI_ISA_IO_PROTOCOL DMA requests
  75 ///
  76 typedef enum {
  77   ///
  78   /// A read operation from system memory by a bus master.
  79   ///
  80   EfiIsaIoOperationBusMasterRead,
  81   ///
  82   /// A write operation to system memory by a bus master.
  83   ///
  84   EfiIsaIoOperationBusMasterWrite,
  85   ///
  86   /// Provides both read and write access to system memory by both the processor
  87   /// and a bus master. The buffer is coherent from both the processor's and the
  88   /// bus master's point of view.
  89   ///
  90   EfiIsaIoOperationBusMasterCommonBuffer,
  91   ///
  92   /// A read operation from system memory by a slave device.
  93   ///
  94   EfiIsaIoOperationSlaveRead,
  95   ///
  96   /// A write operation to system memory by a slave master.
  97   ///
  98   EfiIsaIoOperationSlaveWrite,
  99   EfiIsaIoOperationMaximum
 100 } EFI_ISA_IO_PROTOCOL_OPERATION;
 101
 102 /**
 103   Performs ISA I/O and MMIO Read/Write Cycles
 104
 105   @param[in]      This     A pointer to the EFI_ISA_IO_PROTOCOL instance.
 106   @param[in]      Width    Specifies the width of the I/O or MMIO operation.
 107   @param[in]      Offset   The offset into the ISA I/O or MMIO space to start the
 108                            operation.
 109   @param[in]      Count    The number of I/O or MMIO operations to perform.
 110   @param[in, out] Buffer   For read operations, the destination buffer to store
 111                            the results. For write operations, the source buffer to
 112                            write data from.
 113
 114   @retval EFI_SUCCESS             The data was successfully read from or written to the device.
 115   @retval EFI_UNSUPPORTED         The Offset is not valid for this device.
 116   @retval EFI_INVALID_PARAMETER   Width or Count, or both, were invalid.
 117   @retval EFI_OUT_OF_RESOURCES    The request could not be completed due to a lack of resources.
 118
 119 **/
 120 typedef
 121 EFI_STATUS
 122 (EFIAPI *EFI_ISA_IO_PROTOCOL_IO_MEM)(
 123   IN     EFI_ISA_IO_PROTOCOL        *This,
 124   IN     EFI_ISA_IO_PROTOCOL_WIDTH  Width,
 125   IN     UINT32                     Offset,
 126   IN     UINTN                      Count,
 127   IN OUT VOID                       *Buffer
 128   );
 129
 130 ///
 131 /// Structure of functions for accessing ISA I/O and MMIO space
 132 ///
 133 typedef struct {
 134   ///
 135   /// Read from ISA I/O or MMIO space.
 136   ///
 137   EFI_ISA_IO_PROTOCOL_IO_MEM  Read;
 138   ///
 139   /// Write to ISA I/O or MMIO space.
 140   ///
 141   EFI_ISA_IO_PROTOCOL_IO_MEM  Write;
 142 } EFI_ISA_IO_PROTOCOL_ACCESS;
 143
 144 /**
 145   Copies data from one region of ISA MMIO space to another region of ISA
 146   MMIO space.
 147
 148   @param[in] This         A pointer to the EFI_ISA_IO_PROTOCOL instance.
 149   @param[in] Width        Specifies the width of the MMIO copy operation.
 150   @param[in] DestOffset   The offset of the destination in ISA MMIO space
 151   @param[in] SrcOffset    The offset of the source in ISA MMIO space
 152   @param[in] Count        The number tranfers to perform for this copy operation
 153
 154   @retval EFI_SUCCESS             The data was copied sucessfully.
 155   @retval EFI_UNSUPPORTED         The DestOffset or SrcOffset is not valid for this device.
 156   @retval EFI_INVALID_PARAMETER   Width or Count, or both, were invalid.
 157   @retval EFI_OUT_OF_RESOURCES    The request could not be completed due to a lack of resources.
 158
 159 **/
 160 typedef
 161 EFI_STATUS
 162 (EFIAPI *EFI_ISA_IO_PROTOCOL_COPY_MEM)(
 163   IN EFI_ISA_IO_PROTOCOL         *This,
 164   IN EFI_ISA_IO_PROTOCOL_WIDTH   Width,
 165   IN UINT32                      DestOffset,
 166   IN UINT32                      SrcOffset,
 167   IN UINTN                       Count
 168   );
 169
 170 /**
 171   Maps a memory region for DMA.
 172
 173   This function returns the device-specific addresses required to access system memory.
 174   This function is used to map system memory for ISA DMA operations.  All ISA DMA
 175   operations must be performed through their mapped addresses, and such mappings must
 176   be freed with EFI_ISA_IO_PROTOCOL.Unmap() after the DMA operation is completed.
 177
 178   If the DMA operation is a single read or write data transfer through an ISA bus
 179   master, then EfiIsaIoOperationBusMasterRead or EfiIsaIoOperationBusMasterWrite
 180   is used and the range is unmapped to complete the operation. If the DMA operation
 181   is a single read or write data transfer through an ISA slave controller, then
 182   EfiIsaIoOperationSlaveRead or EfiIsaIoOperationSlaveWrite is used and the range
 183   is unmapped to complete the operation.
 184
 185   If performing a DMA read operation, all the data must be present in system memory before the Map() is performed.  Similarly,
 186   if performing a DMA write operation, the data must not be accessed in system
 187   memory until EFI_ISA_IO_PROTOCOL.Unmap() is performed.  Bus master operations that
 188   require both read and write access or require multiple host device interactions
 189   within the same mapped region must use EfiIsaIoOperationBusMasterCommonBuffer.
 190   However, only memory allocated via the EFI_ISA_IO_PROTOCOL.AllocateBuffer() interface
 191   is guaranteed to be able to be mapped for this operation type.  In all mapping
 192   requests the NumberOfBytes returned may be less than originally requested.  It is
 193   the caller's responsibility to make additional requests to complete the entire
 194   transfer.
 195
 196   @param[in]      This                A pointer to the EFI_ISA_IO_PROTOCOL instance.
 197   @param[in]      Operation           Indicates the type of DMA (slave or bus master),
 198                                       and if the DMA operation is going to read or
 199                                       write to system memory.
 200   @param[in]      ChannelNumber       The slave channel number to use for this DMA
 201                                       operation.  If Operation and ChannelAttributes
 202                                       shows that this device performs bus mastering
 203                                       DMA, then this field is ignored.  The legal
 204                                       range for this field is 0..7.
 205   @param[in]      ChannelAttributes   A bitmask of the attributes used to configure
 206                                       the slave DMA channel for this DMA operation.
 207                                       See EFI_ISA_IO_SLAVE_DMA_ATTRIBUTE_* for the
 208                                       legal bit combinations.
 209   @param[in]      HostAddress         The system memory address to map to the device.
 210   @param[in, out] NumberOfBytes       On input the number of bytes to map.  On
 211                                       output the number of bytes that were mapped.
 212   @param[out]     DeviceAddress       The resulting map address for the bus master
 213                                       device to use to access the hosts HostAddress.
 214   @param[out]     Mapping             A returned value that must be passed to into
 215                                       EFI_ISA_IO_PROTOCOL.Unmap() to free all the the
 216                                       resources associated with this map request.
 217
 218   @retval EFI_SUCCESS             The range was mapped for the returned NumberOfBytes.
 219   @retval EFI_INVALID_PARAMETER   The Operation is undefined.
 220   @retval EFI_INVALID_PARAMETER   The HostAddress is undefined.
 221   @retval EFI_UNSUPPORTED         The HostAddress can not be mapped as a common buffer.
 222   @retval EFI_DEVICE_ERROR        The system hardware could not map the requested address.
 223   @retval EFI_OUT_OF_RESOURCES    The memory pages could not be allocated.
 224
 225 **/
 226 typedef
 227 EFI_STATUS
 228 (EFIAPI *EFI_ISA_IO_PROTOCOL_MAP)(
 229   IN     EFI_ISA_IO_PROTOCOL            *This,
 230   IN     EFI_ISA_IO_PROTOCOL_OPERATION  Operation,
 231   IN     UINT8                          ChannelNumber      OPTIONAL,
 232   IN     UINT32                         ChannelAttributes,
 233   IN     VOID                           *HostAddress,
 234   IN OUT UINTN                          *NumberOfBytes,
 235   OUT    EFI_PHYSICAL_ADDRESS           *DeviceAddress,
 236   OUT    VOID                           **Mapping
 237   );
 238
 239 /**
 240   Unmaps a memory region that was previously mapped with EFI_ISA_IO_PROTOCOL.Map()
 241
 242   The EFI_ISA_IO_PROTOCOL.Map() operation is completed and any corresponding
 243   resources are released.  If the operation was EfiIsaIoOperationSlaveWrite
 244   or EfiIsaIoOperationBusMasterWrite, the data is committed to system memory.
 245   Any resources used for the mapping are freed.
 246
 247   @param[in] This           A pointer to the EFI_ISA_IO_PROTOCOL instance.
 248   @param[in] Mapping        The mapping value returned from EFI_ISA_IO_PROTOCOL.Map().
 249
 250   @retval EFI_SUCCESS       The memory region was unmapped.
 251   @retval EFI_DEVICE_ERROR  The data was not committed to the target system memory.
 252 **/
 253 typedef
 254 EFI_STATUS
 255 (EFIAPI *EFI_ISA_IO_PROTOCOL_UNMAP)(
 256   IN  EFI_ISA_IO_PROTOCOL  *This,
 257   IN  VOID                 *Mapping
 258   );
 259
 260 /**
 261   Allocates pages that are suitable for an EfiIsaIoOperationBusMasterCommonBuffer
 262   mapping.
 263
 264   @param[in]  This          A pointer to the EFI_ISA_IO_PROTOCOL instance.
 265   @param[in]  Type          The type allocation to perform.
 266   @param[in]  MemoryType    The type of memory to allocate.
 267   @param[in]  Pages         The number of pages to allocate.
 268   @param[out] HostAddress   A pointer to store the base address of the allocated range.
 269   @param[in]  Attributes    The requested bit mask of attributes for the allocated range.
 270
 271   @retval EFI_SUCCESS             The requested memory pages were allocated.
 272   @retval EFI_INVALID_PARAMETER   Type is invalid.
 273   @retval EFI_INVALID_PARAMETER   MemoryType is invalid
 274   @retval EFI_INVALID_PARAMETER   HostAddress is NULL
 275   @retval EFI_UNSUPPORTED         Attributes is unsupported.
 276   @retval EFI_UNSUPPORTED         The memory range specified by HostAddress, Pages,
 277                                   and Type is not available for common buffer use.
 278   @retval EFI_OUT_OF_RESOURCES    The memory pages could not be allocated.
 279
 280 **/
 281 typedef
 282 EFI_STATUS
 283 (EFIAPI *EFI_ISA_IO_PROTOCOL_ALLOCATE_BUFFER)(
 284   IN  EFI_ISA_IO_PROTOCOL  *This,
 285   IN  EFI_ALLOCATE_TYPE    Type,
 286   IN  EFI_MEMORY_TYPE      MemoryType,
 287   IN  UINTN                Pages,
 288   OUT VOID                 **HostAddress,
 289   IN  UINT64               Attributes
 290   );
 291
 292 /**
 293   Frees a common buffer that was allocated with EFI_ISA_IO_PROTOCOL.AllocateBuffer()
 294
 295   @param[in] This          A pointer to the EFI_ISA_IO_PROTOCOL instance.
 296   @param[in] Pages         The number of pages to free from the previously allocated common buffer.
 297   @param[in] HostAddress   The base address of the previously allocated common buffer.
 298
 299
 300   @retval EFI_SUCCESS             The requested memory pages were freed.
 301   @retval EFI_INVALID_PARAMETER   The memory was not allocated with EFI_ISA_IO.AllocateBufer().
 302
 303 **/
 304 typedef
 305 EFI_STATUS
 306 (EFIAPI *EFI_ISA_IO_PROTOCOL_FREE_BUFFER)(
 307   IN  EFI_ISA_IO_PROTOCOL  *This,
 308   IN  UINTN                Pages,
 309   IN  VOID                 *HostAddress
 310   );
 311
 312 /**
 313   Flushes a DMA buffer, which forces all DMA posted write transactions to complete.
 314
 315   @param[in] This   A pointer to the EFI_ISA_IO_PROTOCOL instance.
 316
 317   @retval  EFI_SUCCESS        The DMA buffers were flushed.
 318   @retval  EFI_DEVICE_ERROR   The buffers were not flushed due to a hardware error.
 319
 320 **/
 321 typedef
 322 EFI_STATUS
 323 (EFIAPI *EFI_ISA_IO_PROTOCOL_FLUSH)(
 324   IN EFI_ISA_IO_PROTOCOL  *This
 325   );
 326
 327 ///
 328 /// The EFI_ISA_IO_PROTOCOL provides the basic Memory, I/O, and DMA interfaces
 329 /// used to abstract accesses to ISA controllers.  There is one EFI_ISA_IO_PROTOCOL
 330 /// instance for each ISA controller on a ISA bus. A device driver that wishes
 331 /// to manage an ISA controller in a system will have to retrieve the
 332 /// ISA_PCI_IO_PROTOCOL instance associated with the ISA controller.
 333 ///
 334 struct _EFI_ISA_IO_PROTOCOL {
 335   EFI_ISA_IO_PROTOCOL_ACCESS           Mem;
 336   EFI_ISA_IO_PROTOCOL_ACCESS           Io;
 337   EFI_ISA_IO_PROTOCOL_COPY_MEM         CopyMem;
 338   EFI_ISA_IO_PROTOCOL_MAP              Map;
 339   EFI_ISA_IO_PROTOCOL_UNMAP            Unmap;
 340   EFI_ISA_IO_PROTOCOL_ALLOCATE_BUFFER  AllocateBuffer;
 341   EFI_ISA_IO_PROTOCOL_FREE_BUFFER      FreeBuffer;
 342   EFI_ISA_IO_PROTOCOL_FLUSH            Flush;
 343   ///
 344   /// The list of I/O , MMIO, DMA, and Interrupt resources associated with the
 345   /// ISA controller abstracted by this instance of the EFI_ISA_IO_PROTOCOL.
 346   ///
 347   EFI_ISA_ACPI_RESOURCE_LIST           *ResourceList;
 348   ///
 349   /// The size, in bytes, of the ROM image.
 350   ///
 351   UINT32                               RomSize;
 352   ///
 353   /// A pointer to the in memory copy of the ROM image. The ISA Bus Driver is responsible
 354   /// for allocating memory for the ROM image, and copying the contents of the ROM to memory
 355   /// during ISA Bus initialization.
 356   ///
 357   VOID                                 *RomImage;
 358 };
 359
 360 extern EFI_GUID gEfiIsaIoProtocolGuid;
 361
 362 #endif