mirror/pico-sdk
1
0
Fork 0
mirror of https://github.com/raspberrypi/pico-sdk.git synced 2025-12-10 07:14:36 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Improve rom_pick_ab_update_partition docs (#2577)

Browse source 
* Improve rom_pick_ab_update_partition docs

* Some review fixups

Add more `\ref`s and tidy up wording

* Move function docs next to rom_pick_ab_partition

* Add \return to rom_pick_ab_partition docs

* Rename rom_pick_ab_update_partition -> rom_pick_ab_partition_during_update and replace "call"
This commit is contained in:
will-v-pi 2025-07-23 15:13:10 +01:00 • committed by GitHub
parent bf4906b1b5
commit 58d000f210
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 30 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
src/rp2_common/pico_bootrom/bootrom.c
View file

@ -112,7 +112,7 @@ int rom_add_flash_runtime_partition(uint32_t start_offset, uint32_t size, uint32
return PICO_ERROR_INSUFFICIENT_RESOURCES;
}
int rom_pick_ab_update_partition(uint32_t *workarea_base, uint32_t workarea_size, uint partition_a_num) {
int rom_pick_ab_partition_during_update(uint32_t *workarea_base, uint32_t workarea_size, uint partition_a_num) {
#if !PICO_RP2040
// Generated from adding the following code into the bootrom
// scan_workarea_t* scan_workarea = (scan_workarea_t*)workarea;

53
src/rp2_common/pico_bootrom/include/pico/bootrom.h
View file

@ -750,12 +750,13 @@ static inline int rom_load_partition_table(uint8_t *workarea_base, uint32_t work
* NOTE: This method does not look at owner partitions, only the A partition passed and it's corresponding B partition.
*
* NOTE: You should not call this method directly when performing a Flash Update Boot before calling `explicit_buy`, as it may prevent
* any version downgrade from occuring - instead see \ref rom_pick_ab_update_partition() which wraps this function.
* any version downgrade from occuring - instead see \ref rom_pick_ab_partition_during_update() which wraps this function.
*
* \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
* \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);
@ -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 perform the same function as \ref 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 \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_partition_during_update(uint32_t *workarea_base, uint32_t workarea_size, uint partition_a_num);
/*!
* \brief Get B partition
* \ingroup pico_bootrom
@ -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

2
src/rp2_common/pico_cyw43_driver/cyw43_driver.c
View file

@ -152,7 +152,7 @@ bool cyw43_driver_init(async_context_t *context) {
rom_set_bootrom_stack(&stack);
#endif
uint32_t* workarea = malloc(0x1000);
picked_p = rom_pick_ab_update_partition(workarea, 0x1000, picked_p);
picked_p = rom_pick_ab_partition_during_update(workarea, 0x1000, picked_p);
free(workarea);
#ifdef __riscv
// Reset bootrom stack