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

Code before:
static inline int rom_get_last_boot_type(void) {
    int rc = rom_get_last_boot_type_with_chained_flag();
    if (rc >= 0) rc &= ~BOOT_TYPE_CHAINED_FLAG;
    return rc;
}

/*! \brief  Add a runtime partition to the partition table to specify flash permissions
 * \ingroup pico_bootrom
 *
 * Note that a partition is added to the runtime view of the partition table maintained by the bootrom if there is space to do so
 *
 * Note that these permissions cannot override the permissions for any pre-existing partitions, as permission matches are made on a first partition found basis.
 *
 * @param start_offset the start_offset into flash in bytes (must be a multiple of 4K)
 * @param size the size in byte (must be a multiple of 4K)
 * @param permissions the bitwise OR of permissions from PICOBIN_PARTITION_PERMISSION_ constants, e.g. \ref PICOBIN_PARTITION_PERMISSION_S_R_BITS from boot/picobin.h
 * @return >= 0 the partition number added if
 *         PICO_ERROR_BAD_ALIGNMENT if the start_offset or size aren't multiples of 4K.
 *         PICO_ERROR_INVALID_ARG if the start_offset or size are out of range, or invalid permission bits are set.
 */
int rom_add_flash_runtime_partition(uint32_t start_offset, uint32_t size, uint32_t permissions);

/*! \brief  Pick A/B partition for a separate partition
 * \ingroup pico_bootrom
 *
 * This will call `rom_pick_ab_partition` with the current `flash_update_boot_window_base`, while performing extra checks to prevent disrupting a main image TBYB.
 * It requires the same minimum workarea size as `rom_pick_ab_partition`.
 * 
 * For example, if an `explicit_buy` is pending then calling `pick_ab_partition` would normally clear the saved `flash_erase_addr` so the required erase 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 (eg 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, eg 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
}
#endif

#endif // !__ASSEMBLER__

Review comment (suggestion):
Thanks for adding the extra wording. Should the user always prefer using `rom_pick_ab_update_partition` over `rom_pick_ab_partition`, or do they serve different purposes?
Probably worth adding a `\see rom_pick_ab_partition` here? (and vice-versa in the other function's doxygen)

Code after:
        memcpy(info, &result[1], sizeof(boot_info_t));
        return true;
    } else {
        return false;
    }
}

static inline int rom_get_last_boot_type_with_chained_flag(void) {
    uint32_t result[5];
    int words_returned = rom_get_sys_info(result, 5, SYS_INFO_BOOT_INFO);
    if (words_returned == count_of(result) && result[0] == SYS_INFO_BOOT_INFO) {
        // todo use struct
        return (int)((result[1] & 0xff00u) >> 8);
    } else {
        return PICO_ERROR_INVALID_DATA;
    }
}

// BOOT_TYPE_NORMAL       0x0
// BOOT_TYPE_BOOTSEL      0x2
// BOOT_TYPE_RAM_IMAGE    0x3
// BOOT_TYPE_FLASH_UPDATE 0x4
// BOOT_TYPE_PC_SP        0xd
static inline int rom_get_last_boot_type(void) {
    int rc = rom_get_last_boot_type_with_chained_flag();
    if (rc >= 0) rc &= ~BOOT_TYPE_CHAINED_FLAG;
    return rc;
}

/*! \brief  Add a runtime partition to the partition table to specify flash permissions
 * \ingroup pico_bootrom
 *
 * Note that a partition is added to the runtime view of the partition table maintained by the bootrom if there is space to do so
 *
 * Note that these permissions cannot override the permissions for any pre-existing partitions, as permission matches are made on a first partition found basis.
 *
 * @param start_offset the start_offset into flash in bytes (must be a multiple of 4K)
 * @param size the size in byte (must be a multiple of 4K)
 * @param permissions the bitwise OR of permissions from PICOBIN_PARTITION_PERMISSION_ constants, e.g. \ref PICOBIN_PARTITION_PERMISSION_S_R_BITS from boot/picobin.h
 * @return >= 0 the partition number added if
 *         PICO_ERROR_BAD_ALIGNMENT if the start_offset or size aren't multiples of 4K.
 *         PICO_ERROR_INVALID_ARG if the start_offset or size are out of range, or invalid permission bits are set.
 */
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()