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

Code before:
}

/*! \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()
 * 
 * This should be used instead of `rom_pick_ab_partition` when performing a Flash Update Boot before calling `explicit_buy`, and can still be used without
 * issue when a Flash Update Boot is not in progress.
 * 
 * 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
}
#endif


Review comment (suggestion):
Commenting on a wider scope:

* any in progress update or TBYB boot" perhaps "any in progress Flash Update boot or TBYB boot" (note boot repeated), though a TBYB is a flash update boot, so maybe TBYB operation IDK
* I'd put this function right after rom_pick_ab_partition in the header
* we should use \ref to refer to other functions not `func` (cc @lurch)
* arguably "normally" is "always" so really you could lose the word
* bit of a weird '-' in the middle of the For example sentence
* erase 2 partitions -> erase two partitions
* It also checks" It is a big dangly here (perhaps this function)

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

#endif

#ifdef __cplusplus
}
#endif