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 SFC driver api \n 16 * 17 * History: \n 18 * 2022-11-29， Create file. \n 19 */ 20 #ifndef SFC_H 21 #define SFC_H 22 23 #include <stdint.h> 24 #include <errcode.h> 25 #include <common_def.h> 26 27 #ifdef __cplusplus 28 #if __cplusplus 29 extern "C" { 30 #endif /* __cplusplus */ 31 #endif /* __cplusplus */ 32 33 /** 34 * @defgroup drivers_driver_sfc SFC 35 * @ingroup drivers_driver 36 * @{ 37 * 38 */ 39 40 #define NULL_FLASH 0 41 42 /** 43 * @if Eng 44 * @brief Definition of SPI type of the read operation. 45 * @else 46 * @brief 读操作使用的SPI接口类型。 47 * @endif 48 */ 49 typedef enum sfc_read_if { 50 STANDARD_READ = 0x0, /*!< @if Eng Read in standard SPI mode (generally 0x03). 51 @else 以标准SPI模式执行读操作(指令一般为0x03)。 @endif */ 52 FAST_READ = 0x1, /*!< @if Eng Fast Read in standard SPI mode (generally 0x0B). 53 @else 以标准SPI模式执行快速读操作(指令一般为0x0B)。 @endif */ 54 FAST_READ_DUAL_OUTPUT = 0x2, /*!< @if Eng Read in Dual SPI Output mode (generally 0x3B). 55 @else 以双线Out SPI模式执行读操作(指令一般为0x3B)。 @endif */ 56 FAST_READ_DUAL_IO = 0x3, /*!< @if Eng Read in Dual SPI I/O mode (generally 0xBB). 57 @else 以双线In/Out SPI模式执行读操作(指令一般为0xBB)。 @endif */ 58 FAST_READ_QUAD_OUTPUT = 0x4, /*!< @if Eng Read in Quad SPI Output mode (generally 0xBB). 59 @else 以四线Out SPI模式执行读操作(指令一般为0x6B)。 @endif */ 60 FAST_READ_QUAD_IO = 0x5 /*!< @if Eng Read in Quad SPI I/O mode (generally 0xEB). 61 @else 以四线In/Out SPI模式执行读操作(指令一般为0xEB)。 @endif */ 62 } sfc_read_if_t; 63 64 /** 65 * @if Eng 66 * @brief Definition of SPI type of the write operation. 67 * @else 68 * @brief 写操作使用的SPI接口类型。 69 * @endif 70 */ 71 typedef enum sfc_write_if { 72 WRITE_DISABLE = 0x0, /*!< @if Eng Write operation disabled. 73 @else 写操作禁止。 @endif */ 74 PAGE_PROGRAM = 0x1, /*!< @if Eng Write in standard SPI mode 75 @else 以标准SPI模式执行写操作。 @endif */ 76 DUAL_INPUT_PAGE_PROGRAM = 0x2, /*!< @if Eng Write in Dual Input SPI mode 77 @else 以双线In SPI模式执行写操作。 @endif */ 78 DUAL_IO_PAGE_PROGRAM = 0x3, /*!< @if Eng Write in Dual I/O SPI mode 79 @else 以双线I/O SPI模式执行写操作。 @endif */ 80 QUAD_INPUT_PAGE_PROGRAM = 0x4, /*!< @if Eng Write in Quad Input SPI mode 81 @else 以四线In SPI模式执行写操作。 @endif */ 82 QUAD_IO_PAGE_PROGRAM = 0x5 /*!< @if Eng Write in Quad Input SPI mode 83 @else 以四线In SPI模式执行写操作。 @endif */ 84 } sfc_write_if_t; 85 86 /** 87 * @if Eng 88 * @brief Definition of Type of the Flash register operation. 89 * @else 90 * @brief Flash寄存器操作类型。 91 * @endif 92 */ 93 typedef enum sfc_flash_op { 94 READ_TYPE = 0x0, /*!< @if Eng Read flash info. 95 @else 读取Flash相关信息。 @endif */ 96 WRITE_TYPE = 0x1 /*!< @if Eng Set flash attribute. 97 @else 配置Flash状态。 @endif */ 98 } sfc_flash_op_t; 99 100 /** 101 * @if Eng 102 * @brief Initialize the SFC parameters. 103 * @else 104 * @brief SFC初始化参数。 105 * @endif 106 */ 107 typedef struct sfc_flash_config { 108 sfc_read_if_t read_type; /*!< @if Eng SPI type of the read operation. 109 @else 读操作SPI类型。 @endif */ 110 sfc_write_if_t write_type; /*!< @if Eng SPI type of the write operation. 111 @else 写操作SPI类型。 @endif */ 112 uint32_t mapping_addr; /*!< @if Eng Base address for flash memory mapping. 113 * The value corresponds to address 0 of the flash memory. 114 * Needs to be mapped to the SFC internal bus space. 115 * Only the upper 16 bits are valid. 116 * @else Flash映射基地址，对应为Flash的0地址。 117 * 需要映射在SFC内部总线空间，仅高16位有效。 @endif */ 118 uint32_t mapping_size; /*!< @if Eng Size of the flash memory mapping. 119 * The mapping space can be customized. 120 * The parameter must be in the format of 64 KB * 2^n, where n >= 0. 121 * The minimum size is 64 KB. 122 * The end address needs to be in the SFC internal bus space. 123 * If this parameter exceeds the size configured in the form, 124 * this parameter will be setted to the size configured in the form. 125 * @else Flash映射的大小，可自定义映射空间。 126 * 参数形式必须为64KB * 2^n，其中n >= 0。 127 * 尾地址需要在SFC内部总线空间。 128 * 超出了表单配置的Flash大小时会将大小置为表单中配置的大小。 @endif */ 129 } sfc_flash_config_t; 130 131 /** 132 * @if Eng 133 * @brief Initialize and Configure the SFC.The unidentified flash adopts the standard read/write of 512 KB by default. 134 * @param [in] config Initialization parameter, For details, see @ref sfc_flash_config_t. 135 * @retval ERRCODE_SUCC Success. 136 * @retval Other Failure. For details, see @ref errcode_t. 137 * @else 138 * @brief 初始化并配置SFC，未识别的Flash默认采用单线读写512KB的配置。 139 * @param [in] config 初始化参数 参考 @ref sfc_flash_config_t 。 140 * @retval ERRCODE_SUCC 成功。 141 * @retval Other 失败，参考 @ref errcode_t 。 142 * @endif 143 */ 144 errcode_t uapi_sfc_init(sfc_flash_config_t *config); 145 146 /** 147 * @if Eng 148 * @brief Initialize and Configure the SFC.The unidentified flash adopts the standard read/write of 512 KB by default. 149 * @param [in] config Initialization parameter, For details, see @ref sfc_flash_config_t. 150 * @retval ERRCODE_SUCC Success. 151 * @retval Other Failure. For details, see @ref errcode_t. 152 * @else 153 * @brief 初始化并配置SFC。rom 默认采用单线读写512KB的配置。 154 * @param [in] config 初始化参数 参考 @ref sfc_flash_config_t 。 155 * @retval ERRCODE_SUCC 成功。 156 * @retval Other 失败，参考 @ref errcode_t 。 157 * @endif 158 */ 159 errcode_t uapi_sfc_init_rom(sfc_flash_config_t *config); 160 161 /** 162 * @if Eng 163 * @brief Deinitialize the SFC. 164 * @else 165 * @brief 去初始化SFC。 166 * @endif 167 */ 168 void uapi_sfc_deinit(void); 169 170 /** 171 * @if Eng 172 * @brief Provide the read function in register mode. The read data is stored in the read_buffer by byte. 173 * This function cannot be called in an interrupt. 174 * @param [in] flash_addr The start address of the data. 175 * @param [out] read_buffer Buffer for receiving data. 176 * @param [in] read_size Number of bytes. 177 * @retval ERRCODE_SUCC Success. 178 * @retval Other Failure. For details, see @ref errcode_t. 179 * @else 180 * @brief 提供寄存器模式读功能，读取的数据将按字节存入read_buffer中。不允许在中断中调用。 181 * @param [in] flash_addr 数据所在的Flash首地址。 182 * @param [out] read_buffer 用于接收数据的buffer。 183 * @param [in] read_size 读取的字节数。 184 * @retval ERRCODE_SUCC 成功。 185 * @retval Other 失败，参考 @ref errcode_t 。 186 * @endif 187 */ 188 errcode_t uapi_sfc_reg_read(uint32_t flash_addr, uint8_t *read_buffer, uint32_t read_size); 189 190 /** 191 * @if Eng 192 * @brief Write data in register mode. The data to be written is stored in write_data by byte. 193 * This function cannot be called in an interrupt. 194 * @param [in] flash_addr The start address of the data. 195 * @param [in] write_data Data to be written. 196 * @param [in] write_size Number of bytes. 197 * @retval ERRCODE_SUCC Success. 198 * @retval Other Failure. For details, see @ref errcode_t. 199 * @else 200 * @brief 提供寄存器模式写功能，预计写入的数据按字节存入write_data中。不允许在中断中调用。 201 * @param [in] flash_addr 目标Flash首地址。 202 * @param [in] write_data 预计写入的数据。 203 * @param [in] write_size 写入数据的字节数。 204 * @retval ERRCODE_SUCC 成功。 205 * @retval Other 失败，参考 @ref errcode_t 。 206 * @endif 207 */ 208 errcode_t uapi_sfc_reg_write(uint32_t flash_addr, uint8_t *write_data, uint32_t write_size); 209 210 /** 211 * @if Eng 212 * @brief Use the register mode to erase the Flash memory.Enforce flash_addr and erase_size alignment by sector when 213 * writeback is disabled.This function cannot be called in an interrupt. 214 * @param [in] flash_addr Start address for erasing. 215 * @param [in] erase_size Size of the flash memory to be erased. 216 * @retval ERRCODE_SUCC Success. 217 * @retval Other Failure. For details, see @ref errcode_t. 218 * @else 219 * @brief 使用寄存器模式进行对Flash的擦除，不使能写回时强制要求地址和大小按扇区对齐。不允许在中断中调用。 220 * @param [in] flash_addr 擦除的首地址。 221 * @param [in] erase_size 擦除的Flash空间的大小。 222 * @retval ERRCODE_SUCC 成功。 223 * @retval Other 失败，参考 @ref errcode_t 。 224 * @endif 225 */ 226 errcode_t uapi_sfc_reg_erase(uint32_t flash_addr, uint32_t erase_size); 227 228 /** 229 * @if Eng 230 * @brief Use the register mode to erase the entire Flash memory.This function cannot be called in an interrupt. 231 * @retval ERRCODE_SUCC Success. 232 * @retval Other Failure. For details, see @ref errcode_t. 233 * @else 234 * @brief 使用寄存器模式对整片Flash进行擦除。不允许在中断中调用。 235 * @retval ERRCODE_SUCC 成功。 236 * @retval Other 失败，参考 @ref errcode_t 。 237 * @endif 238 */ 239 errcode_t uapi_sfc_reg_erase_chip(void); 240 241 /** 242 * @if Eng 243 * @brief Use the register mode to read and write Flash attribute.This function cannot be called in an interrupt. 244 * @param [in] cmd_type Sets the read/write type of this command. 245 * @param [in] cmd SPI command. 246 * @param [in,out] buffer data buffer. 247 * @param [in] length Length of the data to be read or written. The value must be less than 4. 248 * @retval ERRCODE_SUCC Success. 249 * @retval Other Failure. For details, see @ref errcode_t. 250 * @else 251 * @brief 使用寄存器模式对Flash属性进行读写。不允许在中断中调用。 252 * @param [in] cmd_type 设置指令的读写类型。 253 * @param [in] cmd SPI指令。 254 * @param [in,out] buffer 数据缓冲区。 255 * @param [in] length 需要读/写的数据长度，其值需要小于4。 256 * @retval ERRCODE_SUCC 成功。 257 * @retval Other 失败，参考 @ref errcode_t 。 258 * @endif 259 */ 260 errcode_t uapi_sfc_reg_other_flash_opt(sfc_flash_op_t cmd_type, uint8_t cmd, uint8_t *buffer, uint32_t length); 261 262 #if defined(CONFIG_SFC_SUPPORT_DMA) 263 /** 264 * @if Eng 265 * @brief Provide the read function in DMA mode. The read data is stored in the read_buffer by byte. 266 * This function cannot be called in an interrupt. 267 * @param [in] flash_addr The start address of the data. 268 * @param [out] read_buffer Buffer for receiving data. 269 * @param [in] read_size Number of bytes. 270 * @retval ERRCODE_SUCC Success. 271 * @retval Other Failure. For details, see @ref errcode_t. 272 * @else 273 * @brief 提供DMA模式读功能，读取的数据将按字节存入read_buffer中。不允许在中断中调用。 274 * @param [in] flash_addr 数据的Flash首地址。 275 * @param [out] read_buffer 用于接收数据的buffer。 276 * @param [in] read_size 读取的字节数。 277 * @retval ERRCODE_SUCC 成功。 278 * @retval Other 失败，参考 @ref errcode_t 。 279 * @endif 280 */ 281 errcode_t uapi_sfc_dma_read(uint32_t flash_addr, uint8_t *read_buffer, uint32_t read_size); 282 283 /** 284 * @if Eng 285 * @brief Write data in register mode. The data to be written is stored in write_data by byte. 286 * This function cannot be called in an interrupt. 287 * @param [in] flash_addr The start address of the data. 288 * @param [in] write_buffer Data to be written. 289 * @param [in] write_size Number of bytes. 290 * @retval ERRCODE_SUCC Success. 291 * @retval Other Failure. For details, see @ref errcode_t. 292 * @else 293 * @brief 提供寄存器模式写功能，预计写入的数据按字节存入write_data中。不允许在中断中调用。 294 * @param [in] flash_addr 目标Flash首地址。 295 * @param [in] write_buffer 预计写入的数据。 296 * @param [in] write_size 写入数据的字节数。 297 * @retval ERRCODE_SUCC 成功。 298 * @retval Other 失败，参考 @ref errcode_t 。 299 * @endif 300 */ 301 errcode_t uapi_sfc_dma_write(uint32_t flash_addr, uint8_t *write_buffer, uint32_t write_size); 302 303 #endif /* CONFIG_SFC_SUPPORT_DMA */ 304 305 #if defined(CONFIG_SFC_SUPPORT_LPM) 306 /** 307 * @if Eng 308 * @brief Suspend the SFC. 309 * @param [in] arg Argument for suspend. 310 * @retval ERRCODE_SUCC Success. 311 * @retval Other Failure. For details, see @ref errcode_t. 312 * @else 313 * @brief 挂起SFC。 314 * @param [in] arg 挂起所需要的参数。 315 * @retval ERRCODE_SUCC 成功。 316 * @retval Other 失败，参考 @ref errcode_t 。 317 * @endif 318 */ 319 errcode_t uapi_sfc_suspend(uintptr_t arg); 320 321 /** 322 * @if Eng 323 * @brief Resume the SFC. 324 * @param [in] arg Argument for resume. 325 * @retval ERRCODE_SUCC Success. 326 * @retval Other Failure. For details, see @ref errcode_t. 327 * @else 328 * @brief 恢复SFC。 329 * @param [in] arg 恢复所需要的参数。 330 * @retval ERRCODE_SUCC 成功。 331 * @retval Other 失败，参考 @ref errcode_t 。 332 * @endif 333 */ 334 errcode_t uapi_sfc_resume(uintptr_t arg); 335 #endif /* CONFIG_SFC_SUPPORT_LPM */ 336 337 /** 338 * @} 339 */ 340 #ifdef __cplusplus 341 #if __cplusplus 342 } 343 #endif /* __cplusplus */ 344 #endif /* __cplusplus */ 345 346 #endif 347