Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
rename crate features
Browse files Browse the repository at this point in the history
phip1611 committed Nov 12, 2022

Unverified

This commit is not signed, but one or more authors requires that any commit attributed to them is signed.
1 parent 1068d2e commit 257c447
Showing 25 changed files with 108 additions and 72 deletions.
4 changes: 3 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
@@ -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).
21 changes: 12 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
@@ -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`.

1 change: 1 addition & 0 deletions book/src/SUMMARY.md
Original file line number Diff line number Diff line change
@@ -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)
16 changes: 16 additions & 0 deletions book/src/how_to/crate_features.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion book/src/tutorial/building.md
Original file line number Diff line number Diff line change
@@ -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"]
```

4 changes: 2 additions & 2 deletions src/data_types/mod.rs
Original file line number Diff line number Diff line change
@@ -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;
6 changes: 3 additions & 3 deletions src/data_types/owned_strs.rs
Original file line number Diff line number Diff line change
@@ -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() {
6 changes: 3 additions & 3 deletions src/data_types/strs.rs
Original file line number Diff line number Diff line change
@@ -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]
10 changes: 5 additions & 5 deletions src/data_types/unaligned_slice.rs
Original file line number Diff line number Diff line change
@@ -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() {
File renamed without changes.
26 changes: 19 additions & 7 deletions src/lib.rs
Original file line number Diff line number Diff line change
@@ -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,23 @@
#![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 +71,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;
16 changes: 8 additions & 8 deletions src/proto/device_path/build.rs
Original file line number Diff line number Diff line change
@@ -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,
]);
3 changes: 2 additions & 1 deletion src/proto/device_path/mod.rs
Original file line number Diff line number Diff line change
@@ -558,7 +558,8 @@ pub enum NodeConversionError {
#[cfg(test)]
mod tests {
use super::*;
use alloc_api::vec::Vec;
use crate::{guid, CString16};
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]) {
2 changes: 1 addition & 1 deletion src/proto/media/file/info.rs
Original file line number Diff line number Diff line change
@@ -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;
8 changes: 4 additions & 4 deletions src/proto/media/file/mod.rs
Original file line number Diff line number Diff line change
@@ -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
8 changes: 4 additions & 4 deletions src/table/boot.rs
Original file line number Diff line number Diff line change
@@ -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>> {
Loading

0 comments on commit 257c447

Please sign in to comment.