From 8192ea4a03ecc602c17ea1fea1f4ff314cbba696 Mon Sep 17 00:00:00 2001
From: Philipp Schuster <phip1611@gmail.com>
Date: Tue, 8 Apr 2025 09:26:11 +0200
Subject: [PATCH 1/7] uefi-raw: improve protocol module documentation

---
 uefi-raw/src/protocol/mod.rs | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/uefi-raw/src/protocol/mod.rs b/uefi-raw/src/protocol/mod.rs
index 2ee6985e5..46b30ee98 100644
--- a/uefi-raw/src/protocol/mod.rs
+++ b/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;

From 930719b4d67e494a8b0986484517b04be81c7caa Mon Sep 17 00:00:00 2001
From: Philipp Schuster <phip1611@gmail.com>
Date: Tue, 8 Apr 2025 09:26:54 +0200
Subject: [PATCH 2/7] uefi: forward documentation of Protocol to uefi-raw
 (deduplicate)

---
 uefi/src/proto/mod.rs | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/uefi/src/proto/mod.rs b/uefi/src/proto/mod.rs
index 4d67080b7..4a381aace 100644
--- a/uefi/src/proto/mod.rs
+++ b/uefi/src/proto/mod.rs
@@ -1,14 +1,11 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-//! 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.
+//! High-level wrappers for [UEFI protocols].
 //!
 //! See the [`boot`] documentation for details of how to open a protocol.
 //!
 //! [`boot`]: crate::boot#accessing-protocols
+//! [UEFI protocols]: uefi_raw::protocol
 
 #[cfg(feature = "alloc")]
 pub mod ata;

From 87e740d3550810191e659c532271afd9596c9e56 Mon Sep 17 00:00:00 2001
From: Philipp Schuster <phip1611@gmail.com>
Date: Tue, 8 Apr 2025 09:29:01 +0200
Subject: [PATCH 3/7] uefi: streamline documentation of Protocol structs

Now each struct's documentation begins with "$ProtocolName [`Protocol`]". This
way, readers quickly can figure out what Protocols are in general.
---
 uefi/src/proto/console/gop.rs                |  9 ++++++---
 uefi/src/proto/console/pointer/mod.rs        |  6 +++++-
 uefi/src/proto/console/serial.rs             |  4 +++-
 uefi/src/proto/console/text/input.rs         |  4 +++-
 uefi/src/proto/console/text/output.rs        |  3 ++-
 uefi/src/proto/debug/mod.rs                  |  8 ++++++++
 uefi/src/proto/device_path/mod.rs            | 11 +++++++----
 uefi/src/proto/device_path/text.rs           |  8 ++++++++
 uefi/src/proto/driver/component_name.rs      |  6 ++++++
 uefi/src/proto/loaded_image.rs               |  8 +++++++-
 uefi/src/proto/media/block.rs                |  4 +++-
 uefi/src/proto/media/disk.rs                 | 10 +++++++---
 uefi/src/proto/media/disk_info.rs            |  4 +++-
 uefi/src/proto/media/fs.rs                   |  4 +++-
 uefi/src/proto/media/load_file.rs            |  8 ++++++--
 uefi/src/proto/media/partition.rs            |  4 ++++
 uefi/src/proto/misc.rs                       | 17 ++++++++++++++---
 uefi/src/proto/mod.rs                        |  6 ++++--
 uefi/src/proto/network/pxe.rs                |  4 +++-
 uefi/src/proto/network/snp.rs                |  4 +++-
 uefi/src/proto/pi/mp.rs                      |  4 ++++
 uefi/src/proto/rng.rs                        |  4 +++-
 uefi/src/proto/security/memory_protection.rs |  4 ++++
 uefi/src/proto/shell_params.rs               |  4 +++-
 uefi/src/proto/shim/mod.rs                   |  4 +++-
 uefi/src/proto/string/unicode_collation.rs   |  4 +++-
 uefi/src/proto/tcg/v1.rs                     |  4 +++-
 uefi/src/proto/tcg/v2.rs                     |  7 +++----
 28 files changed, 131 insertions(+), 36 deletions(-)

