Skip to content

Update funcs_migration doc #1329

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 13, 2024
Merged

Update funcs_migration doc #1329

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 13 additions & 10 deletions docs/funcs_migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
# API migration: Deprecating SystemTable/BootServices/RuntimeServices

Starting in uefi-0.31.0, a significant API change has been introduced. We are
transitioning away from modeling UEFI tables with structs, and instead providing
an API based on freestanding functions. These functions make use of a global
system table pointer that is set automatically by the `entry` macro.
We are in the process of introducing a significant API change in the `uefi`
crate. We are transitioning away from modeling UEFI tables with structs, and
instead providing an API based on freestanding functions. These functions make
use of a global system table pointer that is set automatically by the `entry`
macro.

A short example:

Expand All @@ -26,16 +27,18 @@ are replacing, so in most cases migration should be as simple as updating
imports and calling the freestanding function instead of a method on
`SystemTable`, `BootServices`, or `RuntimeServices`.

As of uefi-0.31.0, a few places in the API still require a reference to
`BootServices`. You can retrieve one by calling
`uefi::table::system_table_boot().boot_services()`.

In uefi-0.31.0, the old API has been deprecated, but can still be used. It will
be fully removed in a later release.
You can retrieve a global `SystemTable` with `uefi::table::system_table_boot` or
`uefi::table::system_table_runtime` to help ease the transition.

If you run into any issues with this migration, please feel free to chat with us
on [Zulip] or file an [issue].

## Timeline

As of uefi-0.31, the new API has been introduced alongside the old struct-based
API. We plan to deprecate the old API in the release after that, and then fully
remove the old API in a later release.

## Reason for the change

See [issue #893][RFC] for the discussion that lead to this change.
Expand Down
2 changes: 1 addition & 1 deletion uefi/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# uefi - [Unreleased]

See [Deprecating SystemTable/BootServices/RuntimeServices][funcmigrate] for
details of a significant change to the API in this release.
details of the new `system`/`boot`/`runtime` modules, and upcoming deprecations.

## Added
- `uefi::system` is a new module that provides freestanding functions for
Expand Down