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 263