diff --git a/uefi/src/proto/console/gop.rs b/uefi/src/proto/console/gop.rs
index f2e3daf0e..281eafbfa 100644
--- a/uefi/src/proto/console/gop.rs
+++ b/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)]
diff --git a/uefi/src/proto/console/pointer/mod.rs b/uefi/src/proto/console/pointer/mod.rs
index 6c56f16c0..35101dc4a 100644
--- a/uefi/src/proto/console/pointer/mod.rs
+++ b/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)]
diff --git a/uefi/src/proto/console/serial.rs b/uefi/src/proto/console/serial.rs
index a41f74a5d..378fadc49 100644
--- a/uefi/src/proto/console/serial.rs
+++ b/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)]
diff --git a/uefi/src/proto/console/text/input.rs b/uefi/src/proto/console/text/input.rs
index 865758051..ca594bd5c 100644
--- a/uefi/src/proto/console/text/input.rs
+++ b/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)]
diff --git a/uefi/src/proto/console/text/output.rs b/uefi/src/proto/console/text/output.rs
index 8e94f032c..8fedbbeb6 100644
--- a/uefi/src/proto/console/text/output.rs
+++ b/uefi/src/proto/console/text/output.rs
@@ -5,7 +5,7 @@ use crate::{CStr16, Result, ResultExt, Status, StatusExt};
 use core::fmt;
 use uefi_raw::protocol::console::{SimpleTextOutputMode, SimpleTextOutputProtocol};
 
-/// Interface for text-based output devices.
+/// Simple Text Output [`Protocol`]. Interface for text-based output devices.
 ///
 /// It implements the fmt::Write trait, so you can use it to print text with
 /// standard Rust constructs like the `write!()` and `writeln!()` macros.
@@ -22,6 +22,7 @@ use uefi_raw::protocol::console::{SimpleTextOutputMode, SimpleTextOutputProtocol
 /// [`system::stdout`]: crate::system::with_stdout
 /// [`system::stderr`]: crate::system::with_stderr
 /// [`boot`]: crate::boot#accessing-protocols
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(SimpleTextOutputProtocol::GUID)]
diff --git a/uefi/src/proto/debug/mod.rs b/uefi/src/proto/debug/mod.rs
index 088f061d3..74e04597a 100644
--- a/uefi/src/proto/debug/mod.rs
+++ b/uefi/src/proto/debug/mod.rs
@@ -23,6 +23,8 @@ pub use exception::ExceptionType;
 mod context;
 mod exception;
 
+/// Debug support [`Protocol`].
+///
 /// The debugging support protocol allows debuggers to connect to a UEFI machine.
 /// It is expected that there will typically be two instances of the EFI Debug Support protocol in the system.
 /// One associated with the native processor instruction set (IA-32, x64, ARM, RISC-V, or Itanium processor
@@ -31,6 +33,8 @@ mod exception;
 /// one for any given instruction set.
 ///
 /// NOTE: OVMF only implements this protocol interface for the virtual EBC processor
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(C)]
 #[unsafe_protocol("2755590c-6f3c-42fa-9ea4-a3ba543cda25")]
@@ -178,8 +182,12 @@ pub enum ProcessorArch: u32 => {
     RISCV_128   = 0x5128,
 }}
 
+/// Debug Port [`Protocol`].
+///
 /// The debug port protocol abstracts the underlying debug port
 /// hardware, whether it is a regular Serial port or something else.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(C)]
 #[unsafe_protocol("eba4e8d2-3858-41ec-a281-2647ba9660d0")]
diff --git a/uefi/src/proto/device_path/mod.rs b/uefi/src/proto/device_path/mod.rs
index d3e6bf049..c0b74a202 100644
--- a/uefi/src/proto/device_path/mod.rs
+++ b/uefi/src/proto/device_path/mod.rs
@@ -1,9 +1,8 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-//! Device Path protocol
+//! Helpers to work with UEFI Device Paths and the Device Path Protocol.
 //!
-//! A UEFI device path is a very flexible structure for encoding a
-//! programmatic path such as a hard drive or console.
+//! The main export of this module is [`DevicePath`].
 //!
 //! A device path is made up of a packed list of variable-length nodes of
 //! various types. The entire device path is terminated with an
@@ -400,7 +399,7 @@ impl ToOwned for DevicePathInstance {
     }
 }
 
