Conversation

phip1611

Changes

  • improve documentation of exit_boot_services()
  • change signature of exit_boot_services()

Please look into the commit messages! This closes #1604

Checklist

  • Sensible git history (for example, squash "typo" or "fix" commits). See the Rewriting History guide for help.
  • Update the changelog (if necessary)

@phip1611phip1611 self-assigned this Apr 6, 2025
@phip1611phip1611 changed the title uefi/doc: improve documentation of exit_boot_services uefi/doc: improve documentation of exit_boot_services + change signature Apr 6, 2025
TL;DR: Document why exit_boot_services needs to do more than just
       call the UEFI function.

Exiting UEFI boot services requires a non-trivial sequence of steps,
including safe retrieval and finalization of the memory map. To clarify
why our exit_boot_services function is more than a thin wrapper, the
documentation has been updated accordingly.

This complexity is also reflected in the Linux source code [0].
In fact, the sequence of steps uefi-rs uses is inspired by the Linux
source code.

[0] https://.com/torvalds/linux/blob/e544a0743/drivers/firmware/efi/libstub/efi-stub-helper.c#L375
People probably want to use 99% of the time LOADER_DATA here.
Therefore, we indicate in our function signature, that people should
use the default (`None`) if they are unsure what to do here.

LOADER_DATA is also what Linux uses [0].

[0] https://elixir.bootlin.com/linux/v6.13.7/source/drivers/firmware/efi/libstub/mem.c#L24
@phip1611phip1611 mentioned this pull request Apr 6, 2025
15 tasks
@nicholasbishopnicholasbishop added this pull request to the merge queue Apr 7, 2025
Merged via the queue into main with commit c8ccc4f Apr 7, 2025
19 checks passed
@nicholasbishopnicholasbishop deleted the doc2 branch April 7, 2025 23:28
Sign up for free to join this conversation on . Already have an account? Sign in to comment
None yet
None yet

Successfully merging this pull request may close these issues.

Feature Request: Better explain the role of exit_boot_services() or rename it