Merge pull request #1612 from rust-osdev/doc-devicepath

doc/uefi: improve Protocol documentation

Author: nicholasbishop

book/src/how_to/protocols.md

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

uefi-raw/CHANGELOG.md

@@ -6,6 +6,8 @@
 - Added `ConfigKeywordHandlerProtocol`.
 - Added `HiiConfigAccessProtocol`.
 
+## Changed
+- The documentation for UEFI protocols has been streamlined and improved.
 
 # uefi-raw - 0.11.0 (2025-05-04)
 
@@ -28,11 +30,6 @@
 ## Changed
 - `DevicePathProtocol` now derives
   `Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash`
-- The documentation for UEFI device paths has been streamlined and improved.
-
-## Changed
-
-- **Breaking:** The MSRV is now 1.85.1 and the crate uses the Rust 2024 edition.
 
 
 # uefi-raw - 0.10.0 (2025-02-07)

uefi-raw/src/protocol/device_path.rs

@@ -7,7 +7,7 @@
 //!
 //! # Terminology: Device Paths, Device Path Instances, and Device Path Nodes
 //! An open UEFI device path [protocol], also called _device path_, is a
-//! flexible and structured sequence of binary nodes that describe a route from
+//! flexible and structured sequence of binary nodes that describes a route from
 //! the UEFI root to a particular device, controller, or file.
 //!
 //! An entire device path can be made up of multiple device path instances,

uefi-raw/src/protocol/mod.rs

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

uefi/CHANGELOG.md

@@ -17,6 +17,7 @@
   it in case you are also using the `logger` feature and if you run your UEFI
   image in QEMU or Cloud Hypervisor, when the debugcon/debug-console device is
   available.
+- The documentation for UEFI protocols has been streamlined and improved.
 
 # uefi - 0.35.0 (2025-05-04)
 
@@ -64,7 +65,6 @@
   bugs on some devices.
 - The UEFI `allocator::Allocator` has been optimized for page-aligned
   allocations.
-- The documentation for UEFI device paths has been streamlined and improved.
 
 
 # uefi - 0.34.1 (2025-02-07)

uefi/src/boot.rs

@@ -853,12 +853,14 @@ pub fn protocols_per_handle(handle: Handle) -> Result<ProtocolsPerHandle> {
         })
 }
 
-/// Locates the handle of a device on the device path that supports the specified protocol.
+/// Locates the handle of a device on the [`DevicePath`] that supports the
+/// specified [`Protocol`].
 ///
-/// The `device_path` is updated to point at the remaining part of the [`DevicePath`] after
-/// the part that matched the protocol. For example, it can be used with a device path
-/// that contains a file path to strip off the file system portion of the device path,
-/// leaving the file path and handle to the file system driver needed to access the file.
+/// The `device_path` is updated to point at the remaining part that matched the
+/// protocol. For example, this function can be used with a device path that
+/// contains a file path to strip off the file system portion of the device
+/// path, leaving the file path and handle to the file system driver needed to
+/// access the file.
 ///
 /// If the first node of `device_path` matches the protocol, the `device_path`
 /// 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> {
         })
 }
 
-/// Returns all the handles implementing a certain protocol.
+/// Returns all the handles implementing a certain [`Protocol`].
 ///
 /// # Errors
 ///
@@ -1038,7 +1040,7 @@ pub fn get_handle_for_protocol<P: ProtocolPointer + ?Sized>() -> Result<Handle>
         .ok_or_else(|| Status::NOT_FOUND.into())
 }
 
-/// Opens a protocol interface for a handle.
+/// Opens a [`Protocol`] interface for a handle.
 ///
 /// See also [`open_protocol_exclusive`], which provides a safe subset of this
 /// functionality.
@@ -1101,7 +1103,7 @@ pub unsafe fn open_protocol<P: ProtocolPointer + ?Sized>(
     })
 }
 
-/// Opens a protocol interface for a handle in exclusive mode.
+/// Opens a [`Protocol`] interface for a handle in exclusive mode.
 ///
 /// If successful, a [`ScopedProtocol`] is returned that will automatically
 /// close the protocol interface when dropped.
@@ -1129,7 +1131,7 @@ pub fn open_protocol_exclusive<P: ProtocolPointer + ?Sized>(
     }
 }
 
-/// Tests whether a handle supports a protocol.
+/// Tests whether a handle supports a [`Protocol`].
 ///
 /// Returns `Ok(true)` if the handle supports the protocol, `Ok(false)` if not.
 ///
@@ -1543,7 +1545,7 @@ impl Deref for ProtocolsPerHandle {
 }
 
 /// A buffer returned by [`locate_handle_buffer`] that contains an array of
-/// [`Handle`]s that support the requested protocol.
+/// [`Handle`]s that support the requested [`Protocol`].
 #[derive(Debug, Eq, PartialEq)]
 pub struct HandleBuffer {
     count: usize,
@@ -1564,7 +1566,7 @@ impl Deref for HandleBuffer {
     }
 }
 
-/// An open protocol interface. Automatically closes the protocol
+/// An open [`Protocol`] interface. Automatically closes the protocol
 /// interface on drop.
 ///
 /// Most protocols have interface data associated with them. `ScopedProtocol`

uefi/src/proto/console/gop.rs

@@ -65,10 +65,13 @@ use uefi_raw::protocol::console::{
 
 pub use uefi_raw::protocol::console::PixelBitmask;
 
-/// Provides access to the video hardware's frame buffer.
+/// Graphics Output [`Protocol`] (GOP). Provides access to the video hardware's
+/// frame buffer.
 ///
-/// The GOP can be used to set the properties of the frame buffer,
-/// and also allows the app to access the in-memory buffer.
+/// The GOP can be used to set the properties of the framebuffer, and also
+/// allows the app to access the in-memory buffer.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(GraphicsOutputProtocol::GUID)]

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

@@ -6,7 +6,11 @@ use crate::proto::unsafe_protocol;
 use crate::{Event, Result, Status, StatusExt};
 use uefi_raw::protocol::console::SimplePointerProtocol;
 
-/// Provides information about a pointer device.
+/// Simple Pointer [`Protocol`]. Provides information about a pointer device.
+///
+/// Pointer devices are mouses, touchpads, and touchscreens.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(SimplePointerProtocol::GUID)]

uefi/src/proto/console/serial.rs

@@ -11,13 +11,15 @@ pub use uefi_raw::protocol::console::serial::{
     ControlBits, Parity, SerialIoMode as IoMode, StopBits,
 };
 
-/// Provides access to a serial I/O device.
+/// Serial IO [`Protocol`]. Provides access to a serial I/O device.
 ///
 /// This can include standard UART devices, serial ports over a USB interface,
 /// or any other character-based communication device.
 ///
 /// Since UEFI drivers are implemented through polling, if you fail to regularly
 /// check for input/output, some data might be lost.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(SerialIoProtocol::GUID)]

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

@@ -5,7 +5,9 @@ use crate::{Char16, Event, Result, Status, StatusExt};
 use core::mem::MaybeUninit;
 use uefi_raw::protocol::console::{InputKey, SimpleTextInputProtocol};
 
-/// Interface for text-based input devices.
+/// Simple Text Input [`Protocol`]. Interface for text-based input devices.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(SimpleTextInputProtocol::GUID)]