Merge pull request #1858 from rust-osdev/handle-convenience

uefi: significantly improve ergonomics of Handle (device path and component2 protocols)

Author: phip1611

uefi-test-runner/src/proto/device_path.rs

@@ -107,7 +107,7 @@ fn test_device_path_to_string() {
     let path = create_test_device_path();
 
     let to_text =
-        |display_only, allow_shortcuts| path.to_string(display_only, allow_shortcuts).unwrap();
+        |display_only, allow_shortcuts| path.to_string16(display_only, allow_shortcuts).unwrap();
 
     assert_eq!(
         &*to_text(DisplayOnly(true), AllowShortcuts(true)),
@@ -167,7 +167,7 @@ fn test_device_path_node_to_string() {
     let nodes: Vec<_> = path.node_iter().collect();
 
     let to_text = |node: &DevicePathNode, display_only, allow_shortcuts| {
-        node.to_string(display_only, allow_shortcuts).unwrap()
+        node.to_string16(display_only, allow_shortcuts).unwrap()
     };
 
     assert_eq!(
@@ -229,20 +229,20 @@ fn test_device_path_append() {
     let node = path.node_iter().next().unwrap();
 
     assert_eq!(
-        path.to_string(DisplayOnly(false), AllowShortcuts(false))
+        path.to_string16(DisplayOnly(false), AllowShortcuts(false))
             .unwrap(),
         cstr16!("Ata(Primary,Master,0x1)/VenMsg(E0C14753-F9BE-11D2-9A0C-0090273FC14D)")
     );
     assert_eq!(
-        node.to_string(DisplayOnly(false), AllowShortcuts(false))
+        node.to_string16(DisplayOnly(false), AllowShortcuts(false))
             .unwrap(),
         cstr16!("Ata(Primary,Master,0x1)")
     );
 
     assert_eq!(
         path.append_path(&path2)
             .unwrap()
-            .to_string(DisplayOnly(false), AllowShortcuts(false))
+            .to_string16(DisplayOnly(false), AllowShortcuts(false))
             .unwrap(),
         cstr16!(
             "Ata(Primary,Master,0x1)/VenMsg(E0C14753-F9BE-11D2-9A0C-0090273FC14D)/Ata(Primary,Master,0x1)/VenMsg(E0C14753-F9BE-11D2-9A0C-0090273FC14D)"
@@ -251,7 +251,7 @@ fn test_device_path_append() {
     assert_eq!(
         path.append_node(node)
             .unwrap()
-            .to_string(DisplayOnly(false), AllowShortcuts(false))
+            .to_string16(DisplayOnly(false), AllowShortcuts(false))
             .unwrap(),
         cstr16!(
             "Ata(Primary,Master,0x1)/VenMsg(E0C14753-F9BE-11D2-9A0C-0090273FC14D)/Ata(Primary,Master,0x1)"

uefi-test-runner/src/proto/mod.rs

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
 use uefi::boot::{self, OpenProtocolParams};
+use uefi::proto::device_path::DevicePath;
+use uefi::proto::driver::ComponentName2;
 use uefi::proto::loaded_image::LoadedImage;
 use uefi::{Identify, proto};
 
@@ -44,6 +46,9 @@ pub fn test() {
     shim::test();
     shell::test();
     tcg::test();
+
+    // now test some convenience that combines several things
+    test_handle_convenience();
 }
 
 fn find_protocol() {
@@ -74,6 +79,32 @@ fn test_test_protocol() {
     );
 }
 
+fn test_handle_convenience() {
+    // Handles that implement the following protocols:
+    // - component name 2
+    // - device path
+    let handles = {
+        let mut cn2_handles = boot::find_handles::<ComponentName2>().unwrap();
+        let dvp_handles = boot::find_handles::<DevicePath>().unwrap();
+
+        cn2_handles.retain(|x| dvp_handles.contains(x));
+        cn2_handles
+    };
+    for handle in handles {
+        let dvp = handle.device_path().expect("should have device path");
+        let cn2 = handle
+            .component_name()
+            .expect("should have component name (v2)");
+        info!("handle: {:x?}", handle);
+        info!("|- dvp: {dvp}");
+        info!("|- cn2 driver: {}", cn2.driver_name("en").unwrap());
+        info!(
+            "|- cn2 controller: {}",
+            cn2.controller_name(handle, None, "en").unwrap()
+        );
+    }
+}
+
 #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
 mod ata;
 mod console;

uefi-test-runner/src/proto/network/http.rs

@@ -2,24 +2,12 @@
 
 use alloc::vec::Vec;
 
-use uefi::proto::device_path::DevicePath;
-use uefi::proto::device_path::text::{AllowShortcuts, DisplayOnly};
 use uefi::proto::network::http::{HttpBinding, HttpHelper};
 use uefi::proto::network::ip4config2::Ip4Config2;
 use uefi::{Handle, boot};
 
 use uefi_raw::protocol::network::http::HttpStatusCode;
 
-pub fn print_handle_devpath(prefix: &str, handle: &Handle) {
-    let Ok(dp) = boot::open_protocol_exclusive::<DevicePath>(*handle) else {
-        info!("{prefix}no device path for handle");
-        return;
-    };
-    if let Ok(string) = dp.to_string(DisplayOnly(true), AllowShortcuts(true)) {
-        info!("{prefix}{string}");
-    }
-}
-
 fn fetch_http(handle: Handle, url: &str) -> Option<Vec<u8>> {
     info!("http: fetching {url} ...");
 
@@ -91,7 +79,7 @@ pub fn test() {
         .expect("get nic handles");
 
     for h in handles.as_ref() {
-        print_handle_devpath("nic: ", h);
+        info!("nic: {}", h.device_path().expect("should have device path"));
 
         info!("Bring up interface (ip4 config2 protocol)");
         let mut ip4 = Ip4Config2::new(*h).expect("open ip4 config2 protocol");

uefi-test-runner/src/proto/nvme/pass_thru.rs

@@ -2,8 +2,6 @@
 
 use core::time::Duration;
 use uefi::boot;
-use uefi::proto::device_path::DevicePath;
-use uefi::proto::device_path::text::{AllowShortcuts, DisplayOnly};
 use uefi::proto::media::block::BlockIO;
 use uefi::proto::nvme::pass_thru::NvmePassThru;
 use uefi::proto::nvme::{NvmeQueueType, NvmeRequestBuilder};
@@ -17,19 +15,14 @@ pub fn test() {
 fn has_nvme_drive() -> bool {
     let block_io_handles = boot::find_handles::<BlockIO>().unwrap();
     for handle in block_io_handles {
-        let Ok(device_path) = boot::open_protocol_exclusive::<DevicePath>(handle) else {
-            continue;
-        };
-        let mut device_path = &*device_path;
+        let device_path_proto = handle.device_path().expect("should have device path");
+        let mut device_path = &*device_path_proto;
 
         let Ok(nvme_pt_handle) = boot::locate_device_path::<NvmePassThru>(&mut device_path) else {
             continue;
         };
         let nvme_pt = boot::open_protocol_exclusive::<NvmePassThru>(nvme_pt_handle).unwrap();
-        let device_path_str = device_path
-            .to_string(DisplayOnly(true), AllowShortcuts(false))
-            .unwrap();
-        info!("- Successfully opened NVMe: {device_path_str}");
+        info!("- Successfully opened NVMe: {device_path_proto}");
         let mut nvme_ctrl = nvme_pt.controller();
 
         let request = NvmeRequestBuilder::new(nvme_pt.io_align(), 0x06, NvmeQueueType::ADMIN)

uefi-test-runner/src/proto/pci/root_bridge.rs

@@ -45,7 +45,7 @@ pub fn test() {
             let subclass_code = ((reg1 >> 16) & 0xFF) as u8;
             let device_path = pci_tree.device_path(&root_device_path, addr).unwrap();
             let device_path_str = device_path
-                .to_string(DisplayOnly(false), AllowShortcuts(false))
+                .to_string16(DisplayOnly(false), AllowShortcuts(false))
                 .unwrap()
                 .to_string();
 
@@ -81,7 +81,7 @@ pub fn test() {
     for scsi_handle in scsi_handles {
         let device_path = get_open_protocol::<DevicePath>(scsi_handle);
         let device_path = device_path
-            .to_string(DisplayOnly(false), AllowShortcuts(false))
+            .to_string16(DisplayOnly(false), AllowShortcuts(false))
             .unwrap()
             .to_string();
         assert!(mass_storage_dev_paths.contains(&device_path));

uefi/CHANGELOG.md

@@ -11,6 +11,13 @@
 - Added `proto::device_path::DevicePathUtilities::duplicate_path()`.
 - Added `proto::pci::enumeration::PciTree::device_path()`.
 - Added `revision()` and `device_type_guid()` to `Serial` protocol
+- Implemented `Display` for `DevicePath`, `DevicePathNode` and `ScopedProtocol`,
+  enabling a easy and convenient way to visualize a device path. For example,
+  this may print `PciRoot(0x0)/Pci(0x6,0x0)/MAC(525400000001,0x1)`.
+  `ScopedProtocol` only implements `Display` if the underlying protocol also
+  implements `Display`.
+- Added `Handle::component_name()` and `Handle::device_path()` to simplify the
+  common use-case of querying more information about a handle.
 
 ## Changed
 - export all `text::{input, output}::*` types
@@ -28,6 +35,12 @@
 - **Breaking:** `boot::check_event` now consumes `&Event` rather than `Event`, removing the
   need for unnecessary `Event::unsafe_clone()`s.
 - MSRV increased to 1.88.
+- **Breaking:** Renamed `DevicePath::to_string()` to `DevicePath::to_string16()`
+  to better differentiate with the new `to_string()` coming from the new
+  `Display`.
+- **Breaking:** Renamed `DevicePathNode::to_string()` to `DevicePathNode::to_string16()`
+  to better differentiate with the new `to_string()` coming from the new
+  `Display`.
 
 # uefi - v0.36.1 (2025-11-05)
 

uefi/src/boot.rs

@@ -45,6 +45,7 @@ use crate::table::Revision;
 use crate::util::opt_nonnull_to_ptr;
 use crate::{Char16, Error, Event, Guid, Handle, Result, Status, StatusExt, table};
 use core::ffi::c_void;
+use core::fmt::{Display, Formatter};
 use core::mem::MaybeUninit;
 use core::ops::{Deref, DerefMut};
 use core::ptr::{self, NonNull};
@@ -1619,6 +1620,20 @@ impl<P: Protocol + ?Sized> ScopedProtocol<P> {
     }
 }
 
+// Forward Display impl to inner protocol:
+impl<P: Protocol + ?Sized + Display> Display for ScopedProtocol<P> {
+    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
+        match self.get() {
+            Some(proto) => {
+                write!(f, "{proto}")
+            }
+            None => {
+                write!(f, "<none>")
+            }
+        }
+    }
+}
+
 impl<P: Protocol + ?Sized> Drop for ScopedProtocol<P> {
     fn drop(&mut self) {
         let bt = boot_services_raw_panicking();