-/// Device path protocol.
+/// Device Path [`Protocol`].
 ///
 /// Can be used on any device handle to obtain generic path/location information
 /// concerning the physical device or logical device. If the handle does not
@@ -413,6 +412,7 @@ impl ToOwned for DevicePathInstance {
 ///
 /// [module-level documentation]: crate::proto::device_path
 /// [`END_ENTIRE`]: DeviceSubType::END_ENTIRE
+/// [`Protocol`]: uefi::proto::Protocol
 #[repr(C, packed)]
 #[unsafe_protocol(uefi_raw::protocol::device_path::DevicePathProtocol::GUID)]
 #[derive(Eq, Pointee)]
@@ -729,12 +729,15 @@ pub enum NodeConversionError {
     UnsupportedType,
 }
 
+/// Loaded Image Device Path [`Protocol`].
+///
 /// Protocol for accessing the device path that was passed in to [`load_image`]
 /// when loading a PE/COFF image.
 ///
 /// The layout of this type is the same as a [`DevicePath`].
 ///
 /// [`load_image`]: crate::boot::load_image
+/// [`Protocol`]: uefi::proto::Protocol
 #[repr(transparent)]
 #[unsafe_protocol("bc62157e-3e33-4fec-9920-2d3b36d750df")]
 #[derive(Debug, Pointee)]
diff --git a/uefi/src/proto/device_path/text.rs b/uefi/src/proto/device_path/text.rs
index 7c39c8921..358dbba00 100644
--- a/uefi/src/proto/device_path/text.rs
+++ b/uefi/src/proto/device_path/text.rs
@@ -47,7 +47,11 @@ pub struct DisplayOnly(pub bool);
 #[derive(Clone, Copy, Debug)]
 pub struct AllowShortcuts(pub bool);
 
+/// Device Path to Text [`Protocol`].
+///
 /// Protocol for converting a [`DevicePath`] or `DevicePathNode`] to a string.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(DevicePathToTextProtocol::GUID)]
@@ -99,7 +103,11 @@ impl DevicePathToText {
     }
 }
 
+/// Device Path from Text [`Protocol`].
+///
 /// Protocol for converting a string to a [`DevicePath`] or `DevicePathNode`].
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol("05c99a21-c70f-4ad2-8a5f-35df3343f51e")]
diff --git a/uefi/src/proto/driver/component_name.rs b/uefi/src/proto/driver/component_name.rs
index fec5d9c9e..c36201c60 100644
--- a/uefi/src/proto/driver/component_name.rs
+++ b/uefi/src/proto/driver/component_name.rs
@@ -13,6 +13,8 @@ use core::fmt::{self, Debug, Display, Formatter};
 use core::{ptr, slice};
 use uefi_raw::protocol::driver::ComponentName2Protocol;
 
+/// Component Name1 [`Protocol`].
+///
 /// Protocol that provides human-readable names for a driver and for each of the
 /// controllers that the driver is managing.
 ///
@@ -27,6 +29,7 @@ use uefi_raw::protocol::driver::ComponentName2Protocol;
 ///
 /// [ISO 639-2]: https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes
 /// [RFC 4646]: https://www.rfc-editor.org/rfc/rfc4646
+/// [`Protocol`]: uefi::proto::Protocol
 #[deprecated = "deprecated in UEFI 2.1; use ComponentName2 where possible"]
 #[unsafe_protocol(ComponentName2Protocol::DEPRECATED_COMPONENT_NAME_GUID)]
 #[derive(Debug)]
@@ -85,6 +88,8 @@ impl ComponentName1 {
     }
 }
 
+/// Component Name2 [`Protocol`].
+///
 /// Protocol that provides human-readable names for a driver and for each of the
 /// controllers that the driver is managing.
 ///
