Skip to content

Improve rom_pick_ab_update_partition docs #2577

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 5 commits into from
Jul 23, 2025
Merged

Improve rom_pick_ab_update_partition docs #2577

Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f4e4af0
Improve rom_pick_ab_update_partition docs
will-v-pi Jul 21, 2025
fea0f6d
Some review fixups
will-v-pi Jul 21, 2025
b92e552
Move function docs next to rom_pick_ab_partition
will-v-pi Jul 21, 2025
858acd6
Add \return to rom_pick_ab_partition docs
will-v-pi Jul 21, 2025
c6daaf4
Rename rom_pick_ab_update_partition -> rom_pick_ab_partition_during_u…
will-v-pi Jul 22, 2025
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
51 changes: 27 additions & 24 deletions src/rp2_common/pico_bootrom/include/pico/bootrom.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -756,6 +756,7 @@ static inline int rom_load_partition_table(uint8_t *workarea_base, uint32_t work
* \param workarea_size size of work area
* \param partition_a_num the A partition of the pair
* \param flash_update_boot_window_base the flash update base, to pick that partition instead of the normally "better" partition
* \return >= 0 the chosen partition number out of the A/B pair
*/
static inline int rom_pick_ab_partition(uint8_t *workarea_base, uint32_t workarea_size, uint partition_a_num, uint32_t flash_update_boot_window_base) {
rom_pick_ab_partition_fn func = (rom_pick_ab_partition_fn) rom_func_lookup_inline(ROM_FUNC_PICK_AB_PARTITION);
Expand All @@ -766,6 +767,32 @@ static inline int rom_pick_ab_partition(uint8_t *workarea_base, uint32_t workare
return rc;
}

/*! \brief Pick A/B partition without disturbing any in progress Flash Update boot or TBYB boot
* \ingroup pico_bootrom
*
* This will call \ref rom_pick_ab_partition() using the `flash_update_boot_window_base` from the current boot, while performing extra checks to prevent disrupting
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we aren't copying the text from rom_pick_ab_partiton() I think we should focus on the fact that this performs the same function as rom_pick_ab_partiont(), but does a few other things. I guess this is implicit, but using "calls" just makes me think the documentation is just a precis of the function code

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've replaced "call" with "perform the same function as" to make that clear

* a main image TBYB boot. It requires the same minimum workarea size as \ref rom_pick_ab_partition().
*
* This should be used instead of \ref rom_pick_ab_partition() when performing a Flash Update Boot before calling \ref rom_explicit_buy(), and can still be
* used without issue when a Flash Update Boot is not in progress.
*
* This function is necessary because if an `explicit_buy` is pending then calling `pick_ab_partition` would clear the saved flash erase address for
* the version downgrade, so the required erase of the other partition would not occur when `explicit_buy` is called. This function saves and restores
* that address to prevent this issue, and returns `BOOTROM_ERROR_NOT_PERMITTED` if the partition chosen by `pick_ab_partition` also requires a flash
* erase version downgrade (as you can't erase two partitions with one `explicit_buy` call).
*
* This function also checks that the chosen partition contained a valid image (e.g. a signed image when using secure boot), and returns
* `BOOTROM_ERROR_NOT_FOUND` if it does not.
*
* \param workarea_base base address of work area
* \param workarea_size size of work area
* \param partition_a_num the A partition of the pair
* \return >= 0 the partition number picked by \ref rom_pick_ab_partition()
* BOOTROM_ERROR_NOT_PERMITTED if not possible to do an update correctly, e.g. if both main image and data image are TBYB
* BOOTROM_ERROR_NOT_FOUND if the chosen partition failed verification
*/
int rom_pick_ab_update_partition(uint32_t *workarea_base, uint32_t workarea_size, uint partition_a_num);

/*!
* \brief Get B partition
* \ingroup pico_bootrom
Expand Down Expand Up @@ -1094,30 +1121,6 @@ static inline int rom_get_last_boot_type(void) {
*/
int rom_add_flash_runtime_partition(uint32_t start_offset, uint32_t size, uint32_t permissions);

/*! \brief Pick A/B partition without disturbing any in progress update or TBYB boot
* \ingroup pico_bootrom
*
* This will call `rom_pick_ab_partition` using the `flash_update_boot_window_base` from the current boot, while performing extra checks to prevent disrupting
* a main image TBYB boot. It requires the same minimum workarea size as `rom_pick_ab_partition`.
* \see rom_pick_ab_partition()
*
* For example, if an `explicit_buy` is pending then calling `pick_ab_partition` would normally clear the saved flash erase address for the version downgrade,
* so the required erase of the other partition would not occur when `explicit_buy` is called - this function saves and restores that address to prevent this
* issue, and returns `BOOTROM_ERROR_NOT_PERMITTED` if the partition chosen by `pick_ab_partition` also requires a flash erase version downgrade (as you can't
* erase 2 partitions with one `explicit_buy` call).
*
* It also checks that the chosen partition contained a valid image (e.g. a signed image when using secure boot), and returns `BOOTROM_ERROR_NOT_FOUND`
* if it does not.
*
* \param workarea_base base address of work area
* \param workarea_size size of work area
* \param partition_a_num the A partition of the pair
* \return >= 0 the partition number picked
* BOOTROM_ERROR_NOT_PERMITTED if not possible to do an update correctly, e.g. if both main image and data image are TBYB
* BOOTROM_ERROR_NOT_FOUND if the chosen partition failed verification
*/
int rom_pick_ab_update_partition(uint32_t *workarea_base, uint32_t workarea_size, uint partition_a_num);

#endif

#ifdef __cplusplus
Expand Down
Loading