MdePkg/Include/Protocol/DeviceIo.h

   1 /** @file
   2   Device IO protocol as defined in the EFI 1.10 specification.
   3
   4   Device IO is used to abstract hardware access to devices. It includes
   5   memory mapped IO, IO, PCI Config space, and DMA.
   6
   7   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   8   SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef __DEVICE_IO_H__
  13 #define __DEVICE_IO_H__
  14
  15 #define EFI_DEVICE_IO_PROTOCOL_GUID \
  16   { \
  17     0xaf6ac311, 0x84c3, 0x11d2, {0x8e, 0x3c, 0x00, 0xa0, 0xc9, 0x69, 0x72, 0x3b } \
  18   }
  19
  20 typedef struct _EFI_DEVICE_IO_PROTOCOL EFI_DEVICE_IO_PROTOCOL;
  21
  22 ///
  23 /// Protocol GUID name defined in EFI1.1.
  24 ///
  25 #define DEVICE_IO_PROTOCOL  EFI_DEVICE_IO_PROTOCOL_GUID
  26
  27 ///
  28 /// Protocol defined in EFI1.1.
  29 ///
  30 typedef EFI_DEVICE_IO_PROTOCOL EFI_DEVICE_IO_INTERFACE;
  31
  32 ///
  33 /// Device IO Access Width
  34 ///
  35 typedef enum {
  36   IO_UINT8  = 0,
  37   IO_UINT16 = 1,
  38   IO_UINT32 = 2,
  39   IO_UINT64 = 3,
  40   //
  41   // Below enumerations are added in "Extensible Firmware Interface Specification,
  42   // Version 1.10, Specification Update, Version 001".
  43   //
  44   MMIO_COPY_UINT8  = 4,
  45   MMIO_COPY_UINT16 = 5,
  46   MMIO_COPY_UINT32 = 6,
  47   MMIO_COPY_UINT64 = 7
  48 } EFI_IO_WIDTH;
  49
  50 /**
  51   Enables a driver to access device registers in the appropriate memory or I/O space.
  52
  53   @param  This                  A pointer to the EFI_DEVICE_IO_INTERFACE instance.
  54   @param  Width                 Signifies the width of the I/O operations.
  55   @param  Address               The base address of the I/O operations.
  56   @param  Count                 The number of I/O operations to perform.
  57   @param  Buffer                For read operations, the destination buffer to store the results. For write
  58                                 operations, the source buffer to write data from. If
  59                                 Width is MMIO_COPY_UINT8, MMIO_COPY_UINT16,
  60                                 MMIO_COPY_UINT32, or MMIO_COPY_UINT64, then
  61                                 Buffer is interpreted as a base address of an I/O operation such as Address.
  62
  63   @retval EFI_SUCCESS           The data was read from or written to the device.
  64   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
  65   @retval EFI_INVALID_PARAMETER Width is invalid.
  66
  67 **/
  68 typedef
  69 EFI_STATUS
  70 (EFIAPI *EFI_DEVICE_IO)(
  71   IN EFI_DEVICE_IO_PROTOCOL         *This,
  72   IN EFI_IO_WIDTH                   Width,
  73   IN UINT64                         Address,
  74   IN UINTN                          Count,
  75   IN OUT VOID                       *Buffer
  76   );
  77
  78 typedef struct {
  79   EFI_DEVICE_IO    Read;
  80   EFI_DEVICE_IO    Write;
  81 } EFI_IO_ACCESS;
  82
  83 /**
  84   Provides an EFI Device Path for a PCI device with the given PCI configuration space address.
  85
  86   @param  This                  A pointer to the EFI_DEVICE_IO_INTERFACE instance.
  87   @param  PciAddress            The PCI configuration space address of the device whose Device Path
  88                                 is going to be returned.
  89   @param  PciDevicePath         A pointer to the pointer for the EFI Device Path for PciAddress.
  90                                 Memory for the Device Path is allocated from the pool.
  91
  92   @retval EFI_SUCCESS           The PciDevicePath returns a pointer to a valid EFI Device Path.
  93   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
  94   @retval EFI_UNSUPPORTED       The PciAddress does not map to a valid EFI Device Path.
  95
  96 **/
  97 typedef
  98 EFI_STATUS
  99 (EFIAPI *EFI_PCI_DEVICE_PATH)(
 100   IN EFI_DEVICE_IO_PROTOCOL           *This,
 101   IN UINT64                           PciAddress,
 102   IN OUT EFI_DEVICE_PATH_PROTOCOL     **PciDevicePath
 103   );
 104
 105 typedef enum {
 106   ///
 107   /// A read operation from system memory by a bus master.
 108   ///
 109   EfiBusMasterRead,
 110
 111   ///
 112   /// A write operation to system memory by a bus master.
 113   ///
 114   EfiBusMasterWrite,
 115
 116   ///
 117   /// Provides both read and write access to system memory
 118   /// by both the processor and a bus master. The buffer is
 119   /// coherent from both the processor's and the bus master's
 120   /// point of view.
 121   ///
 122   EfiBusMasterCommonBuffer
 123 } EFI_IO_OPERATION_TYPE;
 124
 125 /**
 126   Provides the device-specific addresses needed to access system memory.
 127
 128   @param  This                  A pointer to the EFI_DEVICE_IO_INTERFACE instance.
 129   @param  Operation             Indicates if the bus master is going to read or write to system memory.
 130   @param  HostAddress           The system memory address to map to the device.
 131   @param  NumberOfBytes         On input, the number of bytes to map.
 132                                 On output, the number of bytes that were mapped.
 133   @param  DeviceAddress         The resulting map address for the bus master device to use to access the
 134                                 hosts HostAddress.
 135   @param  Mapping               A resulting value to pass to Unmap().
 136
 137   @retval EFI_SUCCESS           The range was mapped for the returned NumberOfBytes.
 138   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
 139   @retval EFI_UNSUPPORTED       The HostAddress cannot be mapped as a common buffer.
 140   @retval EFI_INVALID_PARAMETER The Operation or HostAddress is undefined.
 141   @retval EFI_DEVICE_ERROR      The system hardware could not map the requested address.
 142
 143 **/
 144 typedef
 145 EFI_STATUS
 146 (EFIAPI *EFI_IO_MAP)(
 147   IN EFI_DEVICE_IO_PROTOCOL           *This,
 148   IN EFI_IO_OPERATION_TYPE            Operation,
 149   IN EFI_PHYSICAL_ADDRESS             *HostAddress,
 150   IN OUT UINTN                        *NumberOfBytes,
 151   OUT EFI_PHYSICAL_ADDRESS            *DeviceAddress,
 152   OUT VOID                            **Mapping
 153   );
 154
 155 /**
 156   Completes the Map() operation and releases any corresponding resources.
 157
 158   @param  This                  A pointer to the EFI_DEVICE_IO_INTERFACE instance.
 159   @param  Mapping               A resulting value to pass to Unmap().
 160
 161   @retval EFI_SUCCESS           The range was mapped for the returned NumberOfBytes.
 162   @retval EFI_DEVICE_ERROR      The system hardware could not map the requested address.
 163
 164 **/
 165 typedef
 166 EFI_STATUS
 167 (EFIAPI *EFI_IO_UNMAP)(
 168   IN EFI_DEVICE_IO_PROTOCOL           *This,
 169   IN VOID                             *Mapping
 170   );
 171
 172 /**
 173   Allocates pages that are suitable for an EFIBusMasterCommonBuffer mapping.
 174
 175   @param  This                  A pointer to the EFI_DEVICE_IO_INTERFACE instance.
 176   @param  Type                  The type allocation to perform.
 177   @param  MemoryType            The type of memory to allocate, EfiBootServicesData or
 178                                 EfiRuntimeServicesData.
 179   @param  Pages                 The number of pages to allocate.
 180   @param  HostAddress           A pointer to store the base address of the allocated range.
 181
 182   @retval EFI_SUCCESS           The requested memory pages were allocated.
 183   @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.
 184   @retval EFI_INVALID_PARAMETER The requested memory type is invalid.
 185   @retval EFI_UNSUPPORTED       The requested HostAddress is not supported on
 186                                 this platform.
 187
 188 **/
 189 typedef
 190 EFI_STATUS
 191 (EFIAPI *EFI_IO_ALLOCATE_BUFFER)(
 192   IN EFI_DEVICE_IO_PROTOCOL           *This,
 193   IN EFI_ALLOCATE_TYPE                Type,
 194   IN EFI_MEMORY_TYPE                  MemoryType,
 195   IN UINTN                            Pages,
 196   IN OUT EFI_PHYSICAL_ADDRESS         *HostAddress
 197   );
 198
 199 /**
 200   Flushes any posted write data to the device.
 201
 202   @param  This                  A pointer to the EFI_DEVICE_IO_INTERFACE instance.
 203
 204   @retval EFI_SUCCESS           The buffers were flushed.
 205   @retval EFI_DEVICE_ERROR      The buffers were not flushed due to a hardware error.
 206
 207 **/
 208 typedef
 209 EFI_STATUS
 210 (EFIAPI *EFI_IO_FLUSH)(
 211   IN EFI_DEVICE_IO_PROTOCOL  *This
 212   );
 213
 214 /**
 215   Frees pages that were allocated with AllocateBuffer().
 216
 217   @param  This                  A pointer to the EFI_DEVICE_IO_INTERFACE instance.
 218   @param  Pages                 The number of pages to free.
 219   @param  HostAddress           The base address of the range to free.
 220
 221   @retval EFI_SUCCESS           The requested memory pages were allocated.
 222   @retval EFI_NOT_FOUND         The requested memory pages were not allocated with
 223                                 AllocateBuffer().
 224   @retval EFI_INVALID_PARAMETER HostAddress is not page aligned or Pages is invalid.
 225
 226 **/
 227 typedef
 228 EFI_STATUS
 229 (EFIAPI *EFI_IO_FREE_BUFFER)(
 230   IN EFI_DEVICE_IO_PROTOCOL           *This,
 231   IN UINTN                            Pages,
 232   IN EFI_PHYSICAL_ADDRESS             HostAddress
 233   );
 234
 235 ///
 236 /// This protocol provides the basic Memory, I/O, and PCI interfaces that
 237 /// are used to abstract accesses to devices.
 238 ///
 239 struct _EFI_DEVICE_IO_PROTOCOL {
 240   ///
 241   /// Allows reads and writes to memory mapped I/O space.
 242   ///
 243   EFI_IO_ACCESS             Mem;
 244   ///
 245   /// Allows reads and writes to I/O space.
 246   ///
 247   EFI_IO_ACCESS             Io;
 248   ///
 249   /// Allows reads and writes to PCI configuration space.
 250   ///
 251   EFI_IO_ACCESS             Pci;
 252   EFI_IO_MAP                Map;
 253   EFI_PCI_DEVICE_PATH       PciDevicePath;
 254   EFI_IO_UNMAP              Unmap;
 255   EFI_IO_ALLOCATE_BUFFER    AllocateBuffer;
 256   EFI_IO_FLUSH              Flush;
 257   EFI_IO_FREE_BUFFER        FreeBuffer;
 258 };
 259
 260 extern EFI_GUID  gEfiDeviceIoProtocolGuid;
 261
 262 #endif