device_path: add to_string() and to_node_string_pairs()

phip1611 · phip1611 · commit 59494c5273f8 · 2023-06-11T10:18:32.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@
 - `DevicePath::to_boxed`, `DevicePath::to_owned`, and `DevicePath::as_bytes`
 - `DevicePathInstance::to_boxed`, `DevicePathInstance::to_owned`, and `DevicePathInstance::as_bytes`
 - `DevicePathNode::data`
+- `DevicePath::to_string`, `DevicePath::to_node_string_pairs`, and `DevicePathNode::to_string`,
 
 ### Changed
 - Renamed `LoadImageSource::FromFilePath` to `LoadImageSource::FromDevicePath`
diff --git a/uefi-test-runner/src/proto/device_path.rs b/uefi-test-runner/src/proto/device_path.rs
@@ -7,57 +7,80 @@ use uefi::table::boot::BootServices;
 pub fn test(image: Handle, bt: &BootServices) {
     info!("Running device path protocol test");
 
-    let loaded_image = bt
-        .open_protocol_exclusive::<LoadedImage>(image)
-        .expect("Failed to open LoadedImage protocol");
-
-    let device_path = bt
-        .open_protocol_exclusive::<DevicePath>(loaded_image.device())
-        .expect("Failed to open DevicePath protocol");
-
-    let device_path_to_text = bt
-        .open_protocol_exclusive::<DevicePathToText>(
-            bt.get_handle_for_protocol::<DevicePathToText>()
-                .expect("Failed to get DevicePathToText handle"),
-        )
-        .expect("Failed to open DevicePathToText protocol");
-
-    let device_path_from_text = bt
-        .open_protocol_exclusive::<DevicePathFromText>(
-            bt.get_handle_for_protocol::<DevicePathFromText>()
-                .expect("Failed to get DevicePathFromText handle"),
-        )
-        .expect("Failed to open DevicePathFromText protocol");
-
-    for path in device_path.node_iter() {
-        info!(
-            "path: type={:?}, subtype={:?}, length={}",
-            path.device_type(),
-            path.sub_type(),
-            path.length(),
-        );
-
-        let text = device_path_to_text
-            .convert_device_node_to_text(bt, path, DisplayOnly(true), AllowShortcuts(false))
-            .expect("Failed to convert device path to text");
-        let text = &*text;
-        info!("path name: {text}");
-
-        let convert = device_path_from_text
-            .convert_text_to_device_node(text)
-            .expect("Failed to convert text to device path");
-        assert_eq!(path, convert);
+    // test 1/2: test low-level API by directly opening all protocols
+    {
+        let loaded_image = bt
+            .open_protocol_exclusive::<LoadedImage>(image)
+            .expect("Failed to open LoadedImage protocol");
+
+        let device_path = bt
+            .open_protocol_exclusive::<DevicePath>(loaded_image.device())
+            .expect("Failed to open DevicePath protocol");
+
+        let device_path_to_text = bt
+            .open_protocol_exclusive::<DevicePathToText>(
+                bt.get_handle_for_protocol::<DevicePathToText>()
+                    .expect("Failed to get DevicePathToText handle"),
+            )
+            .expect("Failed to open DevicePathToText protocol");
+
+        let device_path_from_text = bt
+            .open_protocol_exclusive::<DevicePathFromText>(
+                bt.get_handle_for_protocol::<DevicePathFromText>()
+                    .expect("Failed to get DevicePathFromText handle"),
+            )
+            .expect("Failed to open DevicePathFromText protocol");
+
+        for path in device_path.node_iter() {
+            info!(
+                "path: type={:?}, subtype={:?}, length={}",
+                path.device_type(),
+                path.sub_type(),
+                path.length(),
+            );
+
+            let text = device_path_to_text
+                .convert_device_node_to_text(bt, path, DisplayOnly(true), AllowShortcuts(false))
+                .expect("Failed to convert device path to text");
+            let text = &*text;
+            info!("path name: {text}");
+
+            let convert = device_path_from_text
+                .convert_text_to_device_node(text)
+                .expect("Failed to convert text to device path");
+            assert_eq!(path, convert);
+        }
+
+        // Get the `LoadedImageDevicePath`. Verify it start with the same nodes as
+        // `device_path`.
+        let loaded_image_device_path = bt
+            .open_protocol_exclusive::<LoadedImageDevicePath>(image)
+            .expect("Failed to open LoadedImageDevicePath protocol");
+
+        for (n1, n2) in device_path
+            .node_iter()
+            .zip(loaded_image_device_path.node_iter())
+        {
+            assert_eq!(n1, n2);
+        }
     }
 
-    // Get the `LoadedImageDevicePath`. Verify it start with the same nodes as
-    // `device_path`.
-    let loaded_image_device_path = bt
-        .open_protocol_exclusive::<LoadedImageDevicePath>(image)
-        .expect("Failed to open LoadedImageDevicePath protocol");
-    for (n1, n2) in device_path
-        .node_iter()
-        .zip(loaded_image_device_path.node_iter())
+    // test 2/2: test high-level to-string api
     {
-        assert_eq!(n1, n2);
+        let loaded_image_device_path = bt
+            .open_protocol_exclusive::<LoadedImageDevicePath>(image)
+            .expect("Failed to open LoadedImageDevicePath protocol");
+        let device_path: &DevicePath = &loaded_image_device_path;
+
+        // Now also test the higher level interface to the DevicePathToText protocol.
+        // This invokes to_string() on each single node.
+        let vec = device_path
+            .to_node_string_pairs(bt, DisplayOnly(false), AllowShortcuts(false))
+            .unwrap();
+        assert_eq!(vec.len(), device_path.node_iter().count());
+
+        device_path
+            .to_string(bt, DisplayOnly(false), AllowShortcuts(false))
+            .unwrap();
     }
 }
diff --git a/uefi/src/proto/device_path/mod.rs b/uefi/src/proto/device_path/mod.rs
@@ -80,15 +80,21 @@ mod device_path_gen;
 pub use device_path_gen::{
     acpi, bios_boot_spec, end, hardware, media, messaging, DevicePathNodeEnum,
 };
-#[cfg(feature = "alloc")]
-use {alloc::borrow::ToOwned, alloc::boxed::Box};
 
-use crate::proto::{unsafe_protocol, ProtocolPointer};
 use core::ffi::c_void;
-use core::fmt::{self, Debug, Formatter};
+use core::fmt::{self, Debug, Display, Formatter};
 use core::mem;
 use core::ops::Deref;
 use ptr_meta::Pointee;
+use uefi::table::boot::ScopedProtocol;
+#[cfg(feature = "alloc")]
+use {alloc::borrow::ToOwned, alloc::boxed::Box, alloc::vec::Vec, uefi::CString16};
+
+use crate::prelude::BootServices;
+use crate::proto::device_path::text::{AllowShortcuts, DevicePathToText, DisplayOnly};
+use crate::proto::{unsafe_protocol, ProtocolPointer};
+use crate::table::boot::{OpenProtocolAttributes, OpenProtocolParams, SearchType};
+use crate::Identify;
 
 opaque_type! {
     /// Opaque type that should be used to represent a pointer to a
@@ -113,7 +119,23 @@ pub struct DevicePathHeader {
 /// A single node within a [`DevicePath`].
 ///
 /// Each node starts with a [`DevicePathHeader`]. The rest of the data
-/// in the node depends on the type of node.
+/// in the node depends on the type of node. You can "cast" a node to a specific
+/// one like this:
+/// ```no_run
+/// use uefi::proto::device_path::DevicePath;
+/// use uefi::proto::device_path::media::FilePath;
+///
+/// let image_device_path: &DevicePath = unsafe { DevicePath::from_ffi_ptr(0x1337 as *const _) };
+/// let file_path = image_device_path
+///         .node_iter()
+///         .find_map(|node| {
+///             let node: &FilePath = node.try_into().ok()?;
+///             let path = node.path_name().to_cstring16().ok()?;
+///             Some(path.to_string().to_uppercase())
+///         });
+/// ```
+/// More types are available in [`uefi::proto::device_path`]. Builder types
+/// can be found in [`uefi::proto::device_path::builder`]
 ///
 /// See the [module-level documentation] for more details.
 ///
@@ -189,6 +211,31 @@ impl DevicePathNode {
     pub fn as_enum(&self) -> Result<DevicePathNodeEnum, NodeConversionError> {
         DevicePathNodeEnum::try_from(self)
     }
+
+    /// Transforms the device path node to its string representation using the
+    /// [`DevicePathToText`] protocol.
+    ///
+    /// The resulting string is only None, if there was not enough memory.
+    #[cfg(feature = "alloc")]
+    pub fn to_string(
+        &self,
+        bs: &BootServices,
+        display_only: DisplayOnly,
+        allow_shortcuts: AllowShortcuts,
+    ) -> Result<Option<CString16>, DevicePathToTextError> {
+        let to_text_protocol = open_text_protocol(bs)?;
+
+        let cstring16 = to_text_protocol
+            .convert_device_node_to_text(bs, self, display_only, allow_shortcuts)
+            .ok()
+            .map(|pool_string| {
+                let cstr16 = &*pool_string;
+                // Another allocation; pool string is dropped. This overhead
+                // is negligible. CString16 is more convenient to use.
+                CString16::from(cstr16)
+            });
+        Ok(cstring16)
+    }
 }
 
 impl Debug for DevicePathNode {
@@ -377,6 +424,51 @@ impl DevicePath {
         let data = data.into_boxed_slice();
         unsafe { mem::transmute(data) }
     }
+
+    /// Variant of [`Self::to_string`] that creates a list of tuples of each
+    /// [`DevicePathNode`] and the corresponding text representation using the
+    /// [`DevicePathToText`] protocol.
+    ///
+    /// The resulting string is only None, if there was not enough memory.
+    #[cfg(feature = "alloc")]
+    pub fn to_node_string_pairs(
+        &self,
+        bs: &BootServices,
+        display_only: DisplayOnly,
+        allow_shortcuts: AllowShortcuts,
+    ) -> Result<Vec<(&DevicePathNode, Option<CString16>)>, DevicePathToTextError> {
+        let mut vec = Vec::new();
+        for node in self.node_iter() {
+            let string = node.to_string(bs, display_only, allow_shortcuts)?;
+            vec.push((node, string))
+        }
+        Ok(vec)
+    }
+
+    /// Transforms the device path to its string representation using the
+    /// [`DevicePathToText`] protocol.
+    ///
+    /// The resulting string is only None, if there was not enough memory.
+    #[cfg(feature = "alloc")]
+    pub fn to_string(
+        &self,
+        bs: &BootServices,
+        display_only: DisplayOnly,
+        allow_shortcuts: AllowShortcuts,
+    ) -> Result<Option<CString16>, DevicePathToTextError> {
+        let to_text_protocol = open_text_protocol(bs)?;
+
+        let cstring16 = to_text_protocol
+            .convert_device_path_to_text(bs, self, display_only, allow_shortcuts)
+            .ok()
+            .map(|pool_string| {
+                let cstr16 = &*pool_string;
+                // Another allocation; pool string is dropped. This overhead
+                // is negligible. CString16 is more convenient to use.
+                CString16::from(cstr16)
+            });
+        Ok(cstring16)
+    }
 }
 
 impl Debug for DevicePath {
@@ -700,6 +792,64 @@ impl Deref for LoadedImageDevicePath {
     }
 }
 
+/// Errors that may happen when a device path is transformed to a string
+/// representation using:
+/// - [`DevicePath::to_node_string_pairs`]
+/// - [`DevicePath::to_string`]
+/// - [`DevicePathNode::to_string`]
+#[derive(Debug)]
+pub enum DevicePathToTextError {
+    /// Can't locate a handle buffer with handles associated with the
+    /// [`DevicePathToText`] protocol.
+    CantLocateHandleBuffer(crate::Error),
+    /// There is no handle supporting the [`DevicePathToText`] protocol.
+    NoHandle,
+    /// The handle supporting the [`DevicePathToText`] protocol exists but it
+    /// could not be opened.
+    CantOpenProtocol(crate::Error),
+}
+
+impl Display for DevicePathToTextError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        write!(f, "{self:?}")
+    }
+}
+
+#[cfg(feature = "unstable")]
+impl core::error::Error for DevicePathToTextError {
+    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
+        match self {
+            DevicePathToTextError::CantLocateHandleBuffer(e) => Some(e),
+            DevicePathToTextError::CantOpenProtocol(e) => Some(e),
+            _ => None,
+        }
+    }
+}
+
+/// Helper function to open the [`DevicePathToText`] protocol using the boot
+/// services.
+fn open_text_protocol(
+    bs: &BootServices,
+) -> Result<ScopedProtocol<DevicePathToText>, DevicePathToTextError> {
+    let &handle = bs
+        .locate_handle_buffer(SearchType::ByProtocol(&DevicePathToText::GUID))
+        .map_err(DevicePathToTextError::CantLocateHandleBuffer)?
+        .first()
+        .ok_or(DevicePathToTextError::NoHandle)?;
+
+    unsafe {
+        bs.open_protocol::<DevicePathToText>(
+            OpenProtocolParams {
+                handle,
+                agent: bs.image_handle(),
+                controller: None,
+            },
+            OpenProtocolAttributes::GetProtocol,
+        )
+    }
+    .map_err(DevicePathToTextError::CantOpenProtocol)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