@@ -99,6 +104,7 @@ impl ComponentName1 {
 ///
 /// [ISO 639-2]: https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes
 /// [RFC 4646]: https://www.rfc-editor.org/rfc/rfc4646
+/// [`Protocol`]: uefi::proto::Protocol
 #[unsafe_protocol(ComponentName2Protocol::GUID)]
 #[derive(Debug)]
 #[repr(transparent)]
diff --git a/uefi/src/proto/loaded_image.rs b/uefi/src/proto/loaded_image.rs
index 3ab91c4a4..3ca815dcc 100644
--- a/uefi/src/proto/loaded_image.rs
+++ b/uefi/src/proto/loaded_image.rs
@@ -12,7 +12,13 @@ use core::ffi::c_void;
 use core::{mem, slice};
 use uefi_raw::protocol::loaded_image::LoadedImageProtocol;
 
-/// The LoadedImage protocol. This can be opened on any image handle using the `HandleProtocol` boot service.
+/// The Loaded Image [`Protocol`].
+///
+/// This can be opened on any image handle using [`boot::open_protocol`],
+/// for example.
+///
+/// [`Protocol`]: uefi::proto::Protocol
+/// [`boot::open_protocol`]: uefi::boot::open_protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(LoadedImageProtocol::GUID)]
diff --git a/uefi/src/proto/media/block.rs b/uefi/src/proto/media/block.rs
index 2bfb3d36e..ec79e2ec4 100644
--- a/uefi/src/proto/media/block.rs
+++ b/uefi/src/proto/media/block.rs
@@ -7,7 +7,9 @@ use crate::{Result, StatusExt};
 
 pub use uefi_raw::protocol::block::{BlockIoProtocol, Lba};
 
-/// The Block I/O protocol.
+/// Block I/O [`Protocol`].
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(BlockIoProtocol::GUID)]
diff --git a/uefi/src/proto/media/disk.rs b/uefi/src/proto/media/disk.rs
index 22ef6f64e..f3a87b2f9 100644
--- a/uefi/src/proto/media/disk.rs
+++ b/uefi/src/proto/media/disk.rs
@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-//! Disk I/O protocols.
+//! Disk I/O protocols [`DiskIo`] and [`DiskIo2`].
 
 use crate::proto::unsafe_protocol;
 use crate::util::opt_nonnull_to_ptr;
@@ -8,12 +8,14 @@ use crate::{Event, Result, Status, StatusExt};
 use core::ptr::NonNull;
 use uefi_raw::protocol::disk::{DiskIo2Protocol, DiskIoProtocol};
 
-/// The disk I/O protocol.
+/// Disk I/O [`Protocol`].
 ///
 /// This protocol is used to abstract the block accesses of the block I/O
 /// protocol to a more general offset-length protocol. Firmware is
 /// responsible for adding this protocol to any block I/O interface that
 /// appears in the system that does not already have a disk I/O protocol.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(DiskIoProtocol::GUID)]
@@ -82,10 +84,12 @@ pub struct DiskIo2Token {
     pub transaction_status: Status,
 }
 
-/// The disk I/O 2 protocol.
+/// Disk I/O 2 [`Protocol`].
 ///
 /// This protocol provides an extension to the disk I/O protocol to enable
 /// non-blocking / asynchronous byte-oriented disk operation.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(DiskIo2Protocol::GUID)]
diff --git a/uefi/src/proto/media/disk_info.rs b/uefi/src/proto/media/disk_info.rs
index bba5dbcc9..608139739 100644
--- a/uefi/src/proto/media/disk_info.rs
+++ b/uefi/src/proto/media/disk_info.rs
@@ -52,7 +52,7 @@ pub struct DeviceLocationInfo {
     pub device: u32,
 }
 
-/// DiskInfo protocol.
+/// Disk Info [`Protocol`].
 ///
 /// This allows querying hardware information for detected disks in a simple way.
 /// Originally, this was designed for IDE and it shows.
