From 1f52a318c4c1a64692b22deca671ebd852b53f46 Mon Sep 17 00:00:00 2001 From: Nicholas Bishop Date: Sat, 25 Jan 2025 15:46:32 -0500 Subject: [PATCH] relicensing: Rewrite PR "DevicePathToText and DevicePathFromText Protocol" This covers these commits: fa91d553677d3f46a0e3f12a745b454b5e01e674 1c95dd559a163842279aff28caa48d61f0a40ca7 704e98b5e89f63fdba657ff8c9dedbcd6c9110b1 --- uefi/src/proto/device_path/text.rs | 79 ++++++++++++++---------------- 1 file changed, 38 insertions(+), 41 deletions(-) diff --git a/uefi/src/proto/device_path/text.rs b/uefi/src/proto/device_path/text.rs index 4e6bbad8a..9e920be93 100644 --- a/uefi/src/proto/device_path/text.rs +++ b/uefi/src/proto/device_path/text.rs @@ -1,4 +1,4 @@ -//! `DevicePathToText` and `DevicePathFromText` Protocol +//! Protocols for converting between UEFI strings and [`DevicePath`]/[`DevicePathNode`]. // Note on return types: the specification of the conversion functions // is a little unusual in that they return a pointer rather than @@ -16,32 +16,39 @@ use core::ops::Deref; use core::ptr::NonNull; use uefi_raw::protocol::device_path::{DevicePathFromTextProtocol, DevicePathToTextProtocol}; -/// This struct is a wrapper of `display_only` parameter -/// used by Device Path to Text protocol. +/// Parameter for [`DevicePathToText`] that alters the output format. /// -/// The `display_only` parameter controls whether the longer -/// (parseable) or shorter (display-only) form of the conversion -/// is used. If `display_only` is TRUE, then the shorter text -/// representation of the display node is used, where applicable. -/// If `display_only` is FALSE, then the longer text representation -/// of the display node is used. +/// * `DisplayOnly(false)` produces parseable output. +/// * `DisplayOnly(true)` produces output that _may_ be shorter and not +/// parseable. +/// +/// Example of how a node's text representation may be altered by this +/// parameter: +/// * `DisplayOnly(false)`: `Ata(Primary,Master,0x1)` +/// * `DisplayOnly(true)`: `Ata(0x1)` #[derive(Clone, Copy, Debug)] pub struct DisplayOnly(pub bool); -/// This struct is a wrapper of `allow_shortcuts` parameter -/// used by Device Path to Text protocol. +/// Parameter for [`DevicePathToText`] that alters the output format. +/// +/// * `AllowShortcuts(false)`: node names are based only on the node's type and +/// subtype. +/// * `AllowShortcuts(true)` _may_ alter the node name based on other fields +/// within the node. /// -/// The `allow_shortcuts` is FALSE, then the shortcut forms of -/// text representation for a device node cannot be used. A -/// shortcut form is one which uses information other than the -/// type or subtype. If `allow_shortcuts is TRUE, then the -/// shortcut forms of text representation for a device node -/// can be used, where applicable. +/// Example of how a node's text representation may be altered by this +/// parameter: +/// * `AllowShortcuts(false)`: `VenMsg(E0C14753-F9BE-11D2-9A0C-0090273FC14D)` +/// * `AllowShortcuts(true)`: `VenPcAnsi()` #[derive(Clone, Copy, Debug)] pub struct AllowShortcuts(pub bool); -/// Wrapper for a string internally allocated from -/// UEFI boot services memory. +/// UCS-2 string allocated from UEFI pool memory. +/// +/// This is similar to a [`CString16`], but used for memory that was allocated +/// internally by UEFI rather than the Rust allocator. +/// +/// [`CString16`]: crate::CString16 #[derive(Debug)] pub struct PoolString(PoolAllocation); @@ -85,17 +92,14 @@ impl Deref for PoolDevicePathNode { } } -/// Device Path to Text protocol. -/// -/// This protocol provides common utility functions for converting device -/// nodes and device paths to a text representation. +/// Protocol for converting a [`DevicePath`] or `DevicePathNode`] to a string. #[derive(Debug)] #[repr(transparent)] #[unsafe_protocol(DevicePathToTextProtocol::GUID)] pub struct DevicePathToText(DevicePathToTextProtocol); impl DevicePathToText { - /// Convert a device node to its text representation. + /// Convert a [`DevicePathNode`] to a [`PoolString`]. /// /// Returns an [`OUT_OF_RESOURCES`] error if there is insufficient /// memory for the conversion. @@ -107,17 +111,17 @@ impl DevicePathToText { display_only: DisplayOnly, allow_shortcuts: AllowShortcuts, ) -> Result { - let text_device_node = unsafe { + let text = unsafe { (self.0.convert_device_node_to_text)( device_node.as_ffi_ptr().cast(), display_only.0, allow_shortcuts.0, ) }; - PoolString::new(text_device_node.cast()) + PoolString::new(text.cast()) } - /// Convert a device path to its text representation. + /// Convert a [`DevicePath`] to a [`PoolString`]. /// /// Returns an [`OUT_OF_RESOURCES`] error if there is insufficient /// memory for the conversion. @@ -129,32 +133,27 @@ impl DevicePathToText { display_only: DisplayOnly, allow_shortcuts: AllowShortcuts, ) -> Result { - let text_device_path = unsafe { + let text = unsafe { (self.0.convert_device_path_to_text)( device_path.as_ffi_ptr().cast(), display_only.0, allow_shortcuts.0, ) }; - PoolString::new(text_device_path.cast()) + PoolString::new(text.cast()) } } -/// Device Path from Text protocol. -/// -/// This protocol provides common utilities for converting text to -/// device paths and device nodes. +/// Protocol for converting a string to a [`DevicePath`] or `DevicePathNode`]. #[derive(Debug)] #[repr(transparent)] #[unsafe_protocol("05c99a21-c70f-4ad2-8a5f-35df3343f51e")] pub struct DevicePathFromText(DevicePathFromTextProtocol); impl DevicePathFromText { - /// Convert text to the binary representation of a device node. + /// Convert a [`CStr16`] to a [`DevicePathNode`]. /// - /// `text_device_node` is the text representation of a device node. - /// Conversion starts with the first character and continues until - /// the first non-device node character. + /// If a non-device-node character is encountered, the rest of the string is ignored. /// /// Returns an [`OUT_OF_RESOURCES`] error if there is insufficient /// memory for the conversion. @@ -172,11 +171,9 @@ impl DevicePathFromText { } } - /// Convert a text to its binary device path representation. + /// Convert a [`CStr16`] to a [`DevicePath`]. /// - /// `text_device_path` is the text representation of a device path. - /// Conversion starts with the first character and continues until - /// the first non-device path character. + /// If a non-device-node character is encountered, the rest of the string is ignored. /// /// Returns an [`OUT_OF_RESOURCES`] error if there is insufficient /// memory for the conversion.