rename crate features

Author: phip1611

Cargo.toml

@@ -21,7 +21,7 @@ license = "MPL-2.0"
 [features]
 default = ["panic-on-logger-errors"]
 alloc = []
-exts = []
+global_allcoator = []
 logger = []
 # Ignore text output errors in logger as a workaround for firmware issues that
 # were observed on the VirtualBox UEFI implementation (see uefi-rs#121).

README.md

@@ -31,17 +31,20 @@ Check out [the UEFI application template](template) for a quick start.
 This project contains multiple sub-crates:
 
 - `uefi` (top directory): defines the standard UEFI tables / interfaces.
-  The objective is to stay unopionated and safely wrap most interfaces.
-
-  Optional features:
-  - `alloc`: implements a global allocator using UEFI functions.
-    - This allows you to allocate objects on the heap.
+  The objective is to stay opinionated and safely wrap most interfaces.
+
+  **Optional Crate Features:**
+  - `alloc`: Enables functionality requiring the `alloc` crate from the Rust standard library.
+    - For example, this allows many convenient `uefi-rs` functions to operate on heap data (`Box`).
+    - It is up to the user to provide a `#[global allocator]`.
+  - `global_allocator`: implements a `#[global allocator]` using UEFI functions.
+    - This allows you to use all abstractions from the `alloc` crate from the Rust standard library
+      during runtime. Hence, `Vec`, `Box`, etc. will be able to allocate memory.
+      **This is optional**, so you can provide a custom `#[global allocator]` as well.
     - There's no guarantee of the efficiency of UEFI's allocator.
-  - `logger`: logging implementation for the standard [log] crate.
-    - Prints output to console.
+  - `logger`: logging implementation for the standard [`log`] crate.
+    - Prints output to UEFI console.
     - No buffering is done: this is not a high-performance logger.
-  - `exts`: extensions providing utility functions for common patterns.
-    - Requires the `alloc` crate (either enable the `alloc` optional feature or your own custom allocator).
 
 - `uefi-macros`: procedural macros that are used to derive some traits in `uefi`.
 

book/src/SUMMARY.md

@@ -7,6 +7,7 @@
   - [Running in a VM](tutorial/vm.md)
 - [How-to](how_to/introduction.md)
   - [Using Protocols](how_to/protocols.md)
+  - [Crate Features](how_to/crate_features.md)
 - [Concepts](concepts/introduction.md)
   - [Boot Stages](concepts/boot_stages.md)
   - [Tables](concepts/tables.md)

book/src/how_to/crate_features.md

@@ -0,0 +1,16 @@
+# Optional Crate Features
+
+There are several optional crate features provided by the `uefi` crate.
+
+## Optional Crate Features:
+- `alloc`: Enables functionality requiring the `alloc` crate from the Rust standard library.
+  - For example, this allows many convenient `uefi-rs` functions to operate on heap data (`Box`).
+  - It is up to the user to provide a `#[global allocator]`.
+- `global_allocator`: implements a `#[global allocator]` using UEFI functions.
+  - This allows you to use all abstractions from the `alloc` crate from the Rust standard library
+    during runtime. Hence, `Vec`, `Box`, etc. will be able to allocate memory.
+    **This is optional**, so you can provide a custom `#[global allocator]` as well.
+  - There's no guarantee of the efficiency of UEFI's allocator.
+- `logger`: logging implementation for the standard [`log`] crate.
+  - Prints output to UEFI console.
+  - No buffering is done: this is not a high-performance logger.

book/src/tutorial/building.md

@@ -49,7 +49,7 @@ Create `.cargo/config.toml` with these contents:
 target = "x86_64-unknown-uefi"
 
 [unstable]
