rename crate features

phip1611 · phip1611 · commit b15c60a443e4 · 2022-11-18T08:42:00.000+01:00
To prevent confusion, this renames the `alloc` crate feature to
`global_allocator` and the `exts` feature to `alloc` to match the
conventions of the ecosystem.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -30,6 +30,8 @@
 
 ### Changed
 
+- Renamed crate feature `alloc` to `global_allocator`.
+- Renamed crate feature `exts` to `alloc`.
 - Fixed the definition of `AllocateType` so that `MaxAddress` and
   `Address` always take a 64-bit value, regardless of target platform.
 - The conversion methods on `DevicePathToText` and `DevicePathFromText`
diff --git a/README.md b/README.md
@@ -31,17 +31,21 @@ 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.
+  The objective is to stay unopinionated and safely wrap most interfaces.
 
-  Optional features:
-  - `alloc`: implements a global allocator using UEFI functions.
-    - This allows you to allocate objects on the heap.
+  **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`.
 
diff --git a/book/src/SUMMARY.md b/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)
diff --git a/book/src/how_to/crate_features.md b/book/src/how_to/crate_features.md
@@ -0,0 +1,15 @@
+# Optional Crate Features
+
+There are several optional crate features provided by the `uefi` crate.
+
+- `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 the UEFI boot services standard text output.
+  - No buffering is done: this is not a high-performance logger.
diff --git a/template/Cargo.toml b/template/Cargo.toml
@@ -5,5 +5,5 @@ edition = "2021"
 publish = false
 
 [dependencies]
-uefi = { version = "0.18.0", features = ["exts"] }
+uefi = { version = "0.18.0", features = ["alloc"] }
 uefi-services = "0.15.0"
diff --git a/uefi-services/Cargo.toml b/uefi-services/Cargo.toml
@@ -15,7 +15,7 @@ is-it-maintained-issue-resolution = { repository = "rust-osdev/uefi-rs" }
 is-it-maintained-open-issues = { repository = "rust-osdev/uefi-rs" }
 
 [dependencies]
-uefi = { version = "0.18.0", features = ["alloc"] }
+uefi = { version = "0.18.0", features = ["global_allocator"] }
 log = { version = "0.4.5", default-features = false }
 cfg-if = "1.0.0"
 qemu-exit = { version = "3.0.1", optional = true }
diff --git a/uefi-services/src/lib.rs b/uefi-services/src/lib.rs
@@ -83,7 +83,7 @@ pub fn init(st: &mut SystemTable<Boot>) -> Result {
         init_logger(st);
 
         let boot_services = st.boot_services();
-        uefi::alloc::init(boot_services);
+        uefi::global_allocator::init(boot_services);
 
         // Schedule these tools to be disabled on exit from UEFI boot services
         boot_services
@@ -181,7 +181,7 @@ unsafe extern "efiapi" fn exit_boot_services(_e: Event, _ctx: Option<NonNull<c_v
         logger.disable();
     }
 
-    uefi::alloc::exit_boot_services();
+    uefi::global_allocator::exit_boot_services();
 }
 
 #[cfg(feature = "panic_handler")]
diff --git a/uefi-test-runner/Cargo.toml b/uefi-test-runner/Cargo.toml
@@ -6,7 +6,7 @@ publish = false
 edition = "2021"
 
 [dependencies]
-uefi = { path = "../uefi", features = ['exts'] }
+uefi = { path = "../uefi", features = ['alloc'] }
 uefi-services = { path = "../uefi-services" }
 
 log = { version = "0.4.11", default-features = false }
diff --git a/uefi/Cargo.toml b/uefi/Cargo.toml
@@ -13,7 +13,7 @@ license = "MPL-2.0"
 [features]
 default = ["panic-on-logger-errors"]
 alloc = []
-exts = []
+global_allocator = []
 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).