@@ -64,6 +64,8 @@ pub struct DeviceLocationInfo {
 ///
 /// # UEFI Spec Description
 /// Provides the basic interfaces to abstract platform information regarding an IDE controller.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(DiskInfoProtocol::GUID)]
diff --git a/uefi/src/proto/media/fs.rs b/uefi/src/proto/media/fs.rs
index 1941d4ef1..4c77dc02f 100644
--- a/uefi/src/proto/media/fs.rs
+++ b/uefi/src/proto/media/fs.rs
@@ -8,7 +8,8 @@ use crate::{Result, StatusExt};
 use core::ptr;
 use uefi_raw::protocol::file_system::SimpleFileSystemProtocol;
 
-/// Allows access to a FAT-12/16/32 file system.
+/// Simple File System [`Protocol`]. Allows access to a FAT-12/16/32 file
+/// system.
 ///
 /// This interface is implemented by some storage devices
 /// to allow file access to the contained file systems.
@@ -22,6 +23,7 @@ use uefi_raw::protocol::file_system::SimpleFileSystemProtocol;
 ///
 /// [`boot::get_image_file_system`]: crate::boot::get_image_file_system
 /// [`boot`]: crate::boot#accessing-protocols
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(SimpleFileSystemProtocol::GUID)]
diff --git a/uefi/src/proto/media/load_file.rs b/uefi/src/proto/media/load_file.rs
index 665145a46..93efb5ae8 100644
--- a/uefi/src/proto/media/load_file.rs
+++ b/uefi/src/proto/media/load_file.rs
@@ -16,7 +16,7 @@ use {
     uefi_raw::Boolean,
 };
 
-/// Load File Protocol.
+/// Load File [`Protocol`].
 ///
 /// Used to obtain files, that are primarily boot options, from arbitrary
 /// devices.
@@ -33,6 +33,8 @@ use {
 /// EFI_LOAD_FILE_PROTOCOL and the LoadFile() function. In this case the
 /// LoadFile() function implements the policy of interpreting the File Path
 /// value.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(LoadFileProtocol::GUID)]
@@ -98,7 +100,7 @@ impl LoadFile {
     }
 }
 
-/// Load File2 Protocol.
+/// Load File2 [`Protocol`].
 ///
 /// The Load File2 protocol is used to obtain files from arbitrary devices that
 /// are not boot options.
@@ -109,6 +111,8 @@ impl LoadFile {
 /// arbitrary devices that are not boot options. It is used by LoadImage() when
 /// its BootOption parameter is FALSE and the FilePath does not have an instance
 /// of the EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(LoadFile2Protocol::GUID)]
diff --git a/uefi/src/proto/media/partition.rs b/uefi/src/proto/media/partition.rs
index 99f1c774e..7e6e5c0db 100644
--- a/uefi/src/proto/media/partition.rs
+++ b/uefi/src/proto/media/partition.rs
@@ -221,7 +221,11 @@ newtype_enum! {
     }
 }
 
+/// Partition Info [`Protocol`].
+///
 /// Protocol for accessing partition information.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[allow(missing_debug_implementations)]
 #[repr(C)]
 #[repr(packed)]
diff --git a/uefi/src/proto/misc.rs b/uefi/src/proto/misc.rs
index 0ccff0729..91fcbbd45 100644
--- a/uefi/src/proto/misc.rs
+++ b/uefi/src/proto/misc.rs
@@ -9,10 +9,17 @@ use uefi_raw::protocol::misc::{
 use crate::proto::unsafe_protocol;
 use crate::{Result, StatusExt};
 
+/// Timestamp [`Protocol`].
+///
 /// Protocol for retrieving a high-resolution timestamp counter.
-/// **Note:**
-/// If your UEFI firmware not support timestamp protocol which first added at UEFI spec 2.4 2013.
-/// you also could use `RDTSC` in rust, here is a demo [Slint-UI](https://github.com/slint-ui/slint/blob/2c0ba2bc0f151eba8d1fa17839fa2ac58832ca80/examples/uefi-demo/main.rs#L28-L62) who use uefi-rs.
+///
+/// # Note
+/// If your UEFI firmware not support timestamp protocol which first added at
+/// UEFI spec 2.4 2013. you also could use `RDTSC` in rust, here is a demo
+/// [Slint-UI](https://github.com/slint-ui/slint/blob/2c0ba2bc0f151eba8d1fa17839fa2ac58832ca80/examples/uefi-demo/main.rs#L28-L62)
+/// who use uefi-rs.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(TimestampProtocol::GUID)]
@@ -32,7 +39,11 @@ impl Timestamp {
     }
 }
 
+/// Reset Notification [`Protocol`].
+///
 /// Protocol to register for a notification when ResetSystem is called.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(ResetNotificationProtocol::GUID)]
diff --git a/uefi/src/proto/mod.rs b/uefi/src/proto/mod.rs
index 4a381aace..5d8d2136c 100644
--- a/uefi/src/proto/mod.rs
+++ b/uefi/src/proto/mod.rs
@@ -40,7 +40,7 @@ use core::ffi::c_void;
 #[cfg(doc)]
 use crate::boot;
 