-build-std = ["core", "compiler_builtins", "alloc"]
+build-std = ["core", "compiler_builtins", "global_allocator"]
 build-std-features = ["compiler-builtins-mem"]
 ```
 

src/data_types/mod.rs

@@ -132,9 +132,9 @@ pub use self::strs::{
     CStr16, CStr8, EqStrUntilNul, FromSliceWithNulError, FromStrWithBufError, UnalignedCStr16Error,
 };
 
-#[cfg(feature = "exts")]
+#[cfg(feature = "alloc")]
 mod owned_strs;
-#[cfg(feature = "exts")]
+#[cfg(feature = "alloc")]
 pub use self::owned_strs::{CString16, FromStrError};
 
 mod unaligned_slice;

src/data_types/owned_strs.rs

@@ -1,6 +1,6 @@
 use super::chars::{Char16, NUL_16};
 use super::strs::{CStr16, FromSliceWithNulError};
-use crate::alloc_api::vec::Vec;
+use crate::alloc::vec::Vec;
 use crate::data_types::strs::EqStrUntilNul;
 use crate::data_types::UnalignedSlice;
 use core::fmt;
@@ -138,8 +138,8 @@ impl<StrType: AsRef<str>> EqStrUntilNul<StrType> for CString16 {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::alloc_api::string::String;
-    use crate::alloc_api::vec;
+    use crate::alloc::string::String;
+    use crate::alloc::vec;
 
     #[test]
     fn test_cstring16_from_str() {

src/data_types/strs.rs

@@ -6,7 +6,7 @@ use core::mem::MaybeUninit;
 use core::result::Result;
 use core::slice;
 
-#[cfg(feature = "exts")]
+#[cfg(feature = "alloc")]
 use super::CString16;
 
 /// Errors which can occur during checked `[uN]` -> `CStrN` conversions
@@ -397,7 +397,7 @@ impl fmt::Display for CStr16 {
     }
 }
 
-#[cfg(feature = "exts")]
+#[cfg(feature = "alloc")]
 impl PartialEq<CString16> for &CStr16 {
     fn eq(&self, other: &CString16) -> bool {
         PartialEq::eq(*self, other.as_ref())
@@ -447,7 +447,7 @@ where
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::alloc_api::string::String;
+    use crate::alloc::string::String;
     use uefi_macros::{cstr16, cstr8};
 
     #[test]

src/data_types/unaligned_slice.rs

@@ -1,8 +1,8 @@
 use core::marker::PhantomData;
 use core::mem::MaybeUninit;
 
-#[cfg(feature = "exts")]
-use crate::alloc_api::vec::Vec;
+#[cfg(feature = "alloc")]
+use crate::alloc::vec::Vec;
 
 /// Slice backed by a potentially-unaligned pointer.
 ///
@@ -110,7 +110,7 @@ impl<'a, T: Copy> UnalignedSlice<'a, T> {
     }
 
     /// Copies `self` into a new `Vec`.
-    #[cfg(feature = "exts")]
+    #[cfg(feature = "alloc")]
     pub fn to_vec(&self) -> Vec<T> {
         let len = self.len();
         let mut v = Vec::with_capacity(len);
@@ -122,7 +122,7 @@ impl<'a, T: Copy> UnalignedSlice<'a, T> {
     }
 }
 
-#[cfg(feature = "exts")]
+#[cfg(feature = "alloc")]
 impl<'a, T: Copy> From<UnalignedSlice<'a, T>> for Vec<T> {
     fn from(input: UnalignedSlice<'a, T>) -> Self {
         input.to_vec()
@@ -185,7 +185,7 @@ impl<'a, T: Copy> Iterator for UnalignedSliceIter<'a, T> {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use alloc_api::vec::Vec;
+    use alloc::vec::Vec;
 
     #[test]
     fn test_unaligned_slice() {

src/alloc.rs renamed to src/global_allocator.rs

@@ -15,6 +15,19 @@
 //! The `proto` module contains the standard UEFI protocols, which are normally provided
 //! by the various UEFI drivers and firmware layers.
 //!
+//! ## Optional Crate Features:
+//! - `alloc`: Enables functionality requiring the `alloc` crate from the Rust standard library.
+//!   - For example, this allows many convenient `uefi-rs` functions to operate on heap data (`Box`).
+//!   - It is up to the user to provide a `#[global allocator]`.
+//! - `global_allocator`: implements a `#[global allocator]` using UEFI functions.
+//!   - This allows you to use all abstractions from the `alloc` crate from the Rust standard library
+//!     during runtime. Hence, `Vec`, `Box`, etc. will be able to allocate memory.
+//!     **This is optional**, so you can provide a custom `#[global allocator]` as well.
+//!   - There's no guarantee of the efficiency of UEFI's allocator.
+//! - `logger`: logging implementation for the standard [`log`] crate.
+//!   - Prints output to UEFI console.
+//!   - No buffering is done: this is not a high-performance logger.
+//!
 //! ## Adapting to local conditions
 //!
 //! Unlike system tables, which are present on *all* UEFI implementations,
