@web-font-path: "roboto-debian.css";
v2.2.0 (RP2040)
Loading...
Searching...
No Matches
pico_bootrom

Access to functions and data in the bootrom. More...

## Macros

#define | ROM_TABLE_CODE(c1, c2)
| Return a bootrom lookup code based on two ASCII characters.

## 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.
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.

## Detailed Description

Access to functions and data in the bootrom.

This header may be included by assembly code

## Macro Definition Documentation

## ROM_TABLE_CODE

#define ROM_TABLE_CODE | ( |  | c1,
|  |  | c2 )

Value:
((c1) | ((c2) << 8))

Return a bootrom lookup code based on two ASCII characters.

These codes are uses to lookup data or function addresses in the bootrom

Parameters

  c1 | the first character
  c2 | the second character

Returns
  the 'code' to use in rom_func_lookup() or rom_data_lookup()

## Function Documentation

## rom_connect_internal_flash()

void rom_connect_internal_flash | ( | void |  | ) |

inline static

Connect the SSI/QMI to the QSPI pads.

Restore all QSPI pad controls to their default state, and connect the SSI/QMI peripheral to the QSPI pads.

## rom_data_lookup()

void * rom_data_lookup | ( | uint32_t | code | ) |

Lookup a bootrom data address by its code.

Parameters

  code | the code

Returns
  a pointer to the data, or NULL if the code does not match any bootrom function

## rom_data_lookup_inline()

__force_inline void * rom_data_lookup_inline | ( | uint32_t | code | ) |

static

Lookup a bootrom data address by its code. This method is forcibly inlined into the caller for FLASH/RAM sensitive code usage.

Parameters

  code | the code

Returns
  a pointer to the data, or NULL if the code does not match any bootrom data

## rom_flash_enter_cmd_xip()

void rom_flash_enter_cmd_xip | ( | void |  | ) |

inline static

Configure the SSI/QMI with a standard command.

Configure the SSI/QMI to generate a standard 03h serial read command, with 24 address bits, upon each XIP access. This is a slow XIP configuration, but is widely supported. CLKDIV is set to 12 on RP2350. The debugger may call this function to ensure that flash is readable following a program/erase operation.

Note that the same setup is performed by flash_exit_xip(), and the RP2350 flash program/erase functions do not leave XIP in an inaccessible state, so calls to this function are largely redundant on RP2350. It is provided on RP2350 for compatibility with RP2040.

## rom_flash_exit_xip()

void rom_flash_exit_xip | ( | void |  | ) |

inline static

Return the QSPI device from its XIP state to a serial command state.

On RP2040, first set up the SSI for serial-mode operations, then issue the fixed XIP exit sequence described in Section 2.8.1.2 of the datasheet. Note that the bootrom code uses the IO forcing logic to drive the CS pin, which must be cleared before returning the SSI to XIP mode (e.g. by a call to _flash_flush_cache). This function configures the SSI with a fixed SCK clock divisor of /6.

## rom_flash_flush_cache()

void rom_flash_flush_cache | ( | void |  | ) |

inline static

Flush the XIP cache.

Flush and enable the XIP cache. Also clears the IO forcing on QSPI CSn, so that the SSI can drive the flash chip select as normal.

## rom_flash_range_erase()

void rom_flash_range_erase | ( | uint32_t | addr,
|  | size_t | count,
|  | uint32_t | block_size,
|  | uint8_t | block_cmd )

inline static

Erase bytes in flash.

Erase count bytes, starting at addr (offset from start of flash). Optionally, pass a block erase command e.g. D8h block erase, and the size of the block erased by this command - this function will use the larger block erase where possible, for much higher erase speed. addr must be aligned to a 4096-byte sector, and count must be a multiple of 4096 bytes.

This is a low-level flash API, and no validation of the arguments is performed.

Parameters

  addr | the offset from start of flash to be erased
  count | number of bytes to erase
  block_size | optional size of block erased by block_cmd
  block_cmd | optional block erase command e.g. D8h block erase

## rom_flash_range_program()

void rom_flash_range_program | ( | uint32_t | addr,
|  | const uint8_t * | data,
|  | size_t | count )

inline static

Program bytes in flash.

Program data to a range of flash addresses starting at addr (offset from the start of flash) and count bytes in size. addr must be aligned to a 256-byte boundary, and count must be a multiple of 256.

This is a low-level flash API, and no validation of the arguments is performed.

Parameters

  addr | the offset from start of flash to be erased
  data | buffer containing the data to be written
  count | number of bytes to erase

## rom_func_lookup()

void * rom_func_lookup | ( | uint32_t | code | ) |

Lookup a bootrom function by its code.

Parameters

  code | the code

Returns
  a pointer to the function, or NULL if the code does not match any bootrom function

## rom_func_lookup_inline()

__force_inline void * rom_func_lookup_inline | ( | uint32_t | code | ) |

static

Lookup a bootrom function by code. This method is forcibly inlined into the caller for FLASH/RAM sensitive code usage.

Parameters

  code | the code

Returns
  a pointer to the function, or NULL if the code does not match any bootrom function

## rom_funcs_lookup()

bool rom_funcs_lookup | ( | uint32_t * | table,
|  | unsigned int | count )

Helper function to lookup the addresses of multiple bootrom functions.

This method looks up the 'codes' in the table, and convert each table entry to the looked up function pointer, if there is a function for that code in the bootrom.

Parameters

  table | an IN/OUT array, elements are codes on input, function pointers on success.
  count | the number of elements in the table

Returns
  true if all the codes were found, and converted to function pointers, false otherwise

## rom_reset_usb_boot()

void rom_reset_usb_boot | ( | uint32_t | usb_activity_gpio_pin_mask,
|  | uint32_t | disable_interface_mask )

Reboot the device into BOOTSEL mode.

This function reboots the device into the BOOTSEL mode ('usb boot"). Facilities are provided to enable an "activity light" via GPIO attached LED for the USB Mass Storage Device, and to limit the USB interfaces exposed.

Parameters

  usb_activity_gpio_pin_mask | 0 No pins are used as per a cold boot. Otherwise a single bit set indicating which GPIO pin should be set to output and raised whenever there is mass storage activity from the host.

  disable_interface_mask

  value to control exposed interfaces
  - 0 To enable both interfaces (as per a cold boot)
  - 1 To disable the USB Mass Storage Interface
  - 2 To disable the USB PICOBOOT Interface

## rom_reset_usb_boot_extra()

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.

This function reboots the device into the BOOTSEL mode ('usb boot"). Facilities are provided to enable an "activity light" via GPIO attached LED for the USB Mass Storage Device, and to limit the USB interfaces exposed.

Parameters

  usb_activity_gpio_pin | GPIO pin to be used as an activitiy pin, or -1 for none from the host.

  disable_interface_mask

  value to control exposed interfaces
  - 0 To enable both interfaces (as per a cold boot)
  - 1 To disable the USB Mass Storage Interface
  - 2 To disable the USB PICOBOOT Interface

  usb_activity_gpio_pin_active_low | Activity GPIO is active low (ignored on RP2040)

## rom_table_code()

uint32_t rom_table_code | ( | uint8_t | c1,
|  | uint8_t | c2 )

inline static

Return a bootrom lookup code based on two ASCII characters.

These codes are uses to lookup data or function addresses in the bootrom

Parameters

  c1 | the first character
  c2 | the second character

Returns
  the 'code' to use in rom_func_lookup() or rom_data_lookup()