1 /* 2 * Copyright 2018-2019 NXP 3 * All rights reserved. 4 * 5 * 6 * SPDX-License-Identifier: BSD-3-Clause 7 */ 8 9 #ifndef __FLASH_H__ 10 #define __FLASH_H__ 11 12 /*! 13 * @addtogroup FLASH_Adapter 14 * @{ 15 */ 16 17 #include "fsl_common.h" 18 /*! ********************************************************************************* 19 ************************************************************************************* 20 * Include 21 ************************************************************************************* 22 ********************************************************************************** */ 23 24 /*! ********************************************************************************* 25 ************************************************************************************* 26 * Public macros 27 ************************************************************************************* 28 ********************************************************************************** */ 29 /*! @brief Whether enable transactional function of the FLASH. (0 - disable, 1 - enable) */ 30 #ifndef HAL_FLASH_TRANSFER_MODE 31 #define HAL_FLASH_TRANSFER_MODE (0U) 32 #endif 33 34 /*! ********************************************************************************* 35 ************************************************************************************* 36 * Public type definitions 37 ************************************************************************************* 38 ********************************************************************************** */ 39 40 /*! @brief Hal flash status. */ 41 typedef enum _hal_flash_status 42 { 43 kStatus_HAL_Flash_Success = kStatus_Success, /*!< flash operation is successful*/ 44 kStatus_HAL_Flash_Fail = MAKE_STATUS(kStatusGroup_HAL_FLASH, 1), /*!< flash operation is not successful*/ 45 kStatus_HAL_Flash_InvalidArgument = MAKE_STATUS(kStatusGroup_HAL_FLASH, 2), /*!< Invalid argument */ 46 kStatus_HAL_Flash_AlignmentError = MAKE_STATUS(kStatusGroup_HAL_FLASH, 3), /*!< Alignment Error */ 47 kStatus_HAL_Flash_EccError = MAKE_STATUS(kStatusGroup_HAL_FLASH, 4), /*!< ECC error detected */ 48 kStatus_HAL_Flash_Error = MAKE_STATUS(kStatusGroup_HAL_FLASH, 5), /*!< Illegal command */ 49 kStatus_HAL_Flash_NotSupport = MAKE_STATUS(kStatusGroup_HAL_FLASH, 6), /*!< Not support */ 50 } hal_flash_status_t; 51 52 /*! @brief Hal flash property. */ 53 typedef enum _hal_flash_property_tag 54 { 55 kHAL_Flash_PropertyPflashSectorSize = 0x00U, /*!< Pflash sector size property.*/ 56 kHAL_Flash_PropertyPflashTotalSize = 0x01U, /*!< Pflash total size property.*/ 57 kHAL_Flash_PropertyPflashBlockSize = 0x02U, /*!< Pflash block size property.*/ 58 kHAL_Flash_PropertyPflashBlockCount = 0x03U, /*!< Pflash block count property.*/ 59 kHAL_Flash_PropertyPflashBlockBaseAddr = 0x04U, /*!< Pflash block base address property.*/ 60 kHAL_Flash_PropertyPflashFacSupport = 0x05U, /*!< Pflash fac support property.*/ 61 kHAL_Flash_PropertyPflashAccessSegmentSize = 0x06U, /*!< Pflash access segment size property.*/ 62 kHAL_Flash_PropertyPflashAccessSegmentCount = 0x07U, /*!< Pflash access segment count property.*/ 63 kHAL_Flash_PropertyFlexRamBlockBaseAddr = 0x08U, /*!< FlexRam block base address property.*/ 64 kHAL_Flash_PropertyFlexRamTotalSize = 0x09U, /*!< FlexRam total size property.*/ 65 kHAL_Flash_PropertyDflashSectorSize = 0x10U, /*!< Dflash sector size property.*/ 66 kHAL_Flash_PropertyDflashTotalSize = 0x11U, /*!< Dflash total size property.*/ 67 kHAL_Flash_PropertyDflashBlockSize = 0x12U, /*!< Dflash block size property.*/ 68 kHAL_Flash_PropertyDflashBlockCount = 0x13U, /*!< Dflash block count property.*/ 69 kHAL_Flash_PropertyDflashBlockBaseAddr = 0x14U, /*!< Dflash block base address property.*/ 70 kHAL_Flash_PropertyEepromTotalSize = 0x15U, /*!< EEPROM total size property.*/ 71 kHAL_Flash_PropertyFlashMemoryIndex = 0x20U /*!< Flash memory index property.*/ 72 } hal_flash_property_tag_t; 73 74 /*! @brief Hal flash security state. */ 75 typedef enum _hal_flash_security_state 76 { 77 kHAL_Flash_SecurityStateNotSecure = 0xc33cc33cU, /*!< Flash is not secure.*/ 78 kHAL_Flash_SecurityStateBackdoorEnabled = 0x5aa55aa5U, /*!< Flash backdoor is enabled.*/ 79 kHAL_Flash_SecurityStateBackdoorDisabled = 0x5ac33ca5U /*!< Flash backdoor is disabled.*/ 80 } hal_flash_security_state_t; 81 82 /*! @brief Hal flash margin value. */ 83 typedef enum _hal_flash_margin_value 84 { 85 kHAL_Flash_MarginValueNormal = 0, /*!< Use the 'normal' read level for 1s.*/ 86 kHAL_Flash_MarginValueUser, /*!< Apply the 'User' margin to the normal read-1 level.*/ 87 kHAL_Flash_MarginValueFactory, /*!< Apply the 'Factory' margin to the normal read-1 level.*/ 88 kHAL_Flash_MarginValueInvalid /*!< Not real margin level, Used to determine the range of valid margin level. */ 89 } hal_flash_margin_value_t; 90 /*! ********************************************************************************* 91 ************************************************************************************* 92 * Public memory declarations 93 ************************************************************************************* 94 ********************************************************************************** */ 95 96 /*! ********************************************************************************* 97 ************************************************************************************* 98 * Public prototypes 99 ************************************************************************************* 100 ********************************************************************************** */ 101 #if defined(__cplusplus) 102 extern "C" { 103 #endif 104 105 /*! 106 * @name Initialization 107 * @{ 108 */ 109 110 /*! 111 * @brief Initializes the flash hal adapter module. 112 * 113 * This function initializes the Flash module for the other Flash APIs. 114 * 115 * @retval #kStatus_HAL_Flash_Success API was executed successfully. 116 * @retval #kStatus_HAL_Flash_InvalidArgument An invalid argument is provided. 117 * @retval #kStatus_HAL_Flash_ExecuteInRamFunctionNotReady Execute-in-RAM function is not available. 118 * @retval #kStatus_HAL_Flash_PartitionStatusUpdateFailure Failed to update the partition status. 119 */ 120 hal_flash_status_t HAL_FlashInit(void); 121 122 /*! 123 * \brief Write aligned data to FLASH 124 * 125 * @note This API should be called after HAL_FlashEraseSector was called to make sure the flash was erased, and 126 * make sure the flash program address and flash program size is aligned with flash write unit size. 127 * 128 * @param dest The address of the Flash location 129 * @param size The number of bytes to be programed 130 * @param pData Pointer to the data to be programmed to Flash 131 * 132 * @retval #kStatus_HAL_Flash_Success API was executed successfully. 133 * 134 */ 135 hal_flash_status_t HAL_FlashProgram(uint32_t dest, uint32_t size, uint8_t *pData); 136 /*! 137 * \brief Write data to FLASH 138 * 139 * @note This API should be called after HAL_FlashEraseSector was called to make sure the flash was erased. 140 * @param dest The address of the Flash location 141 * @param size The number of bytes to be programed 142 * @param pData Pointer to the data to be programmed to Flash 143 * 144 * @retval #kStatus_HAL_Flash_Success API was executed successfully. 145 * 146 */ 147 hal_flash_status_t HAL_FlashProgramUnaligned(uint32_t dest, uint32_t size, uint8_t *pData); 148 149 /*! 150 * \brief Erase the Flash memory which is specified by the parameter dest and parameter size, the content of the 151 * specified flash memory would be 0xFF. 152 * 153 * @param dest The start address of the first sector to be erased 154 * @param size The number of bytes to be erased 155 * 156 * @retval #kStatus_HAL_Flash_Success API was executed successfully. 157 * 158 */ 159 hal_flash_status_t HAL_FlashEraseSector(uint32_t dest, uint32_t size); 160 161 /*! 162 * \brief Verify erase data in Flash 163 * 164 * @param start The address of the Flash location 165 * @param lengthInBytes The number of bytes to be checked 166 * @param margin Flash margin value 167 * @retval #kStatus_HAL_Flash_Success API was executed successfully. 168 */ 169 hal_flash_status_t HAL_FlashVerifyErase(uint32_t start, uint32_t lengthInBytes, hal_flash_margin_value_t margin); 170 /*! 171 * \brief Read data from FLASH 172 * 173 * @param scr The address of the Flash location to be read 174 * @param size The number of bytes to be read 175 * @param pData Pointer to the data to be read from Flash 176 * 177 * @retval #kStatus_HAL_Flash_Success API was executed successfully. 178 * 179 */ 180 hal_flash_status_t HAL_FlashRead(uint32_t src, uint32_t size, uint8_t *pData); 181 182 /*! 183 * \brief Read data from FLASH with ECC Fault detection enabled. 184 * 185 * Note : BusFault is not raised, just SoC indication 186 * 187 * @param scr The address of the Flash location to be read 188 * @param size The number of bytes to be read 189 * @param pData Pointer to the data to be read from Flash 190 * 191 * @retval #kStatus_HAL_Flash_Success API was executed successfully. 192 * #kStatus_HAL_Flash_EccError if ECC Fault error got raised 193 * 194 */ 195 hal_flash_status_t HAL_FlashReadCheckEccFaults(uint32_t src, uint32_t size, uint8_t *pData); 196 197 /*! 198 * @brief Returns the desired hal flash property. 199 * 200 * @param Property The desired property from the list of properties in 201 * enum hal_flash_property_tag_t 202 * @param value A pointer to the value returned for the desired flash property. 203 * 204 * @retval #kStatus_HAL_Flash_Success API was executed successfully. 205 * @retval #kStatus_HAL_Flash_InvalidArgument An invalid argument is provided. 206 * @retval #kStatus_HAL_Flash_NotSupport Flash currently not support. 207 */ 208 hal_flash_status_t HAL_FlashGetProperty(hal_flash_property_tag_t property, uint32_t *value); 209 210 /*! 211 * @brief Set the desired hal flash property. 212 * 213 * @param Property The desired property from the list of properties in 214 * enum hal_flash_property_tag_t 215 * @param value The value would be set to the desired flash property. 216 * 217 * @retval #kStatus_HAL_Flash_Success API was executed successfully. 218 * @retval #kStatus_HAL_Flash_InvalidArgument An invalid argument is provided. 219 * @retval #kStatus_HAL_Flash_NotSupport Flash currently not support. 220 */ 221 hal_flash_status_t HAL_FlashSetProperty(hal_flash_property_tag_t property, uint32_t value); 222 223 /*! 224 * @brief Returns the security state via the pointer passed into the function. 225 * 226 * This function retrieves the current flash security status, including the 227 * security enabling state and the backdoor key enabling state. 228 * 229 * @param state A pointer to the value returned for the current security status 230 * 231 * @retval #kStatus_HAL_Flash_Success API was executed successfully. 232 * @retval #kStatus_HAL_Flash_InvalidArgument An invalid argument is provided. 233 * @retval #kStatus_HAL_Flash_NotSupport Flash currently not support. 234 */ 235 hal_flash_status_t HAL_FlashGetSecurityState(hal_flash_security_state_t *state); 236 237 /*! 238 * \brief Return whether ECC error is currently raised in the the flash controller. 239 * 240 * Note : Used in BusFault handler so as to determine whether ECC correction action is required. 241 * 242 * @retval #true if flash controller is reporting an ECC fault. 243 * 244 */ 245 bool HAL_FlashEccStatusRaised(void); 246 247 #if defined(__cplusplus) 248 } 249 #endif 250 /*! @}*/ 251 #endif /* __FLASH_H__ */
