rename crate features

Author: phip1611

CHANGELOG.md

@@ -19,6 +19,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`
@@ -34,7 +36,7 @@
   replaced with a derived `Debug` impl.
 - `CStr16::from_u16_with_nul_unchecked` and `cstr16!` are now allowed in
   `const` contexts.
-  
+
 ### Removed
 
 - Removed `UnalignedCStr16`; use `UnalignedSlice` instead. An

Cargo.toml

@@ -21,7 +21,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).

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/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() {

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,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 +73,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

@@ -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,
         ]);

src/proto/device_path/build.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]) {

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>> {