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 /** 42 * @if Eng 43 * @brief Get the Flash ID 44 * @param [out] flash_id flash ID is stored in this address. 45 * @retval ERRCODE_SUCC Success. 46 * @retval Other Failure. For details, see @ref errcode_t. 47 * @else 48 * @brief 获取Flash ID操作 49 * @param [out] flash_id 读取到的flash id。 50 * @retval ERRCODE_SUCC 成功。 51 * @retval Other 失败，参考 @ref errcode_t 。 52 * @endif 53 */ 54 typedef errcode_t (*hal_sfc_get_flash_id_t)(uint32_t *flash_id); 55 56 /** 57 * @if Eng 58 * @brief SFC initialization. 59 * @param [in] spi_ctrl For details, see @ref flash_spi_ctrl_t. 60 * @param [in] mapping_address Flash mapping address. 61 * @param [in] flash_size For details, see @ref bus_flash_size_t. 62 * @retval ERRCODE_SUCC Success. 63 * @retval Other Failure. For details, see @ref errcode_t. 64 * @else 65 * @brief SFC 初始化操作。 66 * @param [in] spi_ctrl 参考 @ref flash_spi_ctrl_t 。 67 * @param [in] mapping_address Flash映射地址。 68 * @param [in] flash_size 参考 @ref bus_flash_size 。 69 * @retval ERRCODE_SUCC 成功。 70 * @retval Other 失败，参考 @ref errcode_t 。 71 * @endif 72 */ 73 typedef errcode_t (*hal_sfc_init_t)(flash_spi_ctrl_t *spi_ctrl, uint32_t mapping_address, uint32_t flash_size); 74 75 /** 76 * @if Eng 77 * @brief SFC deinitialize. 78 * @else 79 * @brief SFC 去初始化操作。 80 * @endif 81 */ 82 typedef void (*hal_sfc_deinit_t)(void); 83 84 /** 85 * @if Eng 86 * @brief SFC read operation in SPI mode. 87 * @param [in] flash_addr Start address of the flash memory to be read. 88 * @param [out] read_buffer Pointer to data buffer. 89 * @param [in] read_size Amount of data to be read. 90 * @param [in] read_opreation Read command information. 91 * @retval ERRCODE_SUCC Success. 92 * @retval Other Failure. For details, see @ref errcode_t. 93 * @else 94 * @brief SFC 内嵌SPI模式读操作。 95 * @param [in] flash_addr 读数据首地址。 96 * @param [out] read_buffer 读操作数据缓冲区。 97 * @param [in] read_size 读数据总字节数，在driver层已做参数检查。 98 * @param [in] read_opreation 读指令信息。 99 * @retval ERRCODE_SUCC 成功。 100 * @retval Other 失败，参考 @ref errcode_t 。 101 * @endif 102 */ 103 typedef errcode_t (*hal_sfc_reg_read_t)(uint32_t flash_addr, uint8_t *read_buffer, uint32_t read_size, 104 spi_opreation_t read_opreation); 105 106 /** 107 * @if Eng 108 * @brief SFC write operation in SPI mode. 109 * @param [in] flash_addr Start address of the flash memory to be write. 110 * @param [in] write_data Pointer to data buffer. 111 * @param [in] write_size Amount of data to be write. 112 * @param [in] write_opreation Write command information. 113 * @retval ERRCODE_SUCC Success. 114 * @retval Other Failure. For details, see @ref errcode_t. 115 * @else 116 * @brief SFC 内嵌SPI模式写操作。 117 * @param [in] flash_addr 写数据首地址。 118 * @param [in] write_data 预计写入的数据。 119 * @param [in] write_size 写数据总字节数，在driver层已做参数检查。 120 * @param [in] write_opreation 写操作信息。 121 * @retval ERRCODE_SUCC 成功。 122 * @retval Other 失败，参考 @ref errcode_t 。 123 * @endif 124 */ 125 typedef errcode_t (*hal_sfc_reg_write_t)(uint32_t flash_addr, uint8_t *write_data, uint32_t write_size, 126 spi_opreation_t write_opreation); 127 128 /** 129 * @if Eng 130 * @brief SFC erase operation in SPI mode. 131 * @param [in] flash_addr Start address of the flash memory to be erase. 132 * @param [in] erase_opreation Erase command information. 133 * @param [in] delete_chip Indicates whether to erase the entire chip. 134 * @retval ERRCODE_SUCC Success. 135 * @retval Other Failure. For details, see @ref errcode_t. 136 * @else 137 * @brief SFC 内嵌SPI模式擦除操作。 138 * @param [in] flash_addr 预擦除的首地址。 139 * @param [in] erase_opreation 擦数据信息。 140 * @param [in] delete_chip 是否为整片擦除。 141 * @retval ERRCODE_SUCC 成功。 142 * @retval Other 失败，参考 @ref errcode_t 。 143 * @endif 144 */ 145 typedef errcode_t (*hal_sfc_reg_erase_t)(uint32_t flash_addr, spi_opreation_t erase_opreation, bool delete_chip); 146 147 /** 148 * @if Eng 149 * @brief SFC other flash operations in SPI mode. 150 * @param [in] opt_type Flash operation type. 151 * @param [in] cmd Flash command code. 152 * @param [in,out] buffer Pointer to data buffer 153 * @param [in] length Length of data buffer. The value is less than 4. Processed at the driver layer 154 * @retval ERRCODE_SUCC Success. 155 * @retval Other Failure. For details, see @ref errcode_t. 156 * @else 157 * @brief SFC 内嵌SPI模式Flash其他操作。 158 * @param [in] opt_type Flash操作类型。 159 * @param [in] cmd Flash操作指令码。 160 * @param [in,out] buffer 数据缓冲区。 161 * @param [in] length 缓冲区长度，driver层限制其值小于4。 162 * @retval ERRCODE_SUCC 成功。 163 * @retval Other 失败，参考 @ref errcode_t 。 164 * @endif 165 */ 166 typedef errcode_t (*hal_sfc_reg_flash_opreation_t)(uint32_t opt_type, uint8_t cmd, uint8_t *buffer, uint32_t length); 167 168 #if defined(CONFIG_SFC_SUPPORT_DMA) 169 170 /** 171 * @if Eng 172 * @brief SFC read operation in DMA mode 173 * @param [in] flash_addr Start address of the flash memory to be read. 174 * @param [out] read_buffer Pointer to data buffer 175 * @param [in] read_size Amount of data to be read. 176 * @retval ERRCODE_SUCC Success. 177 * @retval Other Failure. For details, see @ref errcode_t 178 * @else 179 * @brief SFC dma模式读操作 180 * @param [in] flash_addr 读操作flash首地址。 181 * @param [out] read_buffer 读数据缓冲区。 182 * @param [in] read_size 读数据总字节数。 183 * @retval ERRCODE_SUCC 成功。 184 * @retval Other 失败，参考 @ref errcode_t 。 185 * @endif 186 */ 187 typedef errcode_t (*hal_sfc_dma_read_t)(uint32_t flash_addr, uint8_t *read_buffer, uint32_t read_size); 188 189 /** 190 * @if Eng 191 * @brief SFC read operation in DMA mode. 192 * @param [in] flash_addr Start address of the flash memory to be write. 193 * @param [in] write_data Pointer to data buffer 194 * @param [in] write_size Length of the write data. 195 * @retval ERRCODE_SUCC Success. 196 * @retval Other Failure. For details, see @ref errcode_t. 197 * @else 198 * @brief SFC dma模式读操作。 199 * @param [in] flash_addr 写操作flash首地址。 200 * @param [in] write_data 预计写入的数据。 201 * @param [in] write_size 写数据字节数。 202 * @retval ERRCODE_SUCC 成功。 203 * @retval Other 失败，参考 @ref errcode_t 。 204 * @endif 205 */ 206 typedef errcode_t (*hal_sfc_dma_write_t)(uint32_t flash_addr, uint8_t *write_data, uint32_t write_size); 207 #endif /* CONFIG_SFC_SUPPORT_DMA */ 208 209 /** 210 * @if Eng 211 * @brief Interface of watchdog hal. 212 * @else 213 * @brief HAL层SFC的接口 214 * @endif 215 */ 216 typedef struct hal_sfc_funcs { 217 hal_sfc_get_flash_id_t get_flash_id; /*!< @if Eng SFC get flash id interface. 218 @else HAL层获取flash id接口 @endif */ 219 hal_sfc_init_t init; /*!< @if Eng SFC init interface. 220 @else HAL层SFC初始化接口 @endif */ 221 hal_sfc_deinit_t deinit; /*!< @if Eng SFC deinit interface. 222 @else HAL层SFC去初始化接口 @endif */ 223 hal_sfc_reg_read_t reg_read; /*!< @if Eng SFC read in SPI mode interface. 224 @else HAL层SFC内嵌SPI模式读接口 @endif */ 225 hal_sfc_reg_write_t reg_write; /*!< @if Eng SFC write in SPI mode interface. 226 @else HAL层SFC内嵌SPI模式写接口 @endif */ 227 hal_sfc_reg_erase_t reg_erase; /*!< @if Eng SFC erase in SPI mode interface. 228 @else HAL层SFC内嵌SPI模式擦除接口 @endif */ 229 hal_sfc_reg_flash_opreation_t flash_opreation; /*!< @if Eng SFC other flash operations in SPI mode interface. 230 @else HAL层SFC内嵌SPI模式Flash操作接口 @endif */ 231 #if defined(CONFIG_SFC_SUPPORT_DMA) 232 hal_sfc_dma_read_t dma_read; /*!< @if Eng SFC DMA read interface. 233 @else HAL层DMA模式读接口 @endif */ 234 hal_sfc_dma_write_t dma_write; /*!< @if Eng SFC DMA write interface. 235 @else HAL层DMA模式写接口 @endif */ 236 #endif 237 } hal_sfc_funcs_t; 238 239 /** 240 * @if Eng 241 * @brief Set the base address of registers. 242 * @retval ERRCODE_SUCC Success. 243 * @retval Other Failure. For details, see @ref errcode_t 244 * @else 245 * @brief 设置SFC寄存器的基地址 246 * @retval ERRCODE_SUCC 成功 247 * @retval Other 失败，参考 @ref errcode_t 248 * @endif 249 */ 250 errcode_t hal_sfc_regs_init(void); 251 252 /** 253 * @if Eng 254 * @brief Clear the base address of registers has been set by @ref hal_watchdog_regs_init. 255 * @else 256 * @brief 清除由 @ref hal_sfc_regs_init 设置的基地址 257 * @endif 258 */ 259 void hal_sfc_regs_deinit(void); 260 261 /** 262 * @if Eng 263 * @brief Register @ref hal_sfc_funcs_t into the g_hal_sfcs_funcs. 264 * @param [in] funcs Interface of SFC driver and SFC hal. 265 * @retval ERRCODE_SUCC Success. 266 * @retval Other Failure. For details, see @ref errcode_t 267 * @else 268 * @brief 注册 @ref hal_sfc_funcs_t 到 g_hal_sfcs_funcs 269 * @param [in] funcs Driver层SFC和HAL层SFC的接口实例 270 * @retval ERRCODE_SUCC 成功 271 * @retval Other 失败，参考 @ref errcode_t 272 * @endif 273 */ 274 errcode_t hal_sfc_register_funcs(hal_sfc_funcs_t *funcs); 275 276 /** 277 * @if Eng 278 * @brief Unregister @ref hal_sfc_funcs_t from the g_hal_sfcs_funcs. 279 * @return ERRCODE_SUCC Success. 280 * @retval Other Failure. For details, see @ref errcode_t 281 * @else 282 * @brief 从g_hal_sfcs_funcs注销 @ref hal_sfc_funcs_t 283 * @return ERRCODE_SUCC 成功 284 * @retval Other 失败，参考 @ref errcode_t 285 * @endif 286 */ 287 void hal_sfc_unregister_funcs(void); 288 289 /** 290 * @if Eng 291 * @brief Get interface of SFC driver and SFC hal, see @ref hal_sfc_funcs_t. 292 * @return Interface of SFC driver and SFC hal, see @ref hal_sfc_funcs_t. 293 * @else 294 * @brief 获取Driver层SFC和HAL层SFC的接口实例，参考 @ref hal_sfc_funcs_t. 295 * @return Driver层SFC和HAL层SFC的接口实例，参考 @ref hal_sfc_funcs_t. 296 * @endif 297 */ 298 hal_sfc_funcs_t *hal_sfc_get_funcs(void); 299 300 301 /** 302 * @} 303 */ 304 305 #ifdef __cplusplus 306 #if __cplusplus 307 } 308 #endif /* __cplusplus */ 309 #endif /* __cplusplus */ 310 311 #endif