Repository: raspberrypi/pico-sdk
File: src/rp2_common/pico_bootrom/include/pico/bootrom.h (C/C++)

Code before:
 * number of its "B" partition if any).
 * 
 * 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.
 * 
 * \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);
    if (!bootrom_try_acquire_lock(BOOTROM_LOCK_SHA_256))
        return BOOTROM_ERROR_LOCK_REQUIRED;
    int rc = func(workarea_base, workarea_size, partition_a_num, flash_update_boot_window_base);
    bootrom_release_lock(BOOTROM_LOCK_SHA_256);
    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
 * 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

Review comment (suggestion):
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

Code after:
 * number of its "B" partition if any).
 * 
 * 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_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);
    if (!bootrom_try_acquire_lock(BOOTROM_LOCK_SHA_256))
        return BOOTROM_ERROR_LOCK_REQUIRED;
    int rc = func(workarea_base, workarea_size, partition_a_num, flash_update_boot_window_base);
    bootrom_release_lock(BOOTROM_LOCK_SHA_256);
    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