Skip to content

Commit 87e740d

Browse files
phip1611phip1611
committed
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.
1 parent 930719b commit 87e740d

28 files changed

+131
-36
lines changed

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

+6-3
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

+5-1
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

+3-1
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

+3-1
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)]

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

+2-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ use crate::{CStr16, Result, ResultExt, Status, StatusExt};
55
use core::fmt;
66
use uefi_raw::protocol::console::{SimpleTextOutputMode, SimpleTextOutputProtocol};
77

8-
/// Interface for text-based output devices.
8+
/// Simple Text Output [`Protocol`]. Interface for text-based output devices.
99
///
1010
/// It implements the fmt::Write trait, so you can use it to print text with
1111
/// standard Rust constructs like the `write!()` and `writeln!()` macros.
@@ -22,6 +22,7 @@ use uefi_raw::protocol::console::{SimpleTextOutputMode, SimpleTextOutputProtocol
2222
/// [`system::stdout`]: crate::system::with_stdout
2323
/// [`system::stderr`]: crate::system::with_stderr
2424
/// [`boot`]: crate::boot#accessing-protocols
25+
/// [`Protocol`]: uefi::proto::Protocol
2526
#[derive(Debug)]
2627
#[repr(transparent)]
2728
#[unsafe_protocol(SimpleTextOutputProtocol::GUID)]

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

+8
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ pub use exception::ExceptionType;
2323
mod context;
2424
mod exception;
2525

26+
/// Debug support [`Protocol`].
27+
///
2628
/// The debugging support protocol allows debuggers to connect to a UEFI machine.
2729
/// It is expected that there will typically be two instances of the EFI Debug Support protocol in the system.
2830
/// One associated with the native processor instruction set (IA-32, x64, ARM, RISC-V, or Itanium processor
@@ -31,6 +33,8 @@ mod exception;
3133
/// one for any given instruction set.
3234
///
3335
/// NOTE: OVMF only implements this protocol interface for the virtual EBC processor
36+
///
37+
/// [`Protocol`]: uefi::proto::Protocol
3438
#[derive(Debug)]
3539
#[repr(C)]
3640
#[unsafe_protocol("2755590c-6f3c-42fa-9ea4-a3ba543cda25")]
@@ -178,8 +182,12 @@ pub enum ProcessorArch: u32 => {
178182
RISCV_128 = 0x5128,
179183
}}
180184

185+
/// Debug Port [`Protocol`].
186+
///
181187
/// The debug port protocol abstracts the underlying debug port
182188
/// hardware, whether it is a regular Serial port or something else.
189+
///
190+
/// [`Protocol`]: uefi::proto::Protocol
183191
#[derive(Debug)]
184192
#[repr(C)]
185193
#[unsafe_protocol("eba4e8d2-3858-41ec-a281-2647ba9660d0")]

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

+7-4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
// SPDX-License-Identifier: MIT OR Apache-2.0
22

3-
//! Device Path protocol
3+
//! Helpers to work with UEFI Device Paths and the Device Path Protocol.
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+
//! The main export of this module is [`DevicePath`].
76
//!
87
//! A device path is made up of a packed list of variable-length nodes of
98
//! various types. The entire device path is terminated with an
@@ -400,7 +399,7 @@ impl ToOwned for DevicePathInstance {
400399
}
401400
}
402401

