From ebabb2740f53b176b4f30c2970de4472c060da05 Mon Sep 17 00:00:00 2001 From: Nicholas Bishop Date: Sun, 25 Aug 2024 10:49:42 -0400 Subject: [PATCH] book: Update boot_stages and tables Drop remaining references to SystemTable/BootServices/RuntimeServices. --- book/src/concepts/boot_stages.md | 29 +++++++-------- book/src/concepts/tables.md | 64 +++++++++++++++----------------- 2 files changed, 43 insertions(+), 50 deletions(-) diff --git a/book/src/concepts/boot_stages.md b/book/src/concepts/boot_stages.md index acb81db67..a4b56c021 100644 --- a/book/src/concepts/boot_stages.md +++ b/book/src/concepts/boot_stages.md @@ -5,20 +5,19 @@ A UEFI system goes through several distinct phases during the boot process. the scope of `uefi-rs`. It is described by the [UEFI Platform Initialization Specification], which is separate from the main UEFI Specification. -2. **Boot Services.** This is when UEFI drivers and applications are - loaded. Both the [`BootServices`] and [`RuntimeServices`] tables are - accessible. This stage typically culminates in running a bootloader - that loads an operating system. The stage ends when - [`SystemTable::exit_boot_services`] is called, putting the system in - Runtime mode. -3. **Runtime.** This stage is typically active when running an operating - system such as Linux or Windows. UEFI functionality is much more - limited in the Runtime mode. The [`BootServices`] table is no longer - accessible, but the [`RuntimeServices`] table is still - available. Once the system is in Runtime mode, it cannot return to - the Boot Services stage until after a system reset. +2. **Boot Services.** This is when UEFI drivers and applications are loaded. + Functions in both the [`boot`] module and [`runtime`] module can be used. + This stage typically culminates in running a bootloader that loads an + operating system. The stage ends when [`boot::exit_boot_services`] is called, + putting the system in Runtime mode. +3. **Runtime.** This stage is typically active when running an operating system + such as Linux or Windows. UEFI functionality is much more limited in the + Runtime mode. Functions in the [`boot`] module can no longer be used, but + functions in the [`runtime`] module are still available. Once the system is + in Runtime mode, it cannot return to the Boot Services stage until after a + system reset. [UEFI Platform Initialization Specification]: https://uefi.org/specifications -[`BootServices`]: https://docs.rs/uefi/latest/uefi/table/boot/struct.BootServices.html -[`RuntimeServices`]: https://docs.rs/uefi/latest/uefi/table/runtime/struct.RuntimeServices.html -[`SystemTable::exit_boot_services`]: https://docs.rs/uefi/latest/uefi/table/struct.SystemTable.html#method.exit_boot_services +[`boot`]: https://docs.rs/uefi/latest/uefi/boot/index.html +[`runtime`]: https://docs.rs/uefi/latest/uefi/runtime/index.html +[`boot::exit_boot_services`]: https://docs.rs/uefi/latest/uefi/boot/fn.exit_boot_services.html diff --git a/book/src/concepts/tables.md b/book/src/concepts/tables.md index 8e072c710..97cba5d4c 100644 --- a/book/src/concepts/tables.md +++ b/book/src/concepts/tables.md @@ -1,37 +1,31 @@ # Tables -UEFI has a few table structures. These tables are how you get access to -UEFI services. - -[`SystemTable`] (`EFI_SYSTEM_TABLE` in the specification) is the -top-level table that provides access to the other tables. - -[`BootServices`] (`EFI_BOOT_SERVICES` in the specification) provides -access to a wide array of services such as memory allocation, executable -loading, and optional extension interfaces called protocols. This table -is only accessible while in the Boot Services stage. - -[`RuntimeServices`] (`EFI_RUNTIME_SERVICES` in the specification) -provides access to a fairly limited set of services, including variable -storage, system time, and virtual-memory mapping. This table is -accessible during both the Boot Services and Runtime stages. - -When writing a UEFI application, you get access to the system table from -one of the arguments to the `main` entry point: - -```rust,ignore -fn main(handle: Handle, mut system_table: SystemTable) -> Status; -``` - -Then use [`SystemTable::boot_services`] and -[`SystemTable::runtime_services`] to get access to the other -tables. Once [`SystemTable::exit_boot_services`] is called, the original -system table is consumed and a new system table is returned that only -provides access to the [`RuntimeServices`] table. - -[`BootServices`]: https://docs.rs/uefi/latest/uefi/table/boot/struct.BootServices.html -[`RuntimeServices`]: https://docs.rs/uefi/latest/uefi/table/runtime/struct.RuntimeServices.html -[`SystemTable::boot_services`]: https://docs.rs/uefi/latest/uefi/table/struct.SystemTable.html#method.boot_services -[`SystemTable::exit_boot_services`]: https://docs.rs/uefi/latest/uefi/table/struct.SystemTable.html#method.exit_boot_services -[`SystemTable::runtime_services`]: https://docs.rs/uefi/latest/uefi/table/struct.SystemTable.html#method.runtime_services -[`SystemTable`]: https://docs.rs/uefi/latest/uefi/table/struct.SystemTable.html +UEFI has a few table structures. These tables are how you get access to UEFI +services. In the specification and C API, `EFI_SYSTEM_TABLE` is the top-level +table that provides access to the other tables, `EFI_BOOT_SERVICES` and +`EFI_RUNTIME_SERVICES`. + +In `uefi-rs`, these tables are modeled as modules rather than structs. The +functions in each module make use of a global pointer to the system table that +is set automatically by the [`entry`] macro. + +* [`uefi::system`] (`EFI_SYSTEM_TABLE` in the specification) provides access to +system information such as the firmware vendor and version. It can also be used +to access stdout/stderr/stdin. + +* [`uefi::boot`] (`EFI_BOOT_SERVICES` in the specification) provides access to a +wide array of services such as memory allocation, executable loading, and +optional extension interfaces called protocols. Functions in this module can +only be used while in the Boot Services stage. After [`exit_boot_services`] has +been called, these functions will panic. + +* [`uefi::runtime`] (`EFI_RUNTIME_SERVICES` in the specification) provides access +to a fairly limited set of services, including variable storage, system time, +and virtual-memory mapping. Functions in this module are accessible during both +the Boot Services and Runtime stages. + +[`entry`]: https://docs.rs/uefi/latest/uefi/attr.entry.html +[`exit_boot_services`]: https://docs.rs/uefi/latest/uefi/boot/fn.exit_boot_services.html +[`uefi::boot`]: https://docs.rs/uefi/latest/uefi/boot/index.html +[`uefi::runtime`]: https://docs.rs/uefi/latest/uefi/runtime/index.html +[`uefi::system`]: https://docs.rs/uefi/latest/uefi/system/index.html