Merge pull request #550 from timrobertsdev/protocol-handler-services

Implement additional `BootServices` functions

Author: nicholasbishop

CHANGELOG.md

@@ -16,6 +16,11 @@
 - Added structs to represent each type of device path node. All node
   types specified in the UEFI 2.10 Specification are now supported.
 - Added `DevicePathBuilder` for building new device paths.
+- Added `BootServices::install_protocol_interface`,
+  `BootServices::uninstall_protocol_interface`, and
+  `BootServices::reinstall_protocol_interface`.
+- Added `BootServices::register_protocol_notify`.
+- Added `SearchType::ByRegisterNotify`and `ProtocolSearchKey`.
 
 ### Changed
 

src/table/boot.rs

@@ -128,17 +128,35 @@ pub struct BootServices {
     check_event: unsafe extern "efiapi" fn(event: Event) -> Status,
 
     // Protocol handlers
-    install_protocol_interface: usize,
-    reinstall_protocol_interface: usize,
-    uninstall_protocol_interface: usize,
+    install_protocol_interface: unsafe extern "efiapi" fn(
+        handle: &mut Option<Handle>,
+        guid: &Guid,
+        interface_type: InterfaceType,
+        interface: *mut c_void,
+    ) -> Status,
+    reinstall_protocol_interface: unsafe extern "efiapi" fn(
+        handle: Handle,
+        protocol: &Guid,
+        old_interface: *mut c_void,
+        new_interface: *mut c_void,
+    ) -> Status,
+    uninstall_protocol_interface: unsafe extern "efiapi" fn(
+        handle: Handle,
+        protocol: &Guid,
+        interface: *mut c_void,
+    ) -> Status,
     handle_protocol:
         extern "efiapi" fn(handle: Handle, proto: &Guid, out_proto: &mut *mut c_void) -> Status,
     _reserved: usize,
-    register_protocol_notify: usize,
+    register_protocol_notify: extern "efiapi" fn(
+        protocol: &Guid,
+        event: Event,
+        registration: *mut ProtocolSearchKey,
+    ) -> Status,
     locate_handle: unsafe extern "efiapi" fn(
         search_ty: i32,
-        proto: *const Guid,
-        key: *mut c_void,
+        proto: Option<&Guid>,
+        key: Option<ProtocolSearchKey>,
         buf_sz: &mut usize,
         buf: *mut MaybeUninit<Handle>,
     ) -> Status,
@@ -221,8 +239,8 @@ pub struct BootServices {
     ) -> Status,
     locate_handle_buffer: unsafe extern "efiapi" fn(
         search_ty: i32,
-        proto: *const Guid,
-        key: *const c_void,
+        proto: Option<&Guid>,
+        key: Option<ProtocolSearchKey>,
         no_handles: &mut usize,
         buf: &mut *mut Handle,
     ) -> Status,
@@ -618,6 +636,72 @@ impl BootServices {
         }
     }
 
+    /// Installs a protocol interface on a device handle. If the inner `Option` in `handle` is `None`,
+    /// one will be created and added to the list of handles in the system and then returned.
+    ///
+    /// When a protocol interface is installed, firmware will call all functions that have registered
+    /// to wait for that interface to be installed.
+    ///
+    /// # Safety
+    ///
+    /// The caller is responsible for ensuring that they pass a valid `Guid` for `protocol`.
+    pub unsafe fn install_protocol_interface(
+        &self,
+        mut handle: Option<Handle>,
+        protocol: &Guid,
+        interface: *mut c_void,
+    ) -> Result<Handle> {
+        ((self.install_protocol_interface)(
+            &mut handle,
+            protocol,
+            InterfaceType::NATIVE_INTERFACE,
+            interface,
+        ))
+        // this `unwrapped_unchecked` is safe, `handle` is guaranteed to be Some() if this call is
+        // successful
+        .into_with_val(|| handle.unwrap_unchecked())
+    }
+
+    /// Reinstalls a protocol interface on a device handle. `old_interface` is replaced with `new_interface`.
+    /// These interfaces may be the same, in which case the registered protocol notifies occur for the handle
+    /// without replacing the interface.
+    ///
+    /// As with `install_protocol_interface`, any process that has registered to wait for the installation of
+    /// the interface is notified.
+    ///
+    /// # Safety
+    ///
+    /// The caller is responsible for ensuring that there are no references to the `old_interface` that is being
+    /// removed.
+    pub unsafe fn reinstall_protocol_interface(
+        &self,
+        handle: Handle,
+        protocol: &Guid,
+        old_interface: *mut c_void,
+        new_interface: *mut c_void,
+    ) -> Result<()> {
+        (self.reinstall_protocol_interface)(handle, protocol, old_interface, new_interface).into()
+    }
+
+    /// Removes a protocol interface from a device handle.
+    ///
+    /// # Safety
+    ///
+    /// The caller is responsible for ensuring that there are no references to a protocol interface
+    /// that has been removed. Some protocols may not be able to be removed as there is no information
+    /// available regarding the references. This includes Console I/O, Block I/O, Disk I/o, and handles
+    /// to device protocols.
+    ///
+    /// The caller is responsible for ensuring that they pass a valid `Guid` for `protocol`.
+    pub unsafe fn uninstall_protocol_interface(
+        &self,
+        handle: Handle,
+        protocol: &Guid,
+        interface: *mut c_void,
+    ) -> Result<()> {
+        (self.uninstall_protocol_interface)(handle, protocol, interface).into()
+    }
+
     /// Query a handle for a certain protocol.
     ///
     /// This function attempts to get the protocol implementation of a handle,
