1# hidebug.h 2 3<!--Kit: Performance Analysis Kit--> 4<!--Subsystem: HiviewDFX--> 5<!--Owner: @hello_harmony; @yu_haoqiaida--> 6<!--SE: @kutcherzhou1--> 7<!--TSE: @gcw_KuLfPSbe--> 8 9## Overview 10 11Defines the APIs for debugging. 12 13**File to include**: <hidebug/hidebug.h> 14 15**Library**: libohhidebug.so 16 17**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 18 19**Since**: 12 20 21**Related module**: [HiDebug](capi-hidebug.md) 22 23## Summary 24 25### Functions 26 27| Name| typedef Keyword| Description| 28| -- | -- | -- | 29| [double OH_HiDebug_GetSystemCpuUsage()](#oh_hidebug_getsystemcpuusage) | - | Obtains the CPU usage of the system. Note that this API involves cross-process communication and takes a long time. Therefore, you are advised not to call this API in the main thread.| 30| [double OH_HiDebug_GetAppCpuUsage()](#oh_hidebug_getappcpuusage) | - | Obtains the CPU usage of an application. Note that this API involves cross-process communication and takes a long time. Therefore, you are advised not to call this API in the main thread.| 31| [HiDebug_ThreadCpuUsagePtr OH_HiDebug_GetAppThreadCpuUsage()](#oh_hidebug_getappthreadcpuusage) | - | Obtains the CPU usage of all threads of an application. Note that this API involves cross-process communication and takes a long time. Therefore, you are advised not to call this API in the main thread.| 32| [void OH_HiDebug_FreeThreadCpuUsage(HiDebug_ThreadCpuUsagePtr *threadCpuUsage)](#oh_hidebug_freethreadcpuusage) | - | Releases the **HiDebug_ThreadCpuUsagePtr**.| 33| [void OH_HiDebug_GetSystemMemInfo(HiDebug_SystemMemInfo *systemMemInfo)](#oh_hidebug_getsystemmeminfo) | - | Obtains system memory information.| 34| [void OH_HiDebug_GetAppNativeMemInfo(HiDebug_NativeMemInfo *nativeMemInfo)](#oh_hidebug_getappnativememinfo) | - | Obtains the memory information of an application process. Note that this API needs to read the **/proc/{pid}/smaps_rollup** node information, which takes a long time. Therefore, you are advised not to call this API in the main thread.| 35| [void OH_HiDebug_GetAppNativeMemInfoWithCache(HiDebug_NativeMemInfo *nativeMemInfo, bool forceRefresh)](#oh_hidebug_getappnativememinfowithcache) | - | Obtains the memory information of an application process. This API has a cache mechanism to improve its performance. The cache value is valid for 5 minutes. Note that this API needs to read the **/proc/{pid}/smaps_rollup** node information, which takes a long time. Therefore, you are advised not to call this API in the main thread.| 36| [void OH_HiDebug_GetAppMemoryLimit(HiDebug_MemoryLimit *memoryLimit)](#oh_hidebug_getappmemorylimit) | - | Obtains the memory limit of an application process.| 37| [HiDebug_ErrorCode OH_HiDebug_StartAppTraceCapture(HiDebug_TraceFlag flag, uint64_t tags, uint32_t limitSize,char* fileName, uint32_t length)](#oh_hidebug_startapptracecapture) | - | Starts application trace collection.| 38| [HiDebug_ErrorCode OH_HiDebug_StopAppTraceCapture()](#oh_hidebug_stopapptracecapture) | - | Stops application trace collection.| 39| [HiDebug_ErrorCode OH_HiDebug_GetGraphicsMemory(uint32_t *value)](#oh_hidebug_getgraphicsmemory) | - | Obtains the size of the GPU memory. Note that this API involves multiple cross-process communications and may take more than 1 second. Therefore, you are advised not to call this API in the main thread.| 40| [int OH_HiDebug_BacktraceFromFp(HiDebug_Backtrace_Object object, void* startFp, void** pcArray, int size)](#oh_hidebug_backtracefromfp) | - | Performs stack back-tracing based on the given fp address. This function is async-signal-safe.| 41| [typedef void (\*OH_HiDebug_SymbolicAddressCallback)(void* pc, void* arg, const HiDebug_StackFrame* frame)](#oh_hidebug_symbolicaddresscallback) | OH_HiDebug_SymbolicAddressCallback | If the [OH_HiDebug_SymbolicAddress](capi-hidebug-h.md#oh_hidebug_symbolicaddress) API is successfully called, the parsed stack information is returned to the caller through this function. Note that this API involves multiple I/O operations and takes a long time. Therefore, you are advised not to call this API in the main thread.| 42| [HiDebug_ErrorCode OH_HiDebug_SymbolicAddress(HiDebug_Backtrace_Object object, void* pc, void* arg,OH_HiDebug_SymbolicAddressCallback callback)](#oh_hidebug_symbolicaddress) | - | Obtains detailed symbol information based on the specified PC address. This function is not asyn-signal-safe.| 43| [HiDebug_Backtrace_Object OH_HiDebug_CreateBacktraceObject(void)](#oh_hidebug_createbacktraceobject) | - | Creates an object for stack back-tracing and parsing. This function is not asyn-signal-safe.| 44| [void OH_HiDebug_DestroyBacktraceObject(HiDebug_Backtrace_Object object)](#oh_hidebug_destroybacktraceobject) | - | Destroys the object created by [OH_HiDebug_CreateBacktraceObject](capi-hidebug-h.md#oh_hidebug_createbacktraceobject) to release the resources applied for during stack back-tracing and parsing. This function is not asyn-signal-safe.| 45| [HiDebug_ErrorCode OH_HiDebug_SetMallocDispatchTable(struct HiDebug_MallocDispatch *dispatchTable)](#oh_hidebug_setmallocdispatchtable) | - | Sets the MallocDisaptch table of the system C library to replace the custom memory operation functions (such as **malloc**, **free**, **calloc**, **realloc**, **mmap**, and **munmap**). The MallocDisaptch table is a struct that encapsulates memory operation functions such as **malloc**, **calloc**, **realloc**, and **free** in the system C library. HiDebug_MallocDispatch is only a part of the MallocDisaptch struct.| 46| [HiDebug_MallocDispatch* OH_HiDebug_GetDefaultMallocDispatchTable(void)](#oh_hidebug_getdefaultmallocdispatchtable) | - | Obtains the default MallocDispatch table of the system C library. You can call [OH_HiDebug_RestoreMallocDispatchTable](capi-hidebug-h.md#oh_hidebug_restoremallocdispatchtable) to restore the table.| 47| [void OH_HiDebug_RestoreMallocDispatchTable(void)](#oh_hidebug_restoremallocdispatchtable) | - | Restores the MallocDispatch table of the system C library.| 48 49## Function Description 50 51### OH_HiDebug_GetSystemCpuUsage() 52 53``` 54double OH_HiDebug_GetSystemCpuUsage() 55``` 56 57**Description** 58 59Obtains the CPU usage of the system. Note that this API involves cross-process communication and takes a long time. Therefore, you are advised not to call this API in the main thread. 60 61**Since**: 12 62 63**Returns** 64 65| Type| Description| 66| -- | -- | 67| double | Returns the system CPU usage if the operation is successful. Returns **0** if the operation fails.| 68 69### OH_HiDebug_GetAppCpuUsage() 70 71``` 72double OH_HiDebug_GetAppCpuUsage() 73``` 74 75**Description** 76 77Obtains the CPU usage of an application. Note that this API involves cross-process communication and takes a long time. Therefore, you are advised not to call this API in the main thread. 78 79**Since**: 12 80 81**Returns** 82 83| Type| Description| 84| -- | -- | 85| double | Returns the application CPU usage obtained if the operation is successful. If **0** is returned, the CPU usage of the current application is too low.| 86 87### OH_HiDebug_GetAppThreadCpuUsage() 88 89``` 90HiDebug_ThreadCpuUsagePtr OH_HiDebug_GetAppThreadCpuUsage() 91``` 92 93**Description** 94 95Obtains the CPU usage of all threads of an application. Note that this API involves cross-process communication and takes a long time. Therefore, you are advised not to call this API in the main thread. 96 97**Since**: 12 98 99**Returns** 100 101| Type| Description | 102| -- |----------------------------------------------------------------------------------------------| 103| [HiDebug_ThreadCpuUsagePtr](capi-hidebug-hidebug-threadcpuusage.md) | CPU usage of all threads. For details, see [HiDebug_ThreadCpuUsagePtr](capi-hidebug-hidebug-threadcpuusage.md).<br> If null is returned, the thread data may not be obtained.| 104 105### OH_HiDebug_FreeThreadCpuUsage() 106 107``` 108void OH_HiDebug_FreeThreadCpuUsage(HiDebug_ThreadCpuUsagePtr *threadCpuUsage) 109``` 110 111**Description** 112 113Releases the **HiDebug_ThreadCpuUsagePtr**. 114 115**Since**: 12 116 117 118**Parameters** 119 120| Name| Description| 121| -- | -- | 122| [HiDebug_ThreadCpuUsagePtr](capi-hidebug-hidebug-threadcpuusage.md) *threadCpuUsage | Pointer to the available CPU buffer of all threads of the application. For details, see [HiDebug_ThreadCpuUsagePtr](capi-hidebug-hidebug-threadcpuusage.md). The input parameter is obtained by **OH_HiDebug_GetAppThreadCpuUsage()**.| 123 124### OH_HiDebug_GetSystemMemInfo() 125 126``` 127void OH_HiDebug_GetSystemMemInfo(HiDebug_SystemMemInfo *systemMemInfo) 128``` 129 130**Description** 131 132Obtains system memory information. 133 134**Since**: 12 135 136 137**Parameters** 138 139| Name| Description| 140| -- | -- | 141| [HiDebug_SystemMemInfo](capi-hidebug-hidebug-systemmeminfo.md) *systemMemInfo | Pointer to [HiDebug_SystemMemInfo](capi-hidebug-hidebug-systemmeminfo.md). If the struct data is empty after the function is called, the calling fails.| 142 143### OH_HiDebug_GetAppNativeMemInfo() 144 145``` 146void OH_HiDebug_GetAppNativeMemInfo(HiDebug_NativeMemInfo *nativeMemInfo) 147``` 148 149**Description** 150 151Obtains the memory information of an application process. Note that this API needs to read the **/proc/{pid}/smaps_rollup** node information, which takes a long time. Therefore, you are advised not to call this API in the main thread. 152 153**Since**: 12 154 155 156**Parameters** 157 158| Name| Description| 159| -- | -- | 160| [HiDebug_NativeMemInfo](capi-hidebug-hidebug-nativememinfo.md) *nativeMemInfo | Pointer to [HiDebug_NativeMemInfo](capi-hidebug-hidebug-nativememinfo.md). If the struct data is empty after the function is called, the calling fails.| 161 162### OH_HiDebug_GetAppNativeMemInfoWithCache() 163 164``` 165void OH_HiDebug_GetAppNativeMemInfoWithCache(HiDebug_NativeMemInfo *nativeMemInfo, bool forceRefresh) 166``` 167 168**Description** 169 170Obtains the memory information of an application process. This API has a cache mechanism to improve its performance. The cache value is valid for 5 minutes. Note that this API needs to read the **/proc/{pid}/smaps_rollup** node information, which takes a long time. Therefore, you are advised not to call this API in the main thread. 171 172**Since**: 20 173 174 175**Parameters** 176 177| Name| Description| 178| -- | -- | 179| [HiDebug_NativeMemInfo](capi-hidebug-hidebug-nativememinfo.md) *nativeMemInfo | Pointer to [HiDebug_NativeMemInfo](capi-hidebug-hidebug-nativememinfo.md). If the struct data is empty after the function is called, the calling fails.| 180| bool forceRefresh | Whether to ignore the cache validity and forcibly update the cache value.<br> The value **true** means to directly obtain the current memory data and update the cache value.<br> The value **false** means to directly return the cache value if the cache is valid and obtain the current memory data and update the cache value if the cache is invalid.| 181 182### OH_HiDebug_GetAppMemoryLimit() 183 184``` 185void OH_HiDebug_GetAppMemoryLimit(HiDebug_MemoryLimit *memoryLimit) 186``` 187 188**Description** 189 190Obtains the memory limit of an application process. 191 192**Since**: 12 193 194 195**Parameters** 196 197| Name| Description| 198| -- | -- | 199| [HiDebug_MemoryLimit](capi-hidebug-hidebug-memorylimit.md) *memoryLimit | Pointer to [HiDebug_MemoryLimit](capi-hidebug-hidebug-memorylimit.md). If the struct data is empty after the function is called, the calling fails.| 200 201### OH_HiDebug_StartAppTraceCapture() 202 203``` 204HiDebug_ErrorCode OH_HiDebug_StartAppTraceCapture(HiDebug_TraceFlag flag, uint64_t tags, uint32_t limitSize,char* fileName, uint32_t length) 205``` 206 207**Description** 208 209Starts application trace collection. 210 211**Since**: 12 212 213 214**Parameters** 215 216| Name| Description| 217| -- | -- | 218| [HiDebug_TraceFlag](capi-hidebug-type-h.md#hidebug_traceflag) flag | Type of the thread (the main thread or all threads of the application) to trace.| 219| uint64_t tags | Modules or subsystems to trace.| 220| uint32_t limitSize | Maximum size of the trace file (in bytes), which is 500 MB.| 221| char* fileName | Buffer for the output trace file.| 222| uint32_t length | Length of the buffer for the output trace file.| 223 224**Returns** 225 226| Type| Description| 227| -- | -- | 228| [HiDebug_ErrorCode](capi-hidebug-type-h.md#hidebug_errorcode) | **0** - The operation is successful.<br> [HIDEBUG_INVALID_ARGUMENT](capi-hidebug-type-h.md#hidebug_errorcode) 401 - The **fileName** parameter is a null pointer, the input **length** parameter is too small, or the **limitSize** parameter is less than or equal to 0.<br> **11400102** - A trace is already started.<br> **11400103** - You do not have the permission to start the trace function.<br> **11400104** - An internal system error occurs.| 229 230### OH_HiDebug_StopAppTraceCapture() 231 232``` 233HiDebug_ErrorCode OH_HiDebug_StopAppTraceCapture() 234``` 235 236**Description** 237 238Stops application trace collection. 239 240**Since**: 12 241 242**Returns** 243 244| Type| Description| 245| -- | -- | 246| [HiDebug_ErrorCode](capi-hidebug-type-h.md#hidebug_errorcode) | **0** - The operation is successful.<br> **11400104** - An internal system error occurs.<br> **11400105** - No trace collection is running.| 247 248### OH_HiDebug_GetGraphicsMemory() 249 250``` 251HiDebug_ErrorCode OH_HiDebug_GetGraphicsMemory(uint32_t *value) 252``` 253 254**Description** 255 256Obtains the size of the GPU memory. Note that this API involves multiple cross-process communications and may take more than 1 second. Therefore, you are advised not to call this API in the main thread. 257 258**Since**: 14 259 260 261**Parameters** 262 263| Name| Description| 264| -- | -- | 265| uint32_t *value | Pointer to the variable that stores the size (in KB) of the obtained GPU memory.| 266 267**Returns** 268 269| Type| Description| 270| -- | -- | 271| [HiDebug_ErrorCode](capi-hidebug-type-h.md#hidebug_errorcode) | **0** - The API is obtained successfully.<br> **401** - The parameter is a null pointer, which is invalid.<br> **11400104** - An internal system error occurs.| 272 273### OH_HiDebug_BacktraceFromFp() 274 275``` 276int OH_HiDebug_BacktraceFromFp(HiDebug_Backtrace_Object object, void* startFp, void** pcArray, int size) 277``` 278 279**Description** 280 281Performs stack back-tracing based on the given fp address. This function is async-signal-safe. 282 283**Since**: 20 284 285 286**Parameters** 287 288| Name| Description| 289| -- | -- | 290| [HiDebug_Backtrace_Object](capi-hidebug-hidebug-backtrace-object--8h.md) object | Object obtained by the [OH_HiDebug_CreateBacktraceObject](capi-hidebug-h.md#oh_hidebug_createbacktraceobject) API for stack backtracing.| 291| void* startFp | Start frame pointer for stack backtracing.| 292| void** pcArray | Array of PC addresses obtained from stack backtracing.| 293| int size | Length of the PC address array obtained by stack backtracing.| 294 295**Returns** 296 297| Type| Description| 298| -- | -- | 299| int | Number of stack frames that are successfully backtraced and written to **pcArray**. If 0 is returned, stack backtracing may fail.| 300 301### OH_HiDebug_SymbolicAddressCallback() 302 303``` 304typedef void (*OH_HiDebug_SymbolicAddressCallback)(void* pc, void* arg, const HiDebug_StackFrame* frame) 305``` 306 307**Description** 308 309If the [OH_HiDebug_SymbolicAddress](capi-hidebug-h.md#oh_hidebug_symbolicaddress) API is successfully called, the parsed stack information is returned to the caller through this function. Note that this API involves multiple I/O operations and takes a long time. Therefore, you are advised not to call this API in the main thread. 310 311**Since**: 20 312 313 314**Parameters** 315 316| Name| Description| 317| -- | -- | 318| void* pc | PC address transferred to the [OH_HiDebug_SymbolicAddress](capi-hidebug-h.md#oh_hidebug_symbolicaddress) API for parsing.| 319| void* arg | arg value of the [OH_HiDebug_SymbolicAddress](capi-hidebug-h.md#oh_hidebug_symbolicaddress) API.| 320| [ const HiDebug_StackFrame](capi-hidebug-hidebug-stackframe.md)* frame | Pointer to [HiDebug_StackFrame](capi-hidebug-hidebug-stackframe.md), which is obtained by parsing the PC address passed to the [OH_HiDebug_SymbolicAddress](capi-hidebug-h.md#oh_hidebug_symbolicaddress) API. What the pointer points to is valid only in the function scope.| 321 322### OH_HiDebug_SymbolicAddress() 323 324``` 325HiDebug_ErrorCode OH_HiDebug_SymbolicAddress(HiDebug_Backtrace_Object object, void* pc, void* arg,OH_HiDebug_SymbolicAddressCallback callback) 326``` 327 328**Description** 329 330Obtains detailed symbol information based on the specified PC address. This function is not asyn-signal-safe. 331 332**Since**: 20 333 334 335**Parameters** 336 337| Name| Description| 338| -- | -- | 339| [HiDebug_Backtrace_Object](capi-hidebug-hidebug-backtrace-object--8h.md) object | Object created by the [OH_HiDebug_CreateBacktraceObject](capi-hidebug-h.md#oh_hidebug_createbacktraceobject) API.| 340| void* pc | PC address obtained through the [OH_HiDebug_BacktraceFromFp](capi-hidebug-h.md#oh_hidebug_backtracefromfp) API.| 341| void* arg | Reserved custom parameter. After the symbol is successfully parsed, this parameter is passed to [OH_HiDebug_SymbolicAddressCallback](capi-hidebug-h.md#oh_hidebug_symbolicaddresscallback).| 342| [OH_HiDebug_SymbolicAddressCallback](capi-hidebug-h.md#oh_hidebug_symbolicaddresscallback) callback | Callback used to return the parsed stack information.| 343 344**Returns** 345 346| Type| Description| 347| -- | -- | 348| [HiDebug_ErrorCode](capi-hidebug-type-h.md#hidebug_errorcode) | For details, see [HiDebug_ErrorCode](capi-hidebug-type-h.md#hidebug_errorcode).<br> [HIDEBUG_SUCCESS](capi-hidebug-type-h.md#hidebug_errorcode): The detailed stack information is successfully obtained, and the callback input by the function is called.<br> [HIDEBUG_INVALID_ARGUMENT](capi-hidebug-type-h.md#hidebug_errorcode): Invalid parameter.<br> [HIDEBUG_INVALID_SYMBOLIC_PC_ADDRESS](capi-hidebug-type-h.md#hidebug_errorcode): Failed to find the corresponding symbol based on the input PC address.| 349 350### OH_HiDebug_CreateBacktraceObject() 351 352``` 353HiDebug_Backtrace_Object OH_HiDebug_CreateBacktraceObject(void) 354``` 355 356**Description** 357 358Creates an object for stack backtracing and parsing. This function is not asyn-signal-safe. 359 360**Since**: 20 361 362**Returns** 363 364| Type| Description| 365| -- | -- | 366| [HiDebug_Backtrace_Object](capi-hidebug-hidebug-backtrace-object--8h.md) | Pointer to the created object. If the object fails to be created, NULL is returned.| 367 368### OH_HiDebug_DestroyBacktraceObject() 369 370``` 371void OH_HiDebug_DestroyBacktraceObject(HiDebug_Backtrace_Object object) 372``` 373 374**Description** 375 376Destroys the object created by [OH_HiDebug_CreateBacktraceObject](capi-hidebug-h.md#oh_hidebug_createbacktraceobject) to release the resources applied for during stack backtracing and parsing. This function is not asyn-signal-safe. 377 378**Since**: 20 379 380 381**Parameters** 382 383| Name| Description| 384| -- | -- | 385| [HiDebug_Backtrace_Object](capi-hidebug-hidebug-backtrace-object--8h.md) object | Object to destroy.| 386 387### OH_HiDebug_SetMallocDispatchTable() 388 389``` 390HiDebug_ErrorCode OH_HiDebug_SetMallocDispatchTable(struct HiDebug_MallocDispatch *dispatchTable) 391``` 392 393**Description** 394 395Sets the MallocDisaptch table of the system C library to replace the custom memory operation functions (such as **malloc**, **free**, **calloc**, **realloc**, **mmap**, and **munmap**). The MallocDisaptch table is a struct that encapsulates memory operation functions such as **malloc**, **calloc**, **realloc**, and **free** in the system C library. **HiDebug_MallocDispatch** is only a part of the **MallocDisaptch** struct. 396 397**Since**: 20 398 399 400**Parameters** 401 402| Name| Description| 403| -- | -- | 404| [struct HiDebug_MallocDispatch](capi-hidebug-hidebug-mallocdispatch.md) *dispatchTable | Pointer to the [HiDebug_MallocDispatch](capi-hidebug-hidebug-mallocdispatch.md) struct that contains the custom memory operation functions.| 405 406**Returns** 407 408| Type| Description| 409| -- | -- | 410| [HiDebug_ErrorCode](capi-hidebug-type-h.md#hidebug_errorcode) | For details, see [HiDebug_ErrorCode](capi-hidebug-type-h.md#hidebug_errorcode).<br> [HIDEBUG_SUCCESS](capi-hidebug-type-h.md#hidebug_errorcode): The custom memory operation function is set successfully.<br> [HIDEBUG_INVALID_ARGUMENT](capi-hidebug-type-h.md#hidebug_errorcode): Invalid parameter.| 411 412### OH_HiDebug_GetDefaultMallocDispatchTable() 413 414``` 415HiDebug_MallocDispatch* OH_HiDebug_GetDefaultMallocDispatchTable(void) 416``` 417 418**Description** 419 420Obtains the default MallocDispatch table of the system C library. You can call [OH_HiDebug_RestoreMallocDispatchTable](capi-hidebug-h.md#oh_hidebug_restoremallocdispatchtable) to restore the table. 421 422**Since**: 20 423 424**Returns** 425 426| Type| Description| 427| -- | -- | 428| HiDebug_MallocDispatch* | Pointer to the default [HiDebug_MallocDispatch](capi-hidebug-hidebug-mallocdispatch.md) struct of the current C library.| 429 430### OH_HiDebug_RestoreMallocDispatchTable() 431 432``` 433void OH_HiDebug_RestoreMallocDispatchTable(void) 434``` 435 436**Description** 437 438Restores the MallocDispatch table of the system C library. 439 440**Since**: 20 441