uefi-raw: add opaque Boolean type

This way we can be ABI-compatible and guarantee lack of UB, while
being more precise in interfaces.

Author: phip1611

uefi-raw/CHANGELOG.md

@@ -6,7 +6,8 @@
 ## Added
 
 - Added `PAGE_SIZE` constant.
-
+- Added new ABI-compatible `Boolean` type.
+- Added a new `unstable` feature
 
 # uefi-raw - 0.7.0 (2024-08-20)
 

uefi-raw/Cargo.toml

@@ -23,5 +23,9 @@ bitflags.workspace = true
 ptr_meta.workspace = true
 uguid.workspace = true
 
+[features]
+default = []
+unstable = []
+
 [package.metadata.docs.rs]
 rustdoc-args = ["--cfg", "docsrs"]

uefi-raw/src/lib.rs

@@ -31,11 +31,14 @@ pub mod time;
 
 mod status;
 
-use core::ffi::c_void;
-use core::fmt::{self, Debug, Formatter};
 pub use status::Status;
 pub use uguid::{guid, Guid};
 
+#[cfg(feature = "unstable")]
+use core::error::Error;
+use core::ffi::c_void;
+use core::fmt::{self, Debug, Display, Formatter};
+
 /// Handle to an event structure.
 pub type Event = *mut c_void;
 
@@ -65,6 +68,58 @@ pub type PhysicalAddress = u64;
 /// of target platform.
 pub type VirtualAddress = u64;
 
+/// The provided [`Boolean`] can't be converted to [`bool`] as it is neither
+/// `0` nor `1`.
+#[derive(Debug, Copy, Clone, PartialEq, Ord, PartialOrd, Eq)]
+pub struct InvalidBooleanError(u8);
+
+impl Display for InvalidBooleanError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        Debug::fmt(self, f)
+    }
+}
+
+#[cfg(feature = "unstable")]
+impl Error for InvalidBooleanError {}
+
+/// ABI-compatible UEFI boolean.
+///
+/// Opaque 1-byte value holding either `0` for FALSE or a `1` for TRUE. This
+/// type can be converted from and to `bool` via corresponding [`From`]
+/// respectively [`TryFrom`] implementations.
+#[derive(Copy, Clone, Debug, Default, PartialEq, Ord, PartialOrd, Eq, Hash)]
+#[repr(transparent)]
+pub struct Boolean(u8);
+
+impl Boolean {
+    /// [`Boolean`] representing `true`.
+    pub const TRUE: Self = Self(1);
+
+    /// [`Boolean`] representing `false`.
+    pub const FALSE: Self = Self(0);
+}
+
+impl From<bool> for Boolean {
+    fn from(value: bool) -> Self {
+        match value {
+            true => Self(1),
+            false => Self(0),
+        }
+    }
+}
+
+impl TryFrom<Boolean> for bool {
+    type Error = InvalidBooleanError;
+
+    fn try_from(value: Boolean) -> Result<Self, Self::Error> {
+        match value.0 {
+            0 => Ok(false),
+            1 => Ok(true),
+            x => Err(InvalidBooleanError(x)),
+        }
+    }
+}
+
 /// An IPv4 internet protocol address.
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Ord, PartialOrd, Hash)]
 #[repr(transparent)]
@@ -133,3 +188,31 @@ impl Default for IpAddress {
 #[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Ord, PartialOrd, Hash)]
 #[repr(transparent)]
 pub struct MacAddress(pub [u8; 32]);
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    /// Test the properties promised in [0]. This also applies for the other
+    /// architectures.
+    ///
+    /// [0] https://github.com/tianocore/edk2/blob/b0f43dd3fdec2363e3548ec31eb455dc1c4ac761/MdePkg/Include/X64/ProcessorBind.h#L192
+    fn test_boolean_abi() {
+        assert_eq!(size_of::<Boolean>(), 1);
+        assert_eq!(Boolean::from(true).0, 1);
+        assert_eq!(Boolean::from(false).0, 0);
+        assert_eq!(Boolean::TRUE.0, 1);
+        assert_eq!(Boolean::FALSE.0, 0);
+        assert_eq!(bool::try_from(Boolean(0b0)), Ok(false));
+        assert_eq!(bool::try_from(Boolean(0b1)), Ok(true));
+        assert_eq!(
+            bool::try_from(Boolean(0b11)),
+            Err(InvalidBooleanError(0b11))
+        );
+        assert_eq!(
+            bool::try_from(Boolean(0b10)),
+            Err(InvalidBooleanError(0b10))
+        );
+    }
+}

uefi-raw/src/protocol/block.rs

@@ -1,4 +1,4 @@
-use crate::{guid, Guid, Status};
+use crate::{guid, Boolean, Guid, Status};
 use core::ffi::c_void;
 
 /// Logical block address.
