Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 5d233a5

Browse files
Merge pull request #1612 from rust-osdev/doc-devicepath
doc/uefi: improve Protocol documentation
2 parents d61b05a + 4e03942 commit 5d233a5

File tree

34 files changed

+200
-59
lines changed

34 files changed

+200
-59
lines changed

‎book/src/how_to/protocols.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
# Using Protocols
22

3+
## About UEFI Protocols
4+
5+
UEFI protocols are a structured collection of functions and/or data. Please
6+
head to the module documentation in [uefi] for more technical information.
7+
8+
[uefi]: https://docs.rs/uefi/latest/uefi/proto/index.html
9+
10+
## Usage in uefi-rs
11+
312
To open a protocol, you must first get a handle, then open a protocol
413
on that handle. See [Handles and Protocols] for an overview of what
514
these terms mean.

‎uefi-raw/CHANGELOG.md

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66
- Added `ConfigKeywordHandlerProtocol`.
77
- Added `HiiConfigAccessProtocol`.
88

9+
## Changed
10+
- The documentation for UEFI protocols has been streamlined and improved.
911

1012
# uefi-raw - 0.11.0 (2025年05月04日)
1113

@@ -28,11 +30,6 @@
2830
## Changed
2931
- `DevicePathProtocol` now derives
3032
`Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash`
31-
- The documentation for UEFI device paths has been streamlined and improved.
32-
33-
## Changed
34-
35-
- **Breaking:** The MSRV is now 1.85.1 and the crate uses the Rust 2024 edition.
3633

3734

3835
# uefi-raw - 0.10.0 (2025年02月07日)

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
//!
88
//! # Terminology: Device Paths, Device Path Instances, and Device Path Nodes
99
//! 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
10+
//! flexible and structured sequence of binary nodes that describes a route from
1111
//! the UEFI root to a particular device, controller, or file.
1212
//!
1313
//! An entire device path can be made up of multiple device path instances,

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

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,26 @@
22

33
//! Protocol definitions.
44
//!
5-
//! Protocols are sets of related functionality identified by a unique
6-
//! ID. They can be implemented by a UEFI driver or occasionally by a
7-
//! UEFI application.
5+
//! # TL;DR
6+
//! Technically, a protocol is a `C` struct holding functions and/or data, with
7+
//! an associated [`GUID`].
8+
//!
9+
//! # About
10+
//! UEFI protocols are a structured collection of functions and/or data,
11+
//! identified by a [`GUID`], which defines an interface between components in
12+
//! the UEFI environment, such as between drivers, applications, or firmware
13+
//! services.
14+
//!
15+
//! Protocols are central to UEFI’s handle-based object model, and they provide
16+
//! a clean, extensible way for components to discover and use services from one
17+
//! another.
18+
//!
19+
//! Implementation-wise, a protocol is a `C` struct holding function pointers
20+
//! and/or data. Please note that some protocols may use [`core::ptr::null`] as
21+
//! interface. For example, the device path protocol can be implemented but
22+
//! return `null`.
23+
//!
24+
//! [`GUID`]: crate::Guid
825
926
pub mod ata;
1027
pub mod block;

‎uefi/CHANGELOG.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
it in case you are also using the `logger` feature and if you run your UEFI
1818
image in QEMU or Cloud Hypervisor, when the debugcon/debug-console device is
1919
available.
20+
- The documentation for UEFI protocols has been streamlined and improved.
2021

2122
# uefi - 0.35.0 (2025年05月04日)
2223

@@ -64,7 +65,6 @@
6465
bugs on some devices.
6566
- The UEFI `allocator::Allocator` has been optimized for page-aligned
6667
allocations.
67-
- The documentation for UEFI device paths has been streamlined and improved.
6868

6969

7070
# uefi - 0.34.1 (2025年02月07日)

‎uefi/src/boot.rs

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -853,12 +853,14 @@ pub fn protocols_per_handle(handle: Handle) -> Result<ProtocolsPerHandle> {
853853
})
854854
}
855855

856-
/// Locates the handle of a device on the device path that supports the specified protocol.
856+
/// Locates the handle of a device on the [`DevicePath`] that supports the
857+
/// specified [`Protocol`].
857858
///
858-
/// The `device_path` is updated to point at the remaining part of the [`DevicePath`] after
859-
/// the part that matched the protocol. For example, it can be used with a device path
860-
/// that contains a file path to strip off the file system portion of the device path,
861-
/// leaving the file path and handle to the file system driver needed to access the file.
859+
/// The `device_path` is updated to point at the remaining part that matched the
860+
/// protocol. For example, this function can be used with a device path that
861+
/// contains a file path to strip off the file system portion of the device
862+
/// path, leaving the file path and handle to the file system driver needed to
863+
/// access the file.
862864
///
863865
/// If the first node of `device_path` matches the protocol, the `device_path`
864866
/// is advanced to the device path terminator node. If `device_path` is a
@@ -959,7 +961,7 @@ pub fn locate_handle_buffer(search_ty: SearchType) -> Result<HandleBuffer> {
959961
})
960962
}
961963

