Skip to content

Commit

Permalink
book: Update boot_stages and tables
Browse files Browse the repository at this point in the history 
Drop remaining references to SystemTable/BootServices/RuntimeServices.
  • Loading branch information
@nicholasbishop
nicholasbishop committed Aug 25, 2024
1 parent f529325 commit ebabb27
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 50 deletions.
29 changes: 14 additions & 15 deletions book/src/concepts/boot_stages.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
64 changes: 29 additions & 35 deletions book/src/concepts/tables.md
View file
Original file line number Diff line number Diff line change
@@ -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<Boot>) -> 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

0 comments on commit ebabb27

Please sign in to comment.