Skip to content

Commit fc640ce

Browse files
phip1611phip1611
committed
uefi-raw: add opaque Boolean type
This way we can be ABI-compatible and guarantee lack of UB, while being more precise in interfaces.
1 parent 96b27c7 commit fc640ce

File tree

20 files changed

+159
-64
lines changed

20 files changed

+159
-64
lines changed

‎uefi-raw/CHANGELOG.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@
66
## Added
77

88
- Added `PAGE_SIZE` constant.
9-
9+
- Added new ABI-compatible `Boolean` type.
10+
- Added a new `unstable` feature
1011

1112
# uefi-raw - 0.7.0 (2024-08-20)
1213

‎uefi-raw/Cargo.toml

+4
Original file line numberDiff line numberDiff line change
@@ -23,5 +23,9 @@ bitflags.workspace = true
2323
ptr_meta.workspace = true
2424
uguid.workspace = true
2525

26+
[features]
27+
default = []
28+
unstable = []
29+
2630
[package.metadata.docs.rs]
2731
rustdoc-args = ["--cfg", "docsrs"]

‎uefi-raw/src/lib.rs

+85-2
Original file line numberDiff line numberDiff line change
@@ -31,11 +31,14 @@ pub mod time;
3131

3232
mod status;
3333

34-
use core::ffi::c_void;
35-
use core::fmt::{self, Debug, Formatter};
3634
pub use status::Status;
3735
pub use uguid::{guid, Guid};
3836

37+
#[cfg(feature = "unstable")]
38+
use core::error::Error;
39+
use core::ffi::c_void;
40+
use core::fmt::{self, Debug, Display, Formatter};
41+
3942
/// Handle to an event structure.
4043
pub type Event = *mut c_void;
4144

@@ -65,6 +68,58 @@ pub type PhysicalAddress = u64;
6568
/// of target platform.
6669
pub type VirtualAddress = u64;
6770

71+
/// The provided [`Boolean`] can't be converted to [`bool`] as it is neither
72+
/// `0` nor `1`.
73+
#[derive(Debug, Copy, Clone, PartialEq, Ord, PartialOrd, Eq)]
74+
pub struct InvalidBooleanError(u8);
75+
76+
impl Display for InvalidBooleanError {
77+
fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
78+
Debug::fmt(self, f)
79+
}
80+
}
81+
82+
#[cfg(feature = "unstable")]
83+
impl Error for InvalidBooleanError {}
84+
85+
/// ABI-compatible UEFI boolean.
86+
///
87+
/// Opaque 1-byte value holding either `0` for FALSE or a `1` for TRUE. This
88+
/// type can be converted from and to `bool` via corresponding [`From`]
89+
/// respectively [`TryFrom`] implementations.
90+
#[derive(Copy, Clone, Debug, Default, PartialEq, Ord, PartialOrd, Eq, Hash)]
91+
#[repr(transparent)]
92+
pub struct Boolean(u8);
93+
94+
impl Boolean {
95+
/// [`Boolean`] representing `true`.
96+
pub const TRUE: Self = Self(1);
97+
98+
/// [`Boolean`] representing `false`.
99+
pub const FALSE: Self = Self(0);
100+
}
101+
102+
impl From<bool> for Boolean {
103+
fn from(value: bool) -> Self {
104+
match value {
105+
true => Self(1),
106+
false => Self(0),
107+
}
108+
}
109+
}
110+
111+
impl TryFrom<Boolean> for bool {
112+
type Error = InvalidBooleanError;
113+
114+
fn try_from(value: Boolean) -> Result<Self, Self::Error> {
115+
match value.0 {
116+
0 => Ok(false),
117+
1 => Ok(true),
118+
x => Err(InvalidBooleanError(x)),
119+
}
120+
}
121+
}
122+
68123
/// An IPv4 internet protocol address.
69124
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Ord, PartialOrd, Hash)]
70125
#[repr(transparent)]
@@ -133,3 +188,31 @@ impl Default for IpAddress {
133188
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Ord, PartialOrd, Hash)]
134189
#[repr(transparent)]
135190
pub struct MacAddress(pub [u8; 32]);
191+
192+
#[cfg(test)]
193+
mod tests {
194+
use super::*;
195+
196+
#[test]
197+
/// Test the properties promised in [0]. This also applies for the other
198+
/// architectures.
199+
///
200+
/// [0] https://github.com/tianocore/edk2/blob/b0f43dd3fdec2363e3548ec31eb455dc1c4ac761/MdePkg/Include/X64/ProcessorBind.h#L192
201+
fn test_boolean_abi() {
202+
assert_eq!(size_of::<Boolean>(), 1);
203+
assert_eq!(Boolean::from(true).0, 1);
204+
assert_eq!(Boolean::from(false).0, 0);
205+
assert_eq!(Boolean::TRUE.0, 1);
206+
assert_eq!(Boolean::FALSE.0, 0);
207+
assert_eq!(bool::try_from(Boolean(0b0)), Ok(false));
208+
assert_eq!(bool::try_from(Boolean(0b1)), Ok(true));
209+
assert_eq!(
210+
bool::try_from(Boolean(0b11)),
211+
Err(InvalidBooleanError(0b11))
212+
);
213+
assert_eq!(
214+
bool::try_from(Boolean(0b10)),
215+
Err(InvalidBooleanError(0b10))
216+
);
217+
}
218+
}

