From 42815be38ffa214614d0bad57b352f30ee255655 Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Sat, 24 Aug 2024 16:50:34 +0200 Subject: [PATCH 1/3] 2024-08: uefi v0.31 significant changes --- content/this-month/2024-08/index.md | 102 +++++++++++++++++++++++++++- 1 file changed, 100 insertions(+), 2 deletions(-) diff --git a/content/this-month/2024-08/index.md b/content/this-month/2024-08/index.md index ba03d829..c6a862a0 100644 --- a/content/this-month/2024-08/index.md +++ b/content/this-month/2024-08/index.md @@ -4,7 +4,7 @@ date = 2024-09-03 [extra] month = "August 2024" -editors = ["phil-opp"] +editors = ["phil-opp", "phip1611"] +++ Welcome to a new issue of _"This Month in Rust OSDev"_. In these posts, we give a regular overview of notable changes in the Rust operating system development ecosystem. @@ -101,6 +101,105 @@ In this section, we give an overview of notable changes to the projects hosted u <> --> +### [`uefi`](https://github.com/rust-osdev/uefi-rs) +Maintained by [@GabrielMajeri](https://github.com/GabrielMajeri), [@nicholasbishop](https://github.com/nicholasbishop), and [@phip1611](https://github.com/phip1611) + +`uefi` makes it easy to develop Rust software that leverages safe, convenient, +and performant abstractions for UEFI functionality. Recently, we released +version `v0.31` with some notable changes: + +1. We introduced a completely new API to access boot and runtime services +2. We reorganized the MemoryMap-related types. +3. We reorganized the repository README's and `lib.rs` files (documentation for + docs.rs) +4. We talk about how the `std` implementation for UEFI targets compares to + `uefi` and how both can be used together. + +### 1. New API: Freestanding Functions API Change + +We are planning a massive API change and introduced a new replacement API in +release `v0.31`. The old API co-exists and will be marked as +`#[deprecated]` in `0.32`. The new API will make it easier to call boot or +runtime services without having to pass `&BootServices` around all the time. + +The typical use-case of our library users is to write UEFI image with code +leveraging boot services and exiting them. Next, control is handed over to the +next step, which is typically a kernel of an OS. These UEFI images typically +are "99% code" using boot services, until they are exited. + +Although the old API design ensures via the type system that no boot +services can be called after they have been exited, the test of time has proven +that this adds unjustified complexity without bringing much real value add. + +Instead, with the new API, which we provide **additionally** at this point, +one can use freestanding functions which are behind the new modules: + +- `uefi::system`: is a new module that provides freestanding functions for + accessing fields of the global system table. +- `uefi::boot`: + is a new module that provides freestanding functions for boot services using + the global system table. +- `uefi::runtime`: is a new module that provides freestanding functions for + runtime services using the global system table. + +The freestanding functions itself are close to the originals ones but without +`&BootServices` or `&RuntimeServices` parameters, as you can see for example +[here](https://github.com/rust-osdev/uefi-rs/pull/1344/files#diff-46f1e3c04d719fff471faf35c4d218430e1d664ac0a0fab9d2c15870c2d0f066). + +The new API design solves API inconsistencies and restrictions already existing +so far, and makes the overall handling a lot easier. This comes with the costs +that functions may panic, if the boot services were exited but one tries to use +them. However, the massive API simplification justifies this. + +Find more and follow the progress and discussions on: +- [the GitHub Issue](https://github.com/rust-osdev/uefi-rs/issues/893#issuecomment-2241610633). +- [The function Migration Guide](https://github.com/rust-osdev/uefi-rs/blob/main/docs/funcs_migration.md) + +#### 2. Memory Map Refactoring + +TL;DR: What used to return `MemoryMap<'buf>` in the API, now returns +`MemoryMapOwned`. Additionally, you can parse a chunk of memory using +`MemoryMapRef` or `MemoryMapRefMut`. + +We put significant effort into refactoring our abstractions for the UEFI memory +map. These started in release v0.29 and were finalized in release v0.31. +Instead of one `MemoryMap<'buf>` type, we now have the traits `MemoryMap` and +`MemoryMapMut` along with the implementations `MemoryMapRef`, `MemoryMapRefMut`, +and `MemoryMapOwned`. It is recommended to work with the specific +implementations, as the main purpose for the traits is only to enforce a +consistent API for these three implementations. This gives users the +flexibility to cover all possible use cases one can have with an UEFI memory +map. Read more: +- [#1175](https://github.com/rust-osdev/uefi-rs/pull/1175) +- [#1251](https://github.com/rust-osdev/uefi-rs/pull/1251) +- [#1240](https://github.com/rust-osdev/uefi-rs/pull/1240) +- [#1263](https://github.com/rust-osdev/uefi-rs/pull/1263) + +In any case, obtaining the memory map from UEFI is hidden behind the +public API of the crate, but we made it very easy to read/parse it in all +possible scenarios! + +#### 3. & 4.: Documentation Reorganization + +We put notable work into our README and `lib.rs` files to improve the +structure of our documentation. The main value-add and improvement is that we +clearly, directly, and precisely talk about: + +- What is `uefi`? +- Which problems does it solve? +- How can it be used? +- How does it compare to the ecosystem, such as `std` for Rust targets? + +To see an example how `uefi` and `std` can be used together, please head to +[our repository](https://github.com/rust-osdev/uefi-rs/tree/main/uefi-std-example). + +### Other + +There were also a ton of other interesting fixes, changes, and additions! +Check out our [Changelog](https://github.com/rust-osdev/uefi-rs/blob/main/uefi/CHANGELOG.md). + +We merged the following PRs this month: + ## Other Projects @@ -115,7 +214,6 @@ In this section, we describe updates to Rust OS projects that are not directly r ...<>... --> - ## Join Us? Are you interested in Rust-based operating system development? Our `rust-osdev` organization is always open to new members and new projects. Just let us know if you want to join! A good way for getting in touch is our [Zulip chat](https://rust-osdev.zulipchat.com). From cb7d42ce326d86eb593bb0b3d3c07fee2ecd58f2 Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Sun, 25 Aug 2024 12:36:18 +0200 Subject: [PATCH 2/3] Update content/this-month/2024-08/index.md Co-authored-by: Nicholas Bishop --- content/this-month/2024-08/index.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/content/this-month/2024-08/index.md b/content/this-month/2024-08/index.md index c6a862a0..15adc81c 100644 --- a/content/this-month/2024-08/index.md +++ b/content/this-month/2024-08/index.md @@ -122,10 +122,12 @@ release `v0.31`. The old API co-exists and will be marked as `#[deprecated]` in `0.32`. The new API will make it easier to call boot or runtime services without having to pass `&BootServices` around all the time. -The typical use-case of our library users is to write UEFI image with code -leveraging boot services and exiting them. Next, control is handed over to the -next step, which is typically a kernel of an OS. These UEFI images typically -are "99% code" using boot services, until they are exited. +The typical use-case of our library users is to write a UEFI bootloader +application that heavily leverages boot services. Then control is handed over to +the next stage, which is typically the kernel of an OS. Boot services are +usually exited either just prior to launching the kernel or by the kernel +itself. In any case, the UEFI application spends almost all of its time with +boot services active. Although the old API design ensures via the type system that no boot services can be called after they have been exited, the test of time has proven From 0613104264ed458b717cc03d34859f1efd2f910e Mon Sep 17 00:00:00 2001 From: Philipp Schuster Date: Sun, 25 Aug 2024 12:36:26 +0200 Subject: [PATCH 3/3] Update content/this-month/2024-08/index.md Co-authored-by: Nicholas Bishop --- content/this-month/2024-08/index.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/content/this-month/2024-08/index.md b/content/this-month/2024-08/index.md index 15adc81c..32f44fea 100644 --- a/content/this-month/2024-08/index.md +++ b/content/this-month/2024-08/index.md @@ -110,10 +110,9 @@ version `v0.31` with some notable changes: 1. We introduced a completely new API to access boot and runtime services 2. We reorganized the MemoryMap-related types. -3. We reorganized the repository README's and `lib.rs` files (documentation for - docs.rs) -4. We talk about how the `std` implementation for UEFI targets compares to - `uefi` and how both can be used together. +3. We reorganized and improved the documentation, and also added documentation + about how the `std` implementation for UEFI targets compares to `uefi` and + how both can be used together. ### 1. New API: Freestanding Functions API Change