uefi: Use unsafe_protocol! for all protocol impls

Switch all uses of `unsafe_guid!` + `derive(Protocol)` to using
`unsafe_protocol!`.

Also update the docstrings for the `Identify` and `Protocol` traits.

Author: nicholasbishop

CONTRIBUTING.md

@@ -81,7 +81,7 @@ in the order the UEFI spec requires.
 Each protocol also has a Globally Unique Identifier (in the C API, they're usually
 found in a `EFI_*_PROTOCOL_GUID` define). In Rust, we store the GUID as an associated
 constant, by implementing the unsafe trait `uefi::proto::Identify`. For convenience,
-this is done through the `unsafe_guid` macro.
+this is done through the `unsafe_protocol` macro.
 
 Finally, you should derive the `Protocol` trait. This is a marker trait,
 extending `Identify`, which is used as a generic bound in the functions which retrieve
@@ -92,8 +92,7 @@ An example protocol declaration:
 ```rust
 /// Protocol which does something.
 #[repr(C)]
-#[unsafe_guid("abcdefgh-1234-5678-9012-123456789abc")]
-#[derive(Protocol)]
+#[unsafe_protocol("abcdefgh-1234-5678-9012-123456789abc")]
 pub struct NewProtocol {
   some_entry_point: extern "efiapi" fn(
     this: *const NewProtocol,

uefi-test-runner/src/boot/misc.rs

@@ -1,9 +1,9 @@
 use core::ffi::c_void;
 use core::ptr::{self, NonNull};
 
-use uefi::proto::Protocol;
+use uefi::proto::unsafe_protocol;
 use uefi::table::boot::{BootServices, EventType, SearchType, TimerTrigger, Tpl};
-use uefi::{unsafe_guid, Event, Identify};
+use uefi::{Event, Identify};
 
 pub fn test(bt: &BootServices) {
     info!("Testing timer...");
@@ -80,8 +80,7 @@ fn test_watchdog(bt: &BootServices) {
 }
 
 /// Dummy protocol for tests
-#[unsafe_guid("1a972918-3f69-4b5d-8cb4-cece2309c7f5")]
-#[derive(Protocol)]
+#[unsafe_protocol("1a972918-3f69-4b5d-8cb4-cece2309c7f5")]
 struct TestProtocol {}
 
 unsafe extern "efiapi" fn _test_notify(_event: Event, _context: Option<NonNull<c_void>>) {

uefi/src/data_types/guid.rs

@@ -114,24 +114,20 @@ impl fmt::Display for Guid {
 /// this trait is a building block to interface them in uefi-rs.
 ///
 /// You should never need to use the `Identify` trait directly, but instead go
-/// for more specific traits such as `Protocol` or `FileProtocolInfo`, which
+/// for more specific traits such as [`Protocol`] or [`FileProtocolInfo`], which
 /// indicate in which circumstances an `Identify`-tagged type should be used.
 ///
+/// For the common case of implementing this trait for a protocol, use
+/// the [`unsafe_protocol`] macro.
+///
 /// # Safety
 ///
 /// Implementing `Identify` is unsafe because attaching an incorrect GUID to a
 /// type can lead to type unsafety on both the Rust and UEFI side.
 ///
-/// You can derive `Identify` for a type using the `unsafe_guid` procedural
-/// macro, which is exported by this module. This macro mostly works like a
-/// custom derive, but also supports type aliases. It takes a GUID in canonical
-/// textual format as an argument, and is used in the following way:
-///
-/// ```
-/// use uefi::unsafe_guid;
-/// #[unsafe_guid("12345678-9abc-def0-1234-56789abcdef0")]
-/// struct Emptiness;
-/// ```
+/// [`Protocol`]: crate::proto::Protocol
+/// [`FileProtocolInfo`]: crate::proto::media::file::FileProtocolInfo
+/// [`unsafe_protocol`]: crate::proto::unsafe_protocol
 pub unsafe trait Identify {
     /// Unique protocol identifier.
     const GUID: Guid;

uefi/src/proto/console/gop.rs

@@ -54,8 +54,8 @@
 //! You will have to implement your own double buffering if you want to
 //! avoid tearing with animations.
 
-use crate::proto::Protocol;
-use crate::{unsafe_guid, Result, Status};
+use crate::proto::unsafe_protocol;
+use crate::{Result, Status};
 use core::marker::PhantomData;
 use core::mem;
 use core::ptr;
@@ -65,8 +65,7 @@ use core::ptr;
 /// The GOP can be used to set the properties of the frame buffer,
 /// and also allows the app to access the in-memory buffer.
 #[repr(C)]
-#[unsafe_guid("9042a9de-23dc-4a38-96fb-7aded080516a")]
-#[derive(Protocol)]
+#[unsafe_protocol("9042a9de-23dc-4a38-96fb-7aded080516a")]
 pub struct GraphicsOutput<'boot> {
     query_mode: extern "efiapi" fn(
         &GraphicsOutput,

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

@@ -1,13 +1,12 @@
 //! Pointer device access.
 
-use crate::proto::Protocol;
-use crate::{unsafe_guid, Event, Result, Status};
+use crate::proto::unsafe_protocol;
+use crate::{Event, Result, Status};
 use core::mem::MaybeUninit;
 
 /// Provides information about a pointer device.
 #[repr(C)]
-#[unsafe_guid("31878c87-0b75-11d5-9a4f-0090273fc14d")]
-#[derive(Protocol)]
+#[unsafe_protocol("31878c87-0b75-11d5-9a4f-0090273fc14d")]
 pub struct Pointer<'boot> {
     reset: extern "efiapi" fn(this: &mut Pointer, ext_verif: bool) -> Status,
     get_state: extern "efiapi" fn(this: &Pointer, state: *mut PointerState) -> Status,

uefi/src/proto/console/serial.rs

@@ -2,8 +2,8 @@
 
 use core::fmt::Write;
 
-use crate::proto::Protocol;
-use crate::{unsafe_guid, Result, Status};
+use crate::proto::unsafe_protocol;
+use crate::{Result, Status};
 use bitflags::bitflags;
 
 /// Provides access to a serial I/O device.
@@ -14,8 +14,7 @@ use bitflags::bitflags;
 /// Since UEFI drivers are implemented through polling, if you fail to regularly
 /// check for input/output, some data might be lost.
 #[repr(C)]
-#[unsafe_guid("bb25cf6f-f1d4-11d2-9a0c-0090273fc1fd")]
-#[derive(Protocol)]
+#[unsafe_protocol("bb25cf6f-f1d4-11d2-9a0c-0090273fc1fd")]
 pub struct Serial<'boot> {
     // Revision of this protocol, only 1.0 is currently defined.
     // Future versions will be backwards compatible.

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

@@ -1,11 +1,10 @@
-use crate::proto::Protocol;
-use crate::{unsafe_guid, Char16, Event, Result, Status};
+use crate::proto::unsafe_protocol;
+use crate::{Char16, Event, Result, Status};
 use core::mem::MaybeUninit;
 
 /// Interface for text-based input devices.
 #[repr(C)]
-#[unsafe_guid("387477c1-69c7-11d2-8e39-00a0c969723b")]
-#[derive(Protocol)]
+#[unsafe_protocol("387477c1-69c7-11d2-8e39-00a0c969723b")]
 pub struct Input {
     reset: extern "efiapi" fn(this: &mut Input, extended: bool) -> Status,
     read_key_stroke: extern "efiapi" fn(this: &mut Input, key: *mut RawKey) -> Status,

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

@@ -1,5 +1,5 @@
-use crate::proto::Protocol;
-use crate::{unsafe_guid, CStr16, Char16, Result, ResultExt, Status};
+use crate::proto::unsafe_protocol;
+use crate::{CStr16, Char16, Result, ResultExt, Status};
 use core::fmt;
 use core::fmt::{Debug, Formatter};
 
@@ -21,8 +21,7 @@ use core::fmt::{Debug, Formatter};
 /// [`SystemTable::stderr`]: crate::table::SystemTable::stderr
 /// [`BootServices`]: crate::table::boot::BootServices#accessing-protocols
 #[repr(C)]
-#[unsafe_guid("387477c2-69c7-11d2-8e39-00a0c969723b")]
-#[derive(Protocol)]
+#[unsafe_protocol("387477c2-69c7-11d2-8e39-00a0c969723b")]
 pub struct Output<'boot> {
     reset: extern "efiapi" fn(this: &Output, extended: bool) -> Status,
     output_string: unsafe extern "efiapi" fn(this: &Output, string: *const Char16) -> Status,

uefi/src/proto/debug/mod.rs

@@ -11,8 +11,8 @@
 
 use core::ffi::c_void;
 
-use crate::proto::Protocol;
-use crate::{unsafe_guid, Result, Status};
+use crate::proto::unsafe_protocol;
+use crate::{Result, Status};
 
 // re-export for ease of use
 pub use self::context::SystemContext;
@@ -30,8 +30,7 @@ mod exception;
 ///
 /// NOTE: OVMF only implements this protocol interface for the virtual EBC processor
 #[repr(C)]
-#[unsafe_guid("2755590c-6f3c-42fa-9ea4-a3ba543cda25")]
-#[derive(Protocol)]
+#[unsafe_protocol("2755590c-6f3c-42fa-9ea4-a3ba543cda25")]
 pub struct DebugSupport {
     isa: ProcessorArch,
     get_maximum_processor_index:

uefi/src/proto/device_path/mod.rs

@@ -69,6 +69,7 @@
 //!
 //! [`END_ENTIRE`]: DeviceSubType::END_ENTIRE
 //! [`END_INSTANCE`]: DeviceSubType::END_INSTANCE
+//! [`Protocol`]: crate::proto::Protocol
 //! [`device_type`]: DevicePathNode::device_type
 //! [`sub_type`]: DevicePathNode::sub_type
 
@@ -80,8 +81,7 @@ pub use device_path_gen::{
     acpi, bios_boot_spec, end, hardware, media, messaging, DevicePathNodeEnum,
 };
 
-use crate::proto::{Protocol, ProtocolPointer};
-use crate::unsafe_guid;
+use crate::proto::{unsafe_protocol, ProtocolPointer};
 use core::ffi::c_void;
 use core::marker::{PhantomData, PhantomPinned};
 use core::{mem, ptr};
@@ -225,8 +225,8 @@ impl DevicePathInstance {
 /// [module-level documentation]: crate::proto::device_path
 /// [`END_ENTIRE`]: DeviceSubType::END_ENTIRE
 #[repr(C, packed)]
-#[unsafe_guid("09576e91-6d3f-11d2-8e39-00a0c969723b")]
-#[derive(Debug, Eq, PartialEq, Protocol)]
+#[unsafe_protocol("09576e91-6d3f-11d2-8e39-00a0c969723b")]
+#[derive(Debug, Eq, PartialEq)]
 pub struct DevicePath {
     data: [u8],
 }