Loading...
Searching...
No Matches
bootrom.h File Reference
#include "pico.h"
#include "pico/bootrom_constants.h"
#include <string.h>
#include "pico/bootrom/lock.h"
#include "pico/flash.h"

Go to the source code of this file.

Data Structures

struct  rom_helper_flash_op_params_t
 Parameters for the flash operation helper used with flash_safe_execute. More...
struct  rom_helper_explicit_buy_params_t
 Parameters for the explicit buy helper used with flash_safe_execute. More...
struct  boot_info_t
 Boot information returned by the bootrom SYS_INFO_BOOT_INFO query. More...

Macros

#define rom_hword_as_ptr(rom_address)
#define PICO_BOOTROM_WORKAROUND_RP2350_A2_ACTIVITY_LED_BUG   1

Typedefs

typedef void(* rom_reset_usb_boot_fn) (uint32_t, uint32_t)
typedef int(* rom_reboot_fn) (uint32_t flags, uint32_t delay_ms, uint32_t p0, uint32_t p1)
typedef rom_reset_usb_boot_fn reset_usb_boot_fn
typedef void(* rom_connect_internal_flash_fn) (void)
typedef void(* rom_flash_exit_xip_fn) (void)
typedef void(* rom_flash_range_erase_fn) (uint32_t, size_t, uint32_t, uint8_t)
typedef void(* rom_flash_range_program_fn) (uint32_t, const uint8_t *, size_t)
typedef void(* rom_flash_flush_cache_fn) (void)
typedef void(* rom_flash_enter_cmd_xip_fn) (void)
typedef void(* rom_bootrom_state_reset_fn) (uint32_t flags)
typedef void(* rom_flash_reset_address_trans_fn) (void)
typedef void(* rom_flash_select_xip_read_mode_fn) (bootrom_xip_mode_t mode, uint8_t clkdiv)
typedef int(* rom_get_sys_info_fn) (uint32_t *out_buffer, uint32_t out_buffer_word_size, uint32_t flags)
typedef int(* rom_get_partition_table_info_fn) (uint32_t *out_buffer, uint32_t out_buffer_word_size, uint32_t partition_and_flags)
typedef int(* rom_explicit_buy_fn) (uint8_t *buffer, uint32_t buffer_size)
typedef void *(* rom_validate_ns_buffer_fn) (const void *addr, uint32_t size, uint32_t write, uint32_t *ok)
typedef intptr_t(* rom_set_rom_callback_fn) (uint callback_num, bootrom_api_callback_generic_t funcptr)
typedef int(* rom_chain_image_fn) (uint8_t *workarea_base, uint32_t workarea_size, uint32_t window_base, uint32_t window_size)
typedef int(* rom_load_partition_table_fn) (uint8_t *workarea_base, uint32_t workarea_size, bool force_reload)
typedef int(* rom_pick_ab_partition_fn) (uint8_t *workarea_base, uint32_t workarea_size, uint partition_a_num, uint32_t flash_update_boot_window_base)
typedef int(* rom_get_b_partition_fn) (uint pi_a)
typedef int(* rom_get_uf2_target_partition_fn) (uint8_t *workarea_base, uint32_t workarea_size, uint32_t family_id, resident_partition_t *partition_out)
typedef int(* rom_func_otp_access_fn) (uint8_t *buf, uint32_t buf_len, otp_cmd_t cmd)
typedef intptr_t(* rom_flash_runtime_to_storage_addr_fn) (uintptr_t flash_runtime_addr)
typedef int(* rom_flash_op_fn) (cflash_flags_t flags, uintptr_t addr, uint32_t size_bytes, uint8_t *buf)
typedef int(* rom_set_ns_api_permission_fn) (uint ns_api_num, bool allowed)
typedef int(* rom_func_secure_call) (uintptr_t a0,...)
typedef void *(* rom_table_lookup_fn) (uint32_t code, uint32_t mask)

Functions

static uint32_t rom_table_code (uint8_t c1, uint8_t c2)
 Return a bootrom lookup code based on two ASCII characters.
void * rom_func_lookup (uint32_t code)
 Lookup a bootrom function by its code.
void * rom_data_lookup (uint32_t code)
 Lookup a bootrom data address by its code.
bool rom_funcs_lookup (uint32_t *table, unsigned int count)
 Helper function to lookup the addresses of multiple bootrom functions.
static __force_inline void * rom_func_lookup_inline (uint32_t code)
 Lookup a bootrom function by code. This method is forcibly inlined into the caller for FLASH/RAM sensitive code usage.
static __force_inline void * rom_data_lookup_inline (uint32_t code)
 Lookup a bootrom data address by its code. This method is forcibly inlined into the caller for FLASH/RAM sensitive code usage.
void rom_reset_usb_boot (uint32_t usb_activity_gpio_pin_mask, uint32_t disable_interface_mask)
 Reboot the device into BOOTSEL mode.
static void reset_usb_boot (uint32_t usb_activity_gpio_pin_mask, uint32_t disable_interface_mask)
void rom_reset_usb_boot_extra (int usb_activity_gpio_pin, uint32_t disable_interface_mask, bool usb_activity_gpio_pin_active_low)
 Reboot the device into BOOTSEL mode.