diff --git a/uefi/src/data_types/guid.rs b/uefi/src/data_types/guid.rs
@@ -141,9 +141,8 @@ pub use uefi_macros::unsafe_guid;
 
 #[cfg(test)]
 mod tests {
-    use uefi::{guid, unsafe_guid};
-    extern crate alloc;
     use super::*;
+    use uefi::{guid, unsafe_guid};
 
     #[test]
     fn test_guid_display() {
diff --git a/uefi/src/data_types/mod.rs b/uefi/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;
diff --git a/uefi/src/data_types/owned_strs.rs b/uefi/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() {
diff --git a/uefi/src/data_types/strs.rs b/uefi/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]
diff --git a/uefi/src/data_types/unaligned_slice.rs b/uefi/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() {
diff --git a/uefi/src/global_allocator.rs b/uefi/src/global_allocator.rs
diff --git a/uefi/src/lib.rs b/uefi/src/lib.rs
@@ -15,6 +15,20 @@
 //! 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 +41,25 @@
 #![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;
+// Enable once we use vec![] or similar
+// #[cfg_attr(feature = "alloc", macro_use)]
+#[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 +74,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;
diff --git a/uefi/src/proto/device_path/build.rs b/uefi/src/proto/device_path/build.rs
@@ -11,13 +11,13 @@ use crate::proto::device_path::{DevicePath, DevicePathNode};
 use core::mem::MaybeUninit;
 use core::ptr;
 
-#[cfg(feature = "exts")]
-use alloc_api::vec::Vec;
+#[cfg(feature = "alloc")]
+use alloc::vec::Vec;
 
 /// A builder for [`DevicePaths`].
 ///
 /// The builder can be constructed with either a fixed-length buffer or
-/// (if the `exts` feature is enabled) a `Vec`.
+/// (if the `alloc` feature is enabled) a `Vec`.
 ///
 /// Nodes are added via the [`push`] method. To construct a node, use one
 /// of the structs in these submodules:
@@ -82,7 +82,7 @@ impl<'a> DevicePathBuilder<'a> {
     }
 
     /// Create a builder backed by a `Vec`.
-    #[cfg(feature = "exts")]
+    #[cfg(feature = "alloc")]
     pub fn with_vec(v: &'a mut Vec<u8>) -> Self {
         Self {
             storage: BuilderStorage::Vec(v),
@@ -107,7 +107,7 @@ impl<'a> DevicePathBuilder<'a> {
                 );
                 *offset += node_size;
             }
-            #[cfg(feature = "exts")]
+            #[cfg(feature = "alloc")]
             BuilderStorage::Vec(vec) => {
                 let old_size = vec.len();
                 vec.reserve(node_size);
@@ -134,7 +134,7 @@ impl<'a> DevicePathBuilder<'a> {
             BuilderStorage::Buf { buf, offset } => unsafe {
                 MaybeUninit::slice_assume_init_ref(&buf[..*offset])
             },
-            #[cfg(feature = "exts")]
+            #[cfg(feature = "alloc")]
             BuilderStorage::Vec(vec) => vec,
         };
 
@@ -149,7 +149,7 @@ enum BuilderStorage<'a> {
         offset: usize,
     },
 
-    #[cfg(feature = "exts")]
+    #[cfg(feature = "alloc")]
     Vec(&'a mut Vec<u8>),
 }
 
@@ -450,7 +450,7 @@ mod tests {
             0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
             // Logical unit number
             0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
-            
+
             // End-entire node
             0x7f, 0xff, 0x04, 0x00,
         ]);
diff --git a/uefi/src/proto/device_path/mod.rs b/uefi/src/proto/device_path/mod.rs
@@ -558,7 +558,7 @@ pub enum NodeConversionError {
 #[cfg(test)]
 mod tests {
     use super::*;
-    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]) {
diff --git a/uefi/src/proto/media/file/info.rs b/uefi/src/proto/media/file/info.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;
diff --git a/uefi/src/proto/media/file/mod.rs b/uefi/src/proto/media/file/mod.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
diff --git a/uefi/src/table/boot.rs b/uefi/src/table/boot.rs
diff --git a/uefi/src/table/runtime.rs b/uefi/src/table/runtime.rs
diff --git a/uefi/src/table/system.rs b/uefi/src/table/system.rs
diff --git a/xtask/src/cargo.rs b/xtask/src/cargo.rs
diff --git a/xtask/src/main.rs b/xtask/src/main.rs

Original file line number	Diff line number	Diff line change
`@@ -83,7 +83,7 @@ pub fn init(st: &mut SystemTable<Boot>) -> Result {`
`83`	`83`	`init_logger(st);`
`84`	`84`
`85`	`85`	`let boot_services = st.boot_services();`
`86`		`- uefi::alloc::init(boot_services);`
	`86`	`+ uefi::global_allocator::init(boot_services);`
`87`	`87`
`88`	`88`	`// Schedule these tools to be disabled on exit from UEFI boot services`
`89`	`89`	`boot_services`
`@@ -181,7 +181,7 @@ unsafe extern "efiapi" fn exit_boot_services(_e: Event, _ctx: Option<NonNull<c_v`
`181`	`181`	`logger.disable();`
`182`	`182`	`}`
`183`	`183`
`184`		`- uefi::alloc::exit_boot_services();`
	`184`	`+ uefi::global_allocator::exit_boot_services();`
`185`	`185`	`}`
`186`	`186`
`187`	`187`	`#[cfg(feature = "panic_handler")]`