1 /*********************************************************************************************************************** 2 * Copyright [2015-2017] Renesas Electronics Corporation and/or its licensors. All Rights Reserved. 3 * 4 * This file is part of Renesas SynergyTM Software Package (SSP) 5 * 6 * The contents of this file (the "contents") are proprietary and confidential to Renesas Electronics Corporation 7 * and/or its licensors ("Renesas") and subject to statutory and contractual protections. 8 * 9 * This file is subject to a Renesas SSP license agreement. Unless otherwise agreed in an SSP license agreement with 10 * Renesas: 1) you may not use, copy, modify, distribute, display, or perform the contents; 2) you may not use any name 11 * or mark of Renesas for advertising or publicity purposes or in connection with your use of the contents; 3) RENESAS 12 * MAKES NO WARRANTY OR REPRESENTATIONS ABOUT THE SUITABILITY OF THE CONTENTS FOR ANY PURPOSE; THE CONTENTS ARE PROVIDED 13 * "AS IS" WITHOUT ANY EXPRESS OR IMPLIED WARRANTY, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 14 * PARTICULAR PURPOSE, AND NON-INFRINGEMENT; AND 4) RENESAS SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, OR 15 * CONSEQUENTIAL DAMAGES, INCLUDING DAMAGES RESULTING FROM LOSS OF USE, DATA, OR PROJECTS, WHETHER IN AN ACTION OF 16 * CONTRACT OR TORT, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE CONTENTS. Third-party contents 17 * included in this file may be subject to different terms. 18 **********************************************************************************************************************/ 19 20 /*********************************************************************************************************************** 21 * File Name : r_flash_api.h 22 * Description : API Interface for the FLASH peripheral on SC32 MCUs. 23 **********************************************************************************************************************/ 24 25 /*******************************************************************************************************************//** 26 * @ingroup Interface_Library 27 * @defgroup FLASH_API Flash Interface 28 * @brief Interface for the flash controller. 29 * 30 * @section FLASH_API_SUMMARY Summary 31 * The Flash interface provides the functionality necessary to read, write, erase and blank check the 32 * Flash memory. Additionally functions are provided to configure the access window and swap areas of the 33 * flash memory. 34 * 35 * Implemented by: 36 * - @ref FLASH_HP 37 * - @ref FLASH 38 * 39 * Related SSP architecture topics: 40 * - @ref ssp-interfaces 41 * - @ref ssp-predefined-layers 42 * - @ref using-ssp-modules 43 * 44 * Flash Interface description: @ref ModuleFlash 45 * 46 * 47 * @{ 48 **********************************************************************************************************************/ 49 50 #ifndef DRV_FLASH_API_H 51 #define DRV_FLASH_API_H 52 53 /*********************************************************************************************************************** 54 * Includes 55 **********************************************************************************************************************/ 56 /* Register definitions, common services and error codes. */ 57 #include "bsp_api.h" 58 59 /* Common macro for SSP header files. There is also a corresponding SSP_FOOTER macro at the end of this file. */ 60 SSP_HEADER 61 62 /********************************************************************************************************************** 63 * Macro definitions 64 *********************************************************************************************************************/ 65 #define FLASH_API_VERSION_MAJOR (1U) /**< FLASH HAL API version number (Major) */ 66 #define FLASH_API_VERSION_MINOR (5U) /**< FLASH HAL API version number (Minor) */ 67 68 /********************************************************************************************************************* 69 * Typedef definitions 70 *********************************************************************************************************************/ 71 72 /** Result type for certain operations */ 73 typedef enum e_flash_result 74 { 75 FLASH_RESULT_BLANK, ///< Return status for Blank Check Function 76 FLASH_RESULT_NOT_BLANK, ///< Return status for Blank Check Function 77 FLASH_RESULT_BGO_ACTIVE ///< Flash is configured for BGO mode. Result is returned in callback. 78 } flash_result_t; 79 80 /** Parameter for specifying the startup area swap being requested by startupAreaSelect() */ 81 typedef enum e_flash_startup_area_swap 82 { 83 FLASH_STARTUP_AREA_BLOCK1 = 0, ///< Startup area will be set to Block 1 84 FLASH_STARTUP_AREA_BLOCK0, ///< Startup area will be set to Block 0 85 FLASH_STARTUP_AREA_BTFLG ///< Startup area will be set based on the value of the BTFLG 86 } flash_startup_area_swap_t; 87 88 /** Event types returned by the ISR callback when used in Data Flash BGO mode */ 89 typedef enum e_flash_event 90 { 91 FLASH_EVENT_ERASE_COMPLETE, ///< Erase operation successfully completed 92 FLASH_EVENT_WRITE_COMPLETE, ///< Write operation successfully completed 93 FLASH_EVENT_BLANK, ///< Blank check operation successfully completed. Specified area is blank 94 FLASH_EVENT_NOT_BLANK, ///< Blank check operation successfully completed. Specified area is NOT blank 95 FLASH_EVENT_ERR_DF_ACCESS, ///< Data Flash operation failed. Can occur when writing an unerased section. 96 FLASH_EVENT_ERR_CF_ACCESS, ///< Code Flash operation failed. Can occur when writing an unerased section. 97 FLASH_EVENT_ERR_CMD_LOCKED, ///< Operation failed, FCU is in Locked state (often result of an illegal command) 98 FLASH_EVENT_ERR_FAILURE, ///< Erase or Program Operation failed 99 FLASH_EVENT_ERR_ONE_BIT ///< A 1-bit error has been corrected when reading the flash memory area by the sequencer. 100 } flash_event_t; 101 102 /** ID Code Modes for writing to ID code registers */ 103 typedef enum e_flash_id_code_mode 104 { 105 FLASH_ID_CODE_MODE_UNLOCKED, ///< ID code is ignored 106 FLASH_ID_CODE_MODE_LOCKED_WITH_ALL_ERASE_SUPPORT, ///< ID code is checked. All erase is available. 107 FLASH_ID_CODE_MODE_LOCKED ///< ID code is checked. 108 } flash_id_code_mode_t; 109 110 /** Flash block details stored in factory flash. */ 111 typedef struct st_flash_fmi_block_info 112 { 113 uint32_t block_section_st_addr; ///< starting address for this block section (blocks of this size) 114 uint32_t block_section_end_addr; ///< ending address for this block section (blocks of this size) 115 uint32_t block_size; ///< Flash erase block size 116 uint32_t block_size_write; ///< Flash write block size 117 } flash_fmi_block_info_t; 118 119 /** Flash block details */ 120 typedef struct st_flash_fmi_regions 121 { 122 uint32_t num_regions; ///< Length of block info array 123 flash_fmi_block_info_t const * p_block_array; ///< Block info array base address 124 } flash_fmi_regions_t; 125 126 /** Information about the flash blocks */ 127 typedef struct st_flash_info 128 { 129 flash_fmi_regions_t code_flash; ///< Information about the code flash regions 130 flash_fmi_regions_t data_flash; ///< Information about the code flash regions 131 }flash_info_t; 132 133 /** Flash control block. Allocate an instance specific control block to pass into the flash API calls. 134 * @par Implemented as 135 * - flash_lp_instance_ctrl_t 136 * - flash_hp_instance_ctrl_t 137 */ 138 typedef void flash_ctrl_t; 139 140 /** Callback function parameter data */ 141 typedef struct st_flash_user_cb_data 142 { 143 flash_event_t event; ///< Event can be used to identify what caused the callback (flash ready or error). 144 void const * p_context; ///< Placeholder for user data. Set in flash_api_t::open function in::flash_cfg_t. 145 } flash_callback_args_t; 146 147 /** FLASH Configuration */ 148 typedef struct st_flash_cfg 149 { 150 bool data_flash_bgo; ///< True if BGO (Background Operation) is enabled for Data Flash. 151 /* Configuration for FLASH Event processing */ 152 void (* p_callback)(flash_callback_args_t * p_args); ///< Callback provided when a Flash interrupt ISR occurs. 153 /* Pointer to FLASH peripheral specific configuration */ 154 void const * p_extend; ///< FLASH hardware dependent configuration 155 void const * p_context; ///< Placeholder for user data. Passed to user callback in ::flash_callback_args_t. 156 uint8_t irq_ipl; ///< Flash ready interrupt priority 157 uint8_t err_irq_ipl; ///< Flash error interrupt priority (unused in r_flash_lp) 158 } flash_cfg_t; 159 160 /** Shared Interface definition for FLASH */ 161 typedef struct st_flash_api 162 { 163 /** Open FLASH device. 164 * @par Implemented as 165 * - R_FLASH_LP_Open() 166 * - R_FLASH_HP_Open() 167 * 168 * @param[out] p_ctrl Pointer to FLASH device control. Must be declared by user. Value set here. 169 * @param[in] flash_cfg_t Pointer to FLASH configuration structure. All elements of this structure 170 * must be set by the user. 171 */ 172 ssp_err_t (* open)(flash_ctrl_t * const p_ctrl, 173 flash_cfg_t const * const p_cfg); 174 175 /** Write FLASH device. 176 * @par Implemented as 177 * - R_FLASH_LP_Write() 178 * - R_FLASH_HP_Write() 179 * 180 * @param[in] p_ctrl Control for the FLASH device context. 181 * @param[in] src_address Address of the buffer containing the data to write to Flash. 182 * @param[in] flash_address Code Flash or Data Flash address to write. The address must be on a 183 * programming line boundary. 184 * @param[in] num_bytes The number of bytes to write. This number must be a multiple 185 * of the programming size. For Code Flash this is FLASH_MIN_PGM_SIZE_CF. 186 * For Data Flash this is FLASH_MIN_PGM_SIZE_DF. 187 * @warning Specifying a number that is not a multiple of the programming size 188 * will result in SF_FLASH_ERR_BYTES being returned and no data written. 189 */ 190 ssp_err_t (* write)(flash_ctrl_t * const p_ctrl, 191 uint32_t const src_address, 192 uint32_t const flash_address, 193 uint32_t const num_bytes); 194 195 /** Read FLASH device. 196 * @par Implemented as 197 * - R_FLASH_LP_Read() 198 * - R_FLASH_HP_Read() 199 * 200 * @param[in] p_ctrl Control for the FLASH device context. 201 * @param[in] p_dest_address Pointer to caller's destination buffer used to hold the data read from Flash. 202 * @param[in] flash_address Code Flash or Data Flash starting address to read from. 203 * @param[in] num_bytes The number of bytes to read. 204 */ 205 ssp_err_t (* read)(flash_ctrl_t * const p_ctrl, 206 uint8_t * const p_dest_address, 207 uint32_t const flash_address, 208 uint32_t const num_bytes); 209 210 /** Erase FLASH device. 211 * @par Implemented as 212 * R_FLASH_LP_Erase() 213 * R_FLASH_HP_Erase() 214 * 215 * @param[in] p_ctrl Control for the FLASH device. 216 * @param[in] address The block containing this address is the first block erased. 217 * @param[in] num_blocks Specifies the number of blocks to be erased, the starting block determined 218 * by the block_erase_address. 219 */ 220 ssp_err_t (* erase)(flash_ctrl_t * const p_ctrl, 221 uint32_t const address, 222 uint32_t const num_blocks); 223 224 /** Blank check FLASH device. 225 * @par Implemented as 226 * - R_FLASH_LP_BlankCheck() 227 * - R_FLASH_HP_BlankCheck() 228 * 229 * @param[in] p_ctrl Control for the FLASH device context. 230 * @param[in] address The starting address of the Flash area to blank check. 231 * @param[in] num_bytes Specifies the number of bytes that need to be checked. 232 * See the specific handler for details. 233 * @param[out] p_blank_check_result Pointer that will be populated by the API with the results of the blank check 234 * operation in non-BGO (blocking) mode. In this case the blank check operation 235 * completes here and the result is returned. In Data Flash BGO mode the blank 236 * check operation is only started here and the result obtained later when the 237 * supplied callback routine is called. In this case FLASH_RESULT_BGO_ACTIVE will 238 * be returned in p_blank_check_result. 239 */ 240 ssp_err_t (* blankCheck)(flash_ctrl_t * const p_ctrl, 241 uint32_t const address, 242 uint32_t const num_bytes, 243 flash_result_t * const p_blank_check_result); 244 245 /** Close FLASH device. 246 * @par Implemented as 247 * - R_FLASH_LP_InfoGet() 248 * - R_FLASH_HP_InfoGet() 249 * 250 * @param[in] p_ctrl Pointer to FLASH device control. 251 * @param[out] p_info Pointer to FLASH info structure. 252 */ 253 ssp_err_t (* infoGet)(flash_ctrl_t * const p_ctrl, 254 flash_info_t * const p_info); 255 256 /** Close FLASH device. 257 * @par Implemented as 258 * - R_FLASH_LP_Close() 259 * - R_FLASH_HP_Close() 260 * 261 * @param[in] p_ctrl Pointer to FLASH device control. 262 */ 263 ssp_err_t (* close)(flash_ctrl_t * const p_ctrl); 264 265 /** Get Status for FLASH device. 266 * @par Implemented as 267 * - R_FLASH_LP_StatusGet() 268 * - R_FLASH_HP_StatusGet() 269 * 270 * @param[in] p_ctrl Pointer to FLASH device control. 271 */ 272 ssp_err_t (* statusGet)(flash_ctrl_t * const p_ctrl); 273 274 /** Set Access Window for FLASH device. 275 * @par Implemented as 276 * - R_FLASH_LP_AccessWindowSet() 277 * - R_FLASH_HP_AccessWindowSet() 278 * 279 * @param[in] p_ctrl Pointer to FLASH device control. 280 * @param[in] start_addr Determines the Starting block for the Code Flash access window. 281 * @param[in] end_addr Determines the Ending block for the Code Flash access window. 282 */ 283 ssp_err_t (* accessWindowSet)(flash_ctrl_t * const p_ctrl, uint32_t const start_addr, uint32_t const end_addr); 284 285 /** Clear any existing Code Flash access window for FLASH device. 286 * @par Implemented as 287 * - R_FLASH_LP_AccessWindowClear() 288 * - R_FLASH_HP_AccessWindowClear() 289 * 290 * @param[in] p_ctrl Pointer to FLASH device control. 291 * @param[in] start_addr Determines the Starting block for the Code Flash access window. 292 * @param[in] end_addr Determines the Ending block for the Code Flash access window. 293 */ 294 ssp_err_t (* accessWindowClear)(flash_ctrl_t * const p_ctrl); 295 296 /** Set ID Code for FLASH device. Setting the ID code can restrict access to the device. The ID code will be 297 * required to connect to the device. Bits 126 and 127 are set based on the mode. 298 * e.g. uint8_t id_bytes[] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 299 * 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0x00}; 300 * with mode FLASH_ID_CODE_MODE_LOCKED_WITH_ALL_ERASE_SUPPORT 301 * will result in an ID code of 00112233445566778899aabbccddeec0 302 * and with mode FLASH_ID_CODE_MODE_LOCKED 303 * will result in an ID code of 00112233445566778899aabbccddee80 304 * 305 * @par Implemented as 306 * - R_FLASH_LP_IdCodeSet() 307 * - R_FLASH_HP_IdCodeSet() 308 * 309 * @param[in] p_ctrl Pointer to FLASH device control. 310 * @param[in] p_id_bytes Ponter to the ID Code to be written. 311 * @param[in] mode Mode used for checking the ID code. 312 */ 313 ssp_err_t (* idCodeSet)(flash_ctrl_t * const p_ctrl, uint8_t const * const p_id_bytes, flash_id_code_mode_t mode); 314 315 /** Reset function for FLASH device. 316 * @par Implemented as 317 * - R_FLASH_LP_Reset() 318 * - R_FLASH_HP_Reset() 319 * 320 * @param[in] p_ctrl Pointer to FLASH device control. 321 */ 322 ssp_err_t (* reset)(flash_ctrl_t * const p_ctrl); 323 324 /** Update Flash clock frequency (FCLK) and recalculate timeout values 325 * @par Implemented as 326 * - R_FLASH_LP_UpdateFlashClockFreq() 327 * - R_FLASH_HP_UpdateFlashClockFreq() 328 * @param[in] p_ctrl Pointer to FLASH device control. 329 */ 330 ssp_err_t (* updateFlashClockFreq)(flash_ctrl_t * const p_ctrl); 331 332 333 /** Select which block - Default (Block 0) or Alternate (Block 1) is used as the start-up area block. 334 * @par Implemented as 335 * - R_FLASH_LP_StartUpAreaSelect() 336 * - R_FLASH_HP_StartUpAreaSelect() 337 * 338 * @param[in] p_ctrl Pointer to FLASH device control. 339 * @param[in] swap_type FLASH_STARTUP_AREA_BLOCK0, FLASH_STARTUP_AREA_BLOCK1 or FLASH_STARTUP_AREA_BTFLG. 340 * @param[in] is_temporary True or false. See table below. 341 * 342 * swap_type | is_temporary | Operation 343 * FLASH_STARTUP_AREA_BLOCK0: false On next reset Startup area will be Block 0.\n 344 * FLASH_STARTUP_AREA_BLOCK0 | false | On next reset Startup area will be Block 0. 345 * Block 0.\n 346 * FLASH_STARTUP_AREA_BLOCK1: false On next reset Startup area will be Block 1.\n 347 * FLASH_STARTUP_AREA_BLOCK1 | true | Startup area is immediately, but temporarily switched to Block 1. 348 * Block 1.\n 349 * FLASH_STARTUP_AREA_BTFLG | true | Startup area is immediately, but temporarily switched to... 350 * taken.\n 351 352 * the Block determined by the Configuration BTFLG.\n 353 */ 354 ssp_err_t (* startupAreaSelect)(flash_ctrl_t * const p_ctrl, 355 flash_startup_area_swap_t swap_type, 356 bool is_temporary); 357 358 /** Get Flash driver version. 359 * @par Implemented as 360 * - R_FLASH_LP_VersionGet() 361 * - R_FLASH_HP_VersionGet() 362 * 363 * @param[out] p_version Returns version. 364 */ 365 ssp_err_t (* versionGet)(ssp_version_t * p_version); 366 } flash_api_t; 367 368 /** This structure encompasses everything that is needed to use an instance of this interface. */ 369 typedef struct st_flash_instance 370 { 371 flash_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 372 flash_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 373 flash_api_t const * p_api; ///< Pointer to the API structure for this instance 374 } flash_instance_t; 375 376 /******************************************************************************************************************//** 377 * @} (end addtogroup FLASH_API) 378 *********************************************************************************************************************/ 379 380 /* Common macro for SSP header files. There is also a corresponding SSP_HEADER macro at the top of this file. */ 381 SSP_FOOTER 382 383 #endif /* DRV_FLASH_API_H */ 384