efi_open.c File Reference

EFI protocol opening and closing. More...

#include <assert.h>
#include <errno.h>
#include <ipxe/efi/efi.h>

Go to the source code of this file.

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
int	efi_open_untyped (EFI_HANDLE handle, EFI_GUID *protocol, void **interface)
	Open (or test) protocol for ephemeral use. More...
int	efi_open_unsafe_untyped (EFI_HANDLE handle, EFI_GUID *protocol, void **interface)
	Open protocol for unsafe persistent use. More...
void	efi_close_unsafe (EFI_HANDLE handle, EFI_GUID *protocol)
	Close protocol opened for unsafe persistent use. More...
int	efi_open_by_driver_untyped (EFI_HANDLE handle, EFI_GUID *protocol, void **interface)
	Open protocol for persistent use by a driver. More...
void	efi_close_by_driver (EFI_HANDLE handle, EFI_GUID *protocol)
	Close protocol opened for persistent use by a driver. More...
int	efi_open_by_child_untyped (EFI_HANDLE handle, EFI_GUID *protocol, EFI_HANDLE child, void **interface)
	Open protocol for persistent use by a child controller. More...
void	efi_close_by_child (EFI_HANDLE handle, EFI_GUID *protocol, EFI_HANDLE child)
	Close protocol opened for persistent use by a child controller. More...

Detailed Description

EFI protocol opening and closing.

The UEFI model for opening and closing protocols is broken by design and cannot be repaired.

Calling OpenProtocol() to obtain a protocol interface pointer does not, in general, provide any guarantees about the lifetime of that pointer. It is theoretically possible that the pointer has already become invalid by the time that OpenProtocol() returns the pointer to its caller. (This can happen when a USB device is physically removed, for example.)

Various UEFI design flaws make it occasionally necessary to hold on to a protocol interface pointer despite the total lack of guarantees that the pointer will remain valid.

The UEFI driver model overloads the semantics of OpenProtocol() to accommodate the use cases of recording a driver attachment (which is modelled as opening a protocol with EFI_OPEN_PROTOCOL_BY_DRIVER attributes) and recording the existence of a related child controller (which is modelled as opening a protocol with EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER attributes).

The parameters defined for CloseProtocol() are not sufficient to allow the implementation to precisely identify the matching call to OpenProtocol(). While the UEFI model appears to allow for matched open and close pairs, this is merely an illusion. Calling CloseProtocol() will delete all matching records in the protocol open information tables.

Since the parameters defined for CloseProtocol() do not include the attributes passed to OpenProtocol(), this means that a matched open/close pair using EFI_OPEN_PROTOCOL_GET_PROTOCOL can inadvertently end up deleting the record that defines a driver attachment or the existence of a child controller. This in turn can cause some very unexpected side effects, such as allowing other UEFI drivers to start controlling hardware to which iPXE believes it has exclusive access. This rarely ends well.

To prevent this kind of inadvertent deletion, we establish a convention for four different types of protocol opening:

• ephemeral opens: always opened with ControllerHandle = NULL
• unsafe opens: always opened with ControllerHandle = AgentHandle
• by-driver opens: always opened with ControllerHandle = Handle
• by-child opens: always opened with ControllerHandle != Handle

This convention ensures that the four types of open never overlap within the set of parameters defined for CloseProtocol(), and so a close of one type cannot inadvertently delete the record corresponding to a different type.

Definition in file efi_open.c.

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

efi_open_untyped()

int efi_open_untyped	(	EFI_HANDLE	handle,
		EFI_GUID *	protocol,
		void **	interface
	)

Open (or test) protocol for ephemeral use.

Parameters

handle	EFI handle
protocol	Protocol GUID
interface	Protocol interface pointer to fill in (or NULL to test)

Return values

rc	Return status code

