Skip to content

Commit fb4e62f

Browse files
phip1611phip1611
committed
doc: streamline device path documentation between uefi-raw and uefi
1 parent e3d5afb commit fb4e62f

File tree

4 files changed

+87
-37
lines changed

4 files changed

+87
-37
lines changed

‎uefi-raw/CHANGELOG.md

+1
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
## Changed
2020
- `DevicePathProtocol` now derives
2121
`Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash`
22+
- The documentation for UEFI device paths has been streamlined and improved.
2223

2324

2425
# uefi-raw - 0.10.0 (2025-02-07)

‎uefi-raw/src/protocol/device_path.rs

+45-4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,45 @@
11
// SPDX-License-Identifier: MIT OR Apache-2.0
22

3+
//! The UEFI device path protocol, i.e., UEFI device paths.
4+
//!
5+
//! This module provides (generated) ABI-compatible bindings to all known device
6+
//! path node types.
7+
//!
8+
//! # Terminology: Device Paths, Device Path Instances, and Device Path Nodes
9+
//! An open UEFI device path [protocol], also called _device path_, is a
10+
//! flexible and structured sequence of binary nodes that describe a route from
11+
//! the UEFI root to a particular device, controller, or file.
12+
//!
13+
//! An entire device path can be made up of multiple device path instances,
14+
//! and each instance is made up of multiple device path nodes. A device path
15+
//! _may_ contain multiple device-path instances separated by [`END_INSTANCE`]
16+
//! nodes, but typical paths contain only a single instance (in which case no
17+
//! [`END_INSTANCE`] node is needed). The entire device path is terminated with
18+
//! an [`END_ENTIRE`] node.
19+
//!
20+
//! Each node represents a step in the path: PCI device, partition, filesystem,
21+
//! file path, etc. Each node represents a step in the path: PCI device,
22+
//! partition, filesystem, file path, etc.
23+
//!
24+
//! Example of what a device path containing two instances (each comprised of
25+
//! three nodes) might look like:
26+
//!
27+
//! ```text
28+
//! ┌──────┬──────┬──────────────╥───────┬──────────┬────────────┐
29+
//! │ ACPI │ PCI │ END_INSTANCE ║ CDROM │ FILEPATH │ END_ENTIRE │
30+
//! └──────┴──────┴──────────────╨───────┴──────────┴────────────┘
31+
//! ↑ ↑ ↑ ↑ ↑ ↑ ↑
32+
//! ├─Node─╨─Node─╨─────Node─────╨─Node──╨───Node───╨────Node────┤
33+
//! ↑ ↑ ↑
34+
//! ├─── DevicePathInstance ─────╨────── DevicePathInstance ─────┤
35+
//! │ │
36+
//! └──────────────────── Entire DevicePath ─────────────────────┘
37+
//! ```
38+
//!
39+
//! [`END_ENTIRE`]: DeviceSubType::END_ENTIRE
40+
//! [`END_INSTANCE`]: DeviceSubType::END_INSTANCE
41+
//! [protocol]: crate::protocol
42+
343
mod device_path_gen;
444

545
use crate::{guid, Boolean, Char16, Guid};
@@ -8,11 +48,12 @@ pub use device_path_gen::{acpi, bios_boot_spec, end, hardware, media, messaging}
848

