Skip to content

Commit bf7676d

Browse files
phip1611phip1611
committed
doc: stream documentation for device-paths between uefi-raw and uefi
1 parent e3d5afb commit bf7676d

File tree

2 files changed

+81
-35
lines changed

2 files changed

+81
-35
lines changed

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

Lines changed: 46 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,46 @@
11
// SPDX-License-Identifier: MIT OR Apache-2.0
22

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

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

950
/// Device path protocol.
1051
///
11-
/// A device path contains one or more device path instances made up of
12-
/// variable-length nodes.
52+
/// Note that the fields in this struct define the fixed header at the start of
53+
/// each node; a device path is typically larger than these four bytes.
54+
///
55+
/// See the [module-level documentation] for more details.
1356
///
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.
57+
/// [module-level documentation]: self
1658
#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
1759
#[repr(C)]
1860
pub struct DevicePathProtocol {

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

Lines changed: 35 additions & 31 deletions
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 [UEFI device paths] and the UEFI device path
4+
//! [`Protocol`].
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;
@@ -400,19 +380,43 @@ impl ToOwned for DevicePathInstance {
400380
}
401381
}
402382

403-
/// Device path protocol.
404-
///
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.
383+
/// High-level representation of the UEFI [device path protocol](uefi_raw::protocol::device_path).
411384
///
412385
/// See the [module-level documentation] for more details.
413386
///
387+
/// # Usage
388+
/// This type implements [`DevicePathProtocol`] and therefore can be used on any
389+
/// device handle to obtain generic path/location information concerning the
390+
/// physical device or logical device. If the handle does not logically map to a
391+
/// physical device, the handle may not necessarily support the device path
392+
/// protocol. The device path describes the location of the device the handle is
393+
/// for. The size of the Device Path can be determined from the structures that
394+
/// make up the Device Path.
395+
///
396+
/// # Example
397+
/// ```rust,no_run
398+
/// use uefi::Handle;
399+
/// use uefi::boot::{open_protocol_exclusive, ScopedProtocol};
400+
/// use uefi::proto::device_path::DevicePath;
401+
/// use uefi::proto::device_path::text::{AllowShortcuts, DisplayOnly};
402+
/// use uefi::proto::loaded_image::LoadedImage;
403+
///
404+
/// fn open_device_path(image_handle: Handle) {
405+
/// let loaded_image = open_protocol_exclusive::<LoadedImage>(image_handle).unwrap();
406+
/// let device_handle = loaded_image.device().unwrap();
407+
/// let device_path: ScopedProtocol<DevicePath>
408+
/// = open_protocol_exclusive::<DevicePath>(device_handle).unwrap();
409+
/// log::debug!(
410+
/// "Device path: {}",
411+
/// device_path.to_string(DisplayOnly(true), AllowShortcuts(true)).unwrap()
412+
/// );
413+
/// }
414+
/// ```
415+
///
414416
/// [module-level documentation]: crate::proto::device_path
415417
/// [`END_ENTIRE`]: DeviceSubType::END_ENTIRE
418+
/// [`DevicePathProtocol`]: uefi_raw::protocol::device_path::DevicePathProtocol
419+
/// [`Protocol`]: uefi::proto::Protocol
416420
#[repr(C, packed)]
417421
#[unsafe_protocol(uefi_raw::protocol::device_path::DevicePathProtocol::GUID)]
418422
#[derive(Eq, Pointee)]

0 commit comments

Comments
 (0)