1 /* 2 * Copyright (c) 2020 - 2024 Renesas Electronics Corporation and/or its affiliates 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 /*******************************************************************************************************************//** 8 * @ingroup RENESAS_STORAGE_INTERFACES 9 * @defgroup FLASH_API Flash Interface 10 * @brief Interface for the Flash Memory. 11 * 12 * @section FLASH_API_SUMMARY Summary 13 * 14 * The Flash interface provides the ability to read, write, erase, and blank check the code flash and data flash 15 * regions. 16 * 17 * 18 * @{ 19 **********************************************************************************************************************/ 20 21 #ifndef R_FLASH_API_H 22 #define R_FLASH_API_H 23 24 /*********************************************************************************************************************** 25 * Includes 26 **********************************************************************************************************************/ 27 28 /* Register definitions, common services and error codes. */ 29 #include "bsp_api.h" 30 31 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 32 FSP_HEADER 33 34 /********************************************************************************************************************** 35 * Macro definitions 36 *********************************************************************************************************************/ 37 38 /********************************************************************************************************************* 39 * Typedef definitions 40 *********************************************************************************************************************/ 41 42 /** Result type for certain operations */ 43 typedef enum e_flash_result 44 { 45 FLASH_RESULT_BLANK, ///< Return status for Blank Check Function 46 FLASH_RESULT_NOT_BLANK, ///< Return status for Blank Check Function 47 FLASH_RESULT_BGO_ACTIVE ///< Flash is configured for BGO mode. Result is returned in callback. 48 } flash_result_t; 49 50 /** Parameter for specifying the startup area swap being requested by startupAreaSelect() */ 51 typedef enum e_flash_startup_area_swap 52 { 53 FLASH_STARTUP_AREA_BTFLG = 0, ///< Startup area will be set based on the value of the BTFLG 54 FLASH_STARTUP_AREA_BLOCK0 = 0x2, ///< Startup area will be set to Block 0 55 FLASH_STARTUP_AREA_BLOCK1 = 0x3, ///< Startup area will be set to Block 1 56 } flash_startup_area_swap_t; 57 58 /** Event types returned by the ISR callback when used in Data Flash BGO mode */ 59 typedef enum e_flash_event 60 { 61 FLASH_EVENT_ERASE_COMPLETE, ///< Erase operation successfully completed 62 FLASH_EVENT_WRITE_COMPLETE, ///< Write operation successfully completed 63 FLASH_EVENT_BLANK, ///< Blank check operation successfully completed. Specified area is blank 64 FLASH_EVENT_NOT_BLANK, ///< Blank check operation successfully completed. Specified area is NOT blank 65 FLASH_EVENT_ERR_DF_ACCESS, ///< Data Flash operation failed. Can occur when writing an unerased section. 66 FLASH_EVENT_ERR_CF_ACCESS, ///< Code Flash operation failed. Can occur when writing an unerased section. 67 FLASH_EVENT_ERR_CMD_LOCKED, ///< Operation failed, FCU is in Locked state (often result of an illegal command) 68 FLASH_EVENT_ERR_FAILURE, ///< Erase or Program Operation failed 69 FLASH_EVENT_ERR_ONE_BIT ///< A 1-bit error has been corrected when reading the flash memory area by the sequencer. 70 } flash_event_t; 71 72 /** ID Code Modes for writing to ID code registers */ 73 typedef enum e_flash_id_code_mode 74 { 75 FLASH_ID_CODE_MODE_UNLOCKED = 0, ///< ID code is ignored 76 FLASH_ID_CODE_MODE_LOCKED_WITH_ALL_ERASE_SUPPORT = 0xC000U, ///< ID code is checked. All erase is available. 77 FLASH_ID_CODE_MODE_LOCKED = 0x8000U ///< ID code is checked. 78 } flash_id_code_mode_t; 79 80 /** Flash status */ 81 typedef enum e_flash_status 82 { 83 FLASH_STATUS_IDLE, ///< The flash is idle. 84 FLASH_STATUS_BUSY ///< The flash is currently processing a command. 85 } flash_status_t; 86 87 /** Flash block details stored in factory flash. */ 88 typedef struct st_flash_block_info 89 { 90 uint32_t block_section_st_addr; ///< Starting address for this block section (blocks of this size) 91 uint32_t block_section_end_addr; ///< Ending address for this block section (blocks of this size) 92 uint32_t block_size; ///< Flash erase block size 93 uint32_t block_size_write; ///< Flash write block size 94 } flash_block_info_t; 95 96 /** Flash block details */ 97 typedef struct st_flash_regions 98 { 99 uint32_t num_regions; ///< Length of block info array 100 flash_block_info_t const * p_block_array; ///< Block info array base address 101 } flash_regions_t; 102 103 /** Information about the flash blocks */ 104 typedef struct st_flash_info 105 { 106 flash_regions_t code_flash; ///< Information about the code flash regions 107 flash_regions_t data_flash; ///< Information about the code flash regions 108 } flash_info_t; 109 110 /** Flash control block. Allocate an instance specific control block to pass into the flash API calls. 111 */ 112 typedef void flash_ctrl_t; 113 114 /** Callback function parameter data */ 115 typedef struct st_flash_user_cb_data 116 { 117 flash_event_t event; ///< Event can be used to identify what caused the callback (flash ready or error). 118 void const * p_context; ///< Placeholder for user data. Set in @ref flash_api_t::open function in::flash_cfg_t. 119 } flash_callback_args_t; 120 121 /** FLASH Configuration */ 122 typedef struct st_flash_cfg 123 { 124 bool data_flash_bgo; ///< True if BGO (Background Operation) is enabled for Data Flash. 125 126 /* Configuration for FLASH Event processing */ 127 void (* p_callback)(flash_callback_args_t * p_args); ///< Callback provided when a Flash interrupt ISR occurs. 128 129 /* Pointer to FLASH peripheral specific configuration */ 130 void const * p_extend; ///< FLASH hardware dependent configuration 131 void const * p_context; ///< Placeholder for user data. Passed to user callback in @ref flash_callback_args_t. 132 uint8_t ipl; ///< Flash ready interrupt priority 133 IRQn_Type irq; ///< Flash ready interrupt number 134 uint8_t err_ipl; ///< Flash error interrupt priority (unused in r_flash_lp) 135 IRQn_Type err_irq; ///< Flash error interrupt number (unused in r_flash_lp) 136 } flash_cfg_t; 137 138 /** Shared Interface definition for FLASH */ 139 typedef struct st_flash_api 140 { 141 /** Open FLASH device. 142 * 143 * @param[out] p_ctrl Pointer to FLASH device control. Must be declared by user. Value set here. 144 * @param[in] flash_cfg_t Pointer to FLASH configuration structure. All elements of this structure 145 * must be set by the user. 146 */ 147 fsp_err_t (* open)(flash_ctrl_t * const p_ctrl, flash_cfg_t const * const p_cfg); 148 149 /** Write FLASH device. 150 * 151 * @param[in] p_ctrl Control for the FLASH device context. 152 * @param[in] src_address Address of the buffer containing the data to write to Flash. 153 * @param[in] flash_address Code Flash or Data Flash address to write. The address must be on a 154 * programming line boundary. 155 * @param[in] num_bytes The number of bytes to write. This number must be a multiple 156 * of the programming size. For Code Flash this is FLASH_MIN_PGM_SIZE_CF. 157 * For Data Flash this is FLASH_MIN_PGM_SIZE_DF. 158 * @warning Specifying a number that is not a multiple of the programming size 159 * will result in SF_FLASH_ERR_BYTES being returned and no data written. 160 */ 161 fsp_err_t (* write)(flash_ctrl_t * const p_ctrl, uint32_t const src_address, uint32_t const flash_address, 162 uint32_t const num_bytes); 163 164 /** Erase FLASH device. 165 * 166 * @param[in] p_ctrl Control for the FLASH device. 167 * @param[in] address The block containing this address is the first block erased. 168 * @param[in] num_blocks Specifies the number of blocks to be erased, the starting block determined 169 * by the block_erase_address. 170 */ 171 fsp_err_t (* erase)(flash_ctrl_t * const p_ctrl, uint32_t const address, uint32_t const num_blocks); 172 173 /** Blank check FLASH device. 174 * 175 * @param[in] p_ctrl Control for the FLASH device context. 176 * @param[in] address The starting address of the Flash area to blank check. 177 * @param[in] num_bytes Specifies the number of bytes that need to be checked. 178 * See the specific handler for details. 179 * @param[out] p_blank_check_result Pointer that will be populated by the API with the results of the blank check 180 * operation in non-BGO (blocking) mode. In this case the blank check operation 181 * completes here and the result is returned. In Data Flash BGO mode the blank 182 * check operation is only started here and the result obtained later when the 183 * supplied callback routine is called. In this case FLASH_RESULT_BGO_ACTIVE will 184 * be returned in p_blank_check_result. 185 */ 186 fsp_err_t (* blankCheck)(flash_ctrl_t * const p_ctrl, uint32_t const address, uint32_t const num_bytes, 187 flash_result_t * const p_blank_check_result); 188 189 /** Close FLASH device. 190 * 191 * @param[in] p_ctrl Pointer to FLASH device control. 192 * @param[out] p_info Pointer to FLASH info structure. 193 */ 194 fsp_err_t (* infoGet)(flash_ctrl_t * const p_ctrl, flash_info_t * const p_info); 195 196 /** Close FLASH device. 197 * 198 * @param[in] p_ctrl Pointer to FLASH device control. 199 */ 200 fsp_err_t (* close)(flash_ctrl_t * const p_ctrl); 201 202 /** Get Status for FLASH device. 203 * 204 * @param[in] p_ctrl Pointer to FLASH device control. 205 * @param[out] p_ctrl Pointer to the current flash status. 206 */ 207 fsp_err_t (* statusGet)(flash_ctrl_t * const p_ctrl, flash_status_t * const p_status); 208 209 /** Set Access Window for FLASH device. 210 * 211 * @param[in] p_ctrl Pointer to FLASH device control. 212 * @param[in] start_addr Determines the Starting block for the Code Flash access window. 213 * @param[in] end_addr Determines the Ending block for the Code Flash access window. This address will not be 214 * within the access window. 215 */ 216 fsp_err_t (* accessWindowSet)(flash_ctrl_t * const p_ctrl, uint32_t const start_addr, uint32_t const end_addr); 217 218 /** Clear any existing Code Flash access window for FLASH device. 219 * 220 * @param[in] p_ctrl Pointer to FLASH device control. 221 * @param[in] start_addr Determines the Starting block for the Code Flash access window. 222 * @param[in] end_addr Determines the Ending block for the Code Flash access window. 223 */ 224 fsp_err_t (* accessWindowClear)(flash_ctrl_t * const p_ctrl); 225 226 /** Set ID Code for FLASH device. Setting the ID code can restrict access to the device. The ID code will be 227 * required to connect to the device. Bits 126 and 127 are set based on the mode. 228 * 229 * For example, uint8_t id_bytes[] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 230 * 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0x00}; 231 * with mode FLASH_ID_CODE_MODE_LOCKED_WITH_ALL_ERASE_SUPPORT 232 * will result in an ID code of 00112233445566778899aabbccddeec0 233 * 234 * With mode FLASH_ID_CODE_MODE_LOCKED, it 235 * will result in an ID code of 00112233445566778899aabbccddee80 236 * 237 * 238 * @param[in] p_ctrl Pointer to FLASH device control. 239 * @param[in] p_id_bytes Ponter to the ID Code to be written. 240 * @param[in] mode Mode used for checking the ID code. 241 */ 242 fsp_err_t (* idCodeSet)(flash_ctrl_t * const p_ctrl, uint8_t const * const p_id_bytes, flash_id_code_mode_t mode); 243 244 /** Reset function for FLASH device. 245 * 246 * @param[in] p_ctrl Pointer to FLASH device control. 247 */ 248 fsp_err_t (* reset)(flash_ctrl_t * const p_ctrl); 249 250 /** Update Flash clock frequency (FCLK) and recalculate timeout values 251 * @param[in] p_ctrl Pointer to FLASH device control. 252 */ 253 fsp_err_t (* updateFlashClockFreq)(flash_ctrl_t * const p_ctrl); 254 255 /** Select which block - Default (Block 0) or Alternate (Block 1) is used as the start-up area block. 256 * 257 * @param[in] p_ctrl Pointer to FLASH device control. 258 * @param[in] swap_type FLASH_STARTUP_AREA_BLOCK0, FLASH_STARTUP_AREA_BLOCK1 or FLASH_STARTUP_AREA_BTFLG. 259 * @param[in] is_temporary True or false. See table below. 260 * 261 * | swap_type | is_temporary | Operation | 262 * |-----------------------|-----------------|-------------| 263 * | FLASH_STARTUP_AREA_BLOCK0 | false | On next reset Startup area will be Block 0. | 264 * | FLASH_STARTUP_AREA_BLOCK1 | true | Startup area is immediately, but temporarily switched to Block 1. | 265 * | FLASH_STARTUP_AREA_BTFLG | true | Startup area is immediately, but temporarily switched to the Block determined by the Configuration BTFLG. | 266 * 267 */ 268 fsp_err_t (* startupAreaSelect)(flash_ctrl_t * const p_ctrl, flash_startup_area_swap_t swap_type, 269 bool is_temporary); 270 271 /** Swap the bank used as the startup area. On Flash HP, need to change into dual bank mode to use this feature. 272 * 273 * @param[in] p_ctrl Pointer to FLASH device control. 274 */ 275 fsp_err_t (* bankSwap)(flash_ctrl_t * const p_ctrl); 276 277 /** Specify callback function and optional context pointer and working memory pointer. 278 * 279 * @param[in] p_ctrl Control block set in @ref flash_api_t::open call for this timer. 280 * @param[in] p_callback Callback function to register 281 * @param[in] p_context Pointer to send to callback function 282 * @param[in] p_working_memory Pointer to volatile memory where callback structure can be allocated. 283 * Callback arguments allocated here are only valid during the callback. 284 */ 285 fsp_err_t (* callbackSet)(flash_ctrl_t * const p_ctrl, void (* p_callback)(flash_callback_args_t *), 286 void const * const p_context, flash_callback_args_t * const p_callback_memory); 287 } flash_api_t; 288 289 /** This structure encompasses everything that is needed to use an instance of this interface. */ 290 typedef struct st_flash_instance 291 { 292 flash_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 293 flash_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 294 flash_api_t const * p_api; ///< Pointer to the API structure for this instance 295 } flash_instance_t; 296 297 /******************************************************************************************************************//** 298 * @} (end defgroup FLASH_API) 299 *********************************************************************************************************************/ 300 301 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 302 FSP_FOOTER 303 304 #endif 305