Definition at line 96 of file efi_open.c.

                                          {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
        EFI_HANDLE agent = efi_image_handle;
        EFI_HANDLE controller;
        unsigned int attributes;
        EFI_STATUS efirc;
        int rc;

        /* Sanity checks */
        assert ( handle != NULL );
        assert ( protocol != NULL );

        /* Open protocol
         *
         * We set ControllerHandle to NULL to avoid collisions with
         * other open types.
         */
        controller = NULL;
        attributes = ( interface ? EFI_OPEN_PROTOCOL_GET_PROTOCOL :
                       EFI_OPEN_PROTOCOL_TEST_PROTOCOL );
        if ( ( efirc = bs->OpenProtocol ( handle, protocol, interface, agent,
                                          controller, attributes ) ) != 0 ) {
                rc = -EEFI ( efirc );
                if ( interface )
                        *interface = NULL;
                return rc;
        }

        /* Close protocol immediately
         *
         * While it may seem prima facie unsafe to use a protocol
         * after closing it, UEFI doesn't actually give us any safety
         * even while the protocol is nominally open.  Opening a
         * protocol with EFI_OPEN_PROTOCOL_GET_PROTOCOL attributes
         * does not in any way ensure that the interface pointer
         * remains valid: there are no locks or notifications
         * associated with these "opens".
         *
         * The only way to obtain a (partially) guaranteed persistent
         * interface pointer is to open the protocol with the
         * EFI_OPEN_PROTOCOL_BY_DRIVER attributes.  This is not
         * possible in the general case, since UEFI permits only a
         * single image at a time to have the protocol opened with
         * these attributes.
         *
         * We can therefore obtain at best an ephemeral interface
         * pointer: one that is guaranteed to remain valid only for as
         * long as we do not relinquish the thread of control.
         *
         * (Since UEFI permits calls to UninstallProtocolInterface()
         * at levels up to and including TPL_NOTIFY, this means that
         * we technically cannot rely on the pointer remaining valid
         * unless the caller is itself running at TPL_NOTIFY.  This is
         * clearly impractical, and large portions of the EDK2
         * codebase presume that using EFI_OPEN_PROTOCOL_GET_PROTOCOL
         * is safe at lower TPLs.)
         *
         * Closing is not strictly necessary for protocols opened
         * ephemerally (i.e. using EFI_OPEN_PROTOCOL_GET_PROTOCOL or
         * EFI_OPEN_PROTOCOL_TEST_PROTOCOL), but avoids polluting the
         * protocol open information tables with stale data.
         *
         * Closing immediately also simplifies the callers' code
         * paths, since they do not need to worry about closing the
         * protocol.
         *
         * The overall effect is equivalent to using HandleProtocol(),
         * but without the associated pollution of the protocol open
         * information tables, and with improved traceability.
         */
        bs->CloseProtocol ( handle, protocol, agent, controller );

        return 0;
}

References assert(), EFI_SYSTEM_TABLE::BootServices, EFI_BOOT_SERVICES::CloseProtocol, controller, EEFI, efi_image_handle, EFI_OPEN_PROTOCOL_GET_PROTOCOL, EFI_OPEN_PROTOCOL_TEST_PROTOCOL, efi_systab, handle, if(), NULL, protocol, and rc.

efi_open_unsafe_untyped()

int efi_open_unsafe_untyped	(	EFI_HANDLE	handle,
		EFI_GUID *	protocol,
		void **	interface
	)

Open protocol for unsafe persistent use.

Parameters

handle	EFI handle
protocol	Protocol GUID
interface	Protocol interface pointer to fill in

Return values

rc	Return status code

Definition at line 180 of file efi_open.c.

                                                 {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
        EFI_HANDLE agent = efi_image_handle;
        EFI_HANDLE controller;
        unsigned int attributes;
        EFI_STATUS efirc;
        int rc;

        /* Sanity checks */
        assert ( handle != NULL );
        assert ( protocol != NULL );
        assert ( interface != NULL );

        /* Open protocol
         *
         * We set ControllerHandle equal to AgentHandle to avoid
         * collisions with other open types.
         */
        controller = agent;
        attributes = EFI_OPEN_PROTOCOL_GET_PROTOCOL;
        if ( ( efirc = bs->OpenProtocol ( handle, protocol, interface, agent,
                                          controller, attributes ) ) != 0 ) {
                rc = -EEFI ( efirc );
                *interface = NULL;
                return rc;
        }

        return 0;
}

References assert(), EFI_SYSTEM_TABLE::BootServices, controller, EEFI, efi_image_handle, EFI_OPEN_PROTOCOL_GET_PROTOCOL, efi_systab, handle, NULL, EFI_BOOT_SERVICES::OpenProtocol, protocol, and rc.

efi_close_unsafe()

void efi_close_unsafe	(	EFI_HANDLE	handle,
		EFI_GUID *	protocol
	)

Close protocol opened for unsafe persistent use.

Parameters

handle	EFI handle
protocol	Protocol GUID
child	Child controller handle

Definition at line 218 of file efi_open.c.

                                                                {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
        EFI_HANDLE agent = efi_image_handle;
        EFI_HANDLE controller;

        /* Sanity checks */
        assert ( handle != NULL );
        assert ( protocol != NULL );

        /* Close protocol */
        controller = agent;
        bs->CloseProtocol ( handle, protocol, agent, controller );
}

References assert(), EFI_SYSTEM_TABLE::BootServices, EFI_BOOT_SERVICES::CloseProtocol, controller, efi_image_handle, efi_systab, handle, NULL, and protocol.

Referenced by efi_bofm_start(), nii_pci_close(), and nii_pci_open().

efi_open_by_driver_untyped()

int efi_open_by_driver_untyped	(	EFI_HANDLE	handle,
		EFI_GUID *	protocol,
		void **	interface
	)

Open protocol for persistent use by a driver.

Parameters

handle	EFI handle
protocol	Protocol GUID
interface	Protocol interface pointer to fill in

Return values

rc	Return status code

