docs: PORTING: Document the remaining required flash APIs - #2825
Merged
nordicjm merged 1 commit intoAug 11, 2026
Conversation
The list of flash APIs a system must provide is missing three functions that common code in boot/bootutil calls and that no in-tree implementation outside a port supplies: flash_area_get_sector() 8 call sites in boot/bootutil flash_device_base() 2 call sites flash_area_id_from_image_slot() 2 call sites A port written against the current document therefore fails to link, and flash_area_get_sector() in particular is easy to get subtly wrong: both its off parameter and the fs_off it writes back are relative to the flash area rather than to the device, and an implementation using device-absolute offsets prevents the sector walk in boot_erase_region() from terminating. Add a note describing that, and point at the Zephyr implementation as a reference. Signed-off-by: Daniel Riege <daniel.riege99@gmail.com>
nordicjm
approved these changes
Aug 10, 2026
de-nordic
approved these changes
Aug 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds three functions to the list of flash APIs a system must provide in
docs/PORTING.md, and a note on the offset semantics of one of them.Why
The document's "main, also required, set of API functions" is missing three
functions that common code in
boot/bootutilcalls unconditionally, and thatno implementation outside a port supplies:
boot/bootutilflash_area_get_sector()flash_device_base()flash_area_id_from_image_slot()All three are declared in
flash_map_backend.hand implemented per port (seeboot/zephyr/flash_map_extended.c); none has a definition inboot/bootutil.A port written against the current document therefore fails to link, and the
document gives no hint as to what is missing.
flash_area_get_sector()is worth more than a one-line entry, because it iseasy to implement in a way that links and then misbehaves: both the
offparameter and the
fs_offwritten back are relative to the flash area, notto the device. An implementation that treats them as device-absolute — which is
a natural first guess — leaves the sector walk in
boot_erase_region()unableto reach its termination condition. The added note states the convention and
points at the Zephyr implementation as a reference.
Notes
docs/contributing.md("Release notes are generallynot needed for: Some documentation improvements").
flash_area_id_to_image_slot()was deliberately not added: it has nocall sites in
boot/bootutiland is not declared inflash_map_backend.h,so it does not appear to be required of a port.