962-
/// Returns all the handles implementing a certain protocol.
964+
/// Returns all the handles implementing a certain [`Protocol`].
963965
///
964966
/// # Errors
965967
///
@@ -1038,7 +1040,7 @@ pub fn get_handle_for_protocol<P: ProtocolPointer + ?Sized>() -> Result<Handle>
10381040
.ok_or_else(|| Status::NOT_FOUND.into())
10391041
}
10401042

1041-
/// Opens a protocol interface for a handle.
1043+
/// Opens a [`Protocol`] interface for a handle.
10421044
///
10431045
/// See also [`open_protocol_exclusive`], which provides a safe subset of this
10441046
/// functionality.
@@ -1101,7 +1103,7 @@ pub unsafe fn open_protocol<P: ProtocolPointer + ?Sized>(
11011103
})
11021104
}
11031105

1104-
/// Opens a protocol interface for a handle in exclusive mode.
1106+
/// Opens a [`Protocol`] interface for a handle in exclusive mode.
11051107
///
11061108
/// If successful, a [`ScopedProtocol`] is returned that will automatically
11071109
/// close the protocol interface when dropped.
@@ -1129,7 +1131,7 @@ pub fn open_protocol_exclusive<P: ProtocolPointer + ?Sized>(
11291131
}
11301132
}
11311133

1132-
/// Tests whether a handle supports a protocol.
1134+
/// Tests whether a handle supports a [`Protocol`].
11331135
///
11341136
/// Returns `Ok(true)` if the handle supports the protocol, `Ok(false)` if not.
11351137
///
@@ -1543,7 +1545,7 @@ impl Deref for ProtocolsPerHandle {
15431545
}
15441546

15451547
/// A buffer returned by [`locate_handle_buffer`] that contains an array of
1546-
/// [`Handle`]s that support the requested protocol.
1548+
/// [`Handle`]s that support the requested [`Protocol`].
15471549
#[derive(Debug, Eq, PartialEq)]
15481550
pub struct HandleBuffer {
15491551
count: usize,
@@ -1564,7 +1566,7 @@ impl Deref for HandleBuffer {
15641566
}
15651567
}
15661568

1567-
/// An open protocol interface. Automatically closes the protocol
1569+
/// An open [`Protocol`] interface. Automatically closes the protocol
15681570
/// interface on drop.
15691571
///
15701572
/// Most protocols have interface data associated with them. `ScopedProtocol`

‎uefi/src/proto/console/gop.rs

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -65,10 +65,13 @@ use uefi_raw::protocol::console::{
6565

6666
pub use uefi_raw::protocol::console::PixelBitmask;
6767

68-
/// Provides access to the video hardware's frame buffer.
68+
/// Graphics Output [`Protocol`] (GOP). Provides access to the video hardware's
69+
/// frame buffer.
6970
///
70-
/// The GOP can be used to set the properties of the frame buffer,
71-
/// and also allows the app to access the in-memory buffer.
71+
/// The GOP can be used to set the properties of the framebuffer, and also
72+
/// allows the app to access the in-memory buffer.
73+
///
74+
/// [`Protocol`]: uefi::proto::Protocol
7275
#[derive(Debug)]
7376
#[repr(transparent)]
7477
#[unsafe_protocol(GraphicsOutputProtocol::GUID)]

‎uefi/src/proto/console/pointer/mod.rs

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,11 @@ use crate::proto::unsafe_protocol;
66
use crate::{Event, Result, Status, StatusExt};
77
use uefi_raw::protocol::console::SimplePointerProtocol;
88

9-
/// Provides information about a pointer device.
9+
/// Simple Pointer [`Protocol`]. Provides information about a pointer device.
10+
///
11+
/// Pointer devices are mouses, touchpads, and touchscreens.
12+
///
13+
/// [`Protocol`]: uefi::proto::Protocol
1014
#[derive(Debug)]
1115
#[repr(transparent)]
1216
#[unsafe_protocol(SimplePointerProtocol::GUID)]

‎uefi/src/proto/console/serial.rs

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,15 @@ pub use uefi_raw::protocol::console::serial::{
1111
ControlBits, Parity, SerialIoMode as IoMode, StopBits,
1212
};
1313

14-
/// Provides access to a serial I/O device.
14+
/// Serial IO [`Protocol`]. Provides access to a serial I/O device.
1515
///
1616
/// This can include standard UART devices, serial ports over a USB interface,
1717
/// or any other character-based communication device.
1818
///
1919
/// Since UEFI drivers are implemented through polling, if you fail to regularly
2020
/// check for input/output, some data might be lost.
21+
///
22+
/// [`Protocol`]: uefi::proto::Protocol
2123
#[derive(Debug)]
2224
#[repr(transparent)]
2325
#[unsafe_protocol(SerialIoProtocol::GUID)]

‎uefi/src/proto/console/text/input.rs

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@ use crate::{Char16, Event, Result, Status, StatusExt};
55
use core::mem::MaybeUninit;
66
use uefi_raw::protocol::console::{InputKey, SimpleTextInputProtocol};
77

8-
/// Interface for text-based input devices.
8+
/// Simple Text Input [`Protocol`]. Interface for text-based input devices.
9+
///
10+
/// [`Protocol`]: uefi::proto::Protocol
911
#[derive(Debug)]
1012
#[repr(transparent)]
1113
#[unsafe_protocol(SimpleTextInputProtocol::GUID)]

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /