uefi: Add initial incomplete safe wrapper for DevicePathUtilities protocol

Author: seijikun

Diff for: uefi-test-runner/src/proto/device_path.rs

@@ -23,6 +23,8 @@ pub fn test() {
     test_convert_text_to_device_path();
     test_convert_text_to_device_node();
 
+    test_device_path_append();
+
     // Get the current executable's device path via the `LoadedImage` protocol.
     let loaded_image = boot::open_protocol_exclusive::<LoadedImage>(boot::image_handle()).unwrap();
     let device_path =
@@ -219,3 +221,28 @@ fn test_convert_text_to_device_node() {
         expected_node,
     );
 }
+
+/// Test `DevicePath::DevicePath::append_path()` and `DevicePath::DevicePath::append_node()`
+fn test_device_path_append() {
+    let path = create_test_device_path();
+    let path2 = create_test_device_path();
+    let node = path.node_iter().next().unwrap();
+
+    assert_eq!(
+        path.to_string(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)).unwrap(),
+        cstr16!("Ata(Primary,Master,0x1)")
+    );
+
+    assert_eq!(
+        path.append_path(&path2).unwrap().to_string(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)")
+    );
+    assert_eq!(
+        path.append_node(&node).unwrap().to_string(DisplayOnly(false), AllowShortcuts(false)).unwrap(),
+        cstr16!("Ata(Primary,Master,0x1)/VenMsg(E0C14753-F9BE-11D2-9A0C-0090273FC14D)/Ata(Primary,Master,0x1)")
+    );
+}

Diff for: uefi/CHANGELOG.md

@@ -6,6 +6,8 @@
 - Added conversions between `proto::network::MacAddress` and the `[u8; 6]` type that's more commonly used to represent MAC addresses.
 - Added `proto::media::disk_info::DiskInfo`.
 - Added `mem::AlignedBuffer`.
+- Added `proto::device_path::DevicePath::append_path()`.
+- Added `proto::device_path::DevicePath::append_node()`.
 
 ## Changed
 - **Breaking:** Removed `BootPolicyError` as `BootPolicy` construction is no
@@ -16,6 +18,8 @@
   `&self`.
 - **Breaking:** The `pxe::Mode` struct is now opaque. Use method calls to access
   mode data instead of direct field access.
+- **Breaking:** `PoolDevicePathNode` and `PoolDevicePath` moved from module
+  `proto::device_path::text` to `proto::device_path`.
 - `boot::memory_map()` will never return `Status::BUFFER_TOO_SMALL` from now on,
   as this is considered a hard internal error where users can't do anything
   about it anyway. It will panic instead.

Diff for: uefi/src/proto/device_path/mod.rs

@@ -77,13 +77,15 @@
 
 pub mod build;
 pub mod text;
+pub mod util;
 
 mod device_path_gen;
 pub use device_path_gen::{
     acpi, bios_boot_spec, end, hardware, media, messaging, DevicePathNodeEnum,
 };
 pub use uefi_raw::protocol::device_path::{DeviceSubType, DeviceType};
 
+use crate::mem::PoolAllocation;
 use crate::proto::{unsafe_protocol, ProtocolPointer};
 use core::ffi::c_void;
 use core::fmt::{self, Debug, Display, Formatter};
@@ -94,6 +96,7 @@ use ptr_meta::Pointee;
 use {
     crate::boot::{self, OpenProtocolAttributes, OpenProtocolParams, ScopedProtocol, SearchType},
     crate::proto::device_path::text::{AllowShortcuts, DevicePathToText, DisplayOnly},
+    crate::proto::device_path::util::DevicePathUtilities,
     crate::{CString16, Identify},
     alloc::borrow::ToOwned,
     alloc::boxed::Box,
@@ -108,6 +111,30 @@ opaque_type! {
     pub struct FfiDevicePath;
 }
 
+/// Device path allocated from UEFI pool memory.
+#[derive(Debug)]
+pub struct PoolDevicePath(pub(crate) PoolAllocation);
+
+impl Deref for PoolDevicePath {
+    type Target = DevicePath;
+
+    fn deref(&self) -> &Self::Target {
+        unsafe { DevicePath::from_ffi_ptr(self.0.as_ptr().as_ptr().cast()) }
+    }
+}
+
+/// Device path node allocated from UEFI pool memory.
+#[derive(Debug)]
+pub struct PoolDevicePathNode(pub(crate) PoolAllocation);
+
+impl Deref for PoolDevicePathNode {
+    type Target = DevicePathNode;
+
+    fn deref(&self) -> &Self::Target {
+        unsafe { DevicePathNode::from_ffi_ptr(self.0.as_ptr().as_ptr().cast()) }
+    }
+}
+
 /// Header that appears at the start of every [`DevicePathNode`].
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 #[repr(C, packed)]
@@ -499,6 +526,25 @@ impl DevicePath {
             })
             .map_err(|_| DevicePathToTextError::OutOfMemory)
     }
