uefi 0.39.0

This crate makes it easy to develop Rust software that leverages safe, convenient, and performant abstractions for UEFI functionality.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

// SPDX-License-Identifier: MIT OR Apache-2.0

//! High-level wrappers for [UEFI protocols].
//!
//! # TL;DR
//! Technically, a protocol is a `C` struct holding functions and/or data, with
//! an associated [`GUID`].
//!
//! # About
//! UEFI protocols are a structured collection of functions and/or data,
//! identified by a [`GUID`], which defines an interface between components in
//! the UEFI environment, such as between drivers, applications, or firmware
//! services.
//!
//! Protocols are central to UEFI’s handle-based object model, and they provide
//! a clean, extensible way for components to discover and use services from one
//! another.
//!
//! Implementation-wise, a protocol is a `C` struct holding function pointers
//! and/or data. Please note that some protocols may use [`core::ptr::null`] as
//! interface. For example, the device path protocol can be implemented but
//! return `null`.
//!
//! [`GUID`]: crate::Guid
//!
//! # More Info
//! - See the [`boot`] documentation for details of how to open a protocol.
//! - Please find additional low-level information in the
//!   [protocol section of `uefi-raw`][[UEFI protocols]].
//!
//! [`boot`]: crate::boot#accessing-protocols
//! [UEFI protocols]: uefi_raw::protocol

pub mod acpi;
#[cfg(feature = "alloc")]
pub mod ata;
pub mod console;
pub mod debug;
pub mod device_path;
pub mod dma;
pub mod driver;
pub mod hii;
pub mod loaded_image;
pub mod media;
pub mod misc;
pub mod network;
#[cfg(feature = "alloc")]
pub mod nvme;
pub mod pci;
pub mod pi;
pub mod rng;
#[cfg(feature = "alloc")]
pub mod scsi;
pub mod security;
pub mod shell;
pub mod shell_params;
pub mod shim;
pub mod string;
pub mod tcg;
pub mod usb;

mod boot_policy;

pub use boot_policy::BootPolicy;
pub use uefi_macros::unsafe_protocol;

use crate::Identify;
use core::ffi::c_void;

#[cfg(doc)]
use crate::boot;

/// Marker trait for structures that represent [UEFI protocols].
///
/// Implementing this trait allows a protocol to be opened with
/// [`boot::open_protocol`] or [`boot::open_protocol_exclusive`]. Note that
/// implementing this trait does not automatically install a protocol. To
/// install a protocol, call [`boot::install_protocol_interface`].
///
/// As a convenience, you can derive the `Protocol` trait and specify the
/// protocol's GUID using the [`unsafe_protocol`] macro.
///
/// # Example
///
/// ```
/// use uefi::{Identify, guid};
/// use uefi::proto::unsafe_protocol;
///
/// #[unsafe_protocol("12345678-9abc-def0-1234-56789abcdef0")]
/// struct ExampleProtocol {}
///
/// assert_eq!(ExampleProtocol::GUID, guid!("12345678-9abc-def0-1234-56789abcdef0"));
/// ```
///
/// [UEFI protocols]: uefi_raw::protocol
pub trait Protocol: Identify {}

/// Trait for creating a [`Protocol`] pointer from a [`c_void`] pointer.
///
/// There is a blanket implementation for all [`Sized`] protocols that
/// simply casts the pointer to the appropriate type. Protocols that
/// are not sized must provide a custom implementation.
pub trait ProtocolPointer: Protocol {
    /// Create a const pointer to a [`Protocol`] from a [`c_void`] pointer.
    ///
    /// # Safety
    ///
    /// The input pointer must point to valid data.
    unsafe fn ptr_from_ffi(ptr: *const c_void) -> *const Self;

    /// Create a mutable pointer to a [`Protocol`] from a [`c_void`] pointer.
    ///
    /// # Safety
    ///
    /// The input pointer must point to valid data.
    unsafe fn mut_ptr_from_ffi(ptr: *mut c_void) -> *mut Self;
}

impl<P> ProtocolPointer for P
where
    P: Protocol,
{
    unsafe fn ptr_from_ffi(ptr: *const c_void) -> *const Self {
        ptr.cast::<Self>()
    }

    unsafe fn mut_ptr_from_ffi(ptr: *mut c_void) -> *mut Self {
        ptr.cast::<Self>()
    }
}