‎uefi-raw/src/protocol/block.rs

+7-7
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
use crate::{guid, Guid, Status};
1+
use crate::{guid, Boolean, Guid, Status};
22
use core::ffi::c_void;
33

44
/// Logical block address.
@@ -9,11 +9,11 @@ pub type Lba = u64;
99
#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
1010
pub struct BlockIoMedia {
1111
pub media_id: u32,
12-
pub removable_media: bool,
13-
pub media_present: bool,
14-
pub logical_partition: bool,
15-
pub read_only: bool,
16-
pub write_caching: bool,
12+
pub removable_media: Boolean,
13+
pub media_present: Boolean,
14+
pub logical_partition: Boolean,
15+
pub read_only: Boolean,
16+
pub write_caching: Boolean,
1717
pub block_size: u32,
1818
pub io_align: u32,
1919
pub last_block: Lba,
@@ -31,7 +31,7 @@ pub struct BlockIoMedia {
3131
pub struct BlockIoProtocol {
3232
pub revision: u64,
3333
pub media: *const BlockIoMedia,
34-
pub reset: unsafe extern "efiapi" fn(this: *mut Self, extended_verification: bool) -> Status,
34+
pub reset: unsafe extern "efiapi" fn(this: *mut Self, extended_verification: Boolean) -> Status,
3535
pub read_blocks: unsafe extern "efiapi" fn(
3636
this: *const Self,
3737
media_id: u32,

‎uefi-raw/src/protocol/console.rs

+9-9
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
pub mod serial;
22

3-
use crate::{guid, Char16, Event, Guid, PhysicalAddress, Status};
3+
use crate::{guid, Boolean, Char16, Event, Guid, PhysicalAddress, Status};
44
use bitflags::bitflags;
55
use core::ptr;
66

@@ -42,7 +42,7 @@ pub struct AbsolutePointerState {
4242
#[derive(Debug)]
4343
#[repr(C)]
4444
pub struct AbsolutePointerProtocol {
45-
pub reset: unsafe extern "efiapi" fn(this: *mut Self, extended_verification: u8) -> Status,
45+
pub reset: unsafe extern "efiapi" fn(this: *mut Self, extended_verification: Boolean) -> Status,
4646
pub get_state:
4747
unsafe extern "efiapi" fn(this: *const Self, state: *mut AbsolutePointerState) -> Status,
4848
pub wait_for_input: Event,
@@ -63,7 +63,7 @@ pub struct InputKey {
6363
#[derive(Debug)]
6464
#[repr(C)]
6565
pub struct SimpleTextInputProtocol {
66-
pub reset: unsafe extern "efiapi" fn(this: *mut Self, extended_verification: bool) -> Status,
66+
pub reset: unsafe extern "efiapi" fn(this: *mut Self, extended_verification: Boolean) -> Status,
6767
pub read_key_stroke: unsafe extern "efiapi" fn(this: *mut Self, key: *mut InputKey) -> Status,
6868
pub wait_for_key: Event,
6969
}
@@ -80,13 +80,13 @@ pub struct SimpleTextOutputMode {
8080
pub attribute: i32,
8181
pub cursor_column: i32,
8282
pub cursor_row: i32,
83-
pub cursor_visible: bool,
83+
pub cursor_visible: Boolean,
8484
}
8585

8686
#[derive(Debug)]
8787
#[repr(C)]
8888
pub struct SimpleTextOutputProtocol {
89-
pub reset: unsafe extern "efiapi" fn(this: *mut Self, extended: bool) -> Status,
89+
pub reset: unsafe extern "efiapi" fn(this: *mut Self, extended: Boolean) -> Status,
9090
pub output_string: unsafe extern "efiapi" fn(this: *mut Self, string: *const Char16) -> Status,
9191
pub test_string: unsafe extern "efiapi" fn(this: *mut Self, string: *const Char16) -> Status,
9292
pub query_mode: unsafe extern "efiapi" fn(
@@ -100,7 +100,7 @@ pub struct SimpleTextOutputProtocol {
100100
pub clear_screen: unsafe extern "efiapi" fn(this: *mut Self) -> Status,
101101
pub set_cursor_position:
102102
unsafe extern "efiapi" fn(this: *mut Self, column: usize, row: usize) -> Status,
103-
pub enable_cursor: unsafe extern "efiapi" fn(this: *mut Self, visible: bool) -> Status,
103+
pub enable_cursor: unsafe extern "efiapi" fn(this: *mut Self, visible: Boolean) -> Status,
104104
pub mode: *mut SimpleTextOutputMode,
105105
}
106106

@@ -124,16 +124,16 @@ pub struct SimplePointerState {
124124
pub relative_movement_x: i32,
125125
pub relative_movement_y: i32,
126126
pub relative_movement_z: i32,
127-
pub left_button: u8,
128-
pub right_button: u8,
127+
pub left_button: Boolean,
128+
pub right_button: Boolean,
129129
}
130130

131131
#[derive(Debug)]
132132
#[repr(C)]
133133
pub struct SimplePointerProtocol {
134134
pub reset: unsafe extern "efiapi" fn(
135135
this: *mut SimplePointerProtocol,
136-
extended_verification: bool,
136+
extended_verification: Boolean,
137137
) -> Status,
138138
pub get_state: unsafe extern "efiapi" fn(
139139
this: *mut SimplePointerProtocol,

‎uefi-raw/src/protocol/device_path.rs

+5-5
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
use crate::{guid, Char16, Guid};
1+
use crate::{guid, Boolean, Char16, Guid};
22

33
/// Device path protocol.
44
///
@@ -25,13 +25,13 @@ impl DevicePathProtocol {
2525
pub struct DevicePathToTextProtocol {
2626
pub convert_device_node_to_text: unsafe extern "efiapi" fn(
2727
device_node: *const DevicePathProtocol,
28-
display_only: bool,
29-
allow_shortcuts: bool,
28+
display_only: Boolean,
29+
allow_shortcuts: Boolean,
3030
) -> *const Char16,
3131
pub convert_device_path_to_text: unsafe extern "efiapi" fn(
3232
device_path: *const DevicePathProtocol,
33-
display_only: bool,
34-
allow_shortcuts: bool,
33+
display_only: Boolean,
34+
allow_shortcuts: Boolean,
3535
) -> *const Char16,
3636
}
3737

‎uefi-raw/src/protocol/file_system.rs

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
use crate::time::Time;
2-
use crate::{guid, Char16, Event, Guid, Status};
2+
use crate::{guid, Boolean, Char16, Event, Guid, Status};
33
use bitflags::bitflags;
44
use core::ffi::c_void;
55

@@ -151,7 +151,7 @@ impl FileInfo {
151151
#[repr(C)]
152152
pub struct FileSystemInfo {
153153
pub size: u64,
154-
pub read_only: u8,
154+
pub read_only: Boolean,
155155
pub volume_size: u64,
156156
pub free_space: u64,
157157
pub block_size: u32,

‎uefi-raw/src/protocol/media.rs

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
use crate::protocol::device_path::DevicePathProtocol;
2-
use crate::{guid, Guid, Status};
2+
use crate::{guid, Boolean, Guid, Status};
33
use core::ffi::c_void;
44

55
#[derive(Debug)]
@@ -8,7 +8,7 @@ pub struct LoadFileProtocol {
88
pub load_file: unsafe extern "efiapi" fn(
99
this: *mut LoadFileProtocol,
1010
file_path: *const DevicePathProtocol,
11-
boot_policy: bool,
11+
boot_policy: Boolean,
1212
buffer_size: *mut usize,
1313
buffer: *mut c_void,
1414
) -> Status,
@@ -24,7 +24,7 @@ pub struct LoadFile2Protocol {
2424
pub load_file: unsafe extern "efiapi" fn(
2525
this: *mut LoadFile2Protocol,
2626
file_path: *const DevicePathProtocol,
27-
boot_policy: bool,
27+
boot_policy: Boolean,
2828
buffer_size: *mut usize,
2929
buffer: *mut c_void,
3030
) -> Status,

‎uefi-raw/src/protocol/network/dhcp4.rs

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
use crate::{guid, Char8, Event, Guid, Ipv4Address, MacAddress, Status};
1+
use crate::{guid, Boolean, Char8, Event, Guid, Ipv4Address, MacAddress, Status};
22
use core::ffi::c_void;
33

44
newtype_enum! {
@@ -148,7 +148,7 @@ pub struct Dhcp4Protocol {
148148
pub start: unsafe extern "efiapi" fn(this: *mut Self, completion_event: Event) -> Status,
149149
pub renew_rebind: unsafe extern "efiapi" fn(
150150
this: *mut Self,
151-
rebind_request: bool,
151+
rebind_request: Boolean,
152152
completion_event: Event,
153153
) -> Status,
154154
pub release: unsafe extern "efiapi" fn(this: *mut Self) -> Status,

‎uefi-raw/src/protocol/network/http.rs

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
use crate::{guid, Char16, Char8, Event, Guid, Ipv4Address, Ipv6Address, Status};
1+
use crate::{guid, Boolean, Char16, Char8, Event, Guid, Ipv4Address, Ipv6Address, Status};
22
use core::ffi::c_void;
33
use core::fmt::{self, Debug, Formatter};
44

@@ -7,7 +7,7 @@ use core::fmt::{self, Debug, Formatter};
77
pub struct HttpConfigData {
88
pub http_version: HttpVersion,
99
pub time_out_millisec: u32,
10-
pub local_addr_is_ipv6: bool,
10+
pub local_addr_is_ipv6: Boolean,
1111
pub access_point: HttpAccessPoint,
1212
}
1313

@@ -22,7 +22,7 @@ newtype_enum! {
2222
#[derive(Debug)]
2323
#[repr(C)]
2424
pub struct HttpV4AccessPoint {
25-
pub use_default_addr: bool,
25+
pub use_default_addr: Boolean,
2626
pub local_address: Ipv4Address,
2727
pub local_subnet: Ipv4Address,
2828
pub local_port: u16,

‎uefi-raw/src/table/boot.rs

+3-3
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
33
use crate::protocol::device_path::DevicePathProtocol;
44
use crate::table::Header;
5-
use crate::{Char16, Event, Guid, Handle, PhysicalAddress, Status, VirtualAddress};
5+
use crate::{Boolean, Char16, Event, Guid, Handle, PhysicalAddress, Status, VirtualAddress};
66
use bitflags::bitflags;
77
use core::ffi::c_void;
88
use core::ops::RangeInclusive;
@@ -103,7 +103,7 @@ pub struct BootServices {
103103

104104
// Image services
105105
pub load_image: unsafe extern "efiapi" fn(
106-
boot_policy: u8,
106+
boot_policy: Boolean,
107107
parent_image_handle: Handle,
108108
device_path: *const DevicePathProtocol,
109109
source_buffer: *const u8,
@@ -140,7 +140,7 @@ pub struct BootServices {
140140
controller: Handle,
141141
driver_image: Handle,
142142
remaining_device_path: *const DevicePathProtocol,
143-
recursive: bool,
143+
recursive: Boolean,
144144
) -> Status,
145145
pub disconnect_controller: unsafe extern "efiapi" fn(
146146
controller: Handle,

‎uefi-raw/src/table/runtime.rs

+2-2
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ use crate::capsule::CapsuleHeader;
44
use crate::table::boot::MemoryDescriptor;
55
use crate::table::Header;
66
use crate::time::Time;
7-
use crate::{guid, Char16, Guid, PhysicalAddress, Status};
7+
use crate::{guid, Boolean, Char16, Guid, PhysicalAddress, Status};
88
use bitflags::bitflags;
99
use core::ffi::c_void;
1010

@@ -115,7 +115,7 @@ pub struct TimeCapabilities {
115115

116116
/// Whether a time set operation clears the device's time below the
117117
/// "resolution" reporting level. False for normal PC-AT CMOS RTC devices.
118-
pub sets_to_zero: bool,
118+
pub sets_to_zero: Boolean,
119119
}
120120

121121
bitflags! {

‎uefi-test-runner/src/proto/load.rs

+2-2
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,12 @@ use uefi::proto::BootPolicy;
1111
use uefi::{boot, Guid, Handle};
1212
use uefi_raw::protocol::device_path::DevicePathProtocol;
1313
use uefi_raw::protocol::media::{LoadFile2Protocol, LoadFileProtocol};
14-
use uefi_raw::Status;
14+
use uefi_raw::{Boolean, Status};
1515

1616
unsafe extern "efiapi" fn raw_load_file(
1717
this: *mut LoadFile2Protocol,
1818
_file_path: *const DevicePathProtocol,
19-
_boot_policy: bool,
19+
_boot_policy: Boolean,
2020
buffer_size: *mut usize,
2121
buffer: *mut c_void,
2222
) -> Status {

0 commit comments

Comments
 (0)