iPXE
efi_init.c
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2008 Michael Brown <mbrown@fensystems.co.uk>.
3  *
4  * This program is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU General Public License as
6  * published by the Free Software Foundation; either version 2 of the
7  * License, or any later version.
8  *
9  * This program is distributed in the hope that it will be useful, but
10  * WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17  * 02110-1301, USA.
18  */
19 
20 FILE_LICENCE ( GPL2_OR_LATER );
21 
22 #include <string.h>
23 #include <errno.h>
24 #include <endian.h>
25 #include <ipxe/init.h>
26 #include <ipxe/rotate.h>
27 #include <ipxe/efi/efi.h>
28 #include <ipxe/efi/efi_driver.h>
29 #include <ipxe/efi/efi_path.h>
31 
32 /** Image handle passed to entry point */
34 
35 /** Loaded image protocol for this image */
37 
38 /** Device path for the loaded image's device handle */
40 
41 /** System table passed to entry point
42  *
43  * We construct the symbol name efi_systab via the PLATFORM macro.
44  * This ensures that the symbol is defined only in EFI builds, and so
45  * prevents EFI code from being incorrectly linked in to a non-EFI
46  * build.
47  */
48 EFI_SYSTEM_TABLE * _C2 ( PLATFORM, _systab );
49 
50 /** Internal task priority level */
52 
53 /** External task priority level */
55 
56 /** EFI shutdown is in progress */
58 
59 /** Event used to signal shutdown */
61 
62 /** Stack cookie */
63 unsigned long __stack_chk_guard;
64 
65 /** Exit function
66  *
67  * Cached to minimise external dependencies when a stack check
68  * failure is triggered.
69  */
71 
72 /* Forward declarations */
73 static EFI_STATUS EFIAPI efi_unload ( EFI_HANDLE image_handle );
74 
75 /**
76  * Shut down in preparation for booting an OS.
77  *
78  * This hook gets called at ExitBootServices time in order to make
79  * sure that everything is properly shut down before the OS takes
80  * over.
81  */
83  void *context __unused ) {
84 
85  /* This callback is invoked at TPL_NOTIFY in order to ensure
86  * that we have an opportunity to shut down cleanly before
87  * other shutdown hooks perform destructive operations such as
88  * disabling the IOMMU.
89  *
90  * Modify the internal task priority level so that no code
91  * attempts to raise from TPL_NOTIFY to TPL_CALLBACK (which
92  * would trigger a fatal exception).
93  */
95 
96  /* Mark shutdown as being in progress, to indicate that large
97  * parts of the system (e.g. timers) are no longer functional.
98  */
100 
101  /* Shut down iPXE */
102  shutdown_boot();
103 }
104 
105 /**
106  * Look up EFI configuration table
107  *
108  * @v guid Configuration table GUID
109  * @ret table Configuration table, or NULL
110  */
111 static void * efi_find_table ( EFI_GUID *guid ) {
112  unsigned int i;
113 
114  for ( i = 0 ; i < efi_systab->NumberOfTableEntries ; i++ ) {
116  guid, sizeof ( *guid ) ) == 0 )
118  }
119 
120  return NULL;
121 }
122 
123 /**
124  * Construct a stack cookie value
125  *
126  * @v handle Image handle
127  * @ret cookie Stack cookie
128  */
129 __attribute__ (( noinline )) unsigned long
131  unsigned long cookie = 0;
132  unsigned int rotation = ( 8 * sizeof ( cookie ) / 4 );
133 
134  /* There is no viable source of entropy available at this
135  * point. Construct a value that is at least likely to vary
136  * between platforms and invocations.
137  */
138  cookie ^= ( ( unsigned long ) handle );
139  cookie = roll ( cookie, rotation );
140  cookie ^= ( ( unsigned long ) &handle );
141  cookie = roll ( cookie, rotation );
142  cookie ^= profile_timestamp();
143  cookie = roll ( cookie, rotation );
144  cookie ^= build_id;
145 
146  /* Ensure that the value contains a NUL byte, to act as a
147  * runaway string terminator. Construct the NUL using a shift
148  * rather than a mask, to avoid losing valuable entropy in the
149  * lower-order bits.
150  */
151  cookie <<= 8;
152 
153  /* Ensure that the NUL byte is placed at the bottom of the
154  * stack cookie, to avoid potential disclosure via an
155  * unterminated string.
156  */
157  if ( __BYTE_ORDER == __BIG_ENDIAN )
158  cookie >>= 8;
159 
160  return cookie;
161 }
162 
163 /**
164  * Initialise EFI environment
165  *
166  * @v image_handle Image handle
167  * @v systab System table
168  * @ret efirc EFI return status code
169  */
171  EFI_SYSTEM_TABLE *systab ) {
172  EFI_BOOT_SERVICES *bs;
173  struct efi_protocol *prot;
174  struct efi_config_table *tab;
175  void *loaded_image;
176  void *device_path;
177  void *device_path_copy;
178  size_t device_path_len;
179  EFI_STATUS efirc;
180  int rc;
181 
182  /* Store image handle and system table pointer for future use */
183  efi_image_handle = image_handle;
184  efi_systab = systab;
185 
186  /* Sanity checks */
187  if ( ! systab ) {
188  efirc = EFI_NOT_AVAILABLE_YET;
189  goto err_sanity;
190  }
191  if ( ! systab->ConOut ) {
192  efirc = EFI_NOT_AVAILABLE_YET;
193  goto err_sanity;
194  }
195  if ( ! systab->BootServices ) {
196  DBGC ( systab, "EFI provided no BootServices entry point\n" );
197  efirc = EFI_NOT_AVAILABLE_YET;
198  goto err_sanity;
199  }
200  if ( ! systab->RuntimeServices ) {
201  DBGC ( systab, "EFI provided no RuntimeServices entry "
202  "point\n" );
203  efirc = EFI_NOT_AVAILABLE_YET;
204  goto err_sanity;
205  }
206  DBGC ( systab, "EFI handle %p systab %p\n", image_handle, systab );
207  bs = systab->BootServices;
208 
209  /* Store abort function pointer */
210  efi_exit = bs->Exit;
211 
212  /* Look up used protocols */
214  if ( ( efirc = bs->LocateProtocol ( &prot->guid, NULL,
215  prot->protocol ) ) == 0 ) {
216  DBGC ( systab, "EFI protocol %s is at %p\n",
217  efi_guid_ntoa ( &prot->guid ),
218  *(prot->protocol) );
219  } else {
220  DBGC ( systab, "EFI does not provide protocol %s\n",
221  efi_guid_ntoa ( &prot->guid ) );
222  /* Fail if protocol is required */
223  if ( prot->required )
224  goto err_missing_protocol;
225  }
226  }
227 
228  /* Look up used configuration tables */
230  if ( ( *(tab->table) = efi_find_table ( &tab->guid ) ) ) {
231  DBGC ( systab, "EFI configuration table %s is at %p\n",
232  efi_guid_ntoa ( &tab->guid ), *(tab->table) );
233  } else {
234  DBGC ( systab, "EFI does not provide configuration "
235  "table %s\n", efi_guid_ntoa ( &tab->guid ) );
236  if ( tab->required ) {
237  efirc = EFI_NOT_AVAILABLE_YET;
238  goto err_missing_table;
239  }
240  }
241  }
242 
243  /* Get loaded image protocol */
244  if ( ( efirc = bs->OpenProtocol ( image_handle,
246  &loaded_image, image_handle, NULL,
247  EFI_OPEN_PROTOCOL_GET_PROTOCOL ) ) != 0 ) {
248  rc = -EEFI ( efirc );
249  DBGC ( systab, "EFI could not get loaded image protocol: %s",
250  strerror ( rc ) );
251  goto err_no_loaded_image;
252  }
253  efi_loaded_image = loaded_image;
254  DBGC ( systab, "EFI image base address %p\n",
256 
257  /* Get loaded image's device handle's device path */
258  if ( ( efirc = bs->OpenProtocol ( efi_loaded_image->DeviceHandle,
260  &device_path, image_handle, NULL,
261  EFI_OPEN_PROTOCOL_GET_PROTOCOL ) ) != 0 ) {
262  rc = -EEFI ( efirc );
263  DBGC ( systab, "EFI could not get loaded image's device path: "
264  "%s", strerror ( rc ) );
265  goto err_no_device_path;
266  }
267 
268  /* Make a copy of the loaded image's device handle's device
269  * path, since the device handle itself may become invalidated
270  * when we load our own drivers.
271  */
272  device_path_len = ( efi_path_len ( device_path ) +
273  sizeof ( EFI_DEVICE_PATH_PROTOCOL ) );
274  if ( ( efirc = bs->AllocatePool ( EfiBootServicesData, device_path_len,
275  &device_path_copy ) ) != 0 ) {
276  rc = -EEFI ( efirc );
277  goto err_alloc_device_path;
278  }
279  memcpy ( device_path_copy, device_path, device_path_len );
280  efi_loaded_image_path = device_path_copy;
281  DBGC ( systab, "EFI image device path %s\n",
283 
284  /* EFI is perfectly capable of gracefully shutting down any
285  * loaded devices if it decides to fall back to a legacy boot.
286  * For no particularly comprehensible reason, it doesn't
287  * bother doing so when ExitBootServices() is called.
288  */
289  if ( ( efirc = bs->CreateEvent ( EVT_SIGNAL_EXIT_BOOT_SERVICES,
291  NULL, &efi_shutdown_event ) ) != 0 ) {
292  rc = -EEFI ( efirc );
293  DBGC ( systab, "EFI could not create ExitBootServices event: "
294  "%s\n", strerror ( rc ) );
295  goto err_create_event;
296  }
297 
298  /* Install driver binding protocol */
299  if ( ( rc = efi_driver_install() ) != 0 ) {
300  DBGC ( systab, "EFI could not install driver: %s\n",
301  strerror ( rc ) );
302  efirc = EFIRC ( rc );
303  goto err_driver_install;
304  }
305 
306  /* Install image unload method */
308 
309  return 0;
310 
312  err_driver_install:
314  err_create_event:
316  err_alloc_device_path:
317  err_no_device_path:
318  err_no_loaded_image:
319  err_missing_table:
320  err_missing_protocol:
321  err_sanity:
322  return efirc;
323 }
324 
325 /**
326  * Shut down EFI environment
327  *
328  * @v image_handle Image handle
329  */
330 static EFI_STATUS EFIAPI efi_unload ( EFI_HANDLE image_handle __unused ) {
332  EFI_SYSTEM_TABLE *systab = efi_systab;
333  struct efi_saved_tpl tpl;
334 
335  DBGC ( systab, "EFI image unloading\n" );
336 
337  /* Raise TPL */
338  efi_raise_tpl ( &tpl );
339 
340  /* Shut down */
341  shutdown_exit();
342 
343  /* Disconnect any remaining devices */
345 
346  /* Uninstall driver binding protocol */
348 
349  /* Uninstall exit boot services event */
351 
352  /* Free copy of loaded image's device handle's device path */
354 
355  DBGC ( systab, "EFI image unloaded\n" );
356 
357  /* Restore TPL */
358  efi_restore_tpl ( &tpl );
359 
360  return 0;
361 }
362 
363 /**
364  * Abort on stack check failure
365  *
366  */
367 __attribute__ (( noreturn )) void __stack_chk_fail ( void ) {
368  EFI_STATUS efirc;
369  int rc;
370 
371  /* Report failure (when debugging) */
372  DBGC ( efi_systab, "EFI stack check failed (cookie %#lx); aborting\n",
374 
375  /* Attempt to exit cleanly with an error status */
376  if ( efi_exit ) {
378  0, NULL );
379  rc = -EEFI ( efirc );
380  DBGC ( efi_systab, "EFI stack check exit failed: %s\n",
381  strerror ( rc ) );
382  }
383 
384  /* If the exit fails for any reason, lock the system */
385  while ( 1 ) {}
386 
387 }
388 
389 /**
390  * Raise task priority level to internal level
391  *
392  * @v tpl Saved TPL
393  */
394 void efi_raise_tpl ( struct efi_saved_tpl *tpl ) {
396 
397  /* Record current external TPL */
398  tpl->previous = efi_external_tpl;
399 
400  /* Raise TPL and record previous TPL as new external TPL */
401  tpl->current = bs->RaiseTPL ( efi_internal_tpl );
402  efi_external_tpl = tpl->current;
403 }
404 
405 /**
406  * Restore task priority level
407  *
408  * @v tpl Saved TPL
409  */
410 void efi_restore_tpl ( struct efi_saved_tpl *tpl ) {
412 
413  /* Restore external TPL */
414  efi_external_tpl = tpl->previous;
415 
416  /* Restore TPL */
417  bs->RestoreTPL ( tpl->current );
418 }
void efi_driver_uninstall(void)
Uninstall EFI driver.
Definition: efi_driver.c:418
union edd_device_path device_path
Device path.
Definition: edd.h:24
#define __attribute__(x)
Definition: compiler.h:10
EFI_BOOT_SERVICES * BootServices
A pointer to the EFI Boot Services Table.
Definition: UefiSpec.h:2000
void ** protocol
Variable containing pointer to protocol structure.
Definition: efi.h:79
EFI_LOADED_IMAGE_PROTOCOL * efi_loaded_image
Loaded image protocol for this image.
Definition: efi_init.c:36
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
#define EEFI(efirc)
Convert an EFI status code to an iPXE status code.
Definition: efi.h:162
EFI_RAISE_TPL RaiseTPL
Definition: UefiSpec.h:1845
EFI driver interface.
EFI_LOCATE_PROTOCOL LocateProtocol
Definition: UefiSpec.h:1914
128 bit buffer containing a unique identifier value.
Definition: Base.h:263
Error codes.
void efi_raise_tpl(struct efi_saved_tpl *tpl)
Raise task priority level to internal level.
Definition: efi_init.c:394
#define TPL_APPLICATION
Definition: UefiSpec.h:590
VOID * EFI_EVENT
Handle to an event structure.
Definition: UefiBaseType.h:43
EFI_GUID VendorGuid
The 128-bit GUID value that uniquely identifies the system configuration table.
Definition: UefiSpec.h:1939
EFI_GUID guid
GUID.
Definition: efi.h:77
#define __BYTE_ORDER
Definition: endian.h:6
#define DBGC(...)
Definition: compiler.h:505
EFI_GUID efi_loaded_image_protocol_guid
Loaded image protocol GUID.
Definition: efi_guid.c:184
size_t efi_path_len(EFI_DEVICE_PATH_PROTOCOL *path)
Find length of device path (excluding terminator)
Definition: efi_path.c:67
EFI_CLOSE_EVENT CloseEvent
Definition: UefiSpec.h:1864
VOID * ImageBase
The base address at which the image was loaded.
Definition: LoadedImage.h:75
This protocol can be used on any device handle to obtain generic path/location information concerning...
Definition: DevicePath.h:51
EFI_TPL efi_internal_tpl
Internal task priority level.
Definition: efi_init.c:51
#define TPL_NOTIFY
Definition: UefiSpec.h:592
#define EFI_PROTOCOLS
EFI protocol table.
Definition: efi.h:85
FILE_LICENCE(GPL2_OR_LATER)
#define EVT_SIGNAL_EXIT_BOOT_SERVICES
Definition: UefiSpec.h:396
UEFI 2.0 Loaded image protocol definition.
#define EFI_CONFIG_TABLES
EFI configuration table table.
Definition: efi.h:129
An EFI configuration table used by iPXE.
Definition: efi.h:119
EFI_STATUS(EFIAPI * EFI_EXIT)(IN EFI_HANDLE ImageHandle, IN EFI_STATUS ExitStatus, IN UINTN ExitDataSize, IN CHAR16 *ExitData OPTIONAL)
Terminates a loaded EFI image and returns control to boot services.
Definition: UefiSpec.h:925
EFI_DEVICE_PATH_PROTOCOL * efi_loaded_image_path
Device path for the loaded image's device handle.
Definition: efi_init.c:39
void * memcpy(void *dest, const void *src, size_t len) __nonnull
#define EFI_NOT_AVAILABLE_YET
If this value is returned by an API, it means the capability is not yet installed/available/ready to ...
Definition: PiMultiPhase.h:55
Can be used on any image handle to obtain information about the loaded image.
Definition: LoadedImage.h:51
EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL * ConOut
A pointer to the EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL interface that is associated with ConsoleOutHandle.
Definition: UefiSpec.h:1982
static EFI_EVENT efi_shutdown_event
Event used to signal shutdown.
Definition: efi_init.c:60
unsigned long build_id
Build ID.
Definition: version.c:61
EFI_TPL current
Current external TPL.
Definition: efi.h:69
static EFIAPI void efi_shutdown_hook(EFI_EVENT event __unused, void *context __unused)
Shut down in preparation for booting an OS.
Definition: efi_init.c:82
#define EFI_COMPROMISED_DATA
Enumeration of EFI_STATUS.
Definition: UefiBaseType.h:151
EFI_CREATE_EVENT CreateEvent
Definition: UefiSpec.h:1860
static void * efi_find_table(EFI_GUID *guid)
Look up EFI configuration table.
Definition: efi_init.c:111
static void shutdown_exit(void)
Shut down system for exit back to firmware.
Definition: init.h:84
const char * efi_devpath_text(EFI_DEVICE_PATH_PROTOCOL *path)
Get textual representation of device path.
Definition: efi_debug.c:375
#define EFI_OPEN_PROTOCOL_GET_PROTOCOL
Definition: UefiSpec.h:1271
#define __BIG_ENDIAN
Constant representing big-endian byte order.
Definition: endian.h:21
An EFI protocol used by iPXE.
Definition: efi.h:75
const char * efi_guid_ntoa(CONST EFI_GUID *guid)
Convert GUID to a printable string.
Definition: efi_debug.c:192
char * strerror(int errno)
Retrieve string representation of error number.
Definition: strerror.c:78
#define EFIAPI
EFI Boot Services Table.
Definition: UefiSpec.h:1836
EFI_HANDLE efi_image_handle
Image handle passed to entry point.
Definition: efi_init.c:33
EFI_IMAGE_UNLOAD Unload
Definition: LoadedImage.h:79
void efi_driver_disconnect_all(void)
Disconnect EFI driver from all possible devices.
Definition: efi_driver.c:584
EFI_TPL previous
Previous external TPL.
Definition: efi.h:71
#define for_each_table_entry(pointer, table)
Iterate through all entries within a linker table.
Definition: tables.h:358
#define TPL_CALLBACK
Definition: UefiSpec.h:591
EFI device paths.
EFI System Table.
Definition: UefiSpec.h:1949
unsigned long __stack_chk_guard
Stack cookie.
Definition: efi_init.c:63
static unsigned int rotation
Definition: rotate.h:22
EFI_GUID efi_device_path_protocol_guid
Device path protocol GUID.
Definition: efi_guid.c:132
EFI_FREE_POOL FreePool
Definition: UefiSpec.h:1855
EFI API.
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
#define __unused
Declare a variable or data structure as unused.
Definition: compiler.h:573
EFI_RUNTIME_SERVICES * RuntimeServices
A pointer to the EFI Runtime Services Table.
Definition: UefiSpec.h:1996
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
RETURN_STATUS EFI_STATUS
Function return status for EFI API.
Definition: UefiBaseType.h:35
UINTN NumberOfTableEntries
The number of system configuration tables in the buffer ConfigurationTable.
Definition: UefiSpec.h:2004
EFI_STATUS efi_init(EFI_HANDLE image_handle, EFI_SYSTEM_TABLE *systab)
Initialise EFI environment.
Definition: efi_init.c:170
static EFI_EXIT efi_exit
Exit function.
Definition: efi_init.c:70
EFI_SYSTEM_TABLE * efi_systab
EFI_OPEN_PROTOCOL OpenProtocol
Definition: UefiSpec.h:1905
EFI_SYSTEM_TABLE * _C2(PLATFORM, _systab)
System table passed to entry point.
EFI_RESTORE_TPL RestoreTPL
Definition: UefiSpec.h:1846
The data portions of a loaded Boot Serves Driver, and the default data allocation type used by a Boot...
unsigned long efi_stack_cookie(EFI_HANDLE handle)
Construct a stack cookie value.
Definition: efi_init.c:130
int required
Table is required for operation.
Definition: efi.h:125
static EFI_STATUS EFIAPI efi_unload(EFI_HANDLE image_handle)
Shut down EFI environment.
Definition: efi_init.c:330
void __stack_chk_fail(void)
Abort on stack check failure.
Definition: efi_init.c:367
static void shutdown_boot(void)
Shut down system for OS boot.
Definition: init.h:76
uint16_t handle
Handle.
Definition: smbios.h:16
int memcmp(const void *first, const void *second, size_t len)
Compare memory regions.
Definition: string.c:114
void efi_restore_tpl(struct efi_saved_tpl *tpl)
Restore task priority level.
Definition: efi_init.c:410
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362
String functions.
int efi_driver_install(void)
Install EFI driver.
Definition: efi_driver.c:385
#define EFIRC(rc)
Convert an iPXE status code to an EFI status code.
Definition: efi.h:154
Definition: efi.h:50
EFI_HANDLE DeviceHandle
The device handle that the EFI Image was loaded from.
Definition: LoadedImage.h:61
EFI_ALLOCATE_POOL AllocatePool
Definition: UefiSpec.h:1854
Bit operations.
EFI_CONFIGURATION_TABLE * ConfigurationTable
A pointer to the system configuration tables.
Definition: UefiSpec.h:2009
int efi_shutdown_in_progress
EFI shutdown is in progress.
Definition: efi_init.c:57
VOID * VendorTable
A pointer to the table associated with VendorGuid.
Definition: UefiSpec.h:1943
EFI_TPL efi_external_tpl
External task priority level.
Definition: efi_init.c:54