1 /** 2 * @file hi_nv.h 3 * 4 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 * Description: NV items consist of the NV items in the factory partition and NV items in the normal partition. 18 * The NV items in the normal partition are classified into NV items in the reserved partition and 19 * NV items in the common partition. The values of NV items in the reserved partition won't change 20 * after OTA upgrade. \n 21 * CNcomment:NV分为工厂区NV和非工厂区NV，非工厂区NV又分为保留区和普通区，保留区升级后保留NV值。CNend 22 */ 23 24 /** @defgroup iot_nv NV Management 25 * @ingroup system 26 */ 27 #ifndef __HI_NV_H__ 28 #define __HI_NV_H__ 29 #include <hi_types.h> 30 31 /** 32 * @ingroup iot_nv 33 * 34 * Maximum length of an NV item (unit: byte). CNcomment:NV项最大长度（单位：byte）。CNend 35 */ 36 #define HNV_ITEM_MAXLEN (256 - 4) 37 #define PRODUCT_CFG_NV_REG_NUM_MAX 4 38 39 #define HI_FNV_DEFAULT_ADDR 0x8000 40 #define HI_NV_DEFAULT_TOTAL_SIZE 0x2000 41 #define HI_NV_DEFAULT_BLOCK_SIZE 0x1000 42 43 /** 44 * @ingroup iot_nv 45 * 46 * Maximum number of registered hi_nv_register_change_nofity_proc functions. 47 CNcomment:hi_nv_register_change_nofity_proc注册函数个数最大值。CNend 48 */ 49 #define HI_NV_CHANGED_PROC_NUM PRODUCT_CFG_NV_REG_NUM_MAX 50 51 /** 52 * @ingroup iot_nv 53 * @brief Initialize Normal NV.CNcomment:非工厂区NV初始化。CNend 54 * 55 * @par 描述: 56 * Initialize Normal NV.CNcomment:非工厂区NV初始化。CNend 57 * 58 * @attention Parameters are obtained from the partition table and cannot be set randomly. 59 CNcomment:参数从分区表中获取，禁止随意设置。CNend 60 * @param addr [IN] type #hi_u32，Flash address of the normal NV partition, corresponding to the flash 61 * address of the member #HI_FLASH_PARTITON_NORMAL_NV in the partition table. 62 CNcomment:非工厂区NV的FLASH地址，对应分区表成员#HI_FLASH_PARTITON_NORMAL_NV的FLASH地址。CNend 63 * @param total_size [IN] type #hi_u32，total size of normal NV. 64 CNcomment:非工厂区NV的总大小。CNend 65 * @param block_size [IN] type #hi_u32，block size of normal NV. 66 CNcomment:非工厂区NV的块大小。CNend 67 * 68 * @retval #0 Success. 69 * @retval #Other Failure. For details, see hi_errno.h. 70 * @par 依赖: 71 * @li hi_nv.h：Describes NV APIs.CNcomment:文件用于描述NV相关接口。CNend 72 * @see hi_get_partition_table | hi_nv_read | hi_nv_write。 73 */ 74 HI_EAPI hi_u32 hi_nv_init(hi_u32 addr, hi_u32 total_size, hi_u32 block_size); 75 76 /** 77 * @ingroup iot_nv 78 * @brief Set the normal NV value.CNcomment:设置非工厂区NV值。CNend 79 * 80 * @par 描述: 81 * Set the normal NV value.CNcomment:设置非工厂区NV值。CNend 82 * 83 * @attention 84 * @li Only a normal NV item can be operated.CNcomment:仅能操作非工厂区NV。CNend 85 * @li This API is called only in a task and cannot be called in an interrupt. 86 CNcomment:仅支持任务中调用，不支持中断中调用。CNend 87 * @param id [IN] type #hi_u8，NV item ID, ranging from #HI_NV_NORMAL_ID_START to #HI_NV_NORMAL_USR_ID_END. 88 CNcomment:NV项ID，范围从#HI_NV_NORMAL_ID_START到#HI_NV_NORMAL_USR_ID_END。CNend 89 * @param pdata [IN] type #const hi_pvoid，NV item data.CNcomment:NV项数据。CNend 90 * @param len [IN] type #hi_u8，Length of an NV item (unit: byte). The len must be equal to the Length of 91 the real NV item data.CNcomment:NV项长度（单位：byte）。len必须和NV项的实际长度相等。CNend 92 * @param flag [IN] type #hi_u32，Reserve.CNcomment:保留参数。CNend 93 * @retval #0 Success. 94 * @retval #Other Failure. For details, see hi_errno.h. 95 * @par 依赖: 96 * @li hi_nv.h：Describes NV APIs.CNcomment:文件用于描述NV相关接口。CNend 97 * @see hi_nv_read。 98 */ 99 HI_EAPI hi_u32 hi_nv_write(hi_u8 id, const hi_pvoid pdata, hi_u8 len, hi_u32 flag); 100 101 /** 102 * @ingroup iot_nv 103 * @brief Read the normal NV value.CNcomment:读取非工厂区NV值。CNend 104 * 105 * @par 描述: 106 * Read the normal NV value.CNcomment:读取非工厂区NV值。CNend 107 * 108 * @attention 109 * @li Only a normal NV item can be operated.CNcomment:仅能操作非工厂区NV。CNend 110 * @li This API is called only in a task and cannot be called in an interrupt. 111 CNcomment:仅支持任务中调用，不支持中断中调用。CNend 112 * 113 * @param id [IN] type #hi_u8，NV item ID, ranging from #HI_NV_NORMAL_ID_START to #HI_NV_NORMAL_USR_ID_END. 114 CNcomment:NV项ID，范围从#HI_NV_NORMAL_ID_START到#HI_NV_NORMAL_USR_ID_END。CNend 115 * @param pdata [OUT] type #const hi_pvoid，NV item data.CNcomment:NV项数据。CNend 116 * @param len [IN] type #hi_u8，Length of an NV item (unit: byte). The len must be equal to the Length of 117 the real NV item data.CNcomment:NV项长度（单位：byte）。len必须和NV项的实际长度相等。CNend 118 * @param flag [IN] type #hi_u32，Reserve.CNcomment:保留参数。CNend 119 * 120 * @retval #0 Success. 121 * @retval #Other Failure. For details, see hi_errno.h. 122 * @par 依赖: 123 * @li hi_nv.h：Describes NV APIs.CNcomment:文件用于描述NV相关接口。CNend 124 * @see hi_nv_write。 125 */ 126 HI_EAPI hi_u32 hi_nv_read(hi_u8 id, const hi_pvoid pdata, hi_u8 len, hi_u32 flag); 127 128 /** 129 * @ingroup iot_nv 130 * @brief NV item change callback function.CNcomment:NV项变更回调函数。CNend 131 * 132 * @par 描述: 133 * NV item change callback function.CNcomment:NV项变更回调函数。CNend 134 * 135 * @attention This API can be called only after the SAL is initialized. 136 CNcomment:在SAL初始化结束后才可以调用该接口。CNend 137 * 138 * @param id [IN] type #hi_u8，NV item ID, ranging from #HI_NV_NORMAL_ID_START to #HI_NV_NORMAL_USR_ID_END. 139 CNcomment:NV项ID，范围从#HI_NV_NORMAL_ID_START到#HI_NV_NORMAL_USR_ID_END。CNend 140 * 141 * @retval #0 Success. 142 * @retval #Other Failure. For details, see hi_errno.h. 143 * @par 依赖: 144 * @li hi_nv.h：Describes NV APIs.CNcomment:文件用于描述NV相关接口。CNend 145 * @see None 146 */ 147 typedef hi_u32(*hi_nvm_changed_notify_f) (hi_u8 id); 148 149 /** 150 * @ingroup iot_nv 151 * @brief Register the normal NV item change notification function.CNcomment:非工厂区NV项变更通知函数注册。CNend 152 * 153 * @par 描述: 154 * Register the normal NV item change notification function.CNcomment:非工厂区NV项变更通知函数注册。CNend 155 * 156 * @attention 157 * Only the change notification function for normal NV items can be registered. 158 * The maximum number of registered functions is #HI_NV_CHANGED_PROC_NUM. If the number of registered functions 159 * exceeds the maximum, an error code is returned. 160 CNcomment:仅支持非工厂NV项注册变更通知函数处理。注册个数上限为#HI_NV_CHANGED_PROC_NUM，如超过会返回错误码。CNend 161 * 162 * @param min_id [IN] type #hi_u8，Minimum value of an NV item ID.CNcomment:NV项ID最小值。CNend 163 * @param max_id [IN] type #hi_u8，Maximum value of an NV item ID.CNcomment:NV项ID最大值。CNend 164 * @param func [IN] type #hi_nvm_changed_notify_f，Handling function for NV item changes. That is, after an NV item 165 * is changed, the NV module automatically calls the registered API. 166 CNcomment:NV项改变的处理函数, 即NV项变更后，NV模块会自动调用该注册的接口。CNend 167 * 168 * @retval #0 Success. 169 * @retval #Other Failure. For details, see hi_errno.h. 170 * @par 依赖: 171 * @li hi_nv.h：Describes NV APIs.CNcomment:文件用于描述NV相关接口。CNend 172 * @see None 173 */ 174 HI_EAPI hi_u32 hi_nv_register_change_notify_proc(hi_u8 min_id, hi_u8 max_id, hi_nvm_changed_notify_f func); 175 176 /** 177 * @ingroup iot_nv 178 * @brief Initialize factory NV.CNcomment:工厂区NV初始化。CNend 179 * 180 * @par 描述: 181 * Initialize factory NV.CNcomment: 工厂区NV初始化。CNend 182 * 183 * @attention The parameters cannot be set randomly and must match the product delivery plan. 184 CNcomment:参数不能随意配置，需要与产品出厂规划匹配。CNend 185 * @param addr [IN] type #hi_u32，Start address of the NV factory partition in the flash. The address is planned by 186 * the factory and set by the macro #HI_FNV_DEFAULT_ADDR. 187 CNcomment:设置工厂区NV FLASH首地址，由出厂规划，宏定义HI_FNV_DEFAULT_ADDR 统一设置。CNend 188 * @param total_size [IN] type #hi_u32，total size of factory NV. 189 CNcomment:工厂区NV的总大小。CNend 190 * @param block_size [IN] type #hi_u32，block size of factory NV. 191 CNcomment:工厂区NV的块大小。CNend 192 * @retval #0 Success. 193 * @retval #Other Failure. For details, see hi_errno.h. 194 * @par 依赖: 195 * @li hi_nv.h：Describes NV APIs.CNcomment:文件用于描述NV相关接口。CNend 196 * @see hi_factory_nv_write | hi_factory_nv_read。 197 */ 198 HI_EAPI hi_u32 hi_factory_nv_init(hi_u32 addr, hi_u32 total_size, hi_u32 block_size); 199 200 /** 201 * @ingroup iot_nv 202 * @brief Set the NV value in the factory partition. CNcomment:设置工厂区NV值。CNend 203 * 204 * @par 描述: 205 * Set the NV value in the factory partition.CNcomment:设置工厂区NV值。CNend 206 * 207 * @attention None 208 * @param id [IN] type #hi_u8，NV item ID, ranging from #HI_NV_FACTORY_ID_START to #HI_NV_FACTORY_USR_ID_END. 209 CNcomment:NV项ID，范围从#HI_NV_FACTORY_ID_START到#HI_NV_FACTORY_USR_ID_END。CNend 210 * @param pdata [IN] type #hi_pvoid，NV item data.CNcomment:NV项数据。CNend 211 * @param len [IN] type #hi_u8，Length of an NV item (unit: byte). The len must be equal to the Length of 212 the real NV item data.CNcomment:NV项长度（单位：byte）。len必须和NV项的实际长度相等。CNend 213 * @param flag [IN] type #hi_u32，Reserve.CNcomment:保留参数。CNend 214 * 215 * @retval #0 Success. 216 * @retval #Other Failure. For details, see hi_errno.h. 217 * @par 依赖: 218 * @li hi_nv.h：Describes NV APIs.CNcomment:文件用于描述NV相关接口。CNend 219 * @see hi_factory_nv_read。 220 */ 221 HI_EAPI hi_u32 hi_factory_nv_write(hi_u8 id, hi_pvoid pdata, hi_u8 len, hi_u32 flag); 222 223 /** 224 * @ingroup iot_nv 225 * @brief Read the NV value in the factory partition.CNcomment:读取工厂区NV值。CNend 226 * 227 * @par 描述: 228 * Read the NV value in the factory partition.CNcomment:读取工厂区NV值。CNend 229 * 230 * @attention None 231 * 232 * @param id [IN] type #hi_u8，NV item ID, ranging from #HI_NV_NORMAL_ID_START to #HI_NV_NORMAL_USR_ID_END. 233 CNcomment:NV项ID，范围从#HI_NV_NORMAL_ID_START到#HI_NV_NORMAL_USR_ID_END。CNend 234 * @param pdata [OUT] type #hi_pvoid，NV item data.CNcomment:NV项数据。CNend 235 * @param len [IN] type #hi_u8，Length of an NV item (unit: byte). The len must be equal to the Length of 236 the real NV item data.CNcomment:NV项长度（单位：byte）。len必须和NV项的实际长度相等。CNend 237 * @param flag [IN] type #hi_u32，Reserve.CNcomment:保留参数。CNend 238 * 239 * @retval #0 Success. 240 * @retval #Other Failure. For details, see hi_errno.h. 241 * @par 依赖: 242 * @li hi_nv.h：Describes NV APIs.CNcomment:文件用于描述NV相关接口。CNend 243 * @see hi_factory_nv_write。 244 */ 245 HI_EAPI hi_u32 hi_factory_nv_read(hi_u8 id, hi_pvoid pdata, hi_u8 len, hi_u32 flag); 246 247 /** 248 * @ingroup iot_nv 249 * @brief refresh backup nv, always used after finish factory test. 250 CNcomment:更新原始备份区NV，常用于产测完成后。CNend 251 * 252 * @par 描述: 253 * refresh backup nv, always used after finish factory test. 254 CNcomment:更新原始备份区NV，常用于产测完成后。CNend 255 * 256 * @attention should refresh backup nv if factory test modified nv. 257 CNcomment: 如果产测有修改NV参数，应该在产测完成后同步刷新备份区NV。CNend 258 * 259 * @param None 260 * 261 * @retval #0 Success. 262 * @retval #Other Failure. For details, see hi_errno.h. 263 * @par 依赖: 264 * @li hi_nv.h：Describes NV APIs.CNcomment:文件用于描述NV相关接口。CNend 265 */ 266 HI_EAPI hi_u32 hi_nv_refresh_backup(hi_void); 267 268 /** 269 * @ingroup iot_nv 270 * @brief restore nv by oringinal backup nv. 271 CNcomment: 使用原始备份NV 覆盖当前NV，常用于恢复出厂设置。CNend 272 * 273 * @par 描述: 274 * restore nv by oringinal backup nv. 275 CNcomment:使用原始备份NV 覆盖当前NV，常用于恢复出厂设置。CNend 276 * 277 * @attention should reset system after restore nv. only restore normal nv, not include factory nv. 278 CNcomment: 使用备份NV 覆盖原始NV后，须重启系统。 279 仅覆盖工作区NV，不包括工厂区NV。CNend 280 * 281 * @param None 282 * 283 * @retval #0 Success. 284 * @retval #Other Failure. For details, see hi_errno.h. 285 * @par 依赖: 286 * @li hi_nv.h：Describes NV APIs.CNcomment:文件用于描述NV相关接口。CNend 287 */ 288 HI_EAPI hi_u32 hi_nv_restore_by_backup(hi_void); 289 290 #endif 291