Skip to content

docs: PORTING: Document the remaining required flash APIs - #2825

Merged
nordicjm merged 1 commit into
mcu-tools:mainfrom
danielriege:docs-porting-missing-flash-api
Aug 11, 2026
Merged

docs: PORTING: Document the remaining required flash APIs#2825
nordicjm merged 1 commit into
mcu-tools:mainfrom
danielriege:docs-porting-missing-flash-api

Conversation

@danielriege

Copy link
Copy Markdown
Contributor

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/bootutil calls unconditionally, and that
no implementation outside a port supplies:

Function Call sites in boot/bootutil
flash_area_get_sector() 8
flash_device_base() 2
flash_area_id_from_image_slot() 2

All three are declared in flash_map_backend.h and implemented per port (see
boot/zephyr/flash_map_extended.c); none has a definition in boot/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 is
easy to implement in a way that links and then misbehaves: both the off
parameter and the fs_off written back are relative to the flash area, not
to the device. An implementation that treats them as device-absolute — which is
a natural first guess — leaves the sector walk in boot_erase_region() unable
to reach its termination condition. The added note states the convention and
points at the Zephyr implementation as a reference.

Notes

  • Documentation only; no code or behavioural change.
  • No release note stub, per docs/contributing.md ("Release notes are generally
    not needed for: Some documentation improvements").
  • flash_area_id_to_image_slot() was deliberately not added: it has no
    call sites in boot/bootutil and is not declared in flash_map_backend.h,
    so it does not appear to be required of a port.

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>
@danielriege
danielriege requested a review from d3zd3z as a code owner August 6, 2026 09:33
@nordicjm
nordicjm merged commit 40e9c30 into mcu-tools:main Aug 11, 2026
87 checks passed
@danielriege
danielriege deleted the docs-porting-missing-flash-api branch August 11, 2026 08:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants