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>
30 #include <ipxe/efi/efi_cmdline.h>
32 
33 /** Image handle passed to entry point */
35 
36 /** Loaded image protocol for this image */
38 
39 /** Device path for the loaded image's device handle */
41 
42 /** System table passed to entry point
43  *
44  * We construct the symbol name efi_systab via the PLATFORM macro.
45  * This ensures that the symbol is defined only in EFI builds, and so
46  * prevents EFI code from being incorrectly linked in to a non-EFI
47  * build.
48  */
49 EFI_SYSTEM_TABLE * _C2 ( PLATFORM, _systab );
50 
51 /** Internal task priority level */
53 
54 /** External task priority level */
56 
57 /** EFI shutdown is in progress */
59 
60 /** Event used to signal shutdown */
62 
63 /** Stack cookie */
64 unsigned long __stack_chk_guard;
65 
66 /** Exit function
67  *
68  * Cached to minimise external dependencies when a stack check
69  * failure is triggered.
70  */
72 
73 /* Forward declarations */
74 static EFI_STATUS EFIAPI efi_unload ( EFI_HANDLE image_handle );
75 
76 /**
77  * Shut down in preparation for booting an OS.
78  *
79  * This hook gets called at ExitBootServices time in order to make
80  * sure that everything is properly shut down before the OS takes
81  * over.
82  */
84  void *context __unused ) {
85 
86  /* This callback is invoked at TPL_NOTIFY in order to ensure
87  * that we have an opportunity to shut down cleanly before
88  * other shutdown hooks perform destructive operations such as
89  * disabling the IOMMU.
90  *
91  * Modify the internal task priority level so that no code
92  * attempts to raise from TPL_NOTIFY to TPL_CALLBACK (which
93  * would trigger a fatal exception).
94  */
96 
97  /* Mark shutdown as being in progress, to indicate that large
98  * parts of the system (e.g. timers) are no longer functional.
99  */
101 
102  /* Shut down iPXE */
103  shutdown_boot();
104 }
105 
106 /**
107  * Look up EFI configuration table
108  *
109  * @v guid Configuration table GUID
110  * @ret table Configuration table, or NULL
111  */
112 static void * efi_find_table ( EFI_GUID *guid ) {
113  unsigned int i;
114 
115  for ( i = 0 ; i < efi_systab->NumberOfTableEntries ; i++ ) {
117  guid, sizeof ( *guid ) ) == 0 )
119  }
120 
121  return NULL;
122 }
123 
124 /**
125  * Construct a stack cookie value
126  *
127  * @v handle Image handle
128  * @ret cookie Stack cookie
129  */
130 __attribute__ (( noinline )) unsigned long
132  unsigned long cookie = 0;
133  unsigned int rotation = ( 8 * sizeof ( cookie ) / 4 );
134 
135  /* There is no viable source of entropy available at this
136  * point. Construct a value that is at least likely to vary
137  * between platforms and invocations.
138  */
139  cookie ^= ( ( unsigned long ) handle );
140  cookie = roll ( cookie, rotation );
141  cookie ^= ( ( unsigned long ) &handle );
142  cookie = roll ( cookie, rotation );
143  cookie ^= profile_timestamp();
144  cookie = roll ( cookie, rotation );
145  cookie ^= build_id;
146 
147  /* Ensure that the value contains a NUL byte, to act as a
148  * runaway string terminator. Construct the NUL using a shift
149  * rather than a mask, to avoid losing valuable entropy in the
150  * lower-order bits.
151  */
152  cookie <<= 8;
153 
154  /* Ensure that the NUL byte is placed at the bottom of the
155  * stack cookie, to avoid potential disclosure via an
156  * unterminated string.
157  */
158  if ( __BYTE_ORDER == __BIG_ENDIAN )
159  cookie >>= 8;
160 
161  return cookie;
162 }
163 
164 /**
165  * Initialise EFI environment
166  *
167  * @v image_handle Image handle
168  * @v systab System table
169  * @ret efirc EFI return status code
170  */
172  EFI_SYSTEM_TABLE *systab ) {
173  EFI_BOOT_SERVICES *bs;
174  struct efi_protocol *prot;
175  struct efi_config_table *tab;
176  void *loaded_image;
177  void *device_path;
178  void *device_path_copy;
179  size_t device_path_len;
180  EFI_STATUS efirc;
181  int rc;
182 
183  /* Store image handle and system table pointer for future use */
184  efi_image_handle = image_handle;
185  efi_systab = systab;
186 
187  /* Sanity checks */
188  if ( ! systab ) {
189  efirc = EFI_NOT_AVAILABLE_YET;
190  goto err_sanity;
191  }
192  if ( ! systab->ConOut ) {
193  efirc = EFI_NOT_AVAILABLE_YET;
194  goto err_sanity;
195  }
196  if ( ! systab->BootServices ) {
197  DBGC ( systab, "EFI provided no BootServices entry point\n" );
198  efirc = EFI_NOT_AVAILABLE_YET;
199  goto err_sanity;
200  }
201  if ( ! systab->RuntimeServices ) {
202  DBGC ( systab, "EFI provided no RuntimeServices entry "
203  "point\n" );
204  efirc = EFI_NOT_AVAILABLE_YET;
205  goto err_sanity;
206  }
207  DBGC ( systab, "EFI handle %p systab %p\n", image_handle, systab );
208  bs = systab->BootServices;
209 
210  /* Store abort function pointer */
211  efi_exit = bs->Exit;
212 
213  /* Look up used protocols */
215  if ( ( efirc = bs->LocateProtocol ( &prot->guid, NULL,
216  prot->protocol ) ) == 0 ) {
217  DBGC ( systab, "EFI protocol %s is at %p\n",
218  efi_guid_ntoa ( &prot->guid ),
219  *(prot->protocol) );
220  } else {
221  DBGC ( systab, "EFI does not provide protocol %s\n",
222  efi_guid_ntoa ( &prot->guid ) );
223  /* Fail if protocol is required */
224  if ( prot->required )
225  goto err_missing_protocol;
226  }
227  }
228 
229  /* Look up used configuration tables */
231  if ( ( *(tab->table) = efi_find_table ( &tab->guid ) ) ) {
232  DBGC ( systab, "EFI configuration table %s is at %p\n",
233  efi_guid_ntoa ( &tab->guid ), *(tab->table) );
234  } else {
235  DBGC ( systab, "EFI does not provide configuration "
236  "table %s\n", efi_guid_ntoa ( &tab->guid ) );
237  if ( tab->required ) {
238  efirc = EFI_NOT_AVAILABLE_YET;
239  goto err_missing_table;
240  }
241  }
242  }
243 
244  /* Get loaded image protocol */
245  if ( ( efirc = bs->OpenProtocol ( image_handle,
247  &loaded_image, image_handle, NULL,
248  EFI_OPEN_PROTOCOL_GET_PROTOCOL ) ) != 0 ) {
249  rc = -EEFI ( efirc );
250  DBGC ( systab, "EFI could not get loaded image protocol: %s",
251  strerror ( rc ) );
252  goto err_no_loaded_image;
253  }
254  efi_loaded_image = loaded_image;
255  DBGC ( systab, "EFI image base address %p\n",
257 
258  /* Record command line */
261 
262  /* Get loaded image's device handle's device path */
263  if ( ( efirc = bs->OpenProtocol ( efi_loaded_image->DeviceHandle,
265  &device_path, image_handle, NULL,
266  EFI_OPEN_PROTOCOL_GET_PROTOCOL ) ) != 0 ) {
267  rc = -EEFI ( efirc );
268  DBGC ( systab, "EFI could not get loaded image's device path: "
269  "%s", strerror ( rc ) );
270  goto err_no_device_path;
271  }
272 
273  /* Make a copy of the loaded image's device handle's device
274  * path, since the device handle itself may become invalidated
275  * when we load our own drivers.
276  */
277  device_path_len = ( efi_path_len ( device_path ) +
278  sizeof ( EFI_DEVICE_PATH_PROTOCOL ) );
279  if ( ( efirc = bs->AllocatePool ( EfiBootServicesData, device_path_len,
280  &device_path_copy ) ) != 0 ) {
281  rc = -EEFI ( efirc );
282  goto err_alloc_device_path;
283  }
284  memcpy ( device_path_copy, device_path, device_path_len );
285  efi_loaded_image_path = device_path_copy;
286  DBGC ( systab, "EFI image device path %s\n",
288 
289  /* EFI is perfectly capable of gracefully shutting down any
290  * loaded devices if it decides to fall back to a legacy boot.
291  * For no particularly comprehensible reason, it doesn't
292  * bother doing so when ExitBootServices() is called.
293  */
294  if ( ( efirc = bs->CreateEvent ( EVT_SIGNAL_EXIT_BOOT_SERVICES,
296  NULL, &efi_shutdown_event ) ) != 0 ) {
297  rc = -EEFI ( efirc );
298  DBGC ( systab, "EFI could not create ExitBootServices event: "
299  "%s\n", strerror ( rc ) );
300  goto err_create_event;
301  }
302 
303  /* Install driver binding protocol */
304  if ( ( rc = efi_driver_install() ) != 0 ) {
305  DBGC ( systab, "EFI could not install driver: %s\n",
306  strerror ( rc ) );
307  efirc = EFIRC ( rc );
308  goto err_driver_install;
309  }
310 
311  /* Install image unload method */
313 
314  return 0;
315 
317  err_driver_install:
319  err_create_event:
321  err_alloc_device_path:
322  err_no_device_path:
323  err_no_loaded_image:
324  err_missing_table:
325  err_missing_protocol:
326  err_sanity:
327  return efirc;
328 }
329 
330 /**
331  * Shut down EFI environment
332  *
333  * @v image_handle Image handle
334  */
335 static EFI_STATUS EFIAPI efi_unload ( EFI_HANDLE image_handle __unused ) {
337  EFI_SYSTEM_TABLE *systab = efi_systab;
338  struct efi_saved_tpl tpl;
339 
340  DBGC ( systab, "EFI image unloading\n" );
341 
342  /* Raise TPL */
343  efi_raise_tpl ( &tpl );
344 
345  /* Shut down */
346  shutdown_exit();
347 
348  /* Disconnect any remaining devices */
350 
351  /* Uninstall driver binding protocol */
353 
354  /* Uninstall exit boot services event */
356 
357  /* Free copy of loaded image's device handle's device path */
359 
360  DBGC ( systab, "EFI image unloaded\n" );
361 
362  /* Restore TPL */
363  efi_restore_tpl ( &tpl );
364 
365  return 0;
366 }
367 
368 /**
369  * Abort on stack check failure
370  *
371  */
372 __attribute__ (( noreturn )) void __stack_chk_fail ( void ) {
373  EFI_STATUS efirc;
374  int rc;
375 
376  /* Report failure (when debugging) */
377  DBGC ( efi_systab, "EFI stack check failed (cookie %#lx); aborting\n",
379 
380  /* Attempt to exit cleanly with an error status */
381  if ( efi_exit ) {
383  0, NULL );
384  rc = -EEFI ( efirc );
385  DBGC ( efi_systab, "EFI stack check exit failed: %s\n",
386  strerror ( rc ) );
387  }
388 
389  /* If the exit fails for any reason, lock the system */
390  while ( 1 ) {}
391 
392 }
393 
394 /**
395  * Raise task priority level to internal level
396  *
397  * @v tpl Saved TPL
398  */
399 void efi_raise_tpl ( struct efi_saved_tpl *tpl ) {
401 
402  /* Record current external TPL */
403  tpl->previous = efi_external_tpl;
404 
405  /* Raise TPL and record previous TPL as new external TPL */
406  tpl->current = bs->RaiseTPL ( efi_internal_tpl );
407  efi_external_tpl = tpl->current;
408 }
409 
410 /**
411  * Restore task priority level
412  *
413  * @v tpl Saved TPL
414  */
415 void efi_restore_tpl ( struct efi_saved_tpl *tpl ) {
417 
418  /* Restore external TPL */
419  efi_external_tpl = tpl->previous;
420 
421  /* Restore TPL */
422  bs->RestoreTPL ( tpl->current );
423 }
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:2081
void ** protocol
Variable containing pointer to protocol structure.
Definition: efi.h:88
EFI_LOADED_IMAGE_PROTOCOL * efi_loaded_image
Loaded image protocol for this image.
Definition: efi_init.c:37
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:171
EFI_RAISE_TPL RaiseTPL
Definition: UefiSpec.h:1926
EFI driver interface.
const wchar_t * efi_cmdline
EFI command line (may not be wNUL-terminated.
Definition: efi_cmdline.c:43
EFI_LOCATE_PROTOCOL LocateProtocol
Definition: UefiSpec.h:1995
128 bit buffer containing a unique identifier value.
Definition: Base.h:215
Error codes.
void efi_raise_tpl(struct efi_saved_tpl *tpl)
Raise task priority level to internal level.
Definition: efi_init.c:399
#define TPL_APPLICATION
Definition: UefiSpec.h:637
VOID * EFI_EVENT
Handle to an event structure.
Definition: UefiBaseType.h:39
EFI_GUID VendorGuid
The 128-bit GUID value that uniquely identifies the system configuration table.
Definition: UefiSpec.h:2020
EFI_GUID guid
GUID.
Definition: efi.h:86
#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:243
size_t efi_path_len(EFI_DEVICE_PATH_PROTOCOL *path)
Find length of device path (excluding terminator)
Definition: efi_path.c:108
EFI_CLOSE_EVENT CloseEvent
Definition: UefiSpec.h:1945
VOID * ImageBase
The base address at which the image was loaded.
Definition: LoadedImage.h:69
This protocol can be used on any device handle to obtain generic path/location information concerning...
Definition: DevicePath.h:45
EFI_TPL efi_internal_tpl
Internal task priority level.
Definition: efi_init.c:52
#define TPL_NOTIFY
Definition: UefiSpec.h:639
#define EFI_PROTOCOLS
EFI protocol table.
Definition: efi.h:94
FILE_LICENCE(GPL2_OR_LATER)
#define EVT_SIGNAL_EXIT_BOOT_SERVICES
Definition: UefiSpec.h:445
UEFI 2.0 Loaded image protocol definition.
#define EFI_CONFIG_TABLES
EFI configuration table table.
Definition: efi.h:138
An EFI configuration table used by iPXE.
Definition: efi.h:128
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:995
EFI_DEVICE_PATH_PROTOCOL * efi_loaded_image_path
Device path for the loaded image's device handle.
Definition: efi_init.c:40
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:49
Can be used on any image handle to obtain information about the loaded image.
Definition: LoadedImage.h:45
EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL * ConOut
A pointer to the EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL interface that is associated with ConsoleOutHandle.
Definition: UefiSpec.h:2063
static EFI_EVENT efi_shutdown_event
Event used to signal shutdown.
Definition: efi_init.c:61
unsigned long build_id
Build ID.
Definition: version.c:61
EFI_TPL current
Current external TPL.
Definition: efi.h:78
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:83
#define EFI_COMPROMISED_DATA
Enumeration of EFI_STATUS.
Definition: UefiBaseType.h:145
EFI_CREATE_EVENT CreateEvent
Definition: UefiSpec.h:1941
static void * efi_find_table(EFI_GUID *guid)
Look up EFI configuration table.
Definition: efi_init.c:112
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:461
VOID * LoadOptions
A pointer to the image's binary load options.
Definition: LoadedImage.h:64
#define EFI_OPEN_PROTOCOL_GET_PROTOCOL
Definition: UefiSpec.h:1344
#define __BIG_ENDIAN
Constant representing big-endian byte order.
Definition: endian.h:21
An EFI protocol used by iPXE.
Definition: efi.h:84
const char * efi_guid_ntoa(CONST EFI_GUID *guid)
Convert GUID to a printable string.
Definition: efi_debug.c:254
char * strerror(int errno)
Retrieve string representation of error number.
Definition: strerror.c:78
#define EFIAPI
EFI Boot Services Table.
Definition: UefiSpec.h:1917
EFI_HANDLE efi_image_handle
Image handle passed to entry point.
Definition: efi_init.c:34
EFI_IMAGE_UNLOAD Unload
Definition: LoadedImage.h:73
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:80
#define for_each_table_entry(pointer, table)
Iterate through all entries within a linker table.
Definition: tables.h:385
#define TPL_CALLBACK
Definition: UefiSpec.h:638
EFI device paths.
EFI System Table.
Definition: UefiSpec.h:2030
unsigned long __stack_chk_guard
Stack cookie.
Definition: efi_init.c:64
static unsigned int rotation
Definition: rotate.h:22
EFI_GUID efi_device_path_protocol_guid
Device path protocol GUID.
Definition: efi_guid.c:143
EFI_FREE_POOL FreePool
Definition: UefiSpec.h:1936
EFI API.
void ** table
Variable containing pointer to configuration table.
Definition: efi.h:132
uint64_t guid
GUID.
Definition: edd.h:30
UINT32 LoadOptionsSize
The size in bytes of LoadOptions.
Definition: LoadedImage.h:63
int required
Protocol is required.
Definition: efi.h:90
#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:2077
UINTN EFI_TPL
Task priority level.
Definition: UefiBaseType.h:43
An EFI saved task priority level.
Definition: efi.h:76
EFI_GUID guid
GUID.
Definition: efi.h:130
RETURN_STATUS EFI_STATUS
Function return status for EFI API.
Definition: UefiBaseType.h:31
UINTN NumberOfTableEntries
The number of system configuration tables in the buffer ConfigurationTable.
Definition: UefiSpec.h:2085
EFI command line.
EFI_STATUS efi_init(EFI_HANDLE image_handle, EFI_SYSTEM_TABLE *systab)
Initialise EFI environment.
Definition: efi_init.c:171
static EFI_EXIT efi_exit
Exit function.
Definition: efi_init.c:71
EFI_SYSTEM_TABLE * efi_systab
EFI_OPEN_PROTOCOL OpenProtocol
Definition: UefiSpec.h:1986
EFI_SYSTEM_TABLE * _C2(PLATFORM, _systab)
System table passed to entry point.
size_t efi_cmdline_len
Length of EFI command line (in bytes)
Definition: efi_cmdline.c:46
EFI_RESTORE_TPL RestoreTPL
Definition: UefiSpec.h:1927
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:131
int required
Table is required for operation.
Definition: efi.h:134
static EFI_STATUS EFIAPI efi_unload(EFI_HANDLE image_handle)
Shut down EFI environment.
Definition: efi_init.c:335
void __stack_chk_fail(void)
Abort on stack check failure.
Definition: efi_init.c:372
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:415
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321
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:163
Definition: efi.h:59
EFI_HANDLE DeviceHandle
The device handle that the EFI Image was loaded from.
Definition: LoadedImage.h:55
EFI_ALLOCATE_POOL AllocatePool
Definition: UefiSpec.h:1935
Bit operations.
EFI_CONFIGURATION_TABLE * ConfigurationTable
A pointer to the system configuration tables.
Definition: UefiSpec.h:2090
int efi_shutdown_in_progress
EFI shutdown is in progress.
Definition: efi_init.c:58
VOID * VendorTable
A pointer to the table associated with VendorGuid.
Definition: UefiSpec.h:2024
EFI_TPL efi_external_tpl
External task priority level.
Definition: efi_init.c:55