1 /*********************************************************************************************************************** 2 * Copyright [2020-2022] Renesas Electronics Corporation and/or its affiliates. All Rights Reserved. 3 * 4 * This software and documentation are supplied by Renesas Electronics America Inc. and may only be used with products 5 * of Renesas Electronics Corp. and its affiliates ("Renesas"). No other uses are authorized. Renesas products are 6 * sold pursuant to Renesas terms and conditions of sale. Purchasers are solely responsible for the selection and use 7 * of Renesas products and Renesas assumes no liability. No license, express or implied, to any intellectual property 8 * right is granted by Renesas. This software is protected under all applicable laws, including copyright laws. Renesas 9 * reserves the right to change or discontinue this software and/or this documentation. THE SOFTWARE AND DOCUMENTATION 10 * IS DELIVERED TO YOU "AS IS," AND RENESAS MAKES NO REPRESENTATIONS OR WARRANTIES, AND TO THE FULLEST EXTENT 11 * PERMISSIBLE UNDER APPLICABLE LAW, DISCLAIMS ALL WARRANTIES, WHETHER EXPLICITLY OR IMPLICITLY, INCLUDING WARRANTIES 12 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT, WITH RESPECT TO THE SOFTWARE OR 13 * DOCUMENTATION. RENESAS SHALL HAVE NO LIABILITY ARISING OUT OF ANY SECURITY VULNERABILITY OR BREACH. TO THE MAXIMUM 14 * EXTENT PERMITTED BY LAW, IN NO EVENT WILL RENESAS BE LIABLE TO YOU IN CONNECTION WITH THE SOFTWARE OR DOCUMENTATION 15 * (OR ANY PERSON OR ENTITY CLAIMING RIGHTS DERIVED FROM YOU) FOR ANY LOSS, DAMAGES, OR CLAIMS WHATSOEVER, INCLUDING, 16 * WITHOUT LIMITATION, ANY DIRECT, CONSEQUENTIAL, SPECIAL, INDIRECT, PUNITIVE, OR INCIDENTAL DAMAGES; ANY LOST PROFITS, 17 * OTHER ECONOMIC DAMAGE, PROPERTY DAMAGE, OR PERSONAL INJURY; AND EVEN IF RENESAS HAS BEEN ADVISED OF THE POSSIBILITY 18 * OF SUCH LOSS, DAMAGES, CLAIMS OR COSTS. 19 **********************************************************************************************************************/ 20 21 /*******************************************************************************************************************//** 22 * @ingroup RENESAS_INTERFACES 23 * @defgroup FLASH_API Flash Interface 24 * @brief Interface for the Flash Memory. 25 * 26 * @section FLASH_API_SUMMARY Summary 27 * 28 * The Flash interface provides the ability to read, write, erase, and blank check the code flash and data flash 29 * regions. 30 * 31 * The Flash interface is implemented by: 32 * - @ref FLASH_LP 33 * 34 * @{ 35 **********************************************************************************************************************/ 36 37 #ifndef R_FLASH_API_H 38 #define R_FLASH_API_H 39 40 /*********************************************************************************************************************** 41 * Includes 42 **********************************************************************************************************************/ 43 44 /* Register definitions, common services and error codes. */ 45 #include "bsp_api.h" 46 47 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */ 48 FSP_HEADER 49 50 /********************************************************************************************************************** 51 * Macro definitions 52 *********************************************************************************************************************/ 53 54 /********************************************************************************************************************* 55 * Typedef definitions 56 *********************************************************************************************************************/ 57 58 /** Result type for certain operations */ 59 typedef enum e_flash_result 60 { 61 FLASH_RESULT_BLANK, ///< Return status for Blank Check Function 62 FLASH_RESULT_NOT_BLANK, ///< Return status for Blank Check Function 63 FLASH_RESULT_BGO_ACTIVE ///< Flash is configured for BGO mode. Result is returned in callback. 64 } flash_result_t; 65 66 /** Parameter for specifying the startup area swap being requested by startupAreaSelect() */ 67 typedef enum e_flash_startup_area_swap 68 { 69 FLASH_STARTUP_AREA_BTFLG = 0, ///< Startup area will be set based on the value of the BTFLG 70 FLASH_STARTUP_AREA_BLOCK0 = 0x2, ///< Startup area will be set to Block 0 71 FLASH_STARTUP_AREA_BLOCK1 = 0x3, ///< Startup area will be set to Block 1 72 } flash_startup_area_swap_t; 73 74 /** Event types returned by the ISR callback when used in Data Flash BGO mode */ 75 typedef enum e_flash_event 76 { 77 FLASH_EVENT_ERASE_COMPLETE, ///< Erase operation successfully completed 78 FLASH_EVENT_WRITE_COMPLETE, ///< Write operation successfully completed 79 FLASH_EVENT_BLANK, ///< Blank check operation successfully completed. Specified area is blank 80 FLASH_EVENT_NOT_BLANK, ///< Blank check operation successfully completed. Specified area is NOT blank 81 FLASH_EVENT_ERR_DF_ACCESS, ///< Data Flash operation failed. Can occur when writing an unerased section. 82 FLASH_EVENT_ERR_CF_ACCESS, ///< Code Flash operation failed. Can occur when writing an unerased section. 83 FLASH_EVENT_ERR_CMD_LOCKED, ///< Operation failed, FCU is in Locked state (often result of an illegal command) 84 FLASH_EVENT_ERR_FAILURE, ///< Erase or Program Operation failed 85 FLASH_EVENT_ERR_ONE_BIT ///< A 1-bit error has been corrected when reading the flash memory area by the sequencer. 86 } flash_event_t; 87 88 /** ID Code Modes for writing to ID code registers */ 89 typedef enum e_flash_id_code_mode 90 { 91 FLASH_ID_CODE_MODE_UNLOCKED = 0, ///< ID code is ignored 92 FLASH_ID_CODE_MODE_LOCKED_WITH_ALL_ERASE_SUPPORT = 0xC000U, ///< ID code is checked. All erase is available. 93 FLASH_ID_CODE_MODE_LOCKED = 0x8000U ///< ID code is checked. 94 } flash_id_code_mode_t; 95 96 /** Flash status */ 97 typedef enum e_flash_status 98 { 99 FLASH_STATUS_IDLE, ///< The flash is idle. 100 FLASH_STATUS_BUSY ///< The flash is currently processing a command. 101 } flash_status_t; 102 103 /** Flash block details stored in factory flash. */ 104 typedef struct st_flash_block_info 105 { 106 uint32_t block_section_st_addr; ///< Starting address for this block section (blocks of this size) 107 uint32_t block_section_end_addr; ///< Ending address for this block section (blocks of this size) 108 uint32_t block_size; ///< Flash erase block size 109 uint32_t block_size_write; ///< Flash write block size 110 } flash_block_info_t; 111 112 /** Flash block details */ 113 typedef struct st_flash_regions 114 { 115 uint32_t num_regions; ///< Length of block info array 116 flash_block_info_t const * p_block_array; ///< Block info array base address 117 } flash_regions_t; 118 119 /** Information about the flash blocks */ 120 typedef struct st_flash_info 121 { 122 flash_regions_t code_flash; ///< Information about the code flash regions 123 flash_regions_t data_flash; ///< Information about the code flash regions 124 } flash_info_t; 125 126 /** Flash control block. Allocate an instance specific control block to pass into the flash API calls. 127 * @par Implemented as 128 * - flash_lp_instance_ctrl_t 129 * - flash_hp_instance_ctrl_t 130 */ 131 typedef void flash_ctrl_t; 132 133 /** Callback function parameter data */ 134 typedef struct st_flash_user_cb_data 135 { 136 flash_event_t event; ///< Event can be used to identify what caused the callback (flash ready or error). 137 void const * p_context; ///< Placeholder for user data. Set in @ref flash_api_t::open function in::flash_cfg_t. 138 } flash_callback_args_t; 139 140 /** FLASH Configuration */ 141 typedef struct st_flash_cfg 142 { 143 bool data_flash_bgo; ///< True if BGO (Background Operation) is enabled for Data Flash. 144 145 /* Configuration for FLASH Event processing */ 146 void (* p_callback)(flash_callback_args_t * p_args); ///< Callback provided when a Flash interrupt ISR occurs. 147 148 /* Pointer to FLASH peripheral specific configuration */ 149 void const * p_extend; ///< FLASH hardware dependent configuration 150 void const * p_context; ///< Placeholder for user data. Passed to user callback in @ref flash_callback_args_t. 151 uint8_t ipl; ///< Flash ready interrupt priority 152 IRQn_Type irq; ///< Flash ready interrupt number 153 uint8_t err_ipl; ///< Flash error interrupt priority (unused in r_flash_lp) 154 IRQn_Type err_irq; ///< Flash error interrupt number (unused in r_flash_lp) 155 } flash_cfg_t; 156 157 /** Shared Interface definition for FLASH */ 158 typedef struct st_flash_api 159 { 160 /** Open FLASH device. 161 * @par Implemented as 162 * - @ref R_FLASH_LP_Open() 163 * - @ref R_FLASH_HP_Open() 164 * 165 * @param[out] p_ctrl Pointer to FLASH device control. Must be declared by user. Value set here. 166 * @param[in] flash_cfg_t Pointer to FLASH configuration structure. All elements of this structure 167 * must be set by the user. 168 */ 169 fsp_err_t (* open)(flash_ctrl_t * const p_ctrl, flash_cfg_t const * const p_cfg); 170 171 /** Write FLASH device. 172 * @par Implemented as 173 * - @ref R_FLASH_LP_Write() 174 * - @ref R_FLASH_HP_Write() 175 * 176 * @param[in] p_ctrl Control for the FLASH device context. 177 * @param[in] src_address Address of the buffer containing the data to write to Flash. 178 * @param[in] flash_address Code Flash or Data Flash address to write. The address must be on a 179 * programming line boundary. 180 * @param[in] num_bytes The number of bytes to write. This number must be a multiple 181 * of the programming size. For Code Flash this is FLASH_MIN_PGM_SIZE_CF. 182 * For Data Flash this is FLASH_MIN_PGM_SIZE_DF. 183 * @warning Specifying a number that is not a multiple of the programming size 184 * will result in SF_FLASH_ERR_BYTES being returned and no data written. 185 */ 186 fsp_err_t (* write)(flash_ctrl_t * const p_ctrl, uint32_t const src_address, uint32_t const flash_address, 187 uint32_t const num_bytes); 188 189 /** Erase FLASH device. 190 * @par Implemented as 191 * - @ref R_FLASH_LP_Erase() 192 * - @ref R_FLASH_HP_Erase() 193 * 194 * @param[in] p_ctrl Control for the FLASH device. 195 * @param[in] address The block containing this address is the first block erased. 196 * @param[in] num_blocks Specifies the number of blocks to be erased, the starting block determined 197 * by the block_erase_address. 198 */ 199 fsp_err_t (* erase)(flash_ctrl_t * const p_ctrl, uint32_t const address, uint32_t const num_blocks); 200 201 /** Blank check FLASH device. 202 * @par Implemented as 203 * - @ref R_FLASH_LP_BlankCheck() 204 * - @ref R_FLASH_HP_BlankCheck() 205 * 206 * @param[in] p_ctrl Control for the FLASH device context. 207 * @param[in] address The starting address of the Flash area to blank check. 208 * @param[in] num_bytes Specifies the number of bytes that need to be checked. 209 * See the specific handler for details. 210 * @param[out] p_blank_check_result Pointer that will be populated by the API with the results of the blank check 211 * operation in non-BGO (blocking) mode. In this case the blank check operation 212 * completes here and the result is returned. In Data Flash BGO mode the blank 213 * check operation is only started here and the result obtained later when the 214 * supplied callback routine is called. In this case FLASH_RESULT_BGO_ACTIVE will 215 * be returned in p_blank_check_result. 216 */ 217 fsp_err_t (* blankCheck)(flash_ctrl_t * const p_ctrl, uint32_t const address, uint32_t const num_bytes, 218 flash_result_t * const p_blank_check_result); 219 220 /** Close FLASH device. 221 * @par Implemented as 222 * - @ref R_FLASH_LP_InfoGet() 223 * - @ref R_FLASH_HP_InfoGet() 224 * 225 * @param[in] p_ctrl Pointer to FLASH device control. 226 * @param[out] p_info Pointer to FLASH info structure. 227 */ 228 fsp_err_t (* infoGet)(flash_ctrl_t * const p_ctrl, flash_info_t * const p_info); 229 230 /** Close FLASH device. 231 * @par Implemented as 232 * - @ref R_FLASH_LP_Close() 233 * - @ref R_FLASH_HP_Close() 234 * 235 * @param[in] p_ctrl Pointer to FLASH device control. 236 */ 237 fsp_err_t (* close)(flash_ctrl_t * const p_ctrl); 238 239 /** Get Status for FLASH device. 240 * @par Implemented as 241 * - @ref R_FLASH_LP_StatusGet() 242 * - @ref R_FLASH_HP_StatusGet() 243 * 244 * @param[in] p_ctrl Pointer to FLASH device control. 245 * @param[out] p_ctrl Pointer to the current flash status. 246 */ 247 fsp_err_t (* statusGet)(flash_ctrl_t * const p_ctrl, flash_status_t * const p_status); 248 249 /** Set Access Window for FLASH device. 250 * @par Implemented as 251 * - @ref R_FLASH_LP_AccessWindowSet() 252 * - @ref R_FLASH_HP_AccessWindowSet() 253 * 254 * @param[in] p_ctrl Pointer to FLASH device control. 255 * @param[in] start_addr Determines the Starting block for the Code Flash access window. 256 * @param[in] end_addr Determines the Ending block for the Code Flash access window. This address will not be 257 * within the access window. 258 */ 259 fsp_err_t (* accessWindowSet)(flash_ctrl_t * const p_ctrl, uint32_t const start_addr, uint32_t const end_addr); 260 261 /** Clear any existing Code Flash access window for FLASH device. 262 * @par Implemented as 263 * - @ref R_FLASH_LP_AccessWindowClear() 264 * - @ref R_FLASH_HP_AccessWindowClear() 265 * 266 * @param[in] p_ctrl Pointer to FLASH device control. 267 * @param[in] start_addr Determines the Starting block for the Code Flash access window. 268 * @param[in] end_addr Determines the Ending block for the Code Flash access window. 269 */ 270 fsp_err_t (* accessWindowClear)(flash_ctrl_t * const p_ctrl); 271 272 /** Set ID Code for FLASH device. Setting the ID code can restrict access to the device. The ID code will be 273 * required to connect to the device. Bits 126 and 127 are set based on the mode. 274 * 275 * For example, uint8_t id_bytes[] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 276 * 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0x00}; 277 * with mode FLASH_ID_CODE_MODE_LOCKED_WITH_ALL_ERASE_SUPPORT 278 * will result in an ID code of 00112233445566778899aabbccddeec0 279 * 280 * With mode FLASH_ID_CODE_MODE_LOCKED, it 281 * will result in an ID code of 00112233445566778899aabbccddee80 282 * 283 * @par Implemented as 284 * - @ref R_FLASH_LP_IdCodeSet() 285 * - @ref R_FLASH_HP_IdCodeSet() 286 * 287 * @param[in] p_ctrl Pointer to FLASH device control. 288 * @param[in] p_id_bytes Ponter to the ID Code to be written. 289 * @param[in] mode Mode used for checking the ID code. 290 */ 291 fsp_err_t (* idCodeSet)(flash_ctrl_t * const p_ctrl, uint8_t const * const p_id_bytes, flash_id_code_mode_t mode); 292 293 /** Reset function for FLASH device. 294 * @par Implemented as 295 * - @ref R_FLASH_LP_Reset() 296 * - @ref R_FLASH_HP_Reset() 297 * 298 * @param[in] p_ctrl Pointer to FLASH device control. 299 */ 300 fsp_err_t (* reset)(flash_ctrl_t * const p_ctrl); 301 302 /** Update Flash clock frequency (FCLK) and recalculate timeout values 303 * @par Implemented as 304 * - @ref R_FLASH_LP_UpdateFlashClockFreq() 305 * - @ref R_FLASH_HP_UpdateFlashClockFreq() 306 * @param[in] p_ctrl Pointer to FLASH device control. 307 */ 308 fsp_err_t (* updateFlashClockFreq)(flash_ctrl_t * const p_ctrl); 309 310 /** Select which block - Default (Block 0) or Alternate (Block 1) is used as the start-up area block. 311 * @par Implemented as 312 * - @ref R_FLASH_LP_StartUpAreaSelect() 313 * - @ref R_FLASH_HP_StartUpAreaSelect() 314 * 315 * @param[in] p_ctrl Pointer to FLASH device control. 316 * @param[in] swap_type FLASH_STARTUP_AREA_BLOCK0, FLASH_STARTUP_AREA_BLOCK1 or FLASH_STARTUP_AREA_BTFLG. 317 * @param[in] is_temporary True or false. See table below. 318 * 319 * | swap_type | is_temporary | Operation | 320 * |-----------------------|-----------------|-------------| 321 * | FLASH_STARTUP_AREA_BLOCK0 | false | On next reset Startup area will be Block 0. | 322 * | FLASH_STARTUP_AREA_BLOCK1 | true | Startup area is immediately, but temporarily switched to Block 1. | 323 * | FLASH_STARTUP_AREA_BTFLG | true | Startup area is immediately, but temporarily switched to the Block determined by the Configuration BTFLG. | 324 * 325 */ 326 fsp_err_t (* startupAreaSelect)(flash_ctrl_t * const p_ctrl, flash_startup_area_swap_t swap_type, 327 bool is_temporary); 328 329 /** Swap the bank used as the startup area. Only valid in dual bank mode. 330 * @par Implemented as 331 * - @ref R_FLASH_HP_BankSwap() 332 * 333 * @param[in] p_ctrl Pointer to FLASH device control. 334 */ 335 fsp_err_t (* bankSwap)(flash_ctrl_t * const p_ctrl); 336 337 /** Specify callback function and optional context pointer and working memory pointer. 338 * @par Implemented as 339 * - @ref R_FLASH_HP_CallbackSet() 340 * 341 * @param[in] p_ctrl Control block set in @ref flash_api_t::open call for this timer. 342 * @param[in] p_callback Callback function to register 343 * @param[in] p_context Pointer to send to callback function 344 * @param[in] p_working_memory Pointer to volatile memory where callback structure can be allocated. 345 * Callback arguments allocated here are only valid during the callback. 346 */ 347 fsp_err_t (* callbackSet)(flash_ctrl_t * const p_api_ctrl, void (* p_callback)(flash_callback_args_t *), 348 void const * const p_context, flash_callback_args_t * const p_callback_memory); 349 } flash_api_t; 350 351 /** This structure encompasses everything that is needed to use an instance of this interface. */ 352 typedef struct st_flash_instance 353 { 354 flash_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 355 flash_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 356 flash_api_t const * p_api; ///< Pointer to the API structure for this instance 357 } flash_instance_t; 358 359 /******************************************************************************************************************//** 360 * @} (end defgroup FLASH_API) 361 *********************************************************************************************************************/ 362 363 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */ 364 FSP_FOOTER 365 366 #endif 367