@@ -27,24 +40,24 @@
 #![feature(maybe_uninit_slice)]
 #![feature(negative_impls)]
 #![feature(ptr_metadata)]
-#![cfg_attr(feature = "exts", feature(vec_into_raw_parts))]
+#![cfg_attr(feature = "alloc", feature(vec_into_raw_parts))]
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![no_std]
 // Enable some additional warnings and lints.
 #![warn(clippy::ptr_as_ptr, missing_docs, unused)]
 #![deny(clippy::all)]
 
 // `uefi-exts` requires access to memory allocation APIs.
-#[cfg(feature = "exts")]
-extern crate alloc as alloc_api;
+#[cfg(feature = "alloc")]
+extern crate alloc;
 
 // allow referring to self as ::uefi for macros to work universally (from this crate and from others)
 // see https://github.com/rust-lang/rust/issues/54647
 extern crate self as uefi;
 
 #[macro_use]
 pub mod data_types;
-#[cfg(feature = "exts")]
+#[cfg(feature = "alloc")]
 pub use self::data_types::CString16;
 pub use self::data_types::{unsafe_guid, Identify};
 pub use self::data_types::{CStr16, CStr8, Char16, Char8, Event, Guid, Handle};
@@ -59,8 +72,8 @@ pub mod proto;
 
 pub mod prelude;
 
-#[cfg(feature = "alloc")]
-pub mod alloc;
+#[cfg(feature = "global_allocator")]
+pub mod global_allocator;
 
 #[cfg(feature = "logger")]
 pub mod logger;

src/lib.rs

