1 /* 2 * Copyright (c) 2021-2025 Huawei Device Co., Ltd. 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 #ifndef DFX_SIGNAL_HANDLER_H 16 #define DFX_SIGNAL_HANDLER_H 17 18 #include <inttypes.h> 19 #include <stddef.h> 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 /** 26 * @brief Callback function for collecting thread information during a crash 27 * 28 * This function is invoked when a thread crash occurs, allowing custom 29 * thread-specific information to be written into the provided buffer. 30 * 31 * @param buf Buffer for writing thread information 32 * @param len Available buffer length in bytes 33 * @param ucontext Pointer to user-level context information 34 */ 35 typedef void(*ThreadInfoCallBack)(char* buf, size_t len, void* ucontext); 36 37 /** 38 * @brief Registers a callback for collecting thread information 39 * 40 * @param func Callback function pointer. Pass NULL to reset to default behavior. 41 */ 42 void SetThreadInfoCallback(ThreadInfoCallBack func); 43 44 /** 45 * @brief Callback type for retrieving thread stack identifier 46 * 47 * @return Unique stack identifier (TLS-based) for asynchronous stack tracking 48 */ 49 typedef uint64_t(*GetStackIdFunc)(void); 50 51 /** 52 * @brief Registers a callback for retrieving stack identifier 53 * 54 * @param func Callback function pointer. Pass NULL to disable stack ID tracking. 55 */ 56 void DFX_SetAsyncStackCallback(GetStackIdFunc func); 57 58 /** 59 * @brief Retrieves the application's running unique identifier 60 * 61 * @return Pointer to a null-terminated string representing the unique ID 62 * Valid until next call to DFX_SetAppRunningUniqueId() 63 */ 64 const char* DFX_GetAppRunningUniqueId(void); 65 66 /** 67 * @brief Sets the application's running unique identifier 68 * 69 * @param appRunningId Pointer to a null-terminated string (max 63 bytes) 70 * @param len Length of the identifier string (excluding null terminator) 71 * @return 0 on success, -1 on failure (invalid parameters or memory allocation error) 72 */ 73 int DFX_SetAppRunningUniqueId(const char* appRunningId, size_t len); 74 75 /** 76 * @brief Types of crash objects for diagnostic information 77 */ 78 enum CrashObjType : uint8_t { 79 OBJ_STRING = 0, // Null-terminated string (max 1024 bytes) 80 OBJ_MEMORY_64B, // 64-byte memory block 81 OBJ_MEMORY_256B, // 256-byte memory block 82 OBJ_MEMORY_1024B, // 1KB memory block 83 OBJ_MEMORY_2048B, // 2KB memory block 84 OBJ_MEMORY_4096B, // 4KB memory block 85 }; 86 87 /** 88 * @brief Attaches diagnostic information to the current crash context 89 * 90 * Recommended usage in C++: Prefer RAII-based UniqueCrashObj from 91 * dfx_unique_crash_obj.h for automatic resource management. 92 * 93 * @param type Type of diagnostic data (see CrashObjType) 94 * @param addr Pointer to the data buffer (must remain valid until crash) 95 * @return Handle to the previously set crash object (0 if none) 96 * @note The data pointed to by 'addr' must remain valid until crash occurs 97 */ 98 uintptr_t DFX_SetCrashObj(uint8_t type, uintptr_t addr); 99 100 /** 101 * @brief Detaches diagnostic information from the current crash context 102 * 103 * @param crashObj Handle returned by DFX_SetCrashObj() 104 */ 105 void DFX_ResetCrashObj(uintptr_t crashObj); 106 107 /** 108 * @brief Configuration options for crash log generation 109 */ 110 enum CrashLogConfigType : uint8_t { 111 EXTEND_PRINT_PC_LR = 0, // extern PC/LR registers in crash logs 112 CUT_OFF_LOG_FILE, // log file size limits 113 SIMPLIFY_PRINT_MAPS, // simplified process maps 114 }; 115 116 /** 117 * @brief Configures crash log generation behavior 118 * 119 * @param type Configuration attribute (see CrashLogConfigType) 120 * @param value Configuration value (semantics depend on type) 121 * @return 0 on success, -1 on error (check errno for details) 122 * @warning Non-thread-safe and non-signal-safe. Call early in program initialization. 123 */ 124 int DFX_SetCrashLogConfig(uint8_t type, uint32_t value); 125 126 #ifdef __cplusplus 127 } 128 #endif 129 #endif