iPXE
efi.h
Go to the documentation of this file.
1 #ifndef _IPXE_EFI_H
2 #define _IPXE_EFI_H
3 
4 /** @file
5  *
6  * EFI API
7  *
8  * The intention is to include near-verbatim copies of the EFI headers
9  * required by iPXE. This is achieved using the import.pl script in
10  * this directory. Run the import script to update the local copies
11  * of the headers:
12  *
13  * ./import.pl /path/to/edk2/edk2
14  *
15  * where /path/to/edk2/edk2 is the path to your local checkout of the
16  * EFI Development Kit.
17  *
18  * Note that import.pl will modify any #include lines in each imported
19  * header to reflect its new location within the iPXE tree. It will
20  * also tidy up the file by removing carriage return characters and
21  * trailing whitespace.
22  */
23 
24 FILE_LICENCE ( GPL2_OR_LATER );
25 
26 /* EFI headers rudely redefine NULL */
27 #undef NULL
28 
29 /* EFI headers redefine ARRAY_SIZE */
30 #undef ARRAY_SIZE
31 
32 /* EFI headers think your compiler uses the MS ABI by default on X64 */
33 #if __x86_64__
34 #define EFIAPI __attribute__((ms_abi))
35 #endif
36 
37 /* EFI headers assume regparm(0) on i386, but that is not the case for iPXE */
38 #if __i386__
39 #define EFIAPI __attribute__((cdecl,regparm(0)))
40 #endif
41 
42 /* EFI headers define EFI_HANDLE as a void pointer, which renders type
43  * checking somewhat useless. Work around this bizarre sabotage
44  * attempt by redefining EFI_HANDLE as a pointer to an anonymous
45  * structure.
46  */
47 #define EFI_HANDLE STUPID_EFI_HANDLE
49 #undef EFI_HANDLE
50 typedef struct {} *EFI_HANDLE;
51 
52 /* Include the top-level EFI header files */
53 #include <ipxe/efi/Uefi.h>
54 #include <ipxe/efi/PiDxe.h>
56 
57 /* Reset any trailing #pragma pack directives */
58 #pragma pack(1)
59 #pragma pack()
60 
61 #include <ipxe/tables.h>
62 #include <ipxe/uuid.h>
63 #include <ipxe/version.h>
64 #include <ipxe/profile.h>
65 
66 /** An EFI saved task priority level */
67 struct efi_saved_tpl {
68  /** Current external TPL */
70  /** Previous external TPL */
72 };
73 
74 /** An EFI protocol used by iPXE */
75 struct efi_protocol {
76  /** GUID */
78  /** Variable containing pointer to protocol structure */
79  void **protocol;
80  /** Protocol is required */
81  int required;
82 };
83 
84 /** EFI protocol table */
85 #define EFI_PROTOCOLS __table ( struct efi_protocol, "efi_protocols" )
86 
87 /** Declare an EFI protocol used by iPXE */
88 #define __efi_protocol __table_entry ( EFI_PROTOCOLS, 01 )
89 
90 /** Declare an EFI protocol to be required by iPXE
91  *
92  * @v _protocol EFI protocol name
93  * @v _ptr Pointer to protocol instance
94  */
95 #define EFI_REQUIRE_PROTOCOL( _protocol, _ptr ) \
96  struct efi_protocol __ ## _protocol __efi_protocol = { \
97  .guid = _protocol ## _GUID, \
98  .protocol = ( ( void ** ) ( void * ) \
99  ( ( (_ptr) == ( ( _protocol ** ) (_ptr) ) ) ? \
100  (_ptr) : (_ptr) ) ), \
101  .required = 1, \
102  }
103 
104 /** Declare an EFI protocol to be requested by iPXE
105  *
106  * @v _protocol EFI protocol name
107  * @v _ptr Pointer to protocol instance
108  */
109 #define EFI_REQUEST_PROTOCOL( _protocol, _ptr ) \
110  struct efi_protocol __ ## _protocol __efi_protocol = { \
111  .guid = _protocol ## _GUID, \
112  .protocol = ( ( void ** ) ( void * ) \
113  ( ( (_ptr) == ( ( _protocol ** ) (_ptr) ) ) ? \
114  (_ptr) : (_ptr) ) ), \
115  .required = 0, \
116  }
117 
118 /** An EFI configuration table used by iPXE */
120  /** GUID */
122  /** Variable containing pointer to configuration table */
123  void **table;
124  /** Table is required for operation */
125  int required;
126 };
127 
128 /** EFI configuration table table */
129 #define EFI_CONFIG_TABLES \
130  __table ( struct efi_config_table, "efi_config_tables" )
131 
132 /** Declare an EFI configuration table used by iPXE */
133 #define __efi_config_table __table_entry ( EFI_CONFIG_TABLES, 01 )
134 
135 /** Declare an EFI configuration table to be used by iPXE
136  *
137  * @v _table EFI configuration table name
138  * @v _ptr Pointer to configuration table
139  * @v _required Table is required for operation
140  */
141 #define EFI_USE_TABLE( _table, _ptr, _required ) \
142  struct efi_config_table __ ## _table __efi_config_table = { \
143  .guid = _table ## _GUID, \
144  .table = ( ( void ** ) ( void * ) (_ptr) ), \
145  .required = (_required), \
146  }
147 
148 /**
149  * Convert an iPXE status code to an EFI status code
150  *
151  * @v rc iPXE status code
152  * @ret efirc EFI status code
153  */
154 #define EFIRC( rc ) ERRNO_TO_PLATFORM ( -(rc) )
155 
156 /**
157  * Convert an EFI status code to an iPXE status code
158  *
159  * @v efirc EFI status code
160  * @ret rc iPXE status code (before negation)
161  */
162 #define EEFI( efirc ) EPLATFORM ( EINFO_EPLATFORM, efirc )
163 
218 
221 
228 extern int efi_shutdown_in_progress;
229 
230 extern const __attribute__ (( pure )) char *
232 extern const __attribute__ (( pure )) char *
234 extern const __attribute__ (( pure )) char *
235 efi_open_attributes_name ( unsigned int attributes );
236 extern const __attribute__ (( pure )) char *
238 extern const __attribute__ (( pure )) char *
240 
244 extern void dbg_efi_protocols ( EFI_HANDLE handle );
245 
246 #define DBG_EFI_OPENER_IF( level, handle, protocol, \
247  opener ) do { \
248  if ( DBG_ ## level ) { \
249  dbg_efi_opener ( handle, protocol, \
250  opener ); \
251  } \
252  } while ( 0 )
253 
254 #define DBG_EFI_OPENERS_IF( level, handle, protocol ) do { \
255  if ( DBG_ ## level ) { \
256  dbg_efi_openers ( handle, protocol ); \
257  } \
258  } while ( 0 )
259 
260 #define DBG_EFI_PROTOCOLS_IF( level, handle ) do { \
261  if ( DBG_ ## level ) { \
262  dbg_efi_protocols ( handle ); \
263  } \
264  } while ( 0 )
265 
266 #define DBGC_EFI_OPENER_IF( level, id, ... ) do { \
267  DBG_AC_IF ( level, id ); \
268  DBG_EFI_OPENER_IF ( level, __VA_ARGS__ ); \
269  DBG_DC_IF ( level ); \
270  } while ( 0 )
271 
272 #define DBGC_EFI_OPENERS_IF( level, id, ... ) do { \
273  DBG_AC_IF ( level, id ); \
274  DBG_EFI_OPENERS_IF ( level, __VA_ARGS__ ); \
275  DBG_DC_IF ( level ); \
276  } while ( 0 )
277 
278 #define DBGC_EFI_PROTOCOLS_IF( level, id, ... ) do { \
279  DBG_AC_IF ( level, id ); \
280  DBG_EFI_PROTOCOLS_IF ( level, __VA_ARGS__ ); \
281  DBG_DC_IF ( level ); \
282  } while ( 0 )
283 
284 #define DBGC_EFI_OPENER( ... ) \
285  DBGC_EFI_OPENER_IF ( LOG, ##__VA_ARGS__ )
286 #define DBGC_EFI_OPENERS( ... ) \
287  DBGC_EFI_OPENERS_IF ( LOG, ##__VA_ARGS__ )
288 #define DBGC_EFI_PROTOCOLS( ... ) \
289  DBGC_EFI_PROTOCOLS_IF ( LOG, ##__VA_ARGS__ )
290 
291 #define DBGC2_EFI_OPENER( ... ) \
292  DBGC_EFI_OPENER_IF ( EXTRA, ##__VA_ARGS__ )
293 #define DBGC2_EFI_OPENERS( ... ) \
294  DBGC_EFI_OPENERS_IF ( EXTRA, ##__VA_ARGS__ )
295 #define DBGC2_EFI_PROTOCOLS( ... ) \
296  DBGC_EFI_PROTOCOLS_IF ( EXTRA, ##__VA_ARGS__ )
297 
298 #define DBGCP_EFI_OPENER( ... ) \
299  DBGC_EFI_OPENER_IF ( PROFILE, ##__VA_ARGS__ )
300 #define DBGCP_EFI_OPENERS( ... ) \
301  DBGC_EFI_OPENERS_IF ( PROFILE, ##__VA_ARGS__ )
302 #define DBGCP_EFI_PROTOCOLS( ... ) \
303  DBGC_EFI_PROTOCOLS_IF ( PROFILE, ##__VA_ARGS__ )
304 
305 /* Allow for EFI-only interface operations */
306 #ifdef PLATFORM_efi
307 #define EFI_INTF_OP INTF_OP
308 #else
309 #define EFI_INTF_OP UNUSED_INTF_OP
310 #endif
311 
312 extern unsigned long __stack_chk_guard;
313 extern unsigned long efi_stack_cookie ( EFI_HANDLE handle );
314 extern void __stack_chk_fail ( void );
315 
316 /**
317  * Initialise stack cookie
318  *
319  * @v handle Image handle
320  */
321 static inline __attribute__ (( always_inline )) void
323 
324  /* The calling function must not itself use stack protection,
325  * since the change in the stack guard value would trigger a
326  * false positive.
327  *
328  * There is unfortunately no way to annotate a function to
329  * exclude the use of stack protection. We must therefore
330  * rely on correctly anticipating the compiler's decision on
331  * the use of stack protection.
332  *
333  * The calculation of the stack cookie value deliberately
334  * takes the address of a stack variable (to provide an
335  * additional source of entropy). This operation would
336  * trigger the application of stack protection to the calling
337  * function, and so must be externalised.
338  */
340 }
341 
342 extern EFI_STATUS efi_init ( EFI_HANDLE image_handle,
343  EFI_SYSTEM_TABLE *systab );
344 extern void efi_raise_tpl ( struct efi_saved_tpl *tpl );
345 extern void efi_restore_tpl ( struct efi_saved_tpl *tpl );
346 
347 #endif /* _IPXE_EFI_H */
#define __attribute__(x)
Definition: compiler.h:10
void efi_restore_tpl(struct efi_saved_tpl *tpl)
Restore task priority level.
Definition: efi_init.c:410
void ** protocol
Variable containing pointer to protocol structure.
Definition: efi.h:79
EFI_GUID efi_pci_root_bridge_io_protocol_guid
PCI root bridge I/O protocol GUID.
Definition: efi_guid.c:220
EFI_GUID efi_mtftp4_service_binding_protocol_guid
MTFTPv4 service binding protocol GUID.
Definition: efi_guid.c:204
EFI_GUID efi_component_name2_protocol_guid
Component name 2 protocol GUID.
Definition: efi_guid.c:124
static void efi_init_stack_guard(EFI_HANDLE handle)
Initialise stack cookie.
Definition: efi.h:322
EFI Oprn Protocol Information Entry.
Definition: UefiSpec.h:1349
EFI_GUID efi_ip4_protocol_guid
IPv4 protocol GUID.
Definition: efi_guid.c:164
EFI_DEVICE_PATH_PROTOCOL * efi_loaded_image_path
Device path for the loaded image's device handle.
Definition: efi_init.c:39
EFI_GUID efi_block_io_protocol_guid
Block I/O protocol GUID.
Definition: efi_guid.c:108
unsigned long __stack_chk_guard
Stack cookie.
Definition: efi_init.c:63
#define EFI_HANDLE
Definition: efi.h:47
EFI_GUID efi_load_file2_protocol_guid
Load file 2 protocol GUID.
Definition: efi_guid.c:180
EFI_GUID efi_simple_file_system_protocol_guid
Simple file system protocol GUID.
Definition: efi_guid.c:232
128 bit buffer containing a unique identifier value.
Definition: Base.h:263
EFI_GUID efi_dhcp4_protocol_guid
DHCPv4 protocol GUID.
Definition: efi_guid.c:136
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
EFI_GUID efi_simple_pointer_protocol_guid
Simple pointer protocol GUID.
Definition: efi_guid.c:240
EFI_GUID efi_component_name_protocol_guid
Component name protocol GUID.
Definition: efi_guid.c:120
EFI_GUID guid
GUID.
Definition: efi.h:77
EFI_GUID efi_tcp4_service_binding_protocol_guid
TCPv4 service binding protocol GUID.
Definition: efi_guid.c:264
EFI_GUID efi_device_path_protocol_guid
Device path protocol GUID.
Definition: efi_guid.c:132
EFI_GUID efi_apple_net_boot_protocol_guid
Apple NetBoot protocol GUID.
Definition: efi_guid.c:96
EFI_GUID efi_loaded_image_protocol_guid
Loaded image protocol GUID.
Definition: efi_guid.c:184
EFI_GUID efi_acpi_table_protocol_guid
ACPI table protocol GUID.
Definition: efi_guid.c:92
unsigned long efi_stack_cookie(EFI_HANDLE handle)
Construct a stack cookie value.
Definition: efi_init.c:130
const char * efi_locate_search_type_name(EFI_LOCATE_SEARCH_TYPE search_type)
Name locate search type.
Definition: efi_debug.c:225
Universally unique IDs.
void dbg_efi_openers(EFI_HANDLE handle, EFI_GUID *protocol)
Print list of openers of a given protocol on a given handle.
Definition: efi_debug.c:293
EFI_GUID efi_unicode_collation_protocol_guid
Unicode collation protocol GUID.
Definition: efi_guid.c:284
EFI_GUID efi_uga_draw_protocol_guid
UGA draw protocol GUID.
Definition: efi_guid.c:280
This protocol can be used on any device handle to obtain generic path/location information concerning...
Definition: DevicePath.h:51
void dbg_efi_opener(EFI_HANDLE handle, EFI_GUID *protocol, EFI_OPEN_PROTOCOL_INFORMATION_ENTRY *opener)
Print opened protocol information.
Definition: efi_debug.c:272
EFI_GUID efi_load_file_protocol_guid
Load file protocol GUID.
Definition: efi_guid.c:176
EFI_TPL efi_external_tpl
External task priority level.
Definition: efi_init.c:54
void efi_raise_tpl(struct efi_saved_tpl *tpl)
Raise task priority level to internal level.
Definition: efi_init.c:394
EFI_LOADED_IMAGE_PROTOCOL * efi_loaded_image
Loaded image protocol for this image.
Definition: efi_init.c:36
Root include file for Mde Package DXE_CORE, DXE, RUNTIME, SMM, SAL type modules.
UEFI 2.0 Loaded image protocol definition.
An EFI configuration table used by iPXE.
Definition: efi.h:119
EFI_GUID efi_nii_protocol_guid
Network interface identifier protocol GUID (old version)
Definition: efi_guid.c:208
const char * efi_guid_ntoa(CONST EFI_GUID *guid)
Convert GUID to a printable string.
Definition: efi_debug.c:192
Can be used on any image handle to obtain information about the loaded image.
Definition: LoadedImage.h:51
EFI_TPL current
Current external TPL.
Definition: efi.h:69
EFI_GUID efi_block_io2_protocol_guid
Block I/O version 2 protocol GUID.
Definition: efi_guid.c:112
EFI_GUID efi_pxe_base_code_protocol_guid
PXE base code protocol GUID.
Definition: efi_guid.c:224
EFI_GUID efi_console_control_protocol_guid
Console control protocol GUID.
Definition: efi_guid.c:128
EFI_GUID efi_dhcp4_service_binding_protocol_guid
DHCPv4 service binding protocol GUID.
Definition: efi_guid.c:140
const char * efi_devpath_text(EFI_DEVICE_PATH_PROTOCOL *path)
Get textual representation of device path.
Definition: efi_debug.c:375
EFI_GUID efi_usb2_hc_protocol_guid
USB2 host controller protocol GUID.
Definition: efi_guid.c:292
EFI_GUID efi_usb_hc_protocol_guid
USB host controller protocol GUID.
Definition: efi_guid.c:288
EFI_GUID efi_simple_text_input_protocol_guid
Simple text input protocol GUID.
Definition: efi_guid.c:244
EFI_STATUS efi_init(EFI_HANDLE image_handle, EFI_SYSTEM_TABLE *systab)
Initialise EFI environment.
Definition: efi_init.c:170
Profiling.
An EFI protocol used by iPXE.
Definition: efi.h:75
EFI_GUID efi_simple_network_protocol_guid
Simple network protocol GUID.
Definition: efi_guid.c:236
EFI_GUID efi_simple_text_output_protocol_guid
Simple text output protocol GUID.
Definition: efi_guid.c:252
EFI_GUID efi_vlan_config_protocol_guid
VLAN configuration protocol GUID.
Definition: efi_guid.c:300
const char * efi_handle_name(EFI_HANDLE handle)
Get name of an EFI handle.
Definition: efi_debug.c:722
EFI_GUID efi_graphics_output_protocol_guid
Graphics output protocol GUID.
Definition: efi_guid.c:152
EFI_GUID efi_bus_specific_driver_override_protocol_guid
Bus specific driver override protocol GUID.
Definition: efi_guid.c:116
EFI_GUID efi_mtftp4_protocol_guid
MTFTPv4 protocol GUID.
Definition: efi_guid.c:200
EFI_TPL previous
Previous external TPL.
Definition: efi.h:71
Root include file for Mde Package UEFI, UEFI_APPLICATION type modules.
EFI_GUID efi_hii_font_protocol_guid
HII font protocol GUID.
Definition: efi_guid.c:160
EFI_GUID efi_simple_text_input_ex_protocol_guid
Simple text input extension protocol GUID.
Definition: efi_guid.c:248
EFI System Table.
Definition: UefiSpec.h:1949
EFI_GUID efi_arp_protocol_guid
ARP protocol GUID.
Definition: efi_guid.c:100
Version number.
EFI_GUID efi_tcp4_protocol_guid
TCPv4 protocol GUID.
Definition: efi_guid.c:260
EFI_GUID efi_tree_protocol_guid
TrEE protocol GUID.
Definition: efi_guid.c:268
EFI_GUID efi_managed_network_protocol_guid
Managed network protocol GUID.
Definition: efi_guid.c:192
void ** table
Variable containing pointer to configuration table.
Definition: efi.h:123
uint64_t guid
GUID.
Definition: edd.h:30
int required
Protocol is required.
Definition: efi.h:81
EFI_GUID efi_arp_service_binding_protocol_guid
ARP service binding protocol GUID.
Definition: efi_guid.c:104
EFI_GUID efi_serial_io_protocol_guid
Serial I/O protocol GUID.
Definition: efi_guid.c:228
EFI_GUID efi_udp4_protocol_guid
UDPv4 protocol GUID.
Definition: efi_guid.c:272
EFI_TPL efi_internal_tpl
Internal task priority level.
Definition: efi_init.c:51
UINTN EFI_TPL
Task priority level.
Definition: UefiBaseType.h:47
An EFI saved task priority level.
Definition: efi.h:67
EFI_GUID guid
GUID.
Definition: efi.h:121
#define CONST
Datum is read-only.
Definition: Base.h:309
const char * efi_open_attributes_name(unsigned int attributes)
Name protocol open attributes.
Definition: efi_debug.c:250
RETURN_STATUS EFI_STATUS
Function return status for EFI API.
Definition: UefiBaseType.h:35
EFI_GUID efi_nii31_protocol_guid
Network interface identifier protocol GUID (new version)
Definition: efi_guid.c:212
EFI_GUID efi_tcg_protocol_guid
TCG protocol GUID.
Definition: efi_guid.c:256
EFI_GUID efi_udp4_service_binding_protocol_guid
UDPv4 service binding protocol GUID.
Definition: efi_guid.c:276
Defines data types and constants introduced in UEFI.
int efi_shutdown_in_progress
EFI shutdown is in progress.
Definition: efi_init.c:57
Linker tables.
EFI_HANDLE efi_image_handle
Image handle passed to entry point.
Definition: efi_init.c:33
EFI_GUID efi_managed_network_service_binding_protocol_guid
Managed network service binding protocol GUID.
Definition: efi_guid.c:196
EFI_GUID efi_usb_io_protocol_guid
USB I/O protocol GUID.
Definition: efi_guid.c:296
EFI_GUID efi_file_system_info_id
File system information GUID.
Definition: efi_guid.c:306
void __stack_chk_fail(void)
Abort on stack check failure.
Definition: efi_init.c:367
EFI_GUID efi_absolute_pointer_protocol_guid
Absolute pointer protocol GUID.
Definition: efi_guid.c:88
EFI_GUID efi_hii_config_access_protocol_guid
HII configuration access protocol GUID.
Definition: efi_guid.c:156
EFI_SYSTEM_TABLE * efi_systab
uint16_t protocol
Protocol ID.
Definition: stp.h:18
EFI_GUID efi_loaded_image_device_path_protocol_guid
Loaded image device path protocol GUID.
Definition: efi_guid.c:188
EFI_LOCATE_SEARCH_TYPE
Enumeration of EFI Locate Search Types.
Definition: UefiSpec.h:1435
EFI_GUID efi_driver_binding_protocol_guid
Driver binding protocol GUID.
Definition: efi_guid.c:148
EFI_GUID efi_ip4_config_protocol_guid
IPv4 configuration protocol GUID.
Definition: efi_guid.c:168
EFI_GUID efi_pci_io_protocol_guid
PCI I/O protocol GUID.
Definition: efi_guid.c:216
int required
Table is required for operation.
Definition: efi.h:125
EFI_GUID efi_file_info_id
File information GUID.
Definition: efi_guid.c:303
uint16_t handle
Handle.
Definition: smbios.h:16
Definition: efi.h:50
EFI_GUID efi_ip4_service_binding_protocol_guid
IPv4 service binding protocol GUID.
Definition: efi_guid.c:172
EFI_GUID efi_disk_io_protocol_guid
Disk I/O protocol GUID.
Definition: efi_guid.c:144
void dbg_efi_protocols(EFI_HANDLE handle)
Print list of protocol handlers attached to a handle.
Definition: efi_debug.c:332