blob: 87dafb15ccfbec0e07550a4f2e9c0312946c38a8 [file] [log] [blame]
/*
* Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
#ifndef _HARDWARE_FLASH_H
#define _HARDWARE_FLASH_H
#include "pico.h"
/** \file flash.h
* \defgroup hardware_flash hardware_flash
*
* \brief 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 could be the
* 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
* \ref multicore_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.
*
* \subsection flash_example Example
* \include flash_program.c
*/
// PICO_CONFIG: PARAM_ASSERTIONS_ENABLED_HARDWARE_FLASH, Enable/disable assertions in the hardware_flash module, type=bool, default=0, group=hardware_flash
#ifndef PARAM_ASSERTIONS_ENABLED_HARDWARE_FLASH
#ifdef PARAM_ASSERTIONS_ENABLED_FLASH // backwards compatibility with SDK < 2.0.0
#define PARAM_ASSERTIONS_ENABLED_HARDWARE_FLASH PARAM_ASSERTIONS_ENABLED_FLASH
#else
#define PARAM_ASSERTIONS_ENABLED_HARDWARE_FLASH 0
#endif
#endif
#define FLASH_PAGE_SIZE (1u << 8)
#define FLASH_SECTOR_SIZE (1u << 12)
#define FLASH_BLOCK_SIZE (1u << 16)
#define FLASH_UNIQUE_ID_SIZE_BYTES 8
// PICO_CONFIG: PICO_FLASH_SIZE_BYTES, size of primary flash in bytes, type=int, default=Usually provided via board header, group=hardware_flash
#ifdef __cplusplus
extern "C" {
#endif
/*! \brief Erase areas of flash
* \ingroup hardware_flash
*
* \param flash_offs Offset into flash, in bytes, to start the erase. Must be aligned to a 4096-byte flash sector.
* \param 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.
*/
void flash_range_erase(uint32_t flash_offs, size_t count);
/*! \brief Program flash
* \ingroup hardware_flash
*
* \param flash_offs Flash address of the first byte to be programmed. Must be aligned to a 256-byte flash page.
* \param data Pointer to the data to program into flash
* \param 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.
*/
void flash_range_program(uint32_t flash_offs, const uint8_t *data, size_t count);
/*! \brief Get flash unique 64 bit identifier
* \ingroup hardware_flash
*
* 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.
*
* \param id_out Pointer to an 8-byte buffer to which the ID will be written
*/
void flash_get_unique_id(uint8_t *id_out);
/*! \brief Execute bidirectional flash command
* \ingroup hardware_flash
*
* 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.
*
* \param txbuf Pointer to a byte buffer which will be transmitted to the flash
* \param rxbuf Pointer to a byte buffer where data received from the flash will be written. txbuf and rxbuf may be the same buffer.
* \param count Length in bytes of txbuf and of rxbuf
*/
void flash_do_cmd(const uint8_t *txbuf, uint8_t *rxbuf, size_t count);
void flash_flush_cache(void);
#ifdef __cplusplus
}
#endif
#endif