+
+    /// Allocates and returns a new [`DevicePath`] by copying this one and appending the given `right` path.
+    #[cfg(feature = "alloc")]
+    pub fn append_path(&self, right: &Self) -> Result<PoolDevicePath, DevicePathUtilitiesError> {
+        open_utility_protocol()?
+            .append_path(self, right)
+            .map_err(|_| DevicePathUtilitiesError::OutOfMemory)
+    }
+
+    /// Allocates and returns a new [`DevicePath`] by copying this one and appending the given `right` node.
+    #[cfg(feature = "alloc")]
+    pub fn append_node(
+        &self,
+        right: &DevicePathNode,
+    ) -> Result<PoolDevicePath, DevicePathUtilitiesError> {
+        open_utility_protocol()?
+            .append_node(self, right)
+            .map_err(|_| DevicePathUtilitiesError::OutOfMemory)
+    }
 }
 
 impl Debug for DevicePath {
@@ -745,6 +791,63 @@ fn open_text_protocol() -> Result<ScopedProtocol<DevicePathToText>, DevicePathTo
     .map_err(DevicePathToTextError::CantOpenProtocol)
 }
 
+/// Errors that may occur when working with the [`DevicePathUtilities`] protocol.
+///
+/// These errors are typically encountered during operations involving device
+/// paths, such as appending or manipulating path segments.
+#[derive(Debug)]
+pub enum DevicePathUtilitiesError {
+    /// Can't locate a handle buffer with handles associated with the
+    /// [`DevicePathUtilities`] protocol.
+    CantLocateHandleBuffer(crate::Error),
+    /// No handle supporting the [`DevicePathUtilities`] protocol was found.
+    NoHandle,
+    /// The handle supporting the [`DevicePathUtilities`] protocol exists but
+    /// it could not be opened.
+    CantOpenProtocol(crate::Error),
+    /// Memory allocation failed during device path operations.
+    OutOfMemory,
+}
+
+impl Display for DevicePathUtilitiesError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        write!(f, "{self:?}")
+    }
+}
+
+impl core::error::Error for DevicePathUtilitiesError {
+    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
+        match self {
+            Self::CantLocateHandleBuffer(e) => Some(e),
+            Self::CantOpenProtocol(e) => Some(e),
+            _ => None,
+        }
+    }
+}
+
+/// Helper function to open the [`DevicePathUtilities`] protocol using the boot
+/// services.
+#[cfg(feature = "alloc")]
+fn open_utility_protocol() -> Result<ScopedProtocol<DevicePathUtilities>, DevicePathUtilitiesError>
+{
+    let &handle = boot::locate_handle_buffer(SearchType::ByProtocol(&DevicePathToText::GUID))
+        .map_err(DevicePathUtilitiesError::CantLocateHandleBuffer)?
+        .first()
+        .ok_or(DevicePathUtilitiesError::NoHandle)?;
+
+    unsafe {
+        boot::open_protocol::<DevicePathUtilities>(
+            OpenProtocolParams {
+                handle,
+                agent: boot::image_handle(),
+                controller: None,
+            },
+            OpenProtocolAttributes::GetProtocol,
+        )
+    }
+    .map_err(DevicePathUtilitiesError::CantOpenProtocol)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

Diff for: uefi/src/proto/device_path/text.rs

@@ -18,6 +18,8 @@ use core::ops::Deref;
 use core::ptr::NonNull;
 use uefi_raw::protocol::device_path::{DevicePathFromTextProtocol, DevicePathToTextProtocol};
 
+use super::{PoolDevicePath, PoolDevicePathNode};
+
 /// Parameter for [`DevicePathToText`] that alters the output format.
 ///
 /// * `DisplayOnly(false)` produces parseable output.
@@ -70,30 +72,6 @@ impl Deref for PoolString {
     }
 }
 