@@ -689,7 +689,7 @@ newtype_enum! {
 mod tests {
     use super::*;
     use crate::{guid, CString16};
-    use alloc_api::vec::Vec;
+    use alloc::vec::Vec;
 
     /// Create a node to `path` from raw data.
     fn add_node(path: &mut Vec<u8>, device_type: u8, sub_type: u8, node_data: &[u8]) {

src/proto/device_path/mod.rs

@@ -375,7 +375,7 @@ impl FileProtocolInfo for FileSystemVolumeLabel {}
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::alloc_api::vec;
+    use crate::alloc::vec;
     use crate::table::runtime::TimeParams;
     use crate::table::runtime::{Daylight, Time};
     use crate::CString16;

src/proto/media/file/info.rs

@@ -16,10 +16,10 @@ use core::ffi::c_void;
 use core::fmt::Debug;
 use core::mem;
 use core::ptr;
-#[cfg(feature = "exts")]
+#[cfg(feature = "alloc")]
 use {
     crate::ResultExt,
-    alloc_api::{alloc, alloc::Layout, boxed::Box},
+    ::alloc::{alloc, alloc::Layout, boxed::Box},
     core::slice,
 };
 
@@ -165,7 +165,7 @@ pub trait File: Sized {
         (self.imp().flush)(self.imp()).into()
     }
 
-    #[cfg(feature = "exts")]
+    #[cfg(feature = "alloc")]
     /// Get the dynamically allocated info for a file
     fn get_boxed_info<Info: FileProtocolInfo + ?Sized + Debug>(&mut self) -> Result<Box<Info>> {
         // Initially try get_info with an empty array, this should always fail
@@ -408,7 +408,7 @@ mod tests {
     use super::*;
     use crate::table::runtime::Time;
     use crate::{CString16, Identify};
-    use alloc_api::vec;
+    use alloc::vec;
 
     // Test `get_boxed_info` by setting up a fake file, which is mostly
     // just function pointers. Most of the functions can be empty, only

src/proto/media/file/mod.rs

@@ -3,12 +3,12 @@
 use super::{Header, Revision};
 use crate::data_types::{Align, PhysicalAddress, VirtualAddress};
 use crate::proto::device_path::{DevicePath, FfiDevicePath};
-#[cfg(feature = "exts")]
+#[cfg(feature = "alloc")]
 use crate::proto::{loaded_image::LoadedImage, media::fs::SimpleFileSystem};
 use crate::proto::{Protocol, ProtocolPointer};
 use crate::{Char16, Event, Guid, Handle, Result, Status};
-#[cfg(feature = "exts")]
-use alloc_api::vec::Vec;
+#[cfg(feature = "alloc")]
+use alloc::vec::Vec;
 use bitflags::bitflags;
 use core::cell::UnsafeCell;
 use core::ffi::c_void;
@@ -1154,7 +1154,7 @@ impl BootServices {
     }
 }
 
-#[cfg(feature = "exts")]
+#[cfg(feature = "alloc")]
 impl BootServices {
     /// Returns all the handles implementing a certain protocol.
     pub fn find_handles<P: Protocol>(&self) -> Result<Vec<Handle>> {

src/table/boot.rs

@@ -1,16 +1,16 @@
 //! UEFI services available at runtime, even after the OS boots.
 
 use super::{Header, Revision};
-#[cfg(feature = "exts")]
+#[cfg(feature = "alloc")]
 use crate::data_types::FromSliceWithNulError;
 use crate::result::Error;
 use crate::table::boot::MemoryDescriptor;
 use crate::{guid, CStr16, Char16, Guid, Result, Status};
-#[cfg(feature = "exts")]
-use alloc_api::{vec, vec::Vec};
+#[cfg(feature = "alloc")]
+use alloc::{vec, vec::Vec};
 use bitflags::bitflags;
 use core::fmt::{Debug, Formatter};
-#[cfg(feature = "exts")]
+#[cfg(feature = "alloc")]
 use core::mem;
 use core::mem::MaybeUninit;
 use core::{fmt, ptr};
@@ -157,7 +157,7 @@ impl RuntimeServices {
     }
 
     /// Get the names and vendor GUIDs of all currently-set variables.
-    #[cfg(feature = "exts")]
+    #[cfg(feature = "alloc")]
     pub fn variable_keys(&self) -> Result<Vec<VariableKey>> {
         let mut all_variables = Vec::new();
 
@@ -614,23 +614,23 @@ newtype_enum! {
 }
 
 /// Unique key for a variable.
-#[cfg(feature = "exts")]
+#[cfg(feature = "alloc")]
 #[derive(Debug)]
 pub struct VariableKey {
     name: Vec<u16>,
     /// Unique identifier for the vendor.
     pub vendor: VariableVendor,
 }
 
-#[cfg(feature = "exts")]
+#[cfg(feature = "alloc")]
 impl VariableKey {
     /// Name of the variable.
     pub fn name(&self) -> core::result::Result<&CStr16, FromSliceWithNulError> {
         CStr16::from_u16_with_nul(&self.name)
     }
 }
 
-#[cfg(feature = "exts")]
+#[cfg(feature = "alloc")]
 impl fmt::Display for VariableKey {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         write!(f, "VariableKey {{ name: ")?;

src/table/runtime.rs

@@ -4,5 +4,5 @@ version = "0.1.0"
 edition = "2021"
 
 [dependencies]
-uefi = { version = "0.17.0", features = ["exts"] }
+uefi = { version = "0.17.0", features = ["alloc"] }
 uefi-services = "0.14.0"

template/Cargo.toml

@@ -6,7 +6,7 @@ publish = false
 edition = "2021"
 
 [dependencies]
-uefi = { path = "..", features = ['exts'] }
+uefi = { path = "..", features = ["alloc"] }
 uefi-services = { path = "../uefi-services" }
 
 log = { version = "0.4.11", default-features = false }