From f1b53392ba199ef35a9fa0291a6195883eddb38c Mon Sep 17 00:00:00 2001 From: Nicholas Bishop Date: Tue, 13 Aug 2024 12:33:30 -0400 Subject: [PATCH] Update funcs_migration doc Change the text to indicate that we don't plan to deprecate until a later release, but the new APIs are available for use. --- docs/funcs_migration.md | 23 +++++++++++++---------- uefi/CHANGELOG.md | 2 +- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/docs/funcs_migration.md b/docs/funcs_migration.md index 950778358..8459e633d 100644 --- a/docs/funcs_migration.md +++ b/docs/funcs_migration.md @@ -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: @@ -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. diff --git a/uefi/CHANGELOG.md b/uefi/CHANGELOG.md index 34580f4fc..23891d54e 100644 --- a/uefi/CHANGELOG.md +++ b/uefi/CHANGELOG.md @@ -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