@@ -9,11 +9,11 @@ pub type Lba = u64;
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
 pub struct BlockIoMedia {
     pub media_id: u32,
-    pub removable_media: bool,
-    pub media_present: bool,
-    pub logical_partition: bool,
-    pub read_only: bool,
-    pub write_caching: bool,
+    pub removable_media: Boolean,
+    pub media_present: Boolean,
+    pub logical_partition: Boolean,
+    pub read_only: Boolean,
+    pub write_caching: Boolean,
     pub block_size: u32,
     pub io_align: u32,
     pub last_block: Lba,
@@ -31,7 +31,7 @@ pub struct BlockIoMedia {
 pub struct BlockIoProtocol {
     pub revision: u64,
     pub media: *const BlockIoMedia,
-    pub reset: unsafe extern "efiapi" fn(this: *mut Self, extended_verification: bool) -> Status,
+    pub reset: unsafe extern "efiapi" fn(this: *mut Self, extended_verification: Boolean) -> Status,
     pub read_blocks: unsafe extern "efiapi" fn(
         this: *const Self,
         media_id: u32,

uefi-raw/src/protocol/console.rs

@@ -1,6 +1,6 @@
 pub mod serial;
 
-use crate::{guid, Char16, Event, Guid, PhysicalAddress, Status};
+use crate::{guid, Boolean, Char16, Event, Guid, PhysicalAddress, Status};
 use bitflags::bitflags;
 use core::ptr;
 
@@ -42,7 +42,7 @@ pub struct AbsolutePointerState {
 #[derive(Debug)]
 #[repr(C)]
 pub struct AbsolutePointerProtocol {
-    pub reset: unsafe extern "efiapi" fn(this: *mut Self, extended_verification: u8) -> Status,
+    pub reset: unsafe extern "efiapi" fn(this: *mut Self, extended_verification: Boolean) -> Status,
     pub get_state:
         unsafe extern "efiapi" fn(this: *const Self, state: *mut AbsolutePointerState) -> Status,
     pub wait_for_input: Event,
@@ -63,7 +63,7 @@ pub struct InputKey {
 #[derive(Debug)]
 #[repr(C)]
 pub struct SimpleTextInputProtocol {
-    pub reset: unsafe extern "efiapi" fn(this: *mut Self, extended_verification: bool) -> Status,
+    pub reset: unsafe extern "efiapi" fn(this: *mut Self, extended_verification: Boolean) -> Status,
     pub read_key_stroke: unsafe extern "efiapi" fn(this: *mut Self, key: *mut InputKey) -> Status,
     pub wait_for_key: Event,
 }
@@ -80,13 +80,13 @@ pub struct SimpleTextOutputMode {
     pub attribute: i32,
     pub cursor_column: i32,
     pub cursor_row: i32,
-    pub cursor_visible: bool,
+    pub cursor_visible: Boolean,
 }
 
 #[derive(Debug)]
 #[repr(C)]
 pub struct SimpleTextOutputProtocol {
-    pub reset: unsafe extern "efiapi" fn(this: *mut Self, extended: bool) -> Status,
+    pub reset: unsafe extern "efiapi" fn(this: *mut Self, extended: Boolean) -> Status,
     pub output_string: unsafe extern "efiapi" fn(this: *mut Self, string: *const Char16) -> Status,
     pub test_string: unsafe extern "efiapi" fn(this: *mut Self, string: *const Char16) -> Status,
     pub query_mode: unsafe extern "efiapi" fn(
@@ -100,7 +100,7 @@ pub struct SimpleTextOutputProtocol {
     pub clear_screen: unsafe extern "efiapi" fn(this: *mut Self) -> Status,
     pub set_cursor_position:
         unsafe extern "efiapi" fn(this: *mut Self, column: usize, row: usize) -> Status,
-    pub enable_cursor: unsafe extern "efiapi" fn(this: *mut Self, visible: bool) -> Status,
+    pub enable_cursor: unsafe extern "efiapi" fn(this: *mut Self, visible: Boolean) -> Status,
     pub mode: *mut SimpleTextOutputMode,
 }
 
@@ -124,16 +124,16 @@ pub struct SimplePointerState {
     pub relative_movement_x: i32,
     pub relative_movement_y: i32,
     pub relative_movement_z: i32,
-    pub left_button: u8,
-    pub right_button: u8,
+    pub left_button: Boolean,
+    pub right_button: Boolean,
 }
 
 #[derive(Debug)]
 #[repr(C)]
 pub struct SimplePointerProtocol {
     pub reset: unsafe extern "efiapi" fn(
         this: *mut SimplePointerProtocol,
-        extended_verification: bool,
+        extended_verification: Boolean,
     ) -> Status,
     pub get_state: unsafe extern "efiapi" fn(
         this: *mut SimplePointerProtocol,

uefi-raw/src/protocol/device_path.rs

@@ -1,4 +1,4 @@
-use crate::{guid, Char16, Guid};
+use crate::{guid, Boolean, Char16, Guid};
 
 /// Device path protocol.
 ///
@@ -25,13 +25,13 @@ impl DevicePathProtocol {
 pub struct DevicePathToTextProtocol {
     pub convert_device_node_to_text: unsafe extern "efiapi" fn(
         device_node: *const DevicePathProtocol,
-        display_only: bool,
-        allow_shortcuts: bool,
+        display_only: Boolean,
+        allow_shortcuts: Boolean,
     ) -> *const Char16,
     pub convert_device_path_to_text: unsafe extern "efiapi" fn(
         device_path: *const DevicePathProtocol,
-        display_only: bool,
-        allow_shortcuts: bool,
+        display_only: Boolean,
+        allow_shortcuts: Boolean,
     ) -> *const Char16,
 }
 

uefi-raw/src/protocol/file_system.rs

@@ -1,5 +1,5 @@
 use crate::time::Time;
-use crate::{guid, Char16, Event, Guid, Status};
+use crate::{guid, Boolean, Char16, Event, Guid, Status};
 use bitflags::bitflags;
 use core::ffi::c_void;
 
@@ -151,7 +151,7 @@ impl FileInfo {
 #[repr(C)]
 pub struct FileSystemInfo {
     pub size: u64,
-    pub read_only: u8,
+    pub read_only: Boolean,
     pub volume_size: u64,
     pub free_space: u64,
     pub block_size: u32,

uefi-raw/src/protocol/media.rs

@@ -1,5 +1,5 @@
 use crate::protocol::device_path::DevicePathProtocol;
-use crate::{guid, Guid, Status};
+use crate::{guid, Boolean, Guid, Status};
 use core::ffi::c_void;
 
 #[derive(Debug)]
@@ -8,7 +8,7 @@ pub struct LoadFileProtocol {
     pub load_file: unsafe extern "efiapi" fn(
         this: *mut LoadFileProtocol,
         file_path: *const DevicePathProtocol,
-        boot_policy: bool,
+        boot_policy: Boolean,
         buffer_size: *mut usize,
         buffer: *mut c_void,
     ) -> Status,
@@ -24,7 +24,7 @@ pub struct LoadFile2Protocol {
     pub load_file: unsafe extern "efiapi" fn(
         this: *mut LoadFile2Protocol,
         file_path: *const DevicePathProtocol,
-        boot_policy: bool,
+        boot_policy: Boolean,
         buffer_size: *mut usize,
         buffer: *mut c_void,
     ) -> Status,

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

@@ -1,4 +1,4 @@
-use crate::{guid, Char8, Event, Guid, Ipv4Address, MacAddress, Status};
+use crate::{guid, Boolean, Char8, Event, Guid, Ipv4Address, MacAddress, Status};
 use core::ffi::c_void;
 
 newtype_enum! {
@@ -148,7 +148,7 @@ pub struct Dhcp4Protocol {
     pub start: unsafe extern "efiapi" fn(this: *mut Self, completion_event: Event) -> Status,
     pub renew_rebind: unsafe extern "efiapi" fn(
         this: *mut Self,
-        rebind_request: bool,
+        rebind_request: Boolean,
         completion_event: Event,
     ) -> Status,
     pub release: unsafe extern "efiapi" fn(this: *mut Self) -> Status,

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

@@ -1,4 +1,4 @@
-use crate::{guid, Char16, Char8, Event, Guid, Ipv4Address, Ipv6Address, Status};
+use crate::{guid, Boolean, Char16, Char8, Event, Guid, Ipv4Address, Ipv6Address, Status};
 use core::ffi::c_void;
 use core::fmt::{self, Debug, Formatter};
 
@@ -7,7 +7,7 @@ use core::fmt::{self, Debug, Formatter};
 pub struct HttpConfigData {
     pub http_version: HttpVersion,
     pub time_out_millisec: u32,
-    pub local_addr_is_ipv6: bool,
+    pub local_addr_is_ipv6: Boolean,
     pub access_point: HttpAccessPoint,
 }
 
@@ -22,7 +22,7 @@ newtype_enum! {
 #[derive(Debug)]
 #[repr(C)]
 pub struct HttpV4AccessPoint {
-    pub use_default_addr: bool,
+    pub use_default_addr: Boolean,
     pub local_address: Ipv4Address,
     pub local_subnet: Ipv4Address,
     pub local_port: u16,