#include <string.h>
#include <errno.h>
#include <endian.h>
#include <ipxe/init.h>
#include <ipxe/rotate.h>
#include <ipxe/efi/efi.h>
#include <ipxe/efi/efi_table.h>
#include <ipxe/efi/efi_driver.h>
#include <ipxe/efi/efi_path.h>
#include <ipxe/efi/efi_cmdline.h>
#include <ipxe/efi/Protocol/LoadedImage.h>

Functions
	FILE_LICENCE (GPL2_OR_LATER)
	FILE_SECBOOT (PERMITTED)
EFI_SYSTEM_TABLE *	_C2 (PLATFORM, _systab)
	System table passed to entry point.
static EFI_STATUS EFIAPI	efi_unload (EFI_HANDLE image_handle __unused)
	Shut down EFI environment.
static EFIAPI void	efi_shutdown_hook (EFI_EVENT event __unused, void *context __unused)
	Shut down in preparation for booting an OS.
unsigned long	efi_stack_cookie (EFI_HANDLE handle)
	Construct a stack cookie value.
EFI_STATUS	efi_init (EFI_HANDLE image_handle, EFI_SYSTEM_TABLE *systab)
	Initialise EFI environment.
void	__stack_chk_fail (void)
	Abort on stack check failure.
void	efi_raise_tpl (struct efi_saved_tpl *tpl)
	Raise task priority level to internal level.
void	efi_restore_tpl (struct efi_saved_tpl *tpl)
	Restore task priority level.

Variables
EFI_HANDLE	efi_image_handle
	Image handle passed to entry point.
EFI_LOADED_IMAGE_PROTOCOL *	efi_loaded_image
	Loaded image protocol for this image.
EFI_DEVICE_PATH_PROTOCOL *	efi_loaded_image_path
	Device path for the loaded image's device handle.
EFI_TPL	efi_internal_tpl = TPL_CALLBACK
	Internal task priority level.
EFI_TPL	efi_external_tpl = TPL_APPLICATION
	External task priority level.
int	efi_shutdown_in_progress
	EFI shutdown is in progress.
static EFI_EVENT	efi_shutdown_event
	Event used to signal shutdown.
unsigned long	__stack_chk_guard
	Stack cookie.
static EFI_EXIT	efi_exit
	Exit function.

Function Documentation

◆ FILE_LICENCE()

FILE_LICENCE ( GPL2_OR_LATER )

◆ FILE_SECBOOT()

FILE_SECBOOT ( PERMITTED )

◆ _C2()

EFI_SYSTEM_TABLE * _C2	(	PLATFORM	,
		_systab	)

System table passed to entry point.

We construct the symbol name efi_systab via the PLATFORM macro. This ensures that the symbol is defined only in EFI builds, and so prevents EFI code from being incorrectly linked in to a non-EFI build.

◆ efi_unload()

EFI_STATUS EFIAPI efi_unload ( EFI_HANDLE image_handle __unused )

static

Shut down EFI environment.

Parameters

image_handle Image handle

Definition at line 319 of file efi_init.c.

                                                                         {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
        EFI_SYSTEM_TABLE *systab = efi_systab;
        struct efi_saved_tpl tpl;
 
        DBGC ( systab, "EFI image unloading\n" );
 
        /* Raise TPL */
        efi_raise_tpl ( &tpl );
 
        /* Shut down */
        shutdown_exit();
 
        /* Disconnect any remaining devices */
        efi_driver_disconnect_all();
 
        /* Uninstall driver binding protocol */
        efi_driver_uninstall();
 
        /* Uninstall exit boot services event */
        bs->CloseEvent ( efi_shutdown_event );
 
        /* Free copy of loaded image's device handle's device path */
        bs->FreePool ( efi_loaded_image_path );
 
        DBGC ( systab, "EFI image unloaded\n" );
 
        /* Restore TPL */
        efi_restore_tpl ( &tpl );
 
        return 0;
}

References __unused, EFI_BOOT_SERVICES::CloseEvent, DBGC, efi_driver_disconnect_all(), efi_driver_uninstall(), EFI_HANDLE, efi_loaded_image_path, efi_raise_tpl(), efi_restore_tpl(), efi_shutdown_event, efi_systab, EFIAPI, EFI_BOOT_SERVICES::FreePool, and shutdown_exit().

Referenced by efi_init().

◆ efi_shutdown_hook()

EFIAPI void efi_shutdown_hook	(	EFI_EVENT event	__unused,
		void *context	__unused )

