Merge pull request #1877 from rust-osdev/improve-handles-doc

uefi: boot: improve documentation for handles

Author: nicholasbishop

uefi/src/boot.rs

@@ -4,13 +4,14 @@
 //!
 //! These functions will panic if called after exiting boot services.
 //!
-//! # Accessing protocols
+//! # Accessing Protocols
 //!
-//! Protocols can be opened using several functions in this module. 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.
+//! Protocols in this module can be opened through multiple functions. In most
+//! cases, [`open_protocol_exclusive`] is the recommended choice. It opens the
+//! protocol with exclusive access, preventing concurrent use until it is
+//! closed, and returns a [`ScopedProtocol`] that automatically releases the
+//! protocol when dropped. Note that this approach has certain caveats; refer to
+//! the documentation of the respective function for details.
 //!
 //! Other methods for opening protocols:
 //!
@@ -19,6 +20,11 @@
 //!
 //! For protocol definitions, see the [`proto`] module.
 //!
+//! # Accessing Handles
+//!
+//! To access handles supporting a certain protocol, we recommend using
+//! [`find_handles`], [`locate_handle`], and [`locate_handle_buffer`].
+//!
 //! [`proto`]: crate::proto
 
 pub use uefi_raw::table::boot::{
@@ -893,7 +899,12 @@ pub fn locate_device_path<P: ProtocolPointer + ?Sized>(
     }
 }
 
-/// Enumerates all handles installed on the system which match a certain query.
+/// Enumerates all [`Handle`]s installed on the system which match a certain
+/// query.
+///
+/// If you use the `alloc` feature, it might be more convenient to use
+/// [`find_handles`] instead. Another alternative might be
+/// [`locate_handle_buffer`].
 ///
 /// # Errors
 ///
@@ -939,6 +950,10 @@ pub fn locate_handle<'buf>(
 ///
 /// See [`SearchType`] for details of the available search operations.
 ///
+/// Unlike [`find_handles`], this doesn't need the `alloc` feature and operates
+/// on the UEFI heap directly. Further, it allows a more fine-grained search
+/// via the provided [`SearchType`].
+///
 /// # Errors
 ///
 /// * [`Status::NOT_FOUND`]: no matching handles.
@@ -1112,6 +1127,11 @@ pub unsafe fn open_protocol<P: ProtocolPointer + ?Sized>(
 /// If successful, a [`ScopedProtocol`] is returned that will automatically
 /// close the protocol interface when dropped.
 ///
+/// Note that if any other drivers currently have the protocol interface opened
+/// with the [`OpenProtocolAttributes::ByDriver`] attribute, they will be
+/// disconnected via [`disconnect_controller`]. For example, opening the
+/// SERIAL_IO_PROTOCOL exclusively will disconnect the console driver from it.
+///
 /// # Errors
 ///
 /// * [`Status::UNSUPPORTED`]: the handle does not support the protocol.
@@ -1548,8 +1568,8 @@ impl Deref for ProtocolsPerHandle {
     }
 }
 
-/// A buffer returned by [`locate_handle_buffer`] that contains an array of
-/// [`Handle`]s that support the requested [`Protocol`].
+/// A buffer on the UEFI heap returned by [`locate_handle_buffer`] that contains
+/// an array of [`Handle`]s that support the requested [`Protocol`].
 #[derive(Debug, Eq, PartialEq)]
 pub struct HandleBuffer {
     count: usize,