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 [`boot`] documentation for details of how to open a protocol.
8 //!
9 //! [`boot`]: crate::boot#accessing-protocols
10 
11 pub mod console;
12 pub mod debug;
13 pub mod device_path;
14 pub mod driver;
15 pub mod loaded_image;
16 pub mod media;
17 pub mod misc;
18 pub mod network;
19 pub mod pi;
20 pub mod rng;
21 pub mod security;
22 pub mod shell_params;
23 pub mod shim;
24 pub mod string;
25 pub mod tcg;
26 
27 mod boot_policy;
28 
29 pub use boot_policy::{BootPolicy, BootPolicyError};
30 pub use uefi_macros::unsafe_protocol;
31 
32 use crate::Identify;
33 use core::ffi::c_void;
34 
35 /// Common trait implemented by all standard UEFI protocols.
36 ///
37 /// You can derive the `Protocol` trait and specify the protocol's GUID using
38 /// the [`unsafe_protocol`] macro.
39 ///
40 /// # Example
41 ///
42 /// ```
43 /// use uefi::{Identify, guid};
44 /// use uefi::proto::unsafe_protocol;
45 ///
46 /// #[unsafe_protocol("12345678-9abc-def0-1234-56789abcdef0")]
47 /// struct ExampleProtocol {}
48 ///
49 /// assert_eq!(ExampleProtocol::GUID, guid!("12345678-9abc-def0-1234-56789abcdef0"));
50 /// ```
51 pub trait Protocol: Identify {}
52 
53 /// Trait for creating a protocol pointer from a [`c_void`] pointer.
54 ///
55 /// There is a blanket implementation for all [`Sized`] protocols that
56 /// simply casts the pointer to the appropriate type. Protocols that
57 /// are not sized must provide a custom implementation.
58 pub trait ProtocolPointer: Protocol {
59     /// Create a const pointer to a [`Protocol`] from a [`c_void`] pointer.
60     ///
61     /// # Safety
62     ///
63     /// The input pointer must point to valid data.
ptr_from_ffi(ptr: *const c_void) -> *const Self64     unsafe fn ptr_from_ffi(ptr: *const c_void) -> *const Self;
65 
66     /// Create a mutable pointer to a [`Protocol`] from a [`c_void`] pointer.
67     ///
68     /// # Safety
69     ///
70     /// The input pointer must point to valid data.
mut_ptr_from_ffi(ptr: *mut c_void) -> *mut Self71     unsafe fn mut_ptr_from_ffi(ptr: *mut c_void) -> *mut Self;
72 }
73 
74 impl<P> ProtocolPointer for P
75 where
76     P: Protocol,
77 {
ptr_from_ffi(ptr: *const c_void) -> *const Self78     unsafe fn ptr_from_ffi(ptr: *const c_void) -> *const Self {
79         ptr.cast::<Self>()
80     }
81 
mut_ptr_from_ffi(ptr: *mut c_void) -> *mut Self82     unsafe fn mut_ptr_from_ffi(ptr: *mut c_void) -> *mut Self {
83         ptr.cast::<Self>()
84     }
85 }
86