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