Skip to content

Commit

Permalink
Merge pull request rust-osdev#1351 from nicholasbishop/bishop-book-up…
Browse files Browse the repository at this point in the history
…dates

book: Update boot_stages and tables
  • Loading branch information
nicholasbishop authored Aug 25, 2024
2 parents 26d3b74 + 3c02e26 commit 2708c3f
Show file tree
Hide file tree
Showing 2 changed files with 44 additions and 51 deletions.
31 changes: 15 additions & 16 deletions book/src/concepts/boot_stages.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,23 +2,22 @@

A UEFI system goes through several distinct phases during the boot process.
1. **Platform Initialization.** This early-boot phase is mostly outside
the scope of `uefi-rs`. It is described by the [UEFI Platform
the scope of the `uefi` crate. 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
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 the `uefi` crate, 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 2708c3f

Please sign in to comment.