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 * 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_FLASH, Enable/disable assertions in the flash module, type=bool, default=0, group=hardware_flash 38 #ifndef PARAM_ASSERTIONS_ENABLED_FLASH 39 #define PARAM_ASSERTIONS_ENABLED_FLASH 0 40 #endif 41 42 #define FLASH_PAGE_SIZE (1u << 8) 43 #define FLASH_SECTOR_SIZE (1u << 12) 44 #define FLASH_BLOCK_SIZE (1u << 16) 45 46 #define FLASH_UNIQUE_ID_SIZE_BYTES 8 47 48 // PICO_CONFIG: PICO_FLASH_SIZE_BYTES, size of primary flash in bytes, type=int, group=hardware_flash 49 50 #ifdef __cplusplus 51 extern "C" { 52 #endif 53 54 /*! \brief Erase areas of flash 55 * \ingroup hardware_flash 56 * 57 * \param flash_offs Offset into flash, in bytes, to start the erase. Must be aligned to a 4096-byte flash sector. 58 * \param count Number of bytes to be erased. Must be a multiple of 4096 bytes (one sector). 59 */ 60 void flash_range_erase(uint32_t flash_offs, size_t count); 61 62 /*! \brief Program flash 63 * \ingroup hardware_flash 64 * 65 * \param flash_offs Flash address of the first byte to be programmed. Must be aligned to a 256-byte flash page. 66 * \param data Pointer to the data to program into flash 67 * \param count Number of bytes to program. Must be a multiple of 256 bytes (one page). 68 */ 69 70 void flash_range_program(uint32_t flash_offs, const uint8_t *data, size_t count); 71 72 /*! \brief Get flash unique 64 bit identifier 73 * \ingroup hardware_flash 74 * 75 * Use a standard 4Bh RUID instruction to retrieve the 64 bit unique 76 * identifier from a flash device attached to the QSPI interface. Since there 77 * is a 1:1 association between the MCU and this flash, this also serves as a 78 * unique identifier for the board. 79 * 80 * \param id_out Pointer to an 8-byte buffer to which the ID will be written 81 */ 82 void flash_get_unique_id(uint8_t *id_out); 83 84 /*! \brief Execute bidirectional flash command 85 * \ingroup hardware_flash 86 * 87 * Low-level function to execute a serial command on a flash device attached 88 * to the QSPI interface. Bytes are simultaneously transmitted and received 89 * from txbuf and to rxbuf. Therefore, both buffers must be the same length, 90 * count, which is the length of the overall transaction. This is useful for 91 * reading metadata from the flash chip, such as device ID or SFDP 92 * parameters. 93 * 94 * The XIP cache is flushed following each command, in case flash state 95 * has been modified. Like other hardware_flash functions, the flash is not 96 * accessible for execute-in-place transfers whilst the command is in 97 * progress, so entering a flash-resident interrupt handler or executing flash 98 * code on the second core concurrently will be fatal. To avoid these pitfalls 99 * it is recommended that this function only be used to extract flash metadata 100 * during startup, before the main application begins to run: see the 101 * implementation of pico_get_unique_id() for an example of this. 102 * 103 * \param txbuf Pointer to a byte buffer which will be transmitted to the flash 104 * \param rxbuf Pointer to a byte buffer where data received from the flash will be written. txbuf and rxbuf may be the same buffer. 105 * \param count Length in bytes of txbuf and of rxbuf 106 */ 107 void flash_do_cmd(const uint8_t *txbuf, uint8_t *rxbuf, size_t count); 108 109 110 #ifdef __cplusplus 111 } 112 #endif 113 114 #endif 115
