doc: update READMEs and CHANGELOGs

Author: phip1611

README.md

@@ -23,9 +23,10 @@ This repository provides various crates:
 
 - `uefi-raw`: Raw Rust UEFI bindings for basic structures and functions.
 - `uefi`: High-level wrapper around various low-level UEFI APIs. \
-  Most probably, you want to use this crate.
-- `uefi-services`: Optional Rust convenience with a global allocator and a
-  `log`-based logger implementation.
+  Offers various optional features for typical Rust convenience, such as a
+  Logger and an Allocator. (_This is what you are usually looking for!_)
+- `uefi-macros`: Helper macros. Used by `uefi`.
+
 
 You can use the abstractions for example to:
 
@@ -44,6 +45,8 @@ our Rust library.
 
 ## User Documentation
 
+<!-- KEEP IN SYNC WITH uefi/README -->
+
 For a quick start, please check out [the UEFI application template](template).
 
 The [uefi-rs book] contains a tutorial, how-tos, and overviews of some important
@@ -53,7 +56,6 @@ UEFI concepts. Reference documentation for the various crates can be found on
 - [docs.rs/uefi](https://docs.rs/uefi)
 - [docs.rs/uefi-macros](https://docs.rs/uefi-macros)
 - [docs.rs/uefi-raw](https://docs.rs/uefi-raw)
-- [docs.rs/uefi-services](https://docs.rs/uefi-services)
 
 For additional information, refer to the [UEFI specification][spec].
 

uefi/CHANGELOG.md

@@ -4,6 +4,11 @@
 - Added `Timestamp` protocol.
 - Added `UnalignedSlice::as_ptr`.
 - Added common derives for `Event` and `Handle`.
+- `uefi::helpers::init` with the functionality that used to be in
+  `uefi::services`. With that, new features were added:
+  - `global_allocator`
+  - `panic_handler`
+  - `qemu`
 
 # uefi - 0.27.0 (2024-03-17)
 

uefi/Cargo.toml

@@ -27,7 +27,7 @@ panic_handler = []
 # were observed on the VirtualBox UEFI implementation (see uefi-rs#121).
 # In those cases, this feature can be excluded by removing the default features.
 panic-on-logger-errors = []
-qemu = ["dep:qemu-exit"]
+qemu = ["dep:qemu-exit", "panic_handler"] # panic_handler: logical, not technical dependency
 
 [dependencies]
 bitflags.workspace = true

uefi/README.md

@@ -2,47 +2,35 @@
 
 [![Crates.io](https://img.shields.io/crates/v/uefi)](https://crates.io/crates/uefi)
 [![Docs.rs](https://docs.rs/uefi/badge.svg)](https://docs.rs/uefi)
-![Stars](https://img.shields.io/github/stars/rust-osdev/uefi-rs)
 ![License](https://img.shields.io/github/license/rust-osdev/uefi-rs)
 ![Build status](https://github.com/rust-osdev/uefi-rs/workflows/Rust/badge.svg)
+![Stars](https://img.shields.io/github/stars/rust-osdev/uefi-rs)
 
-[UEFI] is the successor to the BIOS. It provides an early boot environment for
-OS loaders, hypervisors and other low-level applications.
-
-The `uefi` crate makes it easy to:
-- Write UEFI applications in Rust (for `i686`, `x86_64`, or `aarch64`)
-- Call UEFI functions from an OS (usually built with a [custom target][rustc-custom])
-
-The objective is to provide **safe** and **performant** wrappers for UEFI interfaces,
-and allow developers to write idiomatic Rust code.
 
-Check out the [UEFI application template] for a quick start.
+For an introduction to the `uefi-rs` project and documentation, please refer to
+our main [README].
 
-[UEFI]: https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface
-[rustc-custom]: https://doc.rust-lang.org/rustc/targets/custom.html
-[UEFI application template]: https://github.com/rust-osdev/uefi-rs/tree/HEAD/template
+[README]: https://github.com/rust-osdev/uefi-rs/blob/main/README.md
 
 ## Optional features
 
 This crate's features are described in [`src/lib.rs`].
 
-See also the [`uefi-services`] crate, which provides a panic handler and
-initializes the `global_allocator` and `logger` features.
-
 [`src/lib.rs`]: src/lib.rs
-[`uefi-services`]: https://crates.io/crates/uefi-services
 
-## Documentation
+## User Documentation
+
+<!-- KEEP IN SYNC WITH MAIN README -->
 
-The [uefi-rs book] contains a tutorial, how-tos, and overviews of some
-important UEFI concepts.
+For a quick start, please check out [the UEFI application template](template).
+
+The [uefi-rs book] contains a tutorial, how-tos, and overviews of some important
+UEFI concepts. Reference documentation for the various crates can be found on
+[docs.rs]:
 
-Reference documentation can be found on docs.rs:
 - [docs.rs/uefi](https://docs.rs/uefi)
 - [docs.rs/uefi-macros](https://docs.rs/uefi-macros)
-- [docs.rs/uefi-services](https://docs.rs/uefi-services)
-
-For additional information, refer to the [UEFI specification][spec].
+- [docs.rs/uefi-raw](https://docs.rs/uefi-raw)
 
 [spec]: http://www.uefi.org/specifications
 [uefi-rs book]: https://rust-osdev.github.io/uefi-rs/HEAD

uefi/src/lib.rs

@@ -7,6 +7,12 @@
 //! Feel free to file bug reports and questions in our [issue tracker], and [PR
 //! contributions][contributing] are also welcome!
 //!
+//! # Interaction with uefi services
+//!
+//! With this crate you can write code for the pre- and post-exit boot services
+//! epochs. However, the `uefi` crate unfolds its true potential when
+//! interacting with UEFI boot services.
+//!
 //! # Crate organisation
 //!
 //! The top-level module contains some of the most used types and macros,
@@ -51,24 +57,26 @@
 //! - `logger`: Logging implementation for the standard [`log`] crate
 //!   that prints output to the UEFI console. No buffering is done; this
 //!   is not a high-performance logger.
+//! - `panic_handler`: Add a default panic handler that logs to `stdout`.
 //! - `panic-on-logger-errors` (enabled by default): Panic if a text
 //!   output error occurs in the logger.
 //! - `unstable`: Enable functionality that depends on [unstable
 //!   features] in the nightly compiler.
 //!   As example, in conjunction with the `alloc`-feature, this gate allows
 //!   the `allocator_api` on certain functions.
+//! - `qemu`: Enable some code paths to adapt their execution when executed
+//!   in QEMU, such as using the special `qemu-exit` device when the panic
+//!   handler is called.
 //!
-//! The `global_allocator` and `logger` features require special
-//! handling to perform initialization and tear-down. The
-//! [`uefi-services`] crate provides an `init` method that takes care of
-//! this.
+//! Some of these features, such as the `logger` or `panic_handler` features,
+//! only unfold their potential when you invoke `uefi::helpers::init` as soon
+//! as possible in your application.
 //!
 //! [Rust UEFI Book]: https://rust-osdev.github.io/uefi-rs/HEAD/
 //! [UEFI]: https://uefi.org/
 //! [`BootServices`]: table::boot::BootServices
 //! [`GlobalAlloc`]: alloc::alloc::GlobalAlloc
 //! [`SystemTable`]: table::SystemTable
-//! [`uefi-services`]: https://crates.io/crates/uefi-services
 //! [`unsafe_protocol`]: proto::unsafe_protocol
 //! [contributing]: https://github.com/rust-osdev/uefi-rs/blob/main/CONTRIBUTING.md
 //! [issue tracker]: https://github.com/rust-osdev/uefi-rs/issues

uefi/src/table/system.rs

@@ -225,7 +225,6 @@ impl SystemTable<Boot> {
     ///
     /// [`allocator::exit_boot_services`]: crate::allocator::exit_boot_services
     /// [`Logger::disable`]: crate::logger::Logger::disable
-    /// [`uefi_services::init`]: https://docs.rs/uefi-services/latest/uefi_services/fn.init.html
     #[must_use]
     pub fn exit_boot_services(
         self,