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 - 2010, Intel Corporation. All rights reserved.<BR> 6 This program and the accompanying materials are licensed and made available under 7 the terms and conditions of the BSD License that accompanies this distribution. 8 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 363