patina 21.1.1

Common types and functionality used in UEFI development.
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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

//! Firmware Volume (FV) Protocol
//!
//! The Firmware Volume Protocol provides file-level access to the firmware volume. Each firmware volume driver must
//! produce an instance of the Firmware Volume Protocol if the firmware volume is to be visible to the system during
//! the DXE phase. The Firmware Volume Protocol also provides mechanisms for determining and modifying some attributes
//! of the firmware volume.
//!
//! See <https://uefi.org/specs/PI/1.8A/V3_Code_Definitions.html#efi-firmware-volume2-protocol>.
//!
//! ## License
//!
//! Copyright (c) Microsoft Corporation.
//!
//! SPDX-License-Identifier: Apache-2.0
//!

use crate::pi::fw_fs;

use fw_fs::{
    ffs::section::EfiSectionType,
    fv::{EfiFvFileType, attributes::EfiFvAttributes, file::EfiFvFileAttributes},
};

use core::ffi::c_void;
use r_efi::efi::{Guid, Handle, Status};

/// GUID for the Firmware Volume (FV) Protocol.
///
/// This protocol provides file-level access to firmware volumes. It abstracts
/// the complexity of the firmware volume format to provide simple file-based
/// read and write operations.
pub const PROTOCOL_GUID: crate::BinaryGuid = crate::BinaryGuid::from_string("220E73B6-6BDB-4413-8405-B974B108619A");

/// Enumeration of write policies for firmware volume operations.
pub type EfiFvWritePolicy = u32;

#[repr(C)]
/// Data structure for writing files to firmware volumes.
///
/// Contains the metadata and content information needed to write a file
/// to a firmware volume, including GUID, type, attributes, and data buffer.
pub struct EfiFvWriteFileData {
    name_guid: *mut Guid,
    file_type: EfiFvFileType,
    file_attributes: EfiFvFileAttributes,
    buffer: *mut c_void,
    buffer_size: u32,
}

/// Retrieves the current attributes and current settings of the firmware volume.
///
/// Gets the current attributes and status of the firmware volume. These attributes
/// control volume behavior and indicate current operational capabilities.
pub type GetVolumeAttributes = extern "efiapi" fn(*const Protocol, *mut EfiFvAttributes) -> Status;

/// Modifies the current settings of the firmware volume.
///
/// Sets the firmware volume attributes according to the input parameter, then
/// returns the new settings. Some attributes may not be modifiable after creation.
pub type SetVolumeAttributes = extern "efiapi" fn(*const Protocol, *mut EfiFvAttributes) -> Status;

/// Reads an entire file from the firmware volume.
///
/// Locates a file within a firmware volume and reads the entire file into a buffer.
/// The caller specifies the file to read by its GUID name.
pub type ReadFile = extern "efiapi" fn(
    *const Protocol,
    *const Guid,
    *mut *mut c_void,
    *mut usize,
    *mut EfiFvFileType,
    *mut EfiFvFileAttributes,
    *mut u32,
) -> Status;

/// Reads a specific section from a file within the firmware volume.
///
/// Locates a file by GUID and extracts a specific section by type and instance.
/// This allows selective reading of particular components within a file.
pub type ReadSection = extern "efiapi" fn(
    *const Protocol,
    *const Guid,
    EfiSectionType,
    usize,
    *mut *mut c_void,
    *mut usize,
    *mut u32,
) -> Status;

/// Writes a file to the firmware volume.
///
/// Writes data to the firmware volume according to the specified write policy.
/// The write policy determines how the operation handles existing files.
pub type WriteFile = extern "efiapi" fn(*const Protocol, u32, EfiFvWritePolicy, *mut EfiFvWriteFileData) -> Status;

/// Enumerates files in the firmware volume.
///
/// Retrieves the next file in the firmware volume. Repeated calls enumerate all
/// files within the volume, providing file metadata for each entry.
pub type GetNextFile = extern "efiapi" fn(
    *const Protocol,
    *mut c_void,
    *mut EfiFvFileType,
    *mut Guid,
    *mut EfiFvFileAttributes,
    *mut usize,
) -> Status;

/// Retrieves volume-specific information.
///
/// Returns information about the firmware volume. The information type is specified
/// by the InformationType GUID parameter.
pub type GetInfo = extern "efiapi" fn(*const Protocol, *const Guid, *mut usize, *mut c_void) -> Status;

/// Modifies volume-specific information.
///
/// Sets information about the firmware volume. The information type is specified
/// by the InformationType GUID parameter.
pub type SetInfo = extern "efiapi" fn(*const Protocol, *const Guid, usize, *const c_void) -> Status;

/// The Firmware Volume Protocol provides file-level access to the firmware volume. Each firmware volume driver must
/// produce an instance of the Firmware Volume Protocol if the firmware volume is to be visible to the system during
/// the DXE phase. The Firmware Volume Protocol also provides mechanisms for determining and modifying some attributes
/// of the firmware volume.
///
/// # Documentation
/// UEFI Platform Initialization Specification, Release 1.8, Section III-3.4.1.1
#[repr(C)]
pub struct Protocol {
    /// Gets the current attributes of the firmware volume.
    pub get_volume_attributes: GetVolumeAttributes,
    /// Sets the attributes of the firmware volume.
    pub set_volume_attributes: SetVolumeAttributes,
    /// Reads a file from the firmware volume.
    pub read_file: ReadFile,
    /// Reads a section from a file in the firmware volume.
    pub read_section: ReadSection,
    /// Writes a file to the firmware volume.
    pub write_file: WriteFile,
    /// Finds the next file in the firmware volume.
    pub get_next_file: GetNextFile,
    /// Size of the search key for get_next_file.
    pub key_size: u32,
    /// Handle of the parent firmware volume.
    pub parent_handle: Handle,
    /// Gets information about the firmware volume.
    pub get_info: GetInfo,
    /// Sets information about the firmware volume.
    pub set_info: SetInfo,
}

// SAFETY: The only non-send type in this structure is `Handle` which itself is actually `Send` as it is an opaque
// pointer used purely as a token for identification purposes.
unsafe impl Send for Protocol {}
// SAFETY: The only non-sync type in this structure is `Handle` which itself is actually `Send` as it is an opaque
// pointer used purely as a token for identification purposes.
unsafe impl Sync for Protocol {}