1 /** 2 * @file hi_crash.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 18 /** @defgroup iot_crash_info Crash Log Management 19 * @ingroup system 20 */ 21 22 #ifndef __HI_CRASH_H__ 23 #define __HI_CRASH_H__ 24 #include <hi_types.h> 25 #include <hi_mdm_types.h> 26 #include <hi_os_stat.h> 27 #include <hi_mem.h> 28 #include <hi_isr.h> 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 /** 35 * @ingroup iot_crash_info 36 * 37 * Version of the crash log module. CNcomment:死机存储模块版本号。CNend 38 */ 39 #define HI_SYSERR_VERSION 1 40 41 /** 42 * @ingroup iot_crash_info 43 * 44 * Power down flag. CNcomment:下电标识。CNend 45 */ 46 #define HI_SYSERR_POWER_DOWN 0x646F776E /* 下电标志 */ 47 48 /** 49 * @ingroup iot_crash_info 50 * 51 * No power down flag. CNcomment:未下电标识。CNend 52 */ 53 #define HI_SYSERR_NO_POWER_DOWN 0xFFFFFFFF 54 55 /** 56 * @ingroup iot_crash_info 57 * 58 * Length of the name string of an exception type. CNcomment:异常类型的名字字符串长度限制。CNend 59 */ 60 #define HI_SYSERR_EXC_TYPE_NAME_SIZE 8 61 62 /** 63 * @ingroup iot_crash_info 64 * 65 * Length of the task name string of a logged exception. 66 CNcomment:异常存储的任务名字字符串长度限制。CNend 67 */ 68 #define HI_SYSERR_EXC_TASK_NAME_SIZE 8 69 70 /** 71 * @ingroup iot_crash_info 72 * 73 * Depth of the scheduling track before an exception. CNcomment:异常前调度轨迹深度。CNend 74 */ 75 #define HI_SYSERR_EXC_TRACE_DEPTH 10 76 77 /** 78 * @ingroup iot_crash_info 79 * 80 * Exception stack information depth (unit: word). CNcomment:异常栈信息深度(word为单位)CNend 81 */ 82 #define HI_SYSERR_ESP_DATA_MAX_NUM 36 83 84 /** 85 * @ingroup iot_crash_info 86 * 87 * Extended depth of the exception stack SP to the stack bottom (unit: word). 88 CNcomment:异常栈sp向栈底扩展深度(word为单位)CNend 89 */ 90 #define HI_SYSERR_ESP_PRE_DATA_MAX_NUM 8 91 92 /** 93 * @ingroup iot_crash_info 94 * 95 * Version of the running kernel when the exception occurs. CNcomment:异常时对应的运行版本的版本号CNend 96 */ 97 #define HI_SYSERR_EXC_KERNEL_VER_LEN_MAX 60 98 #if !defined(PRODUCT_CFG_HSO) 99 #if (HI_SYSERR_EXC_KERNEL_VER_LEN_MAX < HI_BUILD_VER_PRODUCT_LEN_MAX) 100 #error "HI_SYSERR_EXC_KERNEL_VER_LEN_MAX != HI_BUILD_VER_PRODUCT_LEN_MAX" 101 #endif 102 #endif 103 104 /** 105 * @ingroup iot_crash_info 106 * Crash type eid.CNcomment:死机类型eid.CNend 107 */ 108 typedef enum { 109 HI_SYSERR_EID_POWER_DOWN, /**< Power Down or first Power on.CNcomment:下电重启或首次上电.CNend */ 110 HI_SYSERR_EID_FAULT_IN_TASK, /**< fault in task.CNcomment:任务中死机.CNend */ 111 HI_SYSERR_EID_FAULT_IN_ISR, /**< fault in isr.CNcomment:中断中死机.CNend */ 112 HI_SYSERR_EID_WATCHDOG_TSK, /**< watchdog reset(in task).CNcomment:看门狗死机(任务中).CNend */ 113 HI_SYSERR_EID_WATCHDOG_ISR, /**< watchdog reset(in isr).CNcomment:看门狗死机(中断中).CNend */ 114 HI_SYSERR_EID_SYS_SOFT_REBOOT, /**< system soft reboot.CNcomment:系统软复位.CNend */ 115 HI_SYSERR_EID_RESERVE, 116 HI_SYSERR_EID_MAX = 0xFF, 117 } hi_syserr_eid; 118 119 /* cpu registers */ 120 typedef struct { 121 hi_u32 mepc; 122 hi_u32 ra; 123 hi_u32 sp; 124 hi_u32 gp; 125 hi_u32 tp; 126 hi_u32 t0; 127 hi_u32 t1; 128 hi_u32 t2; 129 hi_u32 s0; 130 hi_u32 s1; 131 hi_u32 a0; 132 hi_u32 a1; 133 hi_u32 a2; 134 hi_u32 a3; 135 hi_u32 a4; 136 hi_u32 a5; 137 hi_u32 a6; 138 hi_u32 a7; 139 hi_u32 s2; 140 hi_u32 s3; 141 hi_u32 s4; 142 hi_u32 s5; 143 hi_u32 s6; 144 hi_u32 s7; 145 hi_u32 s8; 146 hi_u32 s9; 147 hi_u32 s10; 148 hi_u32 s11; 149 hi_u32 t3; 150 hi_u32 t4; 151 hi_u32 t5; 152 hi_u32 t6; 153 } syserr_reg_info; 154 155 /** 156 * @ingroup iot_crash_info 157 * Task information.CNcomment:任务信息.CNend 158 */ 159 typedef struct { 160 hi_char name[HI_SYSERR_EXC_TASK_NAME_SIZE]; 161 hi_u32 id; /**< task id.CNcomment:任务ID.CNend */ 162 hi_u32 status; /**< task status.CNcomment:任务运行状态.CNend */ 163 hi_u8 reserve[3]; /* reserve's size 3 */ 164 hi_u8 stack_data_index; /**< extended stack information index from stack bottom.CNcomment: 165 向栈底扩展的栈信息个数.CNend */ 166 hi_u16 stack_peak; /**< stack peak.CNcomment:栈使用峰值.CNend */ 167 hi_u16 stack_size; /**< stack size.CNcomment:任务栈大小.CNend */ 168 hi_u32 sp; /**< stack point.CNcomment:栈指针.CNend */ 169 hi_u32 stack[2]; /**< stack[2] is stack top and end address.CNcomment:栈顶和栈底地址.CNend */ 170 hi_u32 real_sp; /**< real stack point.CNcomment:真实栈指针.CNend */ 171 hi_u32 stack_pre_data[HI_SYSERR_ESP_PRE_DATA_MAX_NUM]; /**< extended stack information from stack bottom.CNcomment: 172 向栈底扩展的栈信息，用于回退栈类错误参考.CNend */ 173 hi_u32 stack_data[HI_SYSERR_ESP_DATA_MAX_NUM]; /**< stack data.CNcomment:栈数据.CNend */ 174 hi_u32 overflow_flag; /**< stack overflow flag.CNcomment:栈溢出标识.CNend */ 175 } syserr_task_info; 176 177 /** 178 * @ingroup iot_crash_info 179 * OS information.CNcomment:操作系统信息.CNend 180 */ 181 typedef struct { 182 hi_os_resource_use_stat usage; /**< os resource used count.CNcomment:系统资源使用个数.CNend */ 183 syserr_task_info task; /**< task information.CNcomment:任务信息.CNend */ 184 hi_mem_pool_crash_info mem; /**< memory pool information.CNcomment:动态内存池信息.CNend */ 185 } syserr_os_info; 186 187 /** 188 * @ingroup iot_crash_info 189 * Basic information.CNcomment:基础信息.CNend 190 */ 191 typedef struct { 192 hi_u16 log_ver; /**< log version.CNcomment:Log版本号.CNend */ 193 hi_u16 eid; /**< reset reason id.CNcomment:复位类型.CNend */ 194 hi_u32 rid; /**< exception id.CNcomment:异常类型.CNend */ 195 hi_u32 now_tsec; /**< current time relative start time.CNcomment:当前运行相对启动时间.CNend */ 196 hi_u32 crash_tsec; /**< crash time relative start time.CNcomment:异常时相对当次启动时间.CNend */ 197 hi_u32 boot_ver; 198 hi_char kernel_ver[HI_SYSERR_EXC_KERNEL_VER_LEN_MAX]; /**< kernel version.CNcomment:异常时运行版本的版本号.CNend */ 199 hi_char type_name[HI_SYSERR_EXC_TYPE_NAME_SIZE]; /**< reset reason name.CNcomment:类型名:与eid对应.CNend */ 200 } syserr_basic_info; 201 202 /** 203 * @ingroup iot_crash_info 204 * Watchdog information.CNcomment:看门狗信息.CNend 205 */ 206 typedef struct { 207 hi_u32 wdg_reset_pc; /**< watchdog reset reserved PC.CNcomment:看门狗复位PC.CNend */ 208 hi_u32 time_ms : 31; /**< watchdog timeout.CNcomment:看门狗超时时间.CNend */ 209 hi_u32 enable : 1; /**< watchdog enable.CNcomment:看门狗使能状态.CNend */ 210 } syserr_wdg_info; 211 212 /** 213 * @ingroup iot_crash_info 214 * Flash protect information.CNcomment:Flash保护信息.CNend 215 */ 216 typedef struct { 217 hi_u32 current_block : 13; /**< flash protect current block.CNcomment:Flash保护当前block.CNend */ 218 hi_u32 reserve : 18; 219 hi_u32 enable : 1; /**< flash protect enable.CNcomment:Flash保护使能状态.CNend */ 220 hi_u32 status_reg; /**< flash protect status.CNcomment:Flash保护状态寄存器.CNend */ 221 } syserr_fp_info; 222 223 /** 224 * @ingroup iot_crash_info 225 * Track item information.CNcomment:调度项信息.CNend 226 */ 227 typedef struct { 228 hi_u16 type; /**< track type.CNcomment:调度类型.CNend */ 229 hi_u16 id; /**< track ID.CNcomment:调度项id.CNend */ 230 hi_u32 data; /**< track userdata.CNcomment:调度用户数据.CNend */ 231 hi_u32 entry; /**< track Hook function Entry.CNcomment:调度回调勾子函数.CNend */ 232 hi_u32 timestamp; /**< The low 32 bit of the current time,us.CNcomment:调度时间戳.CNend */ 233 } syserr_track_item; 234 235 /** 236 * @ingroup iot_crash_info 237 * Track information.CNcomment:调度轨迹信息.CNend 238 */ 239 typedef struct { 240 hi_u16 current_item; /**< current track item.CNcomment:当前调度项.CNend */ 241 hi_u16 item_cnt; /**< track count of track information.CNcomment:调度项记录个数.CNend */ 242 syserr_track_item item[HI_SYSERR_EXC_TRACE_DEPTH]; /**< track item data.CNcomment:调度项数据.CNend */ 243 } syserr_track_info; 244 245 /** 246 * @ingroup iot_crash_info 247 * CPU csr registers information.CNcomment:CPU CSR寄存器信息.CNend 248 */ 249 typedef struct { 250 hi_u32 mstatus; /**< CPU mstatus register value.CNcomment:CPU mstatus寄存器值.CNend */ 251 hi_u32 mtval; /**< CPU mtval register value.CNcomment:CPU mtval寄存器值.CNend */ 252 hi_u32 mcause; /**< CPU mcause register value.CNcomment:CPU mcause寄存器值.CNend */ 253 hi_u32 ccause; /**< CPU ccause register value.CNcomment:CPU ccause寄存器值.CNend */ 254 hi_u16 cur_task_id; /**< current task id.CNcomment:当前任务ID.CNend */ 255 } syserr_core_info; 256 257 /** 258 * @ingroup iot_crash_info 259 * Saved exception information.CNcomment:异常时对应存储信息。CNend 260 */ 261 typedef struct { 262 hi_u32 sig_s; /**< header flag of crash information.CNcomment:异常信息前标识.CNend */ 263 hi_u32 power_down : 1; /**< power down flag.CNcomment:下电标识.CNend */ 264 hi_u32 crc_usable : 1; /**< CRC check enable of crash information.CNcomment:死机信息CRC校验使能.CNend */ 265 hi_u32 info_len : 14; /**< crash information length.CNcomment:死机信息长度.CNend */ 266 hi_u32 crc_val : 16; /**< CRC16 calue of crash information.CNcomment:CRC16校验值.CNend */ 267 268 syserr_basic_info basic_info; /**< basic data of crash information.CNcomment:死机基础信息.CNend */ 269 syserr_os_info os_info; /**< OS data of crash information.CNcomment:死机OS信息.CNend */ 270 syserr_reg_info reg_info; /**< CPU registers of crash information.CNcomment:死机CPU寄存器信息.CNend */ 271 syserr_wdg_info wdg_info; /**< watchdog data of crash information.CNcomment:死机看门狗.CNend */ 272 syserr_fp_info protect_info; /**< flash protect data of crash information.CNcomment:死机Flash保护信息.CNend */ 273 syserr_track_info track_info; /**< track data of crash information.CNcomment:死机调度信息.CNend */ 274 syserr_core_info core_info; /**< CPU CSR registers of crash information.CNcomment:死机CPU状态寄存器信息.CNend */ 275 hi_u32 sig_e; /**< end flag of crash information.CNcomment:异常信息后标识.CNend */ 276 } hi_syserr_info; 277 278 typedef hi_void (*hi_syserr_exc_callback)(hi_void); 279 280 /** 281 * @ingroup iot_crash_info 282 * @brief Initializes the exception information module. CNcomment:异常信息模块初始化。CNend 283 * 284 * @par 描述: 285 * Initializes the exception information module. CNcomment:异常信息模块初始化。CNend 286 * 287 * @attention s API can be called only once. Repeated initialization and multi-task calling are not supported. 288 CNcomment:仅初始化一次，未考虑多次初始化及多任务调用场景。CNend 289 * @param None 290 * 291 * @retval None 292 * @par 依赖: 293 * @li hi_crash.h：Describes Crash log APIs. CNcomment:文件用于描述死机相关接口。CNend 294 * @see None 295 */ 296 hi_void hi_syserr_init(hi_void); 297 298 /** 299 * @ingroup iot_crash_info 300 * @brief Obtains the system exception information pointer (in the memory). 301 CNcomment:获取系统异常信息指针(内存中)。CNend 302 * 303 * @par 描述: 304 * Obtains the system exception information pointer (in the memory). 305 CNcomment:获取系统异常信息指针(内存中)。CNend 306 * 307 * @attention None 308 * @param None 309 * 310 * @retval Pointer to the hi_syserr_info structure. CNcomment:hi_syserr_info结构体指针。CNend 311 * @par 依赖: 312 * @li hi_crash.h：Describes Crash log APIs. CNcomment:文件用于描述死机相关接口。CNend 313 * @see None 314 */ 315 hi_syserr_info *hi_syserr_ptr(hi_void); 316 317 /** 318 * @ingroup iot_crash_info 319 * @brief Obtains the system exception information pointer (in the flash). 320 CNcomment:获取系统异常信息指针(flash中)。CNend 321 * 322 * @par 描述: 323 * Obtains the system exception information pointer (in the flash). 324 CNcomment:获取系统异常信息指针(flash中)。CNend 325 * 326 * @attention None 327 * @param info [OUT] type #hi_syserr_info* ，Pointer to the hi_syserr_info structure. 328 CNcomment:异常信息读出后存放地址。CNend 329 * 330 * @retval #HI_ERR_SUCCESS Success. 331 * @retval #Other values Failure. For details, see hi_errno.h. 332 * @par 依赖: 333 * @li hi_crash.h：Describes Crash log APIs. CNcomment:文件用于描述死机相关接口。CNend 334 * @see None 335 */ 336 hi_u32 hi_syserr_get(hi_syserr_info *info); 337 338 /** 339 * @ingroup iot_crash_info 340 * @brief Register exception handling callback. CNcomment:注册异常死机处理回调函数。CNend 341 * 342 * @par 描述: 343 * Register exception handling callback. CNcomment:注册异常死机处理回调函数。CNend 344 * 345 * @attention None 346 * @param func [IN] type #hi_syserr_exc_callback ，Callback function of exception happens 347 CNcoment:异常回调函数。CNend 348 * 349 * @retval None 350 * @par 依赖: 351 * @li hi_crash.h：Describes Crash log APIs. CNcomment:文件用于描述死机相关接口。CNend 352 * @see None 353 */ 354 hi_void hi_syserr_exc_register(hi_syserr_exc_callback func); 355 356 /** 357 * @ingroup iot_crash_info 358 * @brief Retains the PC pointer when the watchdog reset in interrupt. CNcomment:中断中看门狗复位时记录PC值。CNend 359 * 360 * @par 描述: 361 * Retains the PC pointer when the watchdog reset in interrupt. 362 CNcomment:中断中看门狗复位时记录PC值，打开此功能后看门狗复位有复位不完全的风险，量产版本请务必关闭。CNend 363 * 364 * @attention None 365 * @param enable [IN] type #hi_bool ，Enable/Disable retains reset PC pointer function. 366 CNcoment:打开/关闭记录中断中看门狗复位PC值功能。CNend 367 * 368 * @retval None 369 * @par 依赖: 370 * @li hi_crash.h：Describes Crash log APIs. CNcomment:文件用于描述死机相关接口。CNend 371 * @see None 372 */ 373 hi_void hi_syserr_watchdog_debug(hi_bool enable); 374 375 /** 376 * @ingroup iot_crash_info 377 * @brief Whether reset after watchdog in task, default yes. CNcomment: 任务中触发看门狗时是否主动复位，默认复位。CNend 378 * 379 * @par 描述: 380 * Whether reset after wdt in task, default yes. 381 CNcomment: 任务中触发看门狗时是否主动复位，默认复位。CNend 382 * 383 * @attention None 384 * @param reset [IN] type #hi_bool ，Reset/Not reset after watchdog in task. 385 CNcoment:任务中触发看门狗时是否主动复位。CNend 386 * 387 * @retval None 388 * @par 依赖: 389 * @li hi_crash.h：Describes Crash log APIs. CNcomment:文件用于描述死机相关接口。CNend 390 * @see None 391 */ 392 hi_void hi_syserr_reset_after_wdg(hi_bool reset); 393 394 /** 395 * @ingroup iot_crash_info 396 * @brief Whether record crash info in flash, default no. CNcomment: 是否记录宕机信息到FLASH，默认不记录。CNend 397 * 398 * @par 描述: 399 * Whether record crash info in flash, default no. 400 CNcomment: 是否记录宕机信息到FLASH，默认不记录。CNend 401 * 402 * @attention None 403 * @param record [IN] type #hi_bool ，Record/Not record crash info in flash. 404 CNcoment:宕机时是否记录宕机信息到FLASH。CNend 405 * 406 * @retval None 407 * @par 依赖: 408 * @li hi_crash.h：Describes Crash log APIs. CNcomment:文件用于描述死机相关接口。CNend 409 * @see None 410 */ 411 hi_void hi_syserr_record_crash_info(hi_bool record); 412 413 /** 414 * @ingroup iot_crash_info 415 * @brief Retains the latest reboot reason. CNcomment:获取最近一次重启原因。CNend 416 * 417 * @par 描述: 418 * Retains the latest reboot reason. 419 CNcomment:获取最近一次重启原因。CNend 420 * 421 * @attention None 422 * @param err_id [OUT] type #hi_u16 * , error id, see hi_syserr_eid. 423 power_down or hard rebootwould always be 0. 424 CNcomment:重启原因ID，取值含义参见hi_syserr_eid，掉电重启和硬复位值均为0。CNend 425 * @param reboot_cause [OUT] type #hi_u32* , when err_id is soft reboot, see hi_sys_reboot_cause; 426 when err_id is fault in task or isr, reboot_cause would be mcause of cpu regs. Otherwise, reboot_cause would be 0. 427 CNcomment:当重启原因ID 为软复位时，取值含义见hi_sys_reboot_cause； 428 当为任务或中断中异常时，取值为cpu mcause寄存器，否则为0。 429 CNend 430 * 431 * @retval #HI_ERR_SUCCESS Success. 432 * @retval #Other Failure. See hi_errno.h for details. 433 * @par 依赖: 434 * @li hi_crash.h：Describes Crash log APIs. CNcomment:文件用于描述死机相关接口。CNend 435 * @see None 436 */ 437 hi_u32 hi_syserr_get_reboot_reason(hi_u16 *err_id, hi_u32 *reboot_cause); 438 439 440 #ifdef __cplusplus 441 } 442 #endif 443 444 #endif /* __HI_CRASH_H__ */ 445