lib/main/pico-sdk/rp2_common/hardware_flash/include/hardware/flash.h

   1 /*
   2  * Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
   3  *
   4  * SPDX-License-Identifier: BSD-3-Clause
   5  */
   6
   7 #ifndef _HARDWARE_FLASH_H
   8 #define _HARDWARE_FLASH_H
   9
  10 #include "pico.h"
  11
  12 /** \file flash.h
  13  *  \defgroup hardware_flash hardware_flash
  14  *
  15  * \brief Low level flash programming and erase API
  16  *
  17  * Note these functions are *unsafe* if you are using both cores, and the other
  18  * is executing from flash concurrently with the operation. In this could be the
  19  * case, you must perform your own synchronisation to make sure that no XIP
  20  * accesses take place during flash programming. One option is to use the
  21  * \ref multicore_lockout functions.
  22  *
  23  * Likewise they are *unsafe* if you have interrupt handlers or an interrupt
  24  * vector table in flash, so you must disable interrupts before calling in
  25  * this case.
  26  *
  27  * If PICO_NO_FLASH=1 is not defined (i.e. if the program is built to run from
  28  * flash) then these functions will make a static copy of the second stage
  29  * bootloader in SRAM, and use this to reenter execute-in-place mode after
  30  * programming or erasing flash, so that they can safely be called from
  31  * flash-resident code.
  32  *
  33  * \subsection flash_example Example
  34  * \include flash_program.c
  35  */
  36
  37 // PICO_CONFIG: PARAM_ASSERTIONS_ENABLED_HARDWARE_FLASH, Enable/disable assertions in the hardware_flash module, type=bool, default=0, group=hardware_flash
  38 #ifndef PARAM_ASSERTIONS_ENABLED_HARDWARE_FLASH
  39 #ifdef PARAM_ASSERTIONS_ENABLED_FLASH // backwards compatibility with SDK < 2.0.0
  40 #define PARAM_ASSERTIONS_ENABLED_HARDWARE_FLASH PARAM_ASSERTIONS_ENABLED_FLASH
  41 #else
  42 #define PARAM_ASSERTIONS_ENABLED_HARDWARE_FLASH 0
  43 #endif
  44 #endif
  45 #define FLASH_PAGE_SIZE (1u << 8)
  46 #define FLASH_SECTOR_SIZE (1u << 12)
  47 #define FLASH_BLOCK_SIZE (1u << 16)
  48
  49 #ifndef FLASH_UNIQUE_ID_SIZE_BYTES
  50 #define FLASH_UNIQUE_ID_SIZE_BYTES 8
  51 #endif
  52
  53 // PICO_CONFIG: PICO_FLASH_SIZE_BYTES, size of primary flash in bytes, type=int, default=Usually provided via board header, group=hardware_flash
  54
  55 #ifdef __cplusplus
  56 extern "C" {
  57 #endif
  58
  59 /*! \brief  Erase areas of flash
  60  *  \ingroup hardware_flash
  61  *
  62  * \param flash_offs Offset into flash, in bytes, to start the erase. Must be aligned to a 4096-byte flash sector.
  63  * \param count Number of bytes to be erased. Must be a multiple of 4096 bytes (one sector).
  64  *
  65  * @note Erasing a flash sector sets all the bits in all the pages in that sector to one.
  66  * You can then "program" flash pages in the sector to turn some of the bits to zero.
  67  * Once a bit is set to zero it can only be changed back to one by erasing the whole sector again.
  68  */
  69 void flash_range_erase(uint32_t flash_offs, size_t count);
  70
  71 /*! \brief  Program flash
  72  *  \ingroup hardware_flash
  73  *
  74  * \param flash_offs Flash address of the first byte to be programmed. Must be aligned to a 256-byte flash page.
  75  * \param data Pointer to the data to program into flash
  76  * \param count Number of bytes to program. Must be a multiple of 256 bytes (one page).
  77  *
  78  * @note: Programming a flash page effectively changes some of the bits from one to zero.
  79  * The only way to change a zero bit back to one is to "erase" the whole sector that the page resides in.
  80  * So you may need to make sure you have called flash_range_erase before calling flash_range_program.
  81  */
  82
  83 void flash_range_program(uint32_t flash_offs, const uint8_t *data, size_t count);
  84
  85 /*! \brief Get flash unique 64 bit identifier
  86  *  \ingroup hardware_flash
  87  *
  88  * Use a standard 4Bh RUID instruction to retrieve the 64 bit unique
  89  * identifier from a flash device attached to the QSPI interface. Since there
  90  * is a 1:1 association between the MCU and this flash, this also serves as a
  91  * unique identifier for the board.
  92  *
  93  *  \param id_out Pointer to an 8-byte buffer to which the ID will be written
  94  */
  95 void flash_get_unique_id(uint8_t *id_out);
  96
  97 /*! \brief Execute bidirectional flash command
  98  *  \ingroup hardware_flash
  99  *
 100  * Low-level function to execute a serial command on a flash device attached
 101  * to the QSPI interface. Bytes are simultaneously transmitted and received
 102  * from txbuf and to rxbuf. Therefore, both buffers must be the same length,
 103  * count, which is the length of the overall transaction. This is useful for
 104  * reading metadata from the flash chip, such as device ID or SFDP
 105  * parameters.
 106  *
 107  * The XIP cache is flushed following each command, in case flash state
 108  * has been modified. Like other hardware_flash functions, the flash is not
 109  * accessible for execute-in-place transfers whilst the command is in
 110  * progress, so entering a flash-resident interrupt handler or executing flash
 111  * code on the second core concurrently will be fatal. To avoid these pitfalls
 112  * it is recommended that this function only be used to extract flash metadata
 113  * during startup, before the main application begins to run: see the
 114  * implementation of pico_get_unique_id() for an example of this.
 115  *
 116  *  \param txbuf Pointer to a byte buffer which will be transmitted to the flash
 117  *  \param rxbuf Pointer to a byte buffer where data received from the flash will be written. txbuf and rxbuf may be the same buffer.
 118  *  \param count Length in bytes of txbuf and of rxbuf
 119  */
 120 void flash_do_cmd(const uint8_t *txbuf, uint8_t *rxbuf, size_t count);
 121
 122 void flash_flush_cache(void);
 123
 124 #ifdef __cplusplus
 125 }
 126 #endif
 127
 128 #endif