efi_open.c

Go to the documentation of this file.

/*
 * Copyright (C) 2025 Michael Brown <mbrown@fensystems.co.uk>.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 * 02110-1301, USA.
 *
 * You can also choose to distribute this program under the terms of
 * the Unmodified Binary Distribution Licence (as given in the file
 * COPYING.UBDL), provided that you have satisfied its requirements.
 */

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );

/** @file
 *
 * 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.
 */

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

/**
 * Open (or test) protocol for ephemeral use
 *
 * @v handle            EFI handle
 * @v protocol          Protocol GUID
 * @v interface         Protocol interface pointer to fill in (or NULL to test)
 * @ret rc              Return status code
 */
int efi_open_untyped ( EFI_HANDLE handle, EFI_GUID *protocol,
                       void **interface ) {
        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;
}

/**
 * Open protocol for unsafe persistent use
 *
 * @v handle            EFI handle
 * @v protocol          Protocol GUID
 * @v interface         Protocol interface pointer to fill in
 * @ret rc              Return status code
 */
int efi_open_unsafe_untyped ( EFI_HANDLE handle, EFI_GUID *protocol,
                              void **interface ) {
        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;
}

/**
 * Close protocol opened for unsafe persistent use
 *
 * @v handle            EFI handle
 * @v protocol          Protocol GUID
 * @v child             Child controller handle
 */
void efi_close_unsafe ( EFI_HANDLE handle, EFI_GUID *protocol ) {
        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 );
}

/**
 * Open protocol for persistent use by a driver
 *
 * @v handle            EFI handle
 * @v protocol          Protocol GUID
 * @v interface         Protocol interface pointer to fill in
 * @ret rc              Return status code
 */
int efi_open_by_driver_untyped ( EFI_HANDLE handle, EFI_GUID *protocol,
                                 void **interface ) {
        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;
}

/**
 * Close protocol opened for persistent use by a driver
 *
 * @v handle            EFI handle
 * @v protocol          Protocol GUID
 */
void efi_close_by_driver ( EFI_HANDLE handle, EFI_GUID *protocol ) {
        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 );
}

/**
 * Open protocol for persistent use by a child controller
 *
 * @v handle            EFI handle
 * @v protocol          Protocol GUID
 * @v child             Child controller handle
 * @v interface         Protocol interface pointer to fill in
 * @ret rc              Return status code
 */
int efi_open_by_child_untyped ( EFI_HANDLE handle, EFI_GUID *protocol,
                                EFI_HANDLE child, void **interface ) {
        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;
}

/**
 * Close protocol opened for persistent use by a child controller
 *
 * @v handle            EFI handle
 * @v protocol          Protocol GUID
 * @v child             Child controller handle
 */
void efi_close_by_child ( EFI_HANDLE handle, EFI_GUID *protocol,
                          EFI_HANDLE child ) {
        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 );
}