1//! Rusty wrapper for the [Unified Extensible Firmware Interface][UEFI].
2//!
3//! See the [Rust UEFI Book] for a tutorial, how-tos, and overviews of some
4//! important UEFI concepts. For more details of UEFI, see the latest [UEFI
5//! Specification][spec].
6//!
7//! Feel free to file bug reports and questions in our [issue tracker], and [PR
8//! contributions][contributing] are also welcome!
9//!
10//! # Crate organisation
11//!
12//! The top-level module contains some of the most used types and macros,
13//! including the [`Handle`] and [`Result`] types, the [`CStr16`] and
14//! [`CString16`] types for working with UCS-2 strings, and the [`entry`] and
15//! [`guid`] macros.
16//!
17//! ## Tables
18//!
19//! The [`SystemTable`] provides access to almost everything in UEFI. It comes
20//! in two flavors:
21//! - `SystemTable<Boot>`: for boot-time applications such as bootloaders,
22//! provides access to both boot and runtime services.
23//! - `SystemTable<Runtime>`: for operating systems after boot services have
24//! been exited.
25//!
26//! ## Protocols
27//!
28//! When boot services are active, most functionality is provided via UEFI
29//! protocols. Protocols provide operations such as reading and writing files,
30//! drawing to the screen, sending and receiving network requests, and much
31//! more. The list of protocols that are actually available when running an
32//! application depends on the device. For example, a PC with no network card
33//! may not provide network protocols.
34//!
35//! See the [`BootServices`] documentation for details of how to open a
36//! protocol, and see the [`proto`] module for protocol implementations. New
37//! protocols can be defined with the [`unsafe_protocol`] macro.
38//!
39//! ## Optional crate features
40//!
41//! - `alloc`: Enable functionality requiring the [`alloc`] crate from
42//! the Rust standard library. For example, methods that return a
43//! `Vec` rather than filling a statically-sized array. This requires
44//! a global allocator; you can use the `global_allocator` feature or
45//! provide your own.
46//! - `global_allocator`: Implement a [global allocator] using UEFI
47//! functions. This is a simple allocator that relies on the UEFI pool
48//! allocator. You can choose to provide your own allocator instead of
49//! using this feature, or no allocator at all if you don't need to
50//! dynamically allocate any memory.
51//! - `logger`: Logging implementation for the standard [`log`] crate
52//! that prints output to the UEFI console. No buffering is done; this
53//! is not a high-performance logger.
54//! - `panic-on-logger-errors` (enabled by default): Panic if a text
55//! output error occurs in the logger.
56//! - `unstable`: Enable functionality that depends on [unstable
57//! features] in the nightly compiler.
58//! As example, in conjunction with the `alloc`-feature, this gate allows
59//! the `allocator_api` on certain functions.
60//!
61//! The `global_allocator` and `logger` features require special
62//! handling to perform initialization and tear-down. The
63//! [`uefi-services`] crate provides an `init` method that takes care of
64//! this.
65//!
66//! [Rust UEFI Book]: https://rust-osdev.github.io/uefi-rs/HEAD/
67//! [UEFI]: https://uefi.org/
68//! [`BootServices`]: table::boot::BootServices
69//! [`GlobalAlloc`]: alloc::alloc::GlobalAlloc
70//! [`SystemTable`]: table::SystemTable
71//! [`uefi-services`]: https://crates.io/crates/uefi-services
72//! [`unsafe_protocol`]: proto::unsafe_protocol
73//! [contributing]: https://github.com/rust-osdev/uefi-rs/blob/main/CONTRIBUTING.md
74//! [issue tracker]: https://github.com/rust-osdev/uefi-rs/issues
75//! [spec]: https://uefi.org/specifications
76//! [unstable features]: https://doc.rust-lang.org/unstable-book/
77
78#![cfg_attr(feature = "unstable", feature(error_in_core))]
79#![cfg_attr(all(feature = "unstable", feature = "alloc"), feature(allocator_api))]
80#![cfg_attr(docsrs, feature(doc_auto_cfg))]
81#![no_std]
82// Enable some additional warnings and lints.
83#![warn(clippy::ptr_as_ptr, missing_docs, unused)]
84#![deny(clippy::all)]
85#![deny(clippy::must_use_candidate)]
86
87#[cfg(feature = "alloc")]
88extern crate alloc;
89
90// allow referring to self as ::uefi for macros to work universally (from this crate and from others)
91// see https://github.com/rust-lang/rust/issues/54647
92extern crate self as uefi;
93
94#[macro_use]
95pub mod data_types;
96#[cfg(feature = "alloc")]
97pub use self::data_types::CString16;
98pub use self::data_types::Identify;
99pub use self::data_types::{CStr16, CStr8, Char16, Char8, Event, Guid, Handle};
100pub use uefi_macros::{cstr16, cstr8, entry, guid};
101
102mod result;
103pub use self::result::{Error, Result, ResultExt, Status};
104
105pub mod table;
106
107pub mod proto;
108
109pub mod prelude;
110
111#[cfg(feature = "global_allocator")]
112pub mod global_allocator;
113
114#[cfg(feature = "logger")]
115pub mod logger;
116
117// As long as this is behind "alloc", we can simplify cfg-feature attributes in this module.
118#[cfg(feature = "alloc")]
119pub(crate) mod mem;
120
121pub(crate) mod polyfill;
122
123mod util;
124