Improve rom_pick_ab_update_partition docs (#2577)

* 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"

Author: will-v-pi

src/rp2_common/pico_bootrom/bootrom.c

@@ -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;

src/rp2_common/pico_bootrom/include/pico/bootrom.h

@@ -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

src/rp2_common/pico_cyw43_driver/cyw43_driver.c

@@ -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