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

Low level flash programming and erase API. More...

## Functions

void | flash_start_xip (void)
| Initialise QSPI interface and external QSPI devices for execute-in-place.
void | flash_range_erase (uint32_t flash_offs, size_t count)
| Erase areas of flash.
void | flash_range_program (uint32_t flash_offs, const uint8_t *data, size_t count)
| Program flash.
void | flash_get_unique_id (uint8_t *id_out)
| Get flash unique 64 bit identifier.
void | flash_do_cmd (const uint8_t *txbuf, uint8_t *rxbuf, size_t count)
| Execute bidirectional flash command.

## Detailed Description

Low level flash programming and erase API.

Note these functions are unsafe if you are using both cores, and the other is executing from flash concurrently with the operation. In this case, you must perform your own synchronisation to make sure that no XIP accesses take place during flash programming. One option is to use the lockout functions.

Likewise they are unsafe if you have interrupt handlers or an interrupt vector table in flash, so you must disable interrupts before calling in this case.

If PICO_NO_FLASH=1 is not defined (i.e. if the program is built to run from flash) then these functions will make a static copy of the second stage bootloader in SRAM, and use this to reenter execute-in-place mode after programming or erasing flash, so that they can safely be called from flash-resident code.

## Example

## Function Documentation

## flash_do_cmd()

void flash_do_cmd | ( | const uint8_t * | txbuf,
|  | uint8_t * | rxbuf,
|  | size_t | count )

Execute bidirectional flash command.

Low-level function to execute a serial command on a flash device attached to the QSPI interface. Bytes are simultaneously transmitted and received from txbuf and to rxbuf. Therefore, both buffers must be the same length, count, which is the length of the overall transaction. This is useful for reading metadata from the flash chip, such as device ID or SFDP parameters.

The XIP cache is flushed following each command, in case flash state has been modified. Like other hardware_flash functions, the flash is not accessible for execute-in-place transfers whilst the command is in progress, so entering a flash-resident interrupt handler or executing flash code on the second core concurrently will be fatal. To avoid these pitfalls it is recommended that this function only be used to extract flash metadata during startup, before the main application begins to run: see the implementation of pico_get_unique_id() for an example of this.

Parameters

  txbuf | Pointer to a byte buffer which will be transmitted to the flash
  rxbuf | Pointer to a byte buffer where data received from the flash will be written. txbuf and rxbuf may be the same buffer.
  count | Length in bytes of txbuf and of rxbuf

## flash_get_unique_id()

void flash_get_unique_id | ( | uint8_t * | id_out | ) |

Get flash unique 64 bit identifier.

Use a standard 4Bh RUID instruction to retrieve the 64 bit unique identifier from a flash device attached to the QSPI interface. Since there is a 1:1 association between the MCU and this flash, this also serves as a unique identifier for the board.

Parameters

  id_out | Pointer to an 8-byte buffer to which the ID will be written

## flash_range_erase()

void flash_range_erase | ( | uint32_t | flash_offs,
|  | size_t | count )

Erase areas of flash.

Parameters

  flash_offs | Offset into flash, in bytes, to start the erase. Must be aligned to a 4096-byte flash sector.
  count | Number of bytes to be erased. Must be a multiple of 4096 bytes (one sector).

Note
  Erasing a flash sector sets all the bits in all the pages in that sector to one. You can then "program" flash pages in the sector to turn some of the bits to zero. Once a bit is set to zero it can only be changed back to one by erasing the whole sector again.

## flash_range_program()

void flash_range_program | ( | uint32_t | flash_offs,
|  | const uint8_t * | data,
|  | size_t | count )

Program flash.

Parameters

  flash_offs | Flash address of the first byte to be programmed. Must be aligned to a 256-byte flash page.
  data | Pointer to the data to program into flash
  count | Number of bytes to program. Must be a multiple of 256 bytes (one page).

Note
  : Programming a flash page effectively changes some of the bits from one to zero. The only way to change a zero bit back to one is to "erase" the whole sector that the page resides in. So you may need to make sure you have called flash_range_erase before calling flash_range_program.

## flash_start_xip()

void flash_start_xip | ( | void |  | ) |

Initialise QSPI interface and external QSPI devices for execute-in-place.

This function performs the same first-time flash setup that would normally occur over the course of the bootrom locating a flash binary and booting it, and that flash binary executing the SDK crt0. Specifically:

- Initialise QSPI pads to their default states, and (non-RP2040) disable pad isolation latches
- Issue a hardcoded sequence to attached QSPI devices to return them to a serial command state
- Flush the XIP cache
- Configure the QSPI interface for low-speed 03h reads
- If this is not a PICO_NO_FLASH=1 binary:
  - (RP2040) load a boot2 stage from the first 256 bytes of RAM and execute it
  - (non-RP2040) execute an XIP setup function stored in boot RAM by either the bootrom or by crt0

This is mostly useful for initialising flash on a PICO_NO_FLASH=1 binary. (In spite of the name, this binary type really means "preloaded to RAM" and there may still be a flash device.)

This function does not preserve the QSPI interface state or pad state. This is in contrast to most other functions in this library, which preserve at least the QSPI pad state. However, on RP2350 it does preserve the QMI window 1 configuration if you have not opted into bootrom CS1 support via FLASH_DEVINFO.