static void rom_connect_internal_flash (void)
 Connect the SSI/QMI to the QSPI pads.
static void rom_flash_exit_xip (void)
 Return the QSPI device from its XIP state to a serial command state.
static void rom_flash_range_erase (uint32_t addr, size_t count, uint32_t block_size, uint8_t block_cmd)
 Erase bytes in flash.
static void rom_flash_range_program (uint32_t addr, const uint8_t *data, size_t count)
 Program bytes in flash.
static void rom_flash_flush_cache (void)
 Flush the XIP cache.
static void rom_flash_enter_cmd_xip (void)
 Configure the SSI/QMI with a standard command.
static int rom_reboot (uint32_t flags, uint32_t delay_ms, uint32_t p0, uint32_t p1)
 Reboot using the watchdog.
bool rom_get_boot_random (uint32_t out[4])
 Get the per boot random number.
static void rom_bootrom_state_reset (uint32_t flags)
 Reset bootrom state.
static void rom_flash_reset_address_trans (void)
 Reset address translation.
static void rom_flash_select_xip_read_mode (bootrom_xip_mode_t mode, uint8_t clkdiv)
 Configure QMI in a XIP read mode.
static void rom_helper_flash_op (void *param)
static int rom_flash_op (cflash_flags_t flags, uintptr_t addr, uint32_t size_bytes, uint8_t *buf)
 Perform a flash read, erase, or program operation.
static int rom_func_otp_access (uint8_t *buf, uint32_t buf_len, otp_cmd_t cmd)
 Writes data from a buffer into OTP, or reads data from OTP into a buffer.
static int rom_get_partition_table_info (uint32_t *out_buffer, uint32_t out_buffer_word_size, uint32_t partition_and_flags)
 Fills a buffer with information from the partition table.
static int rom_load_partition_table (uint8_t *workarea_base, uint32_t workarea_size, bool force_reload)
 Loads the current partition table from flash, if present.
static int rom_pick_ab_partition (uint8_t *workarea_base, uint32_t workarea_size, uint partition_a_num, uint32_t flash_update_boot_window_base)
 Pick a partition from an A/B pair.
int rom_pick_ab_partition_during_update (uint32_t *workarea_base, uint32_t workarea_size, uint partition_a_num)
 Pick A/B partition without disturbing any in progress Flash Update boot or TBYB boot.
static int rom_get_b_partition (uint pi_a)
 Get B partition.
static int rom_get_uf2_target_partition (uint8_t *workarea_base, uint32_t workarea_size, uint32_t family_id, resident_partition_t *partition_out)
 Get UF2 Target Partition.
static intptr_t rom_flash_runtime_to_storage_addr (uintptr_t flash_runtime_addr)
 Translate runtime to storage address.
static int rom_chain_image (uint8_t *workarea_base, uint32_t workarea_size, uint32_t region_base, uint32_t region_size)
 Chain into a launchable image.
static void rom_helper_explicit_buy (void *param)
static int rom_explicit_buy (uint8_t *buffer, uint32_t buffer_size)
 Buy an image.
static int rom_set_ns_api_permission (uint ns_api_num, bool allowed)
 Set NS API Permission.
static void * rom_validate_ns_buffer (const void *addr, uint32_t size, uint32_t write, uint32_t *ok)
 Validate NS Buffer.
static intptr_t rom_set_rom_callback (uint callback_num, bootrom_api_callback_generic_t funcptr)
 Set ROM callback function.
static int rom_get_sys_info (uint32_t *out_buffer, uint32_t out_buffer_word_size, uint32_t flags)
 Get system information.
static int rom_get_boot_info (boot_info_t *info)
static int rom_get_last_boot_type_with_chained_flag (void)
static int rom_get_last_boot_type (void)
int rom_add_flash_runtime_partition (uint32_t start_offset, uint32_t size, uint32_t permissions)
 Add a runtime partition to the partition table to specify flash permissions.

Macro Definition Documentation

◆ rom_hword_as_ptr

#define rom_hword_as_ptr ( rom_address)
Value:
(void *)(uintptr_t)(*(uint16_t *)(uintptr_t)(rom_address))

Typedef Documentation

◆ rom_func_secure_call

typedef int(* rom_func_secure_call) (uintptr_t a0,...)

Note this is not strictly a C function; you must pass the function you are calling in r4

Parameters
in_r40b0xxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx - a "well known" function selector; do not use for your own methods 0b10xx xxxx xxxx xxxx xxxx xxxx xxxx xxxx - a "unique" function selector intended to be unlikely to clash with others'. The lower 30 bits should be chosen at random 0b11xx xxxx xxxx xxxx xxxx xxxx xxxx xxxx - a "private" function selector intended for use by tightly coupled NS and S code
Returns
whatever the secure call returns BOOTROM_ERROR_INVALID_STATE if no secure handler has been set from the secure side via rom_set_rom_callback_fn(BOOTROM_API_CALLBACK_secure_call, ...)

◆ rom_set_rom_callback_fn

typedef intptr_t(* rom_set_rom_callback_fn) (uint callback_num, bootrom_api_callback_generic_t funcptr)
Returns
BOOTROM_OK if successful BOOTROM_ERROR_INVALID_ARG if ns_api_num is out of range