1 /** 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 * 15 * Description: Provides hal sfc \n 16 * 17 * History: \n 18 * 2022-12-01, Create file. \n 19 */ 20 #ifndef HAL_SFC_H 21 #define HAL_SFC_H 22 23 #include <stdint.h> 24 #include <stdbool.h> 25 #include <common_def.h> 26 #include <errcode.h> 27 #include <sfc_porting.h> 28 29 #ifdef __cplusplus 30 #if __cplusplus 31 extern "C" { 32 #endif /* __cplusplus */ 33 #endif /* __cplusplus */ 34 35 /** 36 * @defgroup drivers_hal_sfc_api SFC 37 * @ingroup drivers_hal_sfc 38 * @{ 39 */ 40 41 #if defined(CONFIG_SFC_SUPPORT_RWE_INDEPENDENT) && CONFIG_SFC_SUPPORT_RWE_INDEPENDENT == 1 42 #define SFC_SECTION __attribute__((section(".FLSLOADERRAMCODE"))) 43 #else 44 #define SFC_SECTION 45 #endif 46 47 /** 48 * @if Eng 49 * @brief Get the Flash ID 50 * @param [out] flash_id flash ID is stored in this address. 51 * @retval ERRCODE_SUCC Success. 52 * @retval Other Failure. For details, see @ref errcode_t. 53 * @else 54 * @brief 获取Flash ID操作 55 * @param [out] flash_id 读取到的flash id。 56 * @retval ERRCODE_SUCC 成功。 57 * @retval Other 失败，参考 @ref errcode_t 。 58 * @endif 59 */ 60 errcode_t hal_sfc_get_flash_id(uint32_t *flash_id); 61 62 /** 63 * @if Eng 64 * @brief SFC initialization. 65 * @param [in] spi_ctrl For details, see @ref flash_spi_ctrl_t. 66 * @param [in] mapping_address Flash mapping address. 67 * @param [in] flash_size For details, see @ref bus_flash_size_t. 68 * @retval ERRCODE_SUCC Success. 69 * @retval Other Failure. For details, see @ref errcode_t. 70 * @else 71 * @brief SFC 初始化操作。 72 * @param [in] spi_ctrl 参考 @ref flash_spi_ctrl_t 。 73 * @param [in] mapping_address Flash映射地址。 74 * @param [in] flash_size 参考 @ref bus_flash_size 。 75 * @retval ERRCODE_SUCC 成功。 76 * @retval Other 失败，参考 @ref errcode_t 。 77 * @endif 78 */ 79 errcode_t hal_sfc_init(flash_spi_ctrl_t *spi_ctrl, uint32_t mapping, uint32_t flash_size); 80 81 /** 82 * @if Eng 83 * @brief SFC deinitialize. 84 * @else 85 * @brief SFC 去初始化操作。 86 * @endif 87 */ 88 void hal_sfc_deinit(void); 89 90 /** 91 * @if Eng 92 * @brief SFC read operation in SPI mode. 93 * @param [in] flash_addr Start address of the flash memory to be read. 94 * @param [out] read_buffer Pointer to data buffer. 95 * @param [in] read_size Amount of data to be read. 96 * @param [in] read_opreation Read command information. 97 * @retval ERRCODE_SUCC Success. 98 * @retval Other Failure. For details, see @ref errcode_t. 99 * @else 100 * @brief SFC 内嵌SPI模式读操作。 101 * @param [in] flash_addr 读数据首地址。 102 * @param [out] read_buffer 读操作数据缓冲区。 103 * @param [in] read_size 读数据总字节数，在driver层已做参数检查。 104 * @param [in] read_opreation 读指令信息。 105 * @retval ERRCODE_SUCC 成功。 106 * @retval Other 失败，参考 @ref errcode_t 。 107 * @endif 108 */ 109 errcode_t hal_sfc_reg_read(uint32_t flash_addr, uint8_t *read_buffer, uint32_t read_size, 110 spi_opreation_t read_opreation); 111 112 /** 113 * @if Eng 114 * @brief SFC write operation in SPI mode. 115 * @param [in] flash_addr Start address of the flash memory to be write. 116 * @param [in] write_data Pointer to data buffer. 117 * @param [in] write_size Amount of data to be write. 118 * @param [in] write_opreation Write command information. 119 * @retval ERRCODE_SUCC Success. 120 * @retval Other Failure. For details, see @ref errcode_t. 121 * @else 122 * @brief SFC 内嵌SPI模式写操作。 123 * @param [in] flash_addr 写数据首地址。 124 * @param [in] write_data 预计写入的数据。 125 * @param [in] write_size 写数据总字节数，在driver层已做参数检查。 126 * @param [in] write_opreation 写操作信息。 127 * @retval ERRCODE_SUCC 成功。 128 * @retval Other 失败，参考 @ref errcode_t 。 129 * @endif 130 */ 131 errcode_t hal_sfc_reg_write(uint32_t flash_addr, uint8_t *write_data, uint32_t write_size, 132 spi_opreation_t write_opreation); 133 134 /** 135 * @if Eng 136 * @brief SFC erase operation in SPI mode. 137 * @param [in] flash_addr Start address of the flash memory to be erase. 138 * @param [in] erase_opreation Erase command information. 139 * @param [in] delete_chip Indicates whether to erase the entire chip. 140 * @retval ERRCODE_SUCC Success. 141 * @retval Other Failure. For details, see @ref errcode_t. 142 * @else 143 * @brief SFC 内嵌SPI模式擦除操作。 144 * @param [in] flash_addr 预擦除的首地址。 145 * @param [in] erase_opreation 擦数据信息。 146 * @param [in] delete_chip 是否为整片擦除。 147 * @retval ERRCODE_SUCC 成功。 148 * @retval Other 失败，参考 @ref errcode_t 。 149 * @endif 150 */ 151 errcode_t hal_sfc_reg_erase(uint32_t flash_addr, spi_opreation_t erase_opreation, bool delete_chip); 152 153 /** 154 * @if Eng 155 * @brief SFC other flash operations in SPI mode. 156 * @param [in] opt_type Flash operation type. 157 * @param [in] cmd Flash command code. 158 * @param [in,out] buffer Pointer to data buffer 159 * @param [in] length Length of data buffer. The value is less than 4. Processed at the driver layer 160 * @retval ERRCODE_SUCC Success. 161 * @retval Other Failure. For details, see @ref errcode_t. 162 * @else 163 * @brief SFC 内嵌SPI模式Flash其他操作。 164 * @param [in] opt_type Flash操作类型。 165 * @param [in] cmd Flash操作指令码。 166 * @param [in,out] buffer 数据缓冲区。 167 * @param [in] length 缓冲区长度，driver层限制其值小于4。 168 * @retval ERRCODE_SUCC 成功。 169 * @retval Other 失败，参考 @ref errcode_t 。 170 * @endif 171 */ 172 typedef errcode_t (*hal_sfc_reg_flash_opreation_t)(uint32_t opt_type, uint8_t cmd, uint8_t *buffer, uint32_t length); 173 174 /** 175 * @if Eng 176 * @brief SFC other flash operations in SPI mode. 177 * @param [in] opt_type Flash operation type. 178 * @param [in] cmd Flash command code. 179 * @param [in,out] buffer Pointer to data buffer 180 * @param [in] length Length of data buffer. The value is less than 4. Processed at the driver layer 181 * @retval ERRCODE_SUCC Success. 182 * @retval Other Failure. For details, see @ref errcode_t. 183 * @else 184 * @brief SFC 内嵌SPI模式Flash其他操作。 185 * @param [in] opt_type Flash操作类型。 186 * @param [in] cmd Flash操作指令码。 187 * @param [in,out] buffer 数据缓冲区。 188 * @param [in] length 缓冲区长度，driver层限制其值小于4。 189 * @retval ERRCODE_SUCC 成功。 190 * @retval Other 失败，参考 @ref errcode_t 。 191 * @endif 192 */ 193 errcode_t hal_sfc_reg_flash_opreations(uint32_t opt_type, uint8_t cmd, uint8_t *buffer, uint32_t length); 194 195 #if defined(CONFIG_SFC_SUPPORT_DMA) 196 197 /** 198 * @if Eng 199 * @brief SFC read operation in DMA mode 200 * @param [in] flash_addr Start address of the flash memory to be read. 201 * @param [out] read_buffer Pointer to data buffer 202 * @param [in] read_size Amount of data to be read. 203 * @retval ERRCODE_SUCC Success. 204 * @retval Other Failure. For details, see @ref errcode_t 205 * @else 206 * @brief SFC dma模式读操作 207 * @param [in] flash_addr 读操作flash首地址。 208 * @param [out] read_buffer 读数据缓冲区。 209 * @param [in] read_size 读数据总字节数。 210 * @retval ERRCODE_SUCC 成功。 211 * @retval Other 失败，参考 @ref errcode_t 。 212 * @endif 213 */ 214 errcode_t hal_sfc_dma_read(uint32_t flash_addr, uint8_t *read_buffer, uint32_t read_size); 215 216 /** 217 * @if Eng 218 * @brief SFC read operation in DMA mode. 219 * @param [in] flash_addr Start address of the flash memory to be write. 220 * @param [in] write_data Pointer to data buffer 221 * @param [in] write_size Length of the write data. 222 * @retval ERRCODE_SUCC Success. 223 * @retval Other Failure. For details, see @ref errcode_t. 224 * @else 225 * @brief SFC dma模式读操作。 226 * @param [in] flash_addr 写操作flash首地址。 227 * @param [in] write_data 预计写入的数据。 228 * @param [in] write_size 写数据字节数。 229 * @retval ERRCODE_SUCC 成功。 230 * @retval Other 失败，参考 @ref errcode_t 。 231 * @endif 232 */ 233 errcode_t hal_sfc_dma_write(uint32_t flash_addr, uint8_t *write_data, uint32_t write_size); 234 #endif /* CONFIG_SFC_SUPPORT_DMA */ 235 236 #if defined(CONFIG_SFC_SUPPORT_LPM) 237 /** 238 * @if Eng 239 * @brief SFC suspend. 240 * @retval ERRCODE_SUCC Success. 241 * @retval Other Failure. For details, see @ref errcode_t. 242 * @else 243 * @brief 挂起SFC。 244 * @retval ERRCODE_SUCC 成功。 245 * @retval Other 失败，参考 @ref errcode_t 。 246 * @endif 247 */ 248 errcode_t hal_sfc_suspend(void); 249 250 /** 251 * @if Eng 252 * @brief SFC resume. 253 * @param [in] quad_mode Initialization operation instruction for enabling the QSPI mode of the flash memory. 254 * @retval ERRCODE_SUCC Success. 255 * @retval Other Failure. For details, see @ref errcode_t. 256 * @else 257 * @brief 恢复SFC。 258 * @param [in] quad_mode Flash开启QSPI模式的初始化操作指令。 259 * @retval ERRCODE_SUCC 成功。 260 * @retval Other 失败，参考 @ref errcode_t 。 261 * @endif 262 */ 263 errcode_t hal_sfc_resume(flash_cmd_execute_t *quad_mode); 264 #endif 265 266 /** 267 * @if Eng 268 * @brief Set the base address of registers. 269 * @retval ERRCODE_SUCC Success. 270 * @retval Other Failure. For details, see @ref errcode_t 271 * @else 272 * @brief 设置SFC寄存器的基地址 273 * @retval ERRCODE_SUCC 成功 274 * @retval Other 失败，参考 @ref errcode_t 275 * @endif 276 */ 277 errcode_t hal_sfc_regs_init(void); 278 279 /** 280 * @if Eng 281 * @brief Clear the base address of registers has been set by @ref hal_watchdog_regs_init. 282 * @else 283 * @brief 清除由 @ref hal_sfc_regs_init 设置的基地址 284 * @endif 285 */ 286 void hal_sfc_regs_deinit(void); 287 288 /** 289 * @if Eng 290 * @brief Sfc en/disable write protect. 291 * @param [in] flash_id sfc flash id. 292 * @param [in] regioon sfc flash protect region. 293 * @retval ERRCODE_SUCC Success. 294 * @retval Other Failure. For details, see @ref errcode_t. 295 * @else 296 * @brief 使能或失能SFC写保护。 297 * @param [in] flash_id sfc flash id。 298 * @param [in] regioon sfc flash保护的区域。 299 * @retval ERRCODE_SUCC 成功。 300 * @retval Other 失败，参考 @ref errcode_t 。 301 * @endif 302 */ 303 errcode_t hal_sfc_lock_protect(uint32_t flash_id, uint8_t region); 304 305 /** 306 * @if Eng 307 * @brief Sfc disable write protect. 308 * @param [in] flash_id sfc flash id. 309 * @retval ERRCODE_SUCC Success. 310 * @retval Other Failure. For details, see @ref errcode_t. 311 * @else 312 * @brief 失能SFC写保护。 313 * @param [in] flash_id sfc flash id。 314 * @retval ERRCODE_SUCC 成功。 315 * @retval Other 失败，参考 @ref errcode_t 。 316 * @endif 317 */ 318 errcode_t hal_sfc_unlock_protect(uint32_t flash_id); 319 320 /** 321 * @} 322 */ 323 324 #ifdef __cplusplus 325 #if __cplusplus 326 } 327 #endif /* __cplusplus */ 328 #endif /* __cplusplus */ 329 330 #endif