949
/// Device path protocol.
1050
///
11-
/// A device path contains one or more device path instances made up of
12-
/// variable-length nodes.
51+
/// Note that the fields in this struct define the fixed header at the start of
52+
/// each node; a device path is typically larger than these four bytes.
53+
///
54+
/// See the [module-level documentation] for more details.
1355
///
14-
/// Note that the fields in this struct define the header at the start of each
15-
/// node; a device path is typically larger than these four bytes.
56+
/// [module-level documentation]: self
1657
#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
1758
#[repr(C)]
1859
pub struct DevicePathProtocol {

‎uefi/CHANGELOG.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,9 @@
4141
- The `Display` impl for `CStr8` now excludes the trailing null character.
4242
- `VariableKeys` initializes with a larger name buffer to work around firmware
4343
bugs on some devices.
44-
- The UEFI `allocator::Allocator` has been optimized for page-aligned
44+
- The UEFI `allocator::Allocator` has been optimized for page-aligned
4545
allocations.
46+
- The documentation for UEFI device paths has been streamlined and improved.
4647

4748

4849
# uefi - 0.34.1 (2025-02-07)

‎uefi/src/proto/device_path/mod.rs

+39-32
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,7 @@
11
// SPDX-License-Identifier: MIT OR Apache-2.0
22

3-
//! Device Path protocol
4-
//!
5-
//! A UEFI device path is a very flexible structure for encoding a
6-
//! programmatic path such as a hard drive or console.
7-
//!
8-
//! A device path is made up of a packed list of variable-length nodes of
9-
//! various types. The entire device path is terminated with an
10-
//! [`END_ENTIRE`] node. A device path _may_ contain multiple device-path
11-
//! instances separated by [`END_INSTANCE`] nodes, but typical paths contain
12-
//! only a single instance (in which case no `END_INSTANCE` node is needed).
13-
//!
14-
//! Example of what a device path containing two instances (each comprised of
15-
//! three nodes) might look like:
16-
//!
17-
//! ```text
18-
//! ┌──────┬─────┬──────────────╥───────┬──────────┬────────────┐
19-
//! │ ACPI │ PCI │ END_INSTANCE ║ CDROM │ FILEPATH │ END_ENTIRE │
20-
//! └──────┴─────┴──────────────╨───────┴──────────┴────────────┘
21-
//! ↑ ↑ ↑
22-
//! ├─── DevicePathInstance ────╨────── DevicePathInstance ─────┤
23-
//! │ │
24-
//! └─────────────────── Entire DevicePath ─────────────────────┘
25-
//! ```
3+
//! High-level wrappers for the UEFI device path [`Protocol`], i.e.,
4+
//! [UEFI device paths].
265
//!
276
//! # Types
287
//!
@@ -74,6 +53,7 @@
7453
//! [`Protocol`]: crate::proto::Protocol
7554
//! [`device_type`]: DevicePathNode::device_type
7655
//! [`sub_type`]: DevicePathNode::sub_type
56+
//! [UEFI device paths]: uefi_raw::protocol::device_path
7757
7858
pub mod build;
7959
pub mod text;
@@ -92,7 +72,6 @@ use core::ffi::c_void;
9272
use core::fmt::{self, Debug, Display, Formatter};
9373
use core::ops::Deref;
9474
use ptr_meta::Pointee;
95-
9675
use uefi_raw::protocol::device_path::DevicePathProtocol;
9776
#[cfg(feature = "alloc")]
9877
use {
@@ -400,21 +379,49 @@ impl ToOwned for DevicePathInstance {
400379
}
401380
}
402381

403-
/// Device path protocol.
382+
/// High-level representation of the UEFI [device path protocol].
404383
///
405-
/// Can be used on any device handle to obtain generic path/location information
406-
/// concerning the physical device or logical device. If the handle does not
407-
/// logically map to a physical device, the handle may not necessarily support
408-
/// the device path protocol. The device path describes the location of the
409-
/// device the handle is for. The size of the Device Path can be determined from
410-
/// the structures that make up the Device Path.
384+
/// This type represents an entire device path, possibly consisting of multiple
385+
/// [`DevicePathInstance`]s and [`DevicePathNode`]s.
411386
///
412387
/// See the [module-level documentation] for more details.
413388
///
389+
/// # Usage
390+
/// This type implements [`Protocol`] and therefore can be used on any
391+
/// device handle to obtain generic path/location information concerning the
392+
/// physical device or logical device. If the handle does not logically map to a
393+
/// physical device, the handle may not necessarily support the device path
394+
/// protocol. The device path describes the location of the device the handle is
395+
/// for. The size of the Device Path can be determined from the structures that
396+
/// make up the Device Path.
397+
///
398+
/// # Example
399+
/// ```rust,no_run
400+
/// use uefi::Handle;
401+
/// use uefi::boot::{open_protocol_exclusive, ScopedProtocol};
402+
/// use uefi::proto::device_path::DevicePath;
403+
/// use uefi::proto::device_path::text::{AllowShortcuts, DisplayOnly};
404+
/// use uefi::proto::loaded_image::LoadedImage;
405+
///
406+
/// fn open_device_path(image_handle: Handle) {
407+
/// let loaded_image = open_protocol_exclusive::<LoadedImage>(image_handle).unwrap();
408+
/// let device_handle = loaded_image.device().unwrap();
409+
/// let device_path: ScopedProtocol<DevicePath>
410+
/// = open_protocol_exclusive::<DevicePath>(device_handle).unwrap();
411+
/// log::debug!(
412+
/// "Device path: {}",
413+
/// device_path.to_string(DisplayOnly(true), AllowShortcuts(true)).unwrap()
414+
/// );
415+
/// }
416+
/// ```
417+
///
414418
/// [module-level documentation]: crate::proto::device_path
415419
/// [`END_ENTIRE`]: DeviceSubType::END_ENTIRE
420+
/// [`DevicePathProtocol`]: uefi_raw::protocol::device_path::DevicePathProtocol
421+
/// [`Protocol`]: uefi::proto::Protocol
422+
/// [device path protocol]: uefi_raw::protocol::device_path
416423
#[repr(C, packed)]
417-
#[unsafe_protocol(uefi_raw::protocol::device_path::DevicePathProtocol::GUID)]
424+
#[unsafe_protocol(DevicePathProtocol::GUID)]
418425
#[derive(Eq, Pointee)]
419426
pub struct DevicePath {
420427
data: [u8],

0 commit comments

Comments
 (0)