Skip to content

Commit 9b9e621

Browse files
nicholasbishopnicholasbishop
authored
Merge pull request #1641 from rust-osdev/doc-devicepath-v2
doc: streamline device path documentation between uefi-raw and uefi
2 parents 6d8185f + 5bcf61d commit 9b9e621

File tree

4 files changed

+110
-28
lines changed

4 files changed

+110
-28
lines changed

‎uefi-raw/CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
## Changed
2727
- `DevicePathProtocol` now derives
2828
`Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash`
29+
- The documentation for UEFI device paths has been streamlined and improved.
2930

3031
## Changed
3132

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

Lines changed: 45 additions & 4 deletions
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::{Boolean, Char16, Guid, 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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@
5656
bugs on some devices.
5757
- The UEFI `allocator::Allocator` has been optimized for page-aligned
5858
allocations.
59+
- The documentation for UEFI device paths has been streamlined and improved.
5960

6061

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

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

Lines changed: 63 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,38 @@
11
// SPDX-License-Identifier: MIT OR Apache-2.0
22

3-
//! Device Path protocol
3+
//! The UEFI device path [`Protocol`], i.e., UEFI device paths.
44
//!
5-
//! A UEFI device path is a very flexible structure for encoding a
6-
//! programmatic path such as a hard drive or console.
5+
//! This module provides high-level wrappers to work with UEFI device paths.
6+
//! Please find additional low-level information in the
7+
//! [device path section of `uefi-raw`].
78
//!
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).
9+
//! # Terminology: Device Paths, Device Path Instances, and Device Path Nodes
10+
//! An open UEFI device path [`Protocol`], also called _device path_, is a
11+
//! flexible and structured sequence of binary nodes that describe a route from
12+
//! the UEFI root to a particular device, controller, or file.
13+
//!
14+
//! An entire device path can be made up of multiple device path instances,
15+
//! and each instance is made up of multiple device path nodes. A device path
16+
//! _may_ contain multiple device-path instances, but typical paths contain only
17+
//! a single instance.
18+
//!
19+
//! Each node represents a step in the path: PCI device, partition, filesystem,
20+
//! file path, etc. Each node represents a step in the path: PCI device,
21+
//! partition, filesystem, file path, etc.
1322
//!
1423
//! Example of what a device path containing two instances (each comprised of
1524
//! three nodes) might look like:
1625
//!
1726
//! ```text
18-
//! ┌──────┬─────┬──────────────╥───────┬──────────┬────────────┐
19-
//! │ ACPI │ PCI │ END_INSTANCE ║ CDROM │ FILEPATH │ END_ENTIRE │
20-
//! └──────┴─────┴──────────────╨───────┴──────────┴────────────┘
21-
//! ↑ ↑ ↑
22-
//! ├─── DevicePathInstance ────╨────── DevicePathInstance ─────┤
23-
//! │ │
24-
//! └─────────────────── Entire DevicePath ─────────────────────┘
27+
//! ┌──────┬──────┬──────────────╥───────┬──────────┬────────────┐
28+
//! │ ACPI │ PCI │ END_INSTANCE ║ CDROM │ FILEPATH │ END_ENTIRE │
29+
//! └──────┴──────┴──────────────╨───────┴──────────┴────────────┘
30+
//! ↑ ↑ ↑ ↑ ↑ ↑ ↑
31+
//! ├─Node─╨─Node─╨─────Node─────╨─Node──╨───Node───╨────Node────┤
32+
//! ↑ ↑ ↑
33+
//! ├─── DevicePathInstance ─────╨────── DevicePathInstance ─────┤
34+
//! │ │
35+
//! └──────────────────── Entire DevicePath ─────────────────────┘
2536
//! ```
2637
//!
2738
//! # Types
@@ -74,6 +85,7 @@
7485
//! [`Protocol`]: crate::proto::Protocol
7586
//! [`device_type`]: DevicePathNode::device_type
7687
//! [`sub_type`]: DevicePathNode::sub_type
88+
//! [device path section of `uefi-raw`]: uefi_raw::protocol::device_path
7789
7890
pub mod build;
7991
pub mod text;
@@ -92,7 +104,6 @@ use core::ffi::c_void;
92104
use core::fmt::{self, Debug, Display, Formatter};
93105
use core::ops::Deref;
94106
use ptr_meta::Pointee;
95-
96107
use uefi_raw::protocol::device_path::DevicePathProtocol;
97108
#[cfg(feature = "alloc")]
98109
use {
@@ -400,21 +411,49 @@ impl ToOwned for DevicePathInstance {
400411
}
401412
}
402413

403-
/// Device path protocol.
414+
/// High-level representation of the UEFI [device path protocol].
404415
///
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.
416+
/// This type represents an entire device path, possibly consisting of multiple
417+
/// [`DevicePathInstance`]s and [`DevicePathNode`]s.
411418
///
412419
/// See the [module-level documentation] for more details.
413420
///
421+
/// # Usage
422+
/// This type implements [`Protocol`] and therefore can be used on any
423+
/// device handle to obtain generic path/location information concerning the
424+
/// physical device or logical device. If the handle does not logically map to a
425+
/// physical device, the handle may not necessarily support the device path
426+
/// protocol. The device path describes the location of the device the handle is
427+
/// for. The size of the Device Path can be determined from the structures that
428+
/// make up the Device Path.
429+
///
430+
/// # Example
431+
/// ```rust,no_run
432+
/// use uefi::Handle;
433+
/// use uefi::boot::{open_protocol_exclusive, ScopedProtocol};
434+
/// use uefi::proto::device_path::DevicePath;
435+
/// use uefi::proto::device_path::text::{AllowShortcuts, DisplayOnly};
436+
/// use uefi::proto::loaded_image::LoadedImage;
437+
///
438+
/// fn open_device_path(image_handle: Handle) {
439+
/// let loaded_image = open_protocol_exclusive::<LoadedImage>(image_handle).unwrap();
440+
/// let device_handle = loaded_image.device().unwrap();
441+
/// let device_path: ScopedProtocol<DevicePath>
442+
/// = open_protocol_exclusive::<DevicePath>(device_handle).unwrap();
443+
/// log::debug!(
444+
/// "Device path: {}",
445+
/// device_path.to_string(DisplayOnly(true), AllowShortcuts(true)).unwrap()
446+
/// );
447+
/// }
448+
/// ```
449+
///
414450
/// [module-level documentation]: crate::proto::device_path
415451
/// [`END_ENTIRE`]: DeviceSubType::END_ENTIRE
452+
/// [`DevicePathProtocol`]: uefi_raw::protocol::device_path::DevicePathProtocol
453+
/// [`Protocol`]: uefi::proto::Protocol
454+
/// [device path protocol]: uefi_raw::protocol::device_path
416455
#[repr(C, packed)]
417-
#[unsafe_protocol(uefi_raw::protocol::device_path::DevicePathProtocol::GUID)]
456+
#[unsafe_protocol(DevicePathProtocol::GUID)]
418457
#[derive(Eq, Pointee)]
419458
pub struct DevicePath {
420459
data: [u8],

0 commit comments

Comments
 (0)