uefi: Copy 'Accessing Protocols' docs to uefi::boot

The new section is copied from the BootServices docstring. Also update various places that link to that doc.
rust-osdev · Aug 26, 2024 · 31492e0 · 31492e0
1 parent 5d52fd8
commit 31492e0
Show file tree

Hide file tree

Showing 5 changed files with 26 additions and 10 deletions.
diff --git a/uefi/src/boot.rs b/uefi/src/boot.rs
@@ -1,6 +1,23 @@
 //! UEFI boot services.
 //!
 //! These functions will panic if called after exiting boot services.
+//!
+//! # Accessing protocols
+//!
+//! Protocols can be opened using several methods of `BootServices`. Most
+//! commonly, [`open_protocol_exclusive`] should be used. This ensures that
+//! nothing else can use the protocol until it is closed, and returns a
+//! [`ScopedProtocol`] that takes care of closing the protocol when it is
+//! dropped.
+//!
+//! Other methods for opening protocols:
+//!
+//! * [`open_protocol`]
+//! * [`get_image_file_system`]
+//!
+//! For protocol definitions, see the [`proto`] module.
+//!
+//! [`proto`]: crate::proto
 
 pub use uefi_raw::table::boot::{EventType, MemoryAttribute, MemoryDescriptor, MemoryType, Tpl};
 

diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs
@@ -116,7 +116,7 @@
 //! application depends on the device. For example, a PC with no network card
 //! may not provide network protocols.
 //!
-//! See the [`BootServices`] documentation for details of how to open a
+//! See the [`boot`] documentation for details of how to open a
 //! protocol, and see the [`proto`] module for protocol implementations. New
 //! protocols can be defined with the [`unsafe_protocol`] macro.
 //!

diff --git a/uefi/src/proto/console/text/output.rs b/uefi/src/proto/console/text/output.rs
@@ -14,12 +14,12 @@ use uefi_raw::protocol::console::{SimpleTextOutputMode, SimpleTextOutputProtocol
 /// using [`SystemTable::stdout`] and [`SystemTable::stderr`], respectively.
 ///
 /// An `Output` protocol can also be accessed like any other UEFI protocol.
-/// See the [`BootServices`] documentation for more details of how to open a
+/// See the [`boot`] documentation for more details of how to open a
 /// protocol.
 ///
 /// [`SystemTable::stdout`]: crate::table::SystemTable::stdout
 /// [`SystemTable::stderr`]: crate::table::SystemTable::stderr
-/// [`BootServices`]: crate::table::boot::BootServices#accessing-protocols
+/// [`boot`]: crate::boot#accessing-protocols
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(SimpleTextOutputProtocol::GUID)]

diff --git a/uefi/src/proto/media/fs.rs b/uefi/src/proto/media/fs.rs
@@ -13,13 +13,13 @@ use uefi_raw::protocol::file_system::SimpleFileSystemProtocol;
 ///
 /// # Accessing `SimpleFileSystem` protocol
 ///
-/// Use [`BootServices::get_image_file_system`] to retrieve the `SimpleFileSystem`
+/// Use [`boot::get_image_file_system`] to retrieve the `SimpleFileSystem`
 /// protocol associated with a given image handle.
 ///
-/// See the [`BootServices`] documentation for more details of how to open a protocol.
+/// See the [`boot`] documentation for more details of how to open a protocol.
 ///
-/// [`BootServices::get_image_file_system`]: crate::table::boot::BootServices::get_image_file_system
-/// [`BootServices`]: crate::table::boot::BootServices#accessing-protocols
+/// [`boot::get_image_file_system`]: crate::boot::get_image_file_system
+/// [`boot`]: crate::boot#accessing-protocols
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(SimpleFileSystemProtocol::GUID)]

diff --git a/uefi/src/proto/mod.rs b/uefi/src/proto/mod.rs
@@ -4,10 +4,9 @@
 //! ID. They can be implemented by a UEFI driver or occasionally by a
 //! UEFI application.
 //!
-//! See the [`BootServices`] documentation for details of how to open a
-//! protocol.
+//! See the [`boot`] documentation for details of how to open a protocol.
 //!
-//! [`BootServices`]: crate::table::boot::BootServices#accessing-protocols
+//! [`boot`]: crate::boot#accessing-protocols
 
 pub mod console;
 pub mod debug;