-/// Marker trait for structures that represent UEFI protocols.
+/// Marker trait for structures that represent [UEFI protocols].
 ///
 /// Implementing this trait allows a protocol to be opened with
 /// [`boot::open_protocol`] or [`boot::open_protocol_exclusive`]. Note that
@@ -61,9 +61,11 @@ use crate::boot;
 ///
 /// assert_eq!(ExampleProtocol::GUID, guid!("12345678-9abc-def0-1234-56789abcdef0"));
 /// ```
+///
+/// [UEFI protocols]: uefi_raw::protocol
 pub trait Protocol: Identify {}
 
-/// Trait for creating a protocol pointer from a [`c_void`] pointer.
+/// Trait for creating a [`Protocol`] pointer from a [`c_void`] pointer.
 ///
 /// There is a blanket implementation for all [`Sized`] protocols that
 /// simply casts the pointer to the appropriate type. Protocols that
diff --git a/uefi/src/proto/network/pxe.rs b/uefi/src/proto/network/pxe.rs
index a46162151..1a55cc485 100644
--- a/uefi/src/proto/network/pxe.rs
+++ b/uefi/src/proto/network/pxe.rs
@@ -25,7 +25,9 @@ pub use uefi_raw::protocol::network::pxe::{
     PxeBaseCodeUdpOpFlags as UdpOpFlags,
 };
 
-/// PXE Base Code protocol
+/// PXE Base Code [`Protocol`].
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(PxeBaseCodeProtocol::GUID)]
diff --git a/uefi/src/proto/network/snp.rs b/uefi/src/proto/network/snp.rs
index 208477d59..bbd790e4e 100644
--- a/uefi/src/proto/network/snp.rs
+++ b/uefi/src/proto/network/snp.rs
@@ -23,7 +23,9 @@ pub use uefi_raw::protocol::network::snp::{
     InterruptStatus, NetworkMode, NetworkState, NetworkStatistics, ReceiveFlags,
 };
 
-/// The Simple Network Protocol
+/// Simple Network [`Protocol`].
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(SimpleNetworkProtocol::GUID)]
diff --git a/uefi/src/proto/pi/mp.rs b/uefi/src/proto/pi/mp.rs
index 80de66c80..e27fc6ad0 100644
--- a/uefi/src/proto/pi/mp.rs
+++ b/uefi/src/proto/pi/mp.rs
@@ -95,7 +95,11 @@ pub struct CpuPhysicalLocation {
     pub thread: u32,
 }
 
+/// MP Services [`Protocol`].
+///
 /// Protocol that provides services needed for multi-processor management.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(C)]
 #[unsafe_protocol("3fdda605-a76e-4f46-ad29-12f4531b3d08")]
diff --git a/uefi/src/proto/rng.rs b/uefi/src/proto/rng.rs
index 18254bc2f..cad744e77 100644
--- a/uefi/src/proto/rng.rs
+++ b/uefi/src/proto/rng.rs
@@ -8,7 +8,9 @@ use core::ptr;
 
 pub use uefi_raw::protocol::rng::RngAlgorithmType;
 
-/// Rng protocol
+/// Random Number Generator [`Protocol`] (RNG).
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(uefi_raw::protocol::rng::RngProtocol::GUID)]
diff --git a/uefi/src/proto/security/memory_protection.rs b/uefi/src/proto/security/memory_protection.rs
index 3481195b8..4258617fd 100644
--- a/uefi/src/proto/security/memory_protection.rs
+++ b/uefi/src/proto/security/memory_protection.rs
@@ -7,9 +7,13 @@ use crate::{Result, StatusExt};
 use core::ops::Range;
 use uefi_raw::protocol::memory_protection::MemoryAttributeProtocol;
 
+/// Memory Attribute [`Protocol`] for Memory Protection.
+///
 /// Protocol for getting and setting memory protection attributes.
 ///
 /// Corresponds to the C type `EFI_MEMORY_ATTRIBUTE_PROTOCOL`.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[repr(transparent)]
 #[derive(Debug)]
 #[unsafe_protocol(MemoryAttributeProtocol::GUID)]
