1 /* 2 * Copyright (c) 2024 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 16 /** 17 * @addtogroup HiDebug 18 * @{ 19 * 20 * @brief Provides debug functions. 21 * 22 * For example, you can use these functions to obtain cpu uage, memory, heap, capture trace. 23 * 24 * @since 12 25 */ 26 27 /** 28 * @file hidebug.h 29 * 30 * @brief Defines the debug functions of the HiDebug module. 31 * 32 * @library libohhidebug.so 33 * @kit PerformanceAnalysisKit 34 * @syscap SystemCapability.HiviewDFX.HiProfiler.HiDebug 35 * @since 12 36 */ 37 38 #ifndef HIVIEWDFX_HIDEBUG_H 39 #define HIVIEWDFX_HIDEBUG_H 40 41 #include <stdint.h> 42 #include "hidebug_type.h" 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif // __cplusplus 47 48 /** 49 * @brief Obtains the cpu usage of system. 50 * 51 * @return Returns the cpu usage of system 52 * If the result is zero,The possible reason is that get failed. 53 * @since 12 54 */ 55 double OH_HiDebug_GetSystemCpuUsage(); 56 57 /** 58 * @brief Obtains the cpu usage percent of a process. 59 * 60 * @return Returns the cpu usage percent of a process 61 * If the result is zero.The possbile reason is the current application usage rate is too low 62 * or acquisition has failed 63 * @since 12 64 */ 65 double OH_HiDebug_GetAppCpuUsage(); 66 67 /** 68 * @brief Obtains cpu usage of application's all thread. 69 * 70 * @return Returns all thread cpu usage. See {@link HiDebug_ThreadCpuUsagePtr}. 71 * If the HiDebug_ThreadCpuUsagePtr is null. 72 * The possible reason is that no thread related data was obtained 73 * @since 12 74 */ 75 HiDebug_ThreadCpuUsagePtr OH_HiDebug_GetAppThreadCpuUsage(); 76 77 /** 78 * @brief Free cpu usage buffer of application's all thread. 79 * 80 * @param threadCpuUsage Indicates applicatoin's all thread. See {@link HiDebug_ThreadCpuUsagePtr} 81 * Use the pointer generated through the OH_HiDebug_GetAppThreadCpuUsage(). 82 * @since 12 83 */ 84 void OH_HiDebug_FreeThreadCpuUsage(HiDebug_ThreadCpuUsagePtr *threadCpuUsage); 85 86 /** 87 * @brief Obtains the system memory size. 88 * 89 * @param systemMemInfo Indicates the pointer to {@link HiDebug_SystemMemInfo}. 90 * If there is no data in structure after the function.The Possible reason is system error. 91 * @since 12 92 */ 93 void OH_HiDebug_GetSystemMemInfo(HiDebug_SystemMemInfo *systemMemInfo); 94 95 /** 96 * @brief Obtains the memory info of application process. 97 * 98 * @param nativeMemInfo Indicates the pointer to {@link HiDebug_NativeMemInfo}. 99 * If there is no data in structure after the function.The Possible reason is system error. 100 * @since 12 101 */ 102 void OH_HiDebug_GetAppNativeMemInfo(HiDebug_NativeMemInfo *nativeMemInfo); 103 104 /** 105 * @brief Obtains the memory info of application process, with optional caching to improve performance. The cached value 106 * remains valid for 5 minutes. 107 * 108 * @param nativeMemInfo Indicates the pointer to {@link HiDebug_NativeMemInfo}. 109 * If there is no data in structure after the function.The Possible reason is system error. 110 * @param forceRefresh Whether to bypass the cache and retrieve fresh data. 111 * Set to true to force retrieve fresh data and immediate refresh the cached value; 112 * Set to false to retrieve the cached value when it is valid; otherwise, retrieve 113 * fresh data and refresh the cache. 114 * @since 20 115 */ 116 void OH_HiDebug_GetAppNativeMemInfoWithCache(HiDebug_NativeMemInfo *nativeMemInfo, bool forceRefresh); 117 118 /** 119 * @brief Obtains the memory limit of application process. 120 * 121 * @param memoryLimit Indicates the pointer to {@link HiDebug_MemoryLimit} 122 * If there is no data in structure after the function.The Possible reason is system error. 123 * @since 12 124 */ 125 void OH_HiDebug_GetAppMemoryLimit(HiDebug_MemoryLimit *memoryLimit); 126 127 /** 128 * @brief Start capture application trace. 129 * 130 * @param flag Trace flag 131 * @param tags Tag of trace 132 * @param limitSize Max size of trace file, in bytes, the max is 500MB. 133 * @param fileName Output trace file name buffer 134 * @param length Output trace file name buffer length 135 * @return 0 - Success 136 * {@link HIDEBUG_INVALID_ARGUMENT} 401 - if the fileName is null or the length is too short or 137 * limitSize is too small 138 * 11400102 - Have already capture trace 139 * 11400103 - Have no permission to trace 140 * 11400104 - The Possible reason is some error in the system. 141 * @since 12 142 */ 143 HiDebug_ErrorCode OH_HiDebug_StartAppTraceCapture(HiDebug_TraceFlag flag, 144 uint64_t tags, uint32_t limitSize, char* fileName, uint32_t length); 145 146 /** 147 * @brief Stop capture application trace. 148 * 149 * @return 0 - Success 150 * 11400104 - Maybe no trace is running or some error in the system. 151 * 11400105 - Have no trace running. 152 * @since 12 153 */ 154 HiDebug_ErrorCode OH_HiDebug_StopAppTraceCapture(); 155 156 /** 157 * @brief Get the graphics memory of application. 158 * 159 * @param value Indicates value of graphics memory, in kibibytes. 160 * @return Result code 161 * {@link HIDEBUG_SUCCESS} Get graphics memory success. 162 * {@link HIDEBUG_INVALID_ARGUMENT} Invalid argument，value is null. 163 * {@link HIDEBUG_TRACE_ABNORMAL} Failed to get the application memory due to a remote exception. 164 * @since 14 165 */ 166 HiDebug_ErrorCode OH_HiDebug_GetGraphicsMemory(uint32_t *value); 167 168 /** 169 * @brief Replace MallocDispatch table with developer customized memory functions. 170 * 171 * @param dispatchTable Indicates pointer of custom dispatch table. 172 * @return Result code 173 * {@link HIDEBUG_SUCCESS} Set customized dispatch table success. 174 * {@link HIDEBUG_INVALID_ARGUMENT} Invalid argument, dispatchTable is null pointer. 175 * @since 20 176 */ 177 HiDebug_ErrorCode OH_HiDebug_SetMallocDispatchTable(struct HiDebug_MallocDispatch *dispatchTable); 178 179 /** 180 * @brief Obtain current MallocDispatch table. 181 * 182 * @return The default dispatch table of malloc function. 183 184 * @since 20 185 */ 186 HiDebug_MallocDispatch* OH_HiDebug_GetDefaultMallocDispatchTable(void); 187 188 /** 189 * @brief Restore original MallocDispatch table. 190 * 191 * @since 20 192 */ 193 void OH_HiDebug_RestoreMallocDispatchTable(void); 194 195 /** 196 * @brief Get backtrace frames start from the given frame pointer and the function is signal-safe. 197 * 198 * @param object The backtrace object create by {@link OH_HiDebug_CreateBacktraceObject}. 199 * @param startFp The entry frame pointer. 200 * @param pcArray The array to place program counter values. 201 * @param size The size of the array to place program counter values. 202 * @return The number of stack frames written to array. 203 * @since 20 204 */ 205 int OH_HiDebug_BacktraceFromFp(HiDebug_Backtrace_Object object, void* startFp, void** pcArray, int size); 206 207 /** 208 * @brief Defines the callback of the {@link OH_HiDebug_SymbolicAddress} function. 209 * 210 * @param pc The program counter pass to {@link OH_HiDebug_SymbolicAddress}. 211 * @param arg The arg pass to {@link OH_HiDebug_SymbolicAddress}. 212 * @param frame The parsed frame content, the content is invalid after return of {@link OH_HiDebug_SymbolicAddress}. 213 * @since 20 214 */ 215 typedef void (*OH_HiDebug_SymbolicAddressCallback)(void* pc, void* arg, const HiDebug_StackFrame* frame); 216 217 /** 218 * @brief Get detailed symbol info by given pc and the function is not signal-safe. 219 * 220 * @param object The backtrace object create by {@link OH_HiDebug_CreateBacktraceObject}. 221 * @param pc The program counter return by {@link OH_HiDebug_BacktraceFromFp}. 222 * @param arg The arg will be pass to callback. 223 * @param callback The function to pass parsed frame to caller. 224 * @return Result code 225 * {@link HIDEBUG_SUCCESS} Get detailed frame info successfully and the callback is invoked. 226 * {@link HIDEBUG_INVALID_ARGUMENT} Invalid argument. 227 * {@link HIDEBUG_INVALID_SYMBOLIC_PC_ADDRESS} Could not find symbol info by given pc. 228 * @since 20 229 */ 230 HiDebug_ErrorCode OH_HiDebug_SymbolicAddress(HiDebug_Backtrace_Object object, void* pc, void* arg, 231 OH_HiDebug_SymbolicAddressCallback callback); 232 233 /** 234 * @brief Create a backtrace object for further using and the function is not signal-safe. 235 * 236 * @return BacktraceObject if Success or NULL if is not supported on current arch 237 * @since 20 238 */ 239 HiDebug_Backtrace_Object OH_HiDebug_CreateBacktraceObject(void); 240 241 /** 242 * @brief Destroy a backtrace object and the function is not signal-safe. 243 * 244 * @param object The object to be destroyed. 245 * @since 20 246 */ 247 void OH_HiDebug_DestroyBacktraceObject(HiDebug_Backtrace_Object object); 248 249 #ifdef __cplusplus 250 } 251 #endif // __cplusplus 252 /** @} */ 253 254 #endif // HIVIEWDFX_HIDEBUG_H