diff --git a/content/this-month/2024-08/index.md b/content/this-month/2024-08/index.md index ba03d829..32f44fea 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,106 @@ 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 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 + +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 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 +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 +215,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).