403-
/// Device path protocol.
402+
/// Device Path [`Protocol`].
404403
///
405404
/// Can be used on any device handle to obtain generic path/location information
406405
/// concerning the physical device or logical device. If the handle does not
@@ -413,6 +412,7 @@ impl ToOwned for DevicePathInstance {
413412
///
414413
/// [module-level documentation]: crate::proto::device_path
415414
/// [`END_ENTIRE`]: DeviceSubType::END_ENTIRE
415+
/// [`Protocol`]: uefi::proto::Protocol
416416
#[repr(C, packed)]
417417
#[unsafe_protocol(uefi_raw::protocol::device_path::DevicePathProtocol::GUID)]
418418
#[derive(Eq, Pointee)]
@@ -729,12 +729,15 @@ pub enum NodeConversionError {
729729
UnsupportedType,
730730
}
731731

732+
/// Loaded Image Device Path [`Protocol`].
733+
///
732734
/// Protocol for accessing the device path that was passed in to [`load_image`]
733735
/// when loading a PE/COFF image.
734736
///
735737
/// The layout of this type is the same as a [`DevicePath`].
736738
///
737739
/// [`load_image`]: crate::boot::load_image
740+
/// [`Protocol`]: uefi::proto::Protocol
738741
#[repr(transparent)]
739742
#[unsafe_protocol("bc62157e-3e33-4fec-9920-2d3b36d750df")]
740743
#[derive(Debug, Pointee)]

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

+8
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,11 @@ pub struct DisplayOnly(pub bool);
4747
#[derive(Clone, Copy, Debug)]
4848
pub struct AllowShortcuts(pub bool);
4949

50+
/// Device Path to Text [`Protocol`].
51+
///
5052
/// Protocol for converting a [`DevicePath`] or `DevicePathNode`] to a string.
53+
///
54+
/// [`Protocol`]: uefi::proto::Protocol
5155
#[derive(Debug)]
5256
#[repr(transparent)]
5357
#[unsafe_protocol(DevicePathToTextProtocol::GUID)]
@@ -99,7 +103,11 @@ impl DevicePathToText {
99103
}
100104
}
101105

106+
/// Device Path from Text [`Protocol`].
107+
///
102108
/// Protocol for converting a string to a [`DevicePath`] or `DevicePathNode`].
109+
///
110+
/// [`Protocol`]: uefi::proto::Protocol
103111
#[derive(Debug)]
104112
#[repr(transparent)]
105113
#[unsafe_protocol("05c99a21-c70f-4ad2-8a5f-35df3343f51e")]

‎uefi/src/proto/driver/component_name.rs

+6
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ use core::fmt::{self, Debug, Display, Formatter};
1313
use core::{ptr, slice};
1414
use uefi_raw::protocol::driver::ComponentName2Protocol;
1515

16+
/// Component Name1 [`Protocol`].
17+
///
1618
/// Protocol that provides human-readable names for a driver and for each of the
1719
/// controllers that the driver is managing.
1820
///
@@ -27,6 +29,7 @@ use uefi_raw::protocol::driver::ComponentName2Protocol;
2729
///
2830
/// [ISO 639-2]: https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes
2931
/// [RFC 4646]: https://www.rfc-editor.org/rfc/rfc4646
32+
/// [`Protocol`]: uefi::proto::Protocol
3033
#[deprecated = "deprecated in UEFI 2.1; use ComponentName2 where possible"]
3134
#[unsafe_protocol(ComponentName2Protocol::DEPRECATED_COMPONENT_NAME_GUID)]
3235
#[derive(Debug)]
@@ -85,6 +88,8 @@ impl ComponentName1 {
8588
}
8689
}
8790