-/// Device path allocated from UEFI pool memory.
-#[derive(Debug)]
-pub struct PoolDevicePath(PoolAllocation);
-
-impl Deref for PoolDevicePath {
-    type Target = DevicePath;
-
-    fn deref(&self) -> &Self::Target {
-        unsafe { DevicePath::from_ffi_ptr(self.0.as_ptr().as_ptr().cast()) }
-    }
-}
-
-/// Device path node allocated from UEFI pool memory.
-#[derive(Debug)]
-pub struct PoolDevicePathNode(PoolAllocation);
-
-impl Deref for PoolDevicePathNode {
-    type Target = DevicePathNode;
-
-    fn deref(&self) -> &Self::Target {
-        unsafe { DevicePathNode::from_ffi_ptr(self.0.as_ptr().as_ptr().cast()) }
-    }
-}
-
 /// Protocol for converting a [`DevicePath`] or `DevicePathNode`] to a string.
 #[derive(Debug)]
 #[repr(transparent)]

Diff for: uefi/src/proto/device_path/util.rs

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+//! Protocol with utility functions for working with device paths.
+
+use super::{DevicePath, DevicePathNode, PoolDevicePath};
+use crate::mem::PoolAllocation;
+use core::ptr::NonNull;
+use uefi_macros::unsafe_protocol;
+use uefi_raw::protocol::device_path::DevicePathUtilitiesProtocol;
+use uefi_raw::Status;
+
+/// Protocol with utility functions for working with device paths.
+#[derive(Debug)]
+#[repr(transparent)]
+#[unsafe_protocol(DevicePathUtilitiesProtocol::GUID)]
+pub struct DevicePathUtilities(DevicePathUtilitiesProtocol);
+
+impl DevicePathUtilities {
+    /// Retrieves the size of the specified device path in bytes, including the
+    /// end-of-device-path node.
+    ///
+    /// # Parameters
+    /// - `device_path`: A reference to the [`DevicePath`] whose size is to be determined.
+    ///
+    /// # Returns
+    /// The size of the specified device path in bytes.
+    #[must_use]
+    pub fn get_size(&self, device_path: &DevicePath) -> usize {
+        unsafe { (self.0.get_device_path_size)(device_path.as_ffi_ptr().cast()) }
+    }
+
+    /// Creates a new device path by appending the second device path to the first.
+    ///
+    /// # Parameters
+    /// - `path0`: A reference to the base device path.
+    /// - `path1`: A reference to the device path to append.
+    ///
+    /// # Returns
+    /// A [`PoolDevicePath`] instance containing the newly created device path,
+    /// or an error if memory could not be allocated.
+    pub fn append_path(
+        &self,
+        path0: &DevicePath,
+        path1: &DevicePath,
+    ) -> crate::Result<PoolDevicePath> {
+        unsafe {
+            let ptr =
+                (self.0.append_device_path)(path0.as_ffi_ptr().cast(), path1.as_ffi_ptr().cast());
+            NonNull::new(ptr.cast_mut())
+                .map(|p| PoolDevicePath(PoolAllocation::new(p.cast())))
+                .ok_or(Status::OUT_OF_RESOURCES.into())
+        }
+    }
+
+    /// Creates a new device path by appending a device node to the base device path.
+    ///
+    /// # Parameters
+    /// - `basepath`: A reference to the base device path.
+    /// - `node`: A reference to the device node to append.
+    ///
+    /// # Returns
+    /// A [`PoolDevicePath`] instance containing the newly created device path,
+    /// or an error if memory could not be allocated.
+    pub fn append_node(
+        &self,
+        basepath: &DevicePath,
+        node: &DevicePathNode,
+    ) -> crate::Result<PoolDevicePath> {
+        unsafe {
+            let ptr =
+                (self.0.append_device_node)(basepath.as_ffi_ptr().cast(), node.as_ffi_ptr().cast());
+            NonNull::new(ptr.cast_mut())
+                .map(|p| PoolDevicePath(PoolAllocation::new(p.cast())))
+                .ok_or(Status::OUT_OF_RESOURCES.into())
+        }
+    }
+
+    /// Creates a new device path by appending the specified device path instance to the base path.
+    ///
+    /// # Parameters
+    /// - `basepath`: A reference to the base device path.
+    /// - `instance`: A reference to the device path instance to append.
+    ///
+    /// # Returns
+    /// A [`PoolDevicePath`] instance containing the newly created device path,
+    /// or an error if memory could not be allocated.
+    pub fn append_instance(
+        &self,
+        basepath: &DevicePath,
+        instance: &DevicePath,
+    ) -> crate::Result<PoolDevicePath> {
+        unsafe {
+            let ptr = (self.0.append_device_path_instance)(
+                basepath.as_ffi_ptr().cast(),
+                instance.as_ffi_ptr().cast(),
+            );
+            NonNull::new(ptr.cast_mut())
+                .map(|p| PoolDevicePath(PoolAllocation::new(p.cast())))
+                .ok_or(Status::OUT_OF_RESOURCES.into())
+        }
+    }
+}