static

Shut down in preparation for booting an OS.

This hook gets called at ExitBootServices time in order to make sure that everything is properly shut down before the OS takes over.

Definition at line 85 of file efi_init.c.

                                                                {
 
        /* This callback is invoked at TPL_NOTIFY in order to ensure
         * that we have an opportunity to shut down cleanly before
         * other shutdown hooks perform destructive operations such as
         * disabling the IOMMU.
         *
         * Modify the internal task priority level so that no code
         * attempts to raise from TPL_NOTIFY to TPL_CALLBACK (which
         * would trigger a fatal exception).
         */
        efi_internal_tpl = TPL_NOTIFY;
 
        /* Mark shutdown as being in progress, to indicate that large
         * parts of the system (e.g. timers) are no longer functional.
         */
        efi_shutdown_in_progress = 1;
 
        /* Shut down iPXE */
        shutdown_boot();
}

References __unused, EFI_EVENT, efi_internal_tpl, efi_shutdown_in_progress, EFIAPI, shutdown_boot(), and TPL_NOTIFY.

Referenced by efi_init().

◆ efi_stack_cookie()

unsigned long efi_stack_cookie ( EFI_HANDLE handle )

Construct a stack cookie value.

Parameters

handle Image handle

Return values

cookie Stack cookie

Definition at line 115 of file efi_init.c.

                                       {
        unsigned long cookie = 0;
        unsigned int rotation = ( 8 * sizeof ( cookie ) / 4 );
 
        /* There is no viable source of entropy available at this
         * point.  Construct a value that is at least likely to vary
         * between platforms and invocations.
         */
        cookie ^= ( ( unsigned long ) handle );
        cookie = roll ( cookie, rotation );
        cookie ^= ( ( unsigned long ) &handle );
        cookie = roll ( cookie, rotation );
        cookie ^= profile_timestamp();
        cookie = roll ( cookie, rotation );
        cookie ^= build_id;
 
        /* Ensure that the value contains a NUL byte, to act as a
         * runaway string terminator.  Construct the NUL using a shift
         * rather than a mask, to avoid losing valuable entropy in the
         * lower-order bits.
         */
        cookie <<= 8;
 
        /* Ensure that the NUL byte is placed at the bottom of the
         * stack cookie, to avoid potential disclosure via an
         * unterminated string.
         */
        if ( __BYTE_ORDER == __BIG_ENDIAN )
                cookie >>= 8;
 
        return cookie;
}

References __BIG_ENDIAN, __BYTE_ORDER, build_id, EFI_HANDLE, handle, profile_timestamp(), and rotation.

Referenced by efi_init_stack_guard().

◆ efi_init()

EFI_STATUS efi_init	(	EFI_HANDLE	image_handle,
		EFI_SYSTEM_TABLE *	systab )

Initialise EFI environment.

Parameters

image_handle	Image handle
systab	System table

Return values

efirc EFI return status code

