uefi: handle: add protocol-based helpers: component_name() and device_path()

In practice, UEFI applications frequently need to extract additional
metadata from handles for logging, debugging, and user-facing selection.
The Device Path and Component Name 2 protocols provide helpful information,
but accessing them repeatedly requires non-trivial boilerplate.

This change introduces convenience helpers on Handle to streamline
common queries and improve ergonomics when working with these protocols.

Author: phip1611

uefi/CHANGELOG.md

@@ -16,6 +16,8 @@
   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

uefi/src/data_types/mod.rs

@@ -30,12 +30,23 @@ pub use strs::{str_num_latin1_chars, str_to_latin1};
 pub use uefi_raw::{PhysicalAddress, VirtualAddress};
 pub use unaligned_slice::UnalignedSlice;
 
+use crate::Result;
+use crate::boot::{self, OpenProtocolAttributes, OpenProtocolParams, ScopedProtocol};
+use crate::proto::device_path::DevicePath;
+use crate::proto::driver::ComponentName2;
 use core::ffi::c_void;
 use core::ptr::{self, NonNull};
+#[cfg(doc)]
+use uefi_raw::Status;
 
 /// Opaque handle to an UEFI entity (protocol, image...), guaranteed to be non-null.
 ///
 /// If you need to have a nullable handle (for a custom UEFI FFI for example) use `Option<Handle>`.
+///
+/// A handle offers some convenient methods to better explore the context of
+/// it, such as:
+/// - [`Handle::component_name`]
+/// - [`Handle::device_path`]
 #[derive(Clone, Copy, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 #[repr(transparent)]
 pub struct Handle(NonNull<c_void>);
@@ -85,6 +96,78 @@ impl Handle {
     pub(crate) fn opt_to_ptr(handle: Option<Self>) -> *mut c_void {
         handle.map(|h| h.0.as_ptr()).unwrap_or(ptr::null_mut())
     }
+
+    // some convenient protocol helpers
+
+    /// Opens the underlying [`ComponentName2`], if it exists.
+    ///
+    /// # Example
+    /// ```rust,no_run
+    /// # use uefi::Handle;
+    /// # let handle = unsafe { Handle::from_ptr(123 as *mut _).unwrap() };
+    /// let cn2_prot = handle
+    ///   .component_name()
+    ///   .expect("should have component name (v2) protocol");
+    /// log::info!(
+    ///     "driver: {}, controller: {}",
+    ///     cn2_prot.driver_name("en").unwrap(),
+    ///     cn2_prot.controller_name(handle, None, "en").unwrap()
+    /// );
+    /// ```
+    ///
+    /// # Errors
+    ///
+    /// * [`Status::INVALID_PARAMETER`]: an invalid combination of `params` and
+    ///   `attributes` was provided.
+    /// * [`Status::UNSUPPORTED`]: the handle does not support the protocol.
+    /// * [`Status::ACCESS_DENIED`] or [`Status::ALREADY_STARTED`]: the protocol is
+    ///   already open in a way that is incompatible with the new request.
+    pub fn component_name(&self) -> Result<ScopedProtocol<ComponentName2>> {
+        // SAFETY: The protocol is only used for reading data.
+        unsafe {
+            boot::open_protocol::<ComponentName2>(
+                OpenProtocolParams {
+                    handle: *self,
+                    agent: boot::image_handle(),
+                    controller: None,
+                },
+                OpenProtocolAttributes::GetProtocol,
+            )
+        }
+    }
+
+    /// Opens the underlying [`DevicePath`] protocol, if it exists.
+    ///
+    /// # Example
+    /// ```rust,no_run
+    /// # use uefi::Handle;
+    /// # let handle = unsafe { Handle::from_ptr(123 as *mut _).unwrap() };
+    /// let device_path = handle
+    ///   .device_path()
+    ///   .expect("should have device path");
+    /// log::info!("device path: {device_path}");
+    /// ```
+    ///
+    /// # Errors
+    ///
+    /// * [`Status::INVALID_PARAMETER`]: an invalid combination of `params` and
+    ///   `attributes` was provided.
+    /// * [`Status::UNSUPPORTED`]: the handle does not support the protocol.
+    /// * [`Status::ACCESS_DENIED`] or [`Status::ALREADY_STARTED`]: the protocol is
+    ///   already open in a way that is incompatible with the new request.
+    pub fn device_path(&self) -> Result<ScopedProtocol<DevicePath>> {
+        // SAFETY: The protocol is only used for reading data.
+        unsafe {
+            boot::open_protocol::<DevicePath>(
+                OpenProtocolParams {
+                    handle: *self,
+                    agent: boot::image_handle(),
+                    controller: None,
+                },
+                OpenProtocolAttributes::GetProtocol,
+            )
+        }
+    }
 }
 
 /// Handle to an event structure, guaranteed to be non-null.