Definition at line 240 of file efi_open.c.

                                                    {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
        EFI_HANDLE agent = efi_image_handle;
        EFI_HANDLE controller;
        unsigned int attributes;
        EFI_STATUS efirc;
        int rc;

        /* Sanity checks */
        assert ( handle != NULL );
        assert ( protocol != NULL );
        assert ( interface != NULL );

        /* Open protocol
         *
         * We set ControllerHandle equal to Handle to avoid collisions
         * with other open types.
         */
        controller = handle;
        attributes = ( EFI_OPEN_PROTOCOL_BY_DRIVER |
                       EFI_OPEN_PROTOCOL_EXCLUSIVE );
        if ( ( efirc = bs->OpenProtocol ( handle, protocol, interface, agent,
                                          controller, attributes ) ) != 0 ) {
                rc = -EEFI ( efirc );
                *interface = NULL;
                return rc;
        }

        return 0;
}

References assert(), EFI_SYSTEM_TABLE::BootServices, controller, EEFI, efi_image_handle, EFI_OPEN_PROTOCOL_BY_DRIVER, EFI_OPEN_PROTOCOL_EXCLUSIVE, efi_systab, handle, NULL, EFI_BOOT_SERVICES::OpenProtocol, protocol, and rc.

efi_close_by_driver()

void efi_close_by_driver	(	EFI_HANDLE	handle,
		EFI_GUID *	protocol
	)

Close protocol opened for persistent use by a driver.

Parameters

handle	EFI handle
protocol	Protocol GUID

Definition at line 278 of file efi_open.c.

                                                                   {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
        EFI_HANDLE agent = efi_image_handle;
        EFI_HANDLE controller;

        /* Sanity checks */
        assert ( handle != NULL );
        assert ( protocol != NULL );

        /* Close protocol */
        controller = handle;
        bs->CloseProtocol ( handle, protocol, agent, controller );
}

References assert(), EFI_SYSTEM_TABLE::BootServices, EFI_BOOT_SERVICES::CloseProtocol, controller, efi_image_handle, efi_systab, handle, NULL, and protocol.

Referenced by efi_file_install(), efi_file_uninstall(), efi_snp_probe(), efi_snp_remove(), efipci_start(), efipci_stop(), mnpnet_start(), mnpnet_stop(), nii_start(), nii_stop(), snpnet_start(), snpnet_stop(), usbio_close(), usbio_start(), and usbio_stop().

efi_open_by_child_untyped()

int efi_open_by_child_untyped	(	EFI_HANDLE	handle,
		EFI_GUID *	protocol,
		EFI_HANDLE	child,
		void **	interface
	)

Open protocol for persistent use by a child controller.

Parameters

handle	EFI handle
protocol	Protocol GUID
child	Child controller handle
interface	Protocol interface pointer to fill in

Return values

rc	Return status code

Definition at line 301 of file efi_open.c.

                                                                     {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
        EFI_HANDLE agent = efi_image_handle;
        EFI_HANDLE controller;
        unsigned int attributes;
        EFI_STATUS efirc;
        int rc;

        /* Sanity checks */
        assert ( handle != NULL );
        assert ( protocol != NULL );
        assert ( child != NULL );
        assert ( interface != NULL );

        /* Open protocol
         *
         * We set ControllerHandle to a non-NULL value distinct from
         * both Handle and AgentHandle to avoid collisions with other
         * open types.
         */
        controller = child;
        assert ( controller != handle );
        assert ( controller != agent );
        attributes = EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER;
        if ( ( efirc = bs->OpenProtocol ( handle, protocol, interface, agent,
                                          controller, attributes ) ) != 0 ) {
                rc = -EEFI ( efirc );
                *interface = NULL;
                return rc;
        }

        return 0;
}

References assert(), EFI_SYSTEM_TABLE::BootServices, controller, EEFI, efi_image_handle, EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER, efi_systab, handle, NULL, EFI_BOOT_SERVICES::OpenProtocol, protocol, and rc.

efi_close_by_child()

void efi_close_by_child	(	EFI_HANDLE	handle,
		EFI_GUID *	protocol,
		EFI_HANDLE	child
	)

Close protocol opened for persistent use by a child controller.

Parameters

handle	EFI handle
protocol	Protocol GUID
child	Child controller handle

Definition at line 343 of file efi_open.c.

                                             {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
        EFI_HANDLE agent = efi_image_handle;
        EFI_HANDLE controller;

        /* Sanity checks */
        assert ( handle != NULL );
        assert ( protocol != NULL );
        assert ( child != NULL );

        /* Close protocol */
        controller = child;
        assert ( controller != handle );
        assert ( controller != agent );
        bs->CloseProtocol ( handle, protocol, agent, controller );
}

References assert(), EFI_SYSTEM_TABLE::BootServices, EFI_BOOT_SERVICES::CloseProtocol, controller, efi_image_handle, efi_systab, handle, NULL, and protocol.

Referenced by efi_child_del().