91+
/// Component Name2 [`Protocol`].
92+
///
8893
/// Protocol that provides human-readable names for a driver and for each of the
8994
/// controllers that the driver is managing.
9095
///
@@ -99,6 +104,7 @@ impl ComponentName1 {
99104
///
100105
/// [ISO 639-2]: https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes
101106
/// [RFC 4646]: https://www.rfc-editor.org/rfc/rfc4646
107+
/// [`Protocol`]: uefi::proto::Protocol
102108
#[unsafe_protocol(ComponentName2Protocol::GUID)]
103109
#[derive(Debug)]
104110
#[repr(transparent)]

‎uefi/src/proto/loaded_image.rs

+7-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,13 @@ use core::ffi::c_void;
1212
use core::{mem, slice};
1313
use uefi_raw::protocol::loaded_image::LoadedImageProtocol;
1414

15-
/// The LoadedImage protocol. This can be opened on any image handle using the `HandleProtocol` boot service.
15+
/// The Loaded Image [`Protocol`].
16+
///
17+
/// This can be opened on any image handle using [`boot::open_protocol`],
18+
/// for example.
19+
///
20+
/// [`Protocol`]: uefi::proto::Protocol
21+
/// [`boot::open_protocol`]: uefi::boot::open_protocol
1622
#[derive(Debug)]
1723
#[repr(transparent)]
1824
#[unsafe_protocol(LoadedImageProtocol::GUID)]

‎uefi/src/proto/media/block.rs

+3-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,9 @@ use crate::{Result, StatusExt};
77

88
pub use uefi_raw::protocol::block::{BlockIoProtocol, Lba};
99

10-
/// The Block I/O protocol.
10+
/// Block I/O [`Protocol`].
11+
///
12+
/// [`Protocol`]: uefi::proto::Protocol
1113
#[derive(Debug)]
1214
#[repr(transparent)]
1315
#[unsafe_protocol(BlockIoProtocol::GUID)]

‎uefi/src/proto/media/disk.rs

+7-3
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,21 @@
11
// SPDX-License-Identifier: MIT OR Apache-2.0
22

3-
//! Disk I/O protocols.
3+
//! Disk I/O protocols [`DiskIo`] and [`DiskIo2`].
44
55
use crate::proto::unsafe_protocol;
66
use crate::util::opt_nonnull_to_ptr;
77
use crate::{Event, Result, Status, StatusExt};
88
use core::ptr::NonNull;
99
use uefi_raw::protocol::disk::{DiskIo2Protocol, DiskIoProtocol};
1010

11-
/// The disk I/O protocol.
11+
/// Disk I/O [`Protocol`].
1212
///
1313
/// This protocol is used to abstract the block accesses of the block I/O
1414
/// protocol to a more general offset-length protocol. Firmware is
1515
/// responsible for adding this protocol to any block I/O interface that
1616
/// appears in the system that does not already have a disk I/O protocol.
17+
///
18+
/// [`Protocol`]: uefi::proto::Protocol
1719
#[derive(Debug)]
1820
#[repr(transparent)]
1921
#[unsafe_protocol(DiskIoProtocol::GUID)]
@@ -82,10 +84,12 @@ pub struct DiskIo2Token {
8284
pub transaction_status: Status,
8385
}
8486

85-
/// The disk I/O 2 protocol.
87+
/// Disk I/O 2 [`Protocol`].
8688
///
8789
/// This protocol provides an extension to the disk I/O protocol to enable
8890
/// non-blocking / asynchronous byte-oriented disk operation.
91+
///
92+
/// [`Protocol`]: uefi::proto::Protocol
8993
#[derive(Debug)]
9094
#[repr(transparent)]
9195
#[unsafe_protocol(DiskIo2Protocol::GUID)]

‎uefi/src/proto/media/disk_info.rs

+3-1
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ pub struct DeviceLocationInfo {
5252
pub device: u32,
5353
}
5454

55-
/// DiskInfo protocol.
55+
/// Disk Info [`Protocol`].
5656
///
5757
/// This allows querying hardware information for detected disks in a simple way.
5858
/// Originally, this was designed for IDE and it shows.
@@ -64,6 +64,8 @@ pub struct DeviceLocationInfo {
6464
///
6565
/// # UEFI Spec Description
6666
/// Provides the basic interfaces to abstract platform information regarding an IDE controller.
67+
///
68+
/// [`Protocol`]: uefi::proto::Protocol
6769
#[derive(Debug)]
6870
#[repr(transparent)]
6971
#[unsafe_protocol(DiskInfoProtocol::GUID)]

‎uefi/src/proto/media/fs.rs

+3-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@ use crate::{Result, StatusExt};
88
use core::ptr;
99
use uefi_raw::protocol::file_system::SimpleFileSystemProtocol;
1010

11-
/// Allows access to a FAT-12/16/32 file system.
11+
/// Simple File System [`Protocol`]. Allows access to a FAT-12/16/32 file
12+
/// system.
1213
///
1314
/// This interface is implemented by some storage devices
1415
/// to allow file access to the contained file systems.
@@ -22,6 +23,7 @@ use uefi_raw::protocol::file_system::SimpleFileSystemProtocol;
2223
///
2324
/// [`boot::get_image_file_system`]: crate::boot::get_image_file_system
2425
/// [`boot`]: crate::boot#accessing-protocols
26+
/// [`Protocol`]: uefi::proto::Protocol
2527
#[derive(Debug)]
2628
#[repr(transparent)]
2729
#[unsafe_protocol(SimpleFileSystemProtocol::GUID)]

‎uefi/src/proto/media/load_file.rs

+6-2
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ use {
1616
uefi_raw::Boolean,
1717
};
1818

19-
/// Load File Protocol.
19+
/// Load File [`Protocol`].
2020
///
2121
/// Used to obtain files, that are primarily boot options, from arbitrary
2222
/// devices.
@@ -33,6 +33,8 @@ use {
3333
/// EFI_LOAD_FILE_PROTOCOL and the LoadFile() function. In this case the
3434
/// LoadFile() function implements the policy of interpreting the File Path
3535
/// value.
36+
///
37+
/// [`Protocol`]: uefi::proto::Protocol
3638
#[derive(Debug)]
3739
#[repr(transparent)]
3840
#[unsafe_protocol(LoadFileProtocol::GUID)]
@@ -98,7 +100,7 @@ impl LoadFile {
98100
}
99101
}
100102

101-
/// Load File2 Protocol.
103+
/// Load File2 [`Protocol`].
102104
///
103105
/// The Load File2 protocol is used to obtain files from arbitrary devices that
104106
/// are not boot options.
@@ -109,6 +111,8 @@ impl LoadFile {
109111
/// arbitrary devices that are not boot options. It is used by LoadImage() when
110112
/// its BootOption parameter is FALSE and the FilePath does not have an instance
111113
/// of the EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.
114+
///
115+
/// [`Protocol`]: uefi::proto::Protocol
112116
#[derive(Debug)]
113117
#[repr(transparent)]
114118
#[unsafe_protocol(LoadFile2Protocol::GUID)]

‎uefi/src/proto/media/partition.rs

+4
Original file line numberDiff line numberDiff line change
@@ -221,7 +221,11 @@ newtype_enum! {
221221
}
222222
}
223223

224+
/// Partition Info [`Protocol`].
225+
///
224226
/// Protocol for accessing partition information.
227+
///
228+
/// [`Protocol`]: uefi::proto::Protocol
225229
#[allow(missing_debug_implementations)]
226230
#[repr(C)]
227231
#[repr(packed)]

‎uefi/src/proto/misc.rs

+14-3
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,17 @@ use uefi_raw::protocol::misc::{
99
use crate::proto::unsafe_protocol;
1010
use crate::{Result, StatusExt};
1111

12+
/// Timestamp [`Protocol`].
13+
///
1214
/// Protocol for retrieving a high-resolution timestamp counter.
13-
/// **Note:**
14-
/// If your UEFI firmware not support timestamp protocol which first added at UEFI spec 2.4 2013.
15-
/// 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.
15+
///
16+
/// # Note
17+
/// If your UEFI firmware not support timestamp protocol which first added at
18+
/// UEFI spec 2.4 2013. you also could use `RDTSC` in rust, here is a demo
19+
/// [Slint-UI](https://github.com/slint-ui/slint/blob/2c0ba2bc0f151eba8d1fa17839fa2ac58832ca80/examples/uefi-demo/main.rs#L28-L62)
20+
/// who use uefi-rs.
21+
///
22+
/// [`Protocol`]: uefi::proto::Protocol
1623
#[derive(Debug)]
1724
#[repr(transparent)]
1825
#[unsafe_protocol(TimestampProtocol::GUID)]
@@ -32,7 +39,11 @@ impl Timestamp {
3239
}
3340
}
3441

42+
/// Reset Notification [`Protocol`].
43+
///
3544
/// Protocol to register for a notification when ResetSystem is called.
45+
///
46+
/// [`Protocol`]: uefi::proto::Protocol
3647
#[derive(Debug)]
3748
#[repr(transparent)]
3849
#[unsafe_protocol(ResetNotificationProtocol::GUID)]

0 commit comments

Comments
 (0)