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