--- /dev/null
+/*
+ * 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 ( 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 ( 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 ( 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 ( 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 );
+}
projects / thirdparty / ipxe.git / commitdiff