diff --git a/uefi/src/proto/shell_params.rs b/uefi/src/proto/shell_params.rs
index 2d4d60209..381a5c598 100644
--- a/uefi/src/proto/shell_params.rs
+++ b/uefi/src/proto/shell_params.rs
@@ -9,7 +9,9 @@ use uefi_raw::protocol::shell_params::ShellParametersProtocol;
 
 use crate::CStr16;
 
-/// The ShellParameters protocol.
+/// The ShellParameters [`Protocol`].
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(ShellParametersProtocol::GUID)]
diff --git a/uefi/src/proto/shim/mod.rs b/uefi/src/proto/shim/mod.rs
index fcde92af8..b1e2569a4 100644
--- a/uefi/src/proto/shim/mod.rs
+++ b/uefi/src/proto/shim/mod.rs
@@ -62,7 +62,7 @@ macro_rules! shim_function {
     (fn $args:tt -> $return_type:ty) => (extern "C" fn $args -> $return_type)
 }
 
-/// The Shim lock protocol.
+/// Shim Lock [`Protocol`].
 ///
 /// This protocol is not part of the UEFI specification, but is
 /// installed by the [Shim bootloader](https://github.com/rhboot/shim)
@@ -72,6 +72,8 @@ macro_rules! shim_function {
 /// application may itself be a bootloader that needs to validate
 /// another EFI application before running it, and the shim lock
 /// protocol exists to support that.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(C)]
 #[unsafe_protocol("605dab50-e046-4300-abb6-3dd810dd8b23")]
diff --git a/uefi/src/proto/string/unicode_collation.rs b/uefi/src/proto/string/unicode_collation.rs
index 0836298f6..0fd1318b0 100644
--- a/uefi/src/proto/string/unicode_collation.rs
+++ b/uefi/src/proto/string/unicode_collation.rs
@@ -11,9 +11,11 @@ use core::cmp::Ordering;
 use core::fmt::{self, Display, Formatter};
 use uefi_raw::protocol::string::UnicodeCollationProtocol;
 
-/// The Unicode Collation Protocol.
+/// Unicode Collation [`Protocol`].
 ///
 /// Used to perform case-insensitive comparisons of strings.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(UnicodeCollationProtocol::GUID)]
diff --git a/uefi/src/proto/tcg/v1.rs b/uefi/src/proto/tcg/v1.rs
index 8ab30f939..47d965952 100644
--- a/uefi/src/proto/tcg/v1.rs
+++ b/uefi/src/proto/tcg/v1.rs
@@ -331,9 +331,11 @@ impl<'a> Iterator for EventLogIter<'a> {
     }
 }
 
-/// Protocol for interacting with TPM 1.1 and 1.2 devices.
+/// Trusted Computing Group [`Protocol`] (TCG) for TPM 1.1 and 1.2 devices.
 ///
 /// The corresponding C type is `EFI_TCG_PROTOCOL`.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(TcgProtocol::GUID)]
diff --git a/uefi/src/proto/tcg/v2.rs b/uefi/src/proto/tcg/v2.rs
index d13573d6e..da71ce1aa 100644
--- a/uefi/src/proto/tcg/v2.rs
+++ b/uefi/src/proto/tcg/v2.rs
@@ -556,12 +556,11 @@ impl<'a> Iterator for EventLogIter<'a> {
     }
 }
 
-/// Protocol for interacting with TPM devices.
-///
-/// This protocol can be used for interacting with older TPM 1.1/1.2
-/// devices, but most firmware only uses it for TPM 2.0.
+/// Trusted Computing Group [`Protocol`] (TCG) for TPM 2.0 devices.
 ///
 /// The corresponding C type is `EFI_TCG2_PROTOCOL`.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(Tcg2Protocol::GUID)]

From e2e75778d83f2c65adf137df2537a453ed84ccf1 Mon Sep 17 00:00:00 2001
From: Philipp Schuster <phip1611@gmail.com>
Date: Tue, 8 Apr 2025 09:29:35 +0200
Subject: [PATCH 4/7] uefi: doc: link to Protocol type in more places

---
 uefi/src/boot.rs | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/uefi/src/boot.rs b/uefi/src/boot.rs