@@ -655,6 +739,31 @@ impl BootServices {
         })
     }
 
+    /// Registers `event` to be signalled whenever a protocol interface is registered for
+    /// `protocol` by `install_protocol_interface()` or `reinstall_protocol_interface()`.
+    ///
+    /// Once `event` has been signalled, `BootServices::locate_handle()` can be used to identify
+    /// the newly (re)installed handles that support `protocol`. The returned `SearchKey` on success
+    /// corresponds to the `search_key` parameter in `locate_handle()`.
+    ///
+    /// Events can be unregistered from protocol interface notification by calling `close_event()`.
+    pub fn register_protocol_notify(
+        &self,
+        protocol: &Guid,
+        event: Event,
+    ) -> Result<(Event, SearchType)> {
+        let mut key: MaybeUninit<ProtocolSearchKey> = MaybeUninit::uninit();
+        // Safety: we clone `event` a couple times, but there will be only one left once we return.
+        unsafe { (self.register_protocol_notify)(protocol, event.unsafe_clone(), key.as_mut_ptr()) }
+            // Safety: as long as this call is successful, `key` will be valid.
+            .into_with_val(|| unsafe {
+                (
+                    event.unsafe_clone(),
+                    SearchType::ByRegisterNotify(key.assume_init()),
+                )
+            })
+    }
+
     /// Enumerates all handles installed on the system which match a certain query.
     ///
     /// You should first call this function with `None` for the output buffer,
