1//! Protocol definitions.
2//!
3//! Protocols are sets of related functionality identified by a unique
4//! ID. They can be implemented by a UEFI driver or occasionally by a
5//! UEFI application.
6//!
7//! See the [`BootServices`] documentation for details of how to open a
8//! protocol.
9//!
10//! [`BootServices`]: crate::table::boot::BootServices#accessing-protocols
11
12use crate::Identify;
13use core::ffi::c_void;
14
15/// Common trait implemented by all standard UEFI protocols.
16///
17/// According to the UEFI's specification, protocols are `!Send` (they expect to
18/// be run on the bootstrap processor) and `!Sync` (they are not thread-safe).
19/// You can derive the `Protocol` trait, add these bounds, and specify the
20/// protocol's GUID using the [`unsafe_protocol`] macro.
21///
22/// # Example
23///
24/// ```
25/// use uefi::{Identify, guid};
26/// use uefi::proto::unsafe_protocol;
27///
28/// #[unsafe_protocol("12345678-9abc-def0-1234-56789abcdef0")]
29/// struct ExampleProtocol {}
30///
31/// assert_eq!(ExampleProtocol::GUID, guid!("12345678-9abc-def0-1234-56789abcdef0"));
32/// ```
33pub trait Protocol: Identify {}
34
35/// Trait for creating a protocol pointer from a [`c_void`] pointer.
36///
37/// There is a blanket implementation for all [`Sized`] protocols that
38/// simply casts the pointer to the appropriate type. Protocols that
39/// are not sized must provide a custom implementation.
40pub trait ProtocolPointer: Protocol {
41 /// Create a const pointer to a [`Protocol`] from a [`c_void`] pointer.
42 ///
43 /// # Safety
44 ///
45 /// The input pointer must point to valid data.
46 unsafe fn ptr_from_ffi(ptr: *const c_void) -> *const Self;
47
48 /// Create a mutable pointer to a [`Protocol`] from a [`c_void`] pointer.
49 ///
50 /// # Safety
51 ///
52 /// The input pointer must point to valid data.
53 unsafe fn mut_ptr_from_ffi(ptr: *mut c_void) -> *mut Self;
54}
55
56impl<P> ProtocolPointer for P
57where
58 P: Protocol,
59{
60 unsafe fn ptr_from_ffi(ptr: *const c_void) -> *const Self {
61 ptr.cast::<Self>()
62 }
63
64 unsafe fn mut_ptr_from_ffi(ptr: *mut c_void) -> *mut Self {
65 ptr.cast::<Self>()
66 }
67}
68
69pub use uefi_macros::unsafe_protocol;
70
71pub mod console;
72pub mod debug;
73pub mod device_path;
74pub mod driver;
75pub mod loaded_image;
76pub mod media;
77pub mod network;
78pub mod pi;
79pub mod rng;
80pub mod security;
81pub mod shim;
82pub mod string;
83pub mod tcg;
84