index 97f439bf7..3c0920410 100644
--- a/uefi/src/boot.rs
+++ b/uefi/src/boot.rs
@@ -819,9 +819,10 @@ 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 `device_path` is updated to point at the remaining part of it 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.
@@ -925,7 +926,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
 ///
@@ -1004,7 +1005,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.
@@ -1067,7 +1068,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.
@@ -1095,7 +1096,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.
 ///
@@ -1494,7 +1495,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,
@@ -1515,7 +1516,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`

From 00d0c4c08e32fd31ded46e5c924e97a7b13491fb Mon Sep 17 00:00:00 2001
From: Philipp Schuster <phip1611@gmail.com>
Date: Wed, 9 Apr 2025 12:55:37 +0200
Subject: [PATCH 5/7] book: improve chapter "Using Protocols"

---
 book/src/how_to/protocols.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/book/src/how_to/protocols.md b/book/src/how_to/protocols.md
index b20f185a0..7deb21500 100644
--- a/book/src/how_to/protocols.md
+++ b/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-raw] for more technical information.
+
+[uefi-raw]: https://docs.rs/uefi-raw/latest/uefi_raw/protocol/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.

From 5f2fa324f9921660aa15092c4d5789b9c26e4fe0 Mon Sep 17 00:00:00 2001
From: Philipp Schuster <phip1611@gmail.com>
Date: Sat, 19 Apr 2025 12:46:45 +0200
Subject: [PATCH 6/7] doc: changelog update

---
 uefi-raw/CHANGELOG.md | 1 +
 uefi/CHANGELOG.md     | 3 ++-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/uefi-raw/CHANGELOG.md b/uefi-raw/CHANGELOG.md
index 3d0d44b0d..e54e35cdb 100644
--- a/uefi-raw/CHANGELOG.md
+++ b/uefi-raw/CHANGELOG.md
@@ -19,6 +19,7 @@
 ## Changed
 - `DevicePathProtocol` now derives
   `Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash`
+- Improved documentation for device paths and their usages
 
 
 # uefi-raw - 0.10.0 (2025-02-07)
diff --git a/uefi/CHANGELOG.md b/uefi/CHANGELOG.md
index fa9cb6218..4c1943d26 100644
--- a/uefi/CHANGELOG.md
+++ b/uefi/CHANGELOG.md
@@ -41,8 +41,9 @@
 - The `Display` impl for `CStr8` now excludes the trailing null character.
 - `VariableKeys` initializes with a larger name buffer to work around firmware
   bugs on some devices.
-- The UEFI `allocator::Allocator` has been optimized for page-aligned 
+- The UEFI `allocator::Allocator` has been optimized for page-aligned
   allocations.
+- Improved documentation for device paths and their usages
 
 
 # uefi - 0.34.1 (2025-02-07)

From 8b74dc7ff309b9b9b550a35f060bad1418c76dfe Mon Sep 17 00:00:00 2001
From: Philipp Schuster <phip1611@gmail.com>
Date: Mon, 21 Apr 2025 14:21:57 +0200
Subject: [PATCH 7/7] doc: uefi: partially duplicate protocol documentation

The idea is that people should not always read the uefi-raw doc
in any case. Therefore, a briefly simplified version of the uefi-raw
doc is now also in uefi.

See #1641 (comment)
for a discussion.
---
 uefi/src/proto/mod.rs | 30 +++++++++++++++++++++++++++---
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/uefi/src/proto/mod.rs b/uefi/src/proto/mod.rs
index 5d8d2136c..037fffb77 100644
--- a/uefi/src/proto/mod.rs
+++ b/uefi/src/proto/mod.rs
@@ -1,11 +1,35 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-//! High-level wrappers for [UEFI protocols].
+//! High-level wrappers for UEFI protocols.
 //!
-//! See the [`boot`] documentation for details of how to open a protocol.
+//! # 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
+//!
+//! # More Info
+//! - See the [`boot`] documentation for details of how to open a protocol.
+//! - Please find additional low-level information in the
+//!   [protocol section of `uefi-raw`].
 //!
 //! [`boot`]: crate::boot#accessing-protocols
-//! [UEFI protocols]: uefi_raw::protocol
+//! [protocol section of `uefi-raw`]: uefi_raw::protocol
 
 #[cfg(feature = "alloc")]
 pub mod ata;