@@ -677,8 +786,9 @@ impl BootServices {
 
         // Obtain the needed data from the parameters.
         let (ty, guid, key) = match search_ty {
-            SearchType::AllHandles => (0, ptr::null(), ptr::null_mut()),
-            SearchType::ByProtocol(guid) => (2, guid as *const _, ptr::null_mut()),
+            SearchType::AllHandles => (0, None, None),
+            SearchType::ByRegisterNotify(registration) => (1, None, Some(registration)),
+            SearchType::ByProtocol(guid) => (2, Some(guid), None),
         };
 
         let status = unsafe { (self.locate_handle)(ty, guid, key, &mut buffer_size, buffer) };
@@ -1095,8 +1205,9 @@ impl BootServices {
 
         // Obtain the needed data from the parameters.
         let (ty, guid, key) = match search_ty {
-            SearchType::AllHandles => (0, ptr::null(), ptr::null_mut()),
-            SearchType::ByProtocol(guid) => (2, guid as *const _, ptr::null_mut()),
+            SearchType::AllHandles => (0, None, None),
+            SearchType::ByRegisterNotify(registration) => (1, None, Some(registration)),
+            SearchType::ByProtocol(guid) => (2, Some(guid), None),
         };
 
         unsafe { (self.locate_handle_buffer)(ty, guid, key, &mut num_handles, &mut buffer) }
@@ -1731,7 +1842,9 @@ pub enum SearchType<'guid> {
     /// If the protocol implements the `Protocol` interface,
     /// you can use the `from_proto` function to construct a new `SearchType`.
     ByProtocol(&'guid Guid),
-    // TODO: add ByRegisterNotify once the corresponding function is implemented.
+    /// Return all handles that implement a protocol when an interface for that protocol
+    /// is (re)installed.
+    ByRegisterNotify(ProtocolSearchKey),
 }
 
 impl<'guid> SearchType<'guid> {
@@ -1844,3 +1957,19 @@ impl<'a> HandleBuffer<'a> {
         unsafe { slice::from_raw_parts(self.buffer, self.count) }
     }
 }
+
+newtype_enum! {
+/// Interface type of a protocol interface
+///
+/// Only has one variant when this was written (v2.10 of the UEFI spec)
+pub enum InterfaceType: i32 => {
+    /// Native interface
+    NATIVE_INTERFACE    = 0,
+}
+}
+
+/// Opaque pointer returned by [`BootServices::register_protocol_notify`] to be used
+/// with [`BootServices::locate_handle`] via [`SearchType::ByRegisterNotify`].
+#[derive(Debug, Clone, Copy)]
+#[repr(transparent)]
+pub struct ProtocolSearchKey(NonNull<c_void>);

uefi-test-runner/src/boot/misc.rs

@@ -1,8 +1,9 @@
 use core::ffi::c_void;
-use core::ptr::NonNull;
+use core::ptr::{self, NonNull};
 
-use uefi::table::boot::{BootServices, EventType, TimerTrigger, Tpl};
-use uefi::Event;
+use uefi::proto::Protocol;
+use uefi::table::boot::{BootServices, EventType, SearchType, TimerTrigger, Tpl};
+use uefi::{unsafe_guid, Event, Identify};
 
 pub fn test(bt: &BootServices) {
     info!("Testing timer...");
@@ -12,6 +13,11 @@ pub fn test(bt: &BootServices) {
     test_callback_with_ctx(bt);
     info!("Testing watchdog...");
     test_watchdog(bt);
+    info!("Testing protocol handler services...");
+    test_register_protocol_notify(bt);
+    test_install_protocol_interface(bt);
+    test_reinstall_protocol_interface(bt);
+    test_uninstall_protocol_interface(bt);
 }
 
 fn test_timer(bt: &BootServices) {
@@ -72,3 +78,71 @@ fn test_watchdog(bt: &BootServices) {
     bt.set_watchdog_timer(0, 0x10000, None)
         .expect("Could not set watchdog timer");
 }
+
+/// Dummy protocol for tests
+#[unsafe_guid("1a972918-3f69-4b5d-8cb4-cece2309c7f5")]
+#[derive(Protocol)]
+struct TestProtocol {}
+
+unsafe extern "efiapi" fn _test_notify(_event: Event, _context: Option<NonNull<c_void>>) {
+    info!("Protocol was (re)installed and this function notified.")
+}
+
+fn test_register_protocol_notify(bt: &BootServices) {
+    let protocol = &TestProtocol::GUID;
+    let event = unsafe {
+        bt.create_event(
+            EventType::NOTIFY_SIGNAL,
+            Tpl::NOTIFY,
+            Some(_test_notify),
+            None,
+        )
+        .expect("Failed to create an event")
+    };
+
+    bt.register_protocol_notify(protocol, event)
+        .expect("Failed to register protocol notify fn");
+}
+
+fn test_install_protocol_interface(bt: &BootServices) {
+    info!("Installing TestProtocol");
+
+    let _ = unsafe {
+        bt.install_protocol_interface(None, &TestProtocol::GUID, ptr::null_mut())
+            .expect("Failed to install protocol interface")
+    };
+
+    let _ = bt
+        .locate_handle_buffer(SearchType::from_proto::<TestProtocol>())
+        .expect("Failed to find protocol after it was installed");
+}
+
+fn test_reinstall_protocol_interface(bt: &BootServices) {
+    info!("Reinstalling TestProtocol");
+    let handle = bt
+        .locate_handle_buffer(SearchType::from_proto::<TestProtocol>())
+        .expect("Failed to find protocol to uninstall")
+        .handles()[0];
+
+    unsafe {
+        let _ = bt.reinstall_protocol_interface(
+            handle,
+            &TestProtocol::GUID,
+            ptr::null_mut(),
+            ptr::null_mut(),
+        );
+    }
+}
+
+fn test_uninstall_protocol_interface(bt: &BootServices) {
+    info!("Uninstalling TestProtocol");
+    let handle = bt
+        .locate_handle_buffer(SearchType::from_proto::<TestProtocol>())
+        .expect("Failed to find protocol to uninstall")
+        .handles()[0];
+
+    unsafe {
+        bt.uninstall_protocol_interface(handle, &TestProtocol::GUID, ptr::null_mut())
+            .expect("Failed to uninstall protocol interface");
+    }
+}

uefi-test-runner/src/main.rs

@@ -1,6 +1,7 @@
 #![no_std]
 #![no_main]
 #![feature(abi_efiapi)]
+#![feature(negative_impls)]
 
 #[macro_use]
 extern crate log;