Definition at line 155 of file efi_init.c.

                                                 {
        EFI_BOOT_SERVICES *bs;
        struct efi_protocol *prot;
        struct efi_config_table *tab;
        EFI_DEVICE_PATH_PROTOCOL *device_path;
        void *device_path_copy;
        size_t device_path_len;
        EFI_STATUS efirc;
        int rc;
 
        /* Store image handle and system table pointer for future use */
        efi_image_handle = image_handle;
        efi_systab = systab;
 
        /* Sanity checks */
        if ( ! systab ) {
                efirc = EFI_NOT_AVAILABLE_YET;
                goto err_sanity;
        }
        if ( ! systab->ConOut ) {
                efirc = EFI_NOT_AVAILABLE_YET;
                goto err_sanity;
        }
        if ( ! systab->BootServices ) {
                DBGC ( systab, "EFI provided no BootServices entry point\n" );
                efirc = EFI_NOT_AVAILABLE_YET;
                goto err_sanity;
        }
        if ( ! systab->RuntimeServices ) {
                DBGC ( systab, "EFI provided no RuntimeServices entry "
                       "point\n" );
                efirc = EFI_NOT_AVAILABLE_YET;
                goto err_sanity;
        }
        DBGC ( systab, "EFI handle %p systab %p\n", image_handle, systab );
        bs = systab->BootServices;
 
        /* Store abort function pointer */
        efi_exit = bs->Exit;
 
        /* Look up used protocols */
        for_each_table_entry ( prot, EFI_PROTOCOLS ) {
                if ( ( efirc = bs->LocateProtocol ( &prot->guid, NULL,
                                                    prot->protocol ) ) == 0 ) {
                        DBGC ( systab, "EFI protocol %s is at %p\n",
                               efi_guid_ntoa ( &prot->guid ),
                               *(prot->protocol) );
                } else {
                        DBGC ( systab, "EFI does not provide protocol %s\n",
                               efi_guid_ntoa ( &prot->guid ) );
                        /* Fail if protocol is required */
                        if ( prot->required )
                                goto err_missing_protocol;
                }
        }
 
        /* Look up used configuration tables */
        for_each_table_entry ( tab, EFI_CONFIG_TABLES ) {
                if ( ( *(tab->table) = efi_find_table ( &tab->guid ) ) ) {
                        DBGC ( systab, "EFI configuration table %s is at %p\n",
                               efi_guid_ntoa ( &tab->guid ), *(tab->table) );
                } else {
                        DBGC ( systab, "EFI does not provide configuration "
                               "table %s\n", efi_guid_ntoa ( &tab->guid ) );
                        if ( tab->required ) {
                                efirc = EFI_NOT_AVAILABLE_YET;
                                goto err_missing_table;
                        }
                }
        }
 
        /* Get loaded image protocol
         *
         * We assume that our loaded image protocol will not be
         * uninstalled while our image code is still running.
         */
        if ( ( rc = efi_open_unsafe ( image_handle,
                                      &efi_loaded_image_protocol_guid,
                                      &efi_loaded_image ) ) != 0 ) {
                DBGC ( systab, "EFI could not get loaded image protocol: %s",
                       strerror ( rc ) );
                efirc = EFIRC ( rc );
                goto err_no_loaded_image;
        }
        DBGC ( systab, "EFI image base address %p\n",
               efi_loaded_image->ImageBase );
 
        /* Record command line */
        efi_cmdline = efi_loaded_image->LoadOptions;
        efi_cmdline_len = efi_loaded_image->LoadOptionsSize;
 
        /* Get loaded image's device handle's device path */
        if ( ( rc = efi_open ( efi_loaded_image->DeviceHandle,
                               &efi_device_path_protocol_guid,
                               &device_path ) ) != 0 ) {
                DBGC ( systab, "EFI could not get loaded image's device path: "
                       "%s", strerror ( rc ) );
                efirc = EFIRC ( rc );
                goto err_no_device_path;
        }
 
        /* Make a copy of the loaded image's device handle's device
         * path, since the device handle itself may become invalidated
         * when we load our own drivers.
         */
        device_path_len = ( efi_path_len ( device_path ) +
                            sizeof ( EFI_DEVICE_PATH_PROTOCOL ) );
        if ( ( efirc = bs->AllocatePool ( EfiBootServicesData, device_path_len,
                                          &device_path_copy ) ) != 0 ) {
                rc = -EEFI ( efirc );
                goto err_alloc_device_path;
        }
        memcpy ( device_path_copy, device_path, device_path_len );
        efi_loaded_image_path = device_path_copy;
        DBGC ( systab, "EFI image device path %s\n",
               efi_devpath_text ( efi_loaded_image_path ) );
 
        /* EFI is perfectly capable of gracefully shutting down any
         * loaded devices if it decides to fall back to a legacy boot.
         * For no particularly comprehensible reason, it doesn't
         * bother doing so when ExitBootServices() is called.
         */
        if ( ( efirc = bs->CreateEvent ( EVT_SIGNAL_EXIT_BOOT_SERVICES,
                                         TPL_NOTIFY, efi_shutdown_hook,
                                         NULL, &efi_shutdown_event ) ) != 0 ) {
                rc = -EEFI ( efirc );
                DBGC ( systab, "EFI could not create ExitBootServices event: "
                       "%s\n", strerror ( rc ) );
                goto err_create_event;
        }
 
        /* Install driver binding protocol */
        if ( ( rc = efi_driver_install() ) != 0 ) {
                DBGC ( systab, "EFI could not install driver: %s\n",
                       strerror ( rc ) );
                efirc = EFIRC ( rc );
                goto err_driver_install;
        }
 
        /* Install image unload method */
        efi_loaded_image->Unload = efi_unload;
 
        return 0;
 
        efi_driver_uninstall();
 err_driver_install:
        bs->CloseEvent ( efi_shutdown_event );
 err_create_event:
        bs->FreePool ( efi_loaded_image_path );
 err_alloc_device_path:
 err_no_device_path:
 err_no_loaded_image:
 err_missing_table:
 err_missing_protocol:
 err_sanity:
        return efirc;
}

References EFI_BOOT_SERVICES::AllocatePool, EFI_SYSTEM_TABLE::BootServices, EFI_BOOT_SERVICES::CloseEvent, EFI_SYSTEM_TABLE::ConOut, EFI_BOOT_SERVICES::CreateEvent, DBGC, device_path, EEFI, efi_cmdline, efi_cmdline_len, EFI_CONFIG_TABLES, efi_device_path_protocol_guid, efi_devpath_text(), efi_driver_install(), efi_driver_uninstall(), efi_exit, efi_find_table(), efi_guid_ntoa(), EFI_HANDLE, efi_image_handle, efi_loaded_image, efi_loaded_image_path, efi_loaded_image_protocol_guid, EFI_NOT_AVAILABLE_YET, efi_open, efi_open_unsafe, efi_path_len(), EFI_PROTOCOLS, efi_shutdown_event, efi_shutdown_hook(), efi_systab, efi_unload(), EfiBootServicesData, EFIRC, EVT_SIGNAL_EXIT_BOOT_SERVICES, EFI_BOOT_SERVICES::Exit, for_each_table_entry, EFI_BOOT_SERVICES::FreePool, efi_config_table::guid, efi_protocol::guid, EFI_BOOT_SERVICES::LocateProtocol, memcpy(), NULL, efi_protocol::protocol, rc, efi_config_table::required, efi_protocol::required, EFI_SYSTEM_TABLE::RuntimeServices, strerror(), efi_config_table::table, and TPL_NOTIFY.

Referenced by _efi_start(), and _efidrv_start().

◆ __stack_chk_fail()

void __stack_chk_fail ( void )

Abort on stack check failure.

Definition at line 356 of file efi_init.c.

                                                            {
        EFI_STATUS efirc;
        int rc;
 
        /* Report failure (when debugging) */
        DBGC ( efi_systab, "EFI stack check failed (cookie %#lx); aborting\n",
               __stack_chk_guard );
 
        /* Attempt to exit cleanly with an error status */
        if ( efi_exit ) {
                efirc = efi_exit ( efi_image_handle, EFI_COMPROMISED_DATA,
                                   0, NULL );
                rc = -EEFI ( efirc );
                DBGC ( efi_systab, "EFI stack check exit failed: %s\n",
                       strerror ( rc ) );
        }
 
        /* If the exit fails for any reason, lock the system */
        while ( 1 ) {}
 
}

References __stack_chk_guard, DBGC, EEFI, EFI_COMPROMISED_DATA, efi_exit, efi_image_handle, efi_systab, NULL, rc, and strerror().

◆ efi_raise_tpl()

void efi_raise_tpl ( struct efi_saved_tpl * tpl )

Raise task priority level to internal level.

Parameters

tpl Saved TPL

Definition at line 383 of file efi_init.c.

                                                 {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
 
        /* Record current external TPL */
        tpl->previous = efi_external_tpl;
 
        /* Raise TPL and record previous TPL as new external TPL */
        tpl->current = bs->RaiseTPL ( efi_internal_tpl );
        efi_external_tpl = tpl->current;
}

References efi_saved_tpl::current, efi_external_tpl, efi_internal_tpl, efi_systab, efi_saved_tpl::previous, and EFI_BOOT_SERVICES::RaiseTPL.

Referenced by _efidrv_start(), efi_driver_start(), efi_driver_stop(), efi_snp_add_claim(), efi_snp_get_status(), efi_snp_initialize(), efi_snp_receive(), efi_snp_reset(), efi_snp_shutdown(), efi_snp_transmit(), efi_snp_wait_for_packet(), efi_unload(), efi_usb_async_interrupt_transfer(), efi_usb_bulk_transfer(), efi_usb_control_transfer(), efi_usb_get_string_descriptor(), efi_usb_sync_interrupt_transfer(), efi_vlan_find(), efi_vlan_remove(), and efi_vlan_set().

◆ efi_restore_tpl()

void efi_restore_tpl ( struct efi_saved_tpl * tpl )

Restore task priority level.

Parameters

tpl Saved TPL

Definition at line 399 of file efi_init.c.

                                                   {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
 
        /* Restore external TPL */
        efi_external_tpl = tpl->previous;
 
        /* Restore TPL */
        bs->RestoreTPL ( tpl->current );
}