hidebug.h
Overview
Defines the APIs for debugging.
File to include: <hidebug/hidebug.h>
Library: libohhidebug.so
System capability: SystemCapability.HiviewDFX.HiProfiler.HiDebug
Since: 12
Related module: HiDebug
Summary
Functions
| Name | typedef Keyword | Description |
|---|---|---|
| double 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. |
| double 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. |
| HiDebug_ThreadCpuUsagePtr 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. |
| void OH_HiDebug_FreeThreadCpuUsage(HiDebug_ThreadCpuUsagePtr *threadCpuUsage) | - | Releases the HiDebug_ThreadCpuUsagePtr. |
| void OH_HiDebug_GetSystemMemInfo(HiDebug_SystemMemInfo *systemMemInfo) | - | Obtains system memory information. |
| void OH_HiDebug_GetAppNativeMemInfo(HiDebug_NativeMemInfo *nativeMemInfo) | - | 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. |
| void OH_HiDebug_GetAppNativeMemInfoWithCache(HiDebug_NativeMemInfo *nativeMemInfo, bool forceRefresh) | - | 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. |
| void OH_HiDebug_GetAppMemoryLimit(HiDebug_MemoryLimit *memoryLimit) | - | Obtains the memory limit of an application process. |
| HiDebug_ErrorCode OH_HiDebug_StartAppTraceCapture(HiDebug_TraceFlag flag, uint64_t tags, uint32_t limitSize, char* fileName, uint32_t length) | - | Starts application trace collection. |
| HiDebug_ErrorCode OH_HiDebug_StopAppTraceCapture() | - | Stops application trace collection. |
| HiDebug_ErrorCode OH_HiDebug_GetGraphicsMemory(uint32_t *value) | - | 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. |
| int OH_HiDebug_BacktraceFromFp(HiDebug_Backtrace_Object object, void* startFp, void** pcArray, int size) | - | Performs stack back-tracing based on the given fp address. This function is async-signal-safe. |
| typedef void (*OH_HiDebug_SymbolicAddressCallback)(void* pc, void* arg, const HiDebug_StackFrame* frame) | OH_HiDebug_SymbolicAddressCallback | If the OH_HiDebug_SymbolicAddress API is successfully called, the parsed stack information is returned to the caller through this function. Note: 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. |
| HiDebug_ErrorCode OH_HiDebug_SymbolicAddress(HiDebug_Backtrace_Object object, void* pc, void* arg, OH_HiDebug_SymbolicAddressCallback callback) | - | Obtains detailed symbol information based on the specified PC address. This function is not asyn-signal-safe. Note: 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. |
| HiDebug_Backtrace_Object OH_HiDebug_CreateBacktraceObject(void) | - | Creates an object for stack backtracing and parsing. This function is not asyn-signal-safe. Note: 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. |
| void OH_HiDebug_DestroyBacktraceObject(HiDebug_Backtrace_Object object) | - | Destroys the object created by OH_HiDebug_CreateBacktraceObject to release the resources applied for during stack back-tracing and parsing. This function is not asyn-signal-safe. |
| HiDebug_ErrorCode OH_HiDebug_SetMallocDispatchTable(struct HiDebug_MallocDispatch *dispatchTable) | - | Sets the MallocDispatch table in the basic C library to temporarily replace the original memory operation functions (such as malloc, free, calloc, realloc, mmap, and munmap) with the custom memory operation functions. The MallocDispatch table is a struct that encapsulates memory operation functions such as malloc, calloc, realloc, and free in the basic C library. HiDebug_MallocDispatch is only a part of the MallocDispatch struct. Note: Do not directly call memory operation functions such as malloc, free, calloc, realloc, mmap, and munmap in the libc standard library in the custom memory operation functions. Otherwise, a deadlock occurs. Do not use hilog to print logs in the custom malloc method. Otherwise, a deadlock occurs. |
| HiDebug_MallocDispatch* OH_HiDebug_GetDefaultMallocDispatchTable(void) | - | Obtains the default MallocDispatch table of the system C library. You can call OH_HiDebug_RestoreMallocDispatchTable to restore the table. |
| void OH_HiDebug_RestoreMallocDispatchTable(void) | - | Restores the MallocDispatch table of the system C library. |
| HiDebug_ErrorCode OH_HiDebug_GetGraphicsMemorySummary(uint32_t interval, HiDebug_GraphicsMemorySummary *summary) | - | Obtains the detailed GPU memory usage of an application. |
| typedef void (*OH_HiDebug_ThreadLiteSamplingCallback)(const char* stacks) | OH_HiDebug_ThreadLiteSamplingCallback | Triggered for the lightweight Perf sampling stack content. Note: The sampling data is valid only during the execution of this callback. If you need to use the data outside the function, deep copy the sampling stack content. |
| HiDebug_ErrorCode OH_HiDebug_RequestThreadLiteSampling(HiDebug_ProcessSamplerConfig* config, OH_HiDebug_ThreadLiteSamplingCallback stacksCallback) | - | Performs Perf sampling on the specified threads and returns the sampling stack content after the call is complete. Note: After this function is called, the current thread is blocked until the sampling process ends. The system strictly limits the number of times that this API is called. If the number of times that this API is called exceeds the upper limit, the error code HIDEBUG_RESOURCE_UNAVAILABLE is returned. |
| uint64_t OH_HiDebug_SetCrashObj(HiDebug_CrashObjType type, void* addr) | - | Adds debugging information to the crash logs. This function is used together with OH_HiDebug_ResetCrashObj. If a program crashes between OH_HiDebug_SetCrashObj and OH_HiDebug_ResetCrashObj, the debugging information set by OH_HiDebug_SetCrashObj is added to the crash logs. |
| void OH_HiDebug_ResetCrashObj(uint64_t crashObj) | - | Resets the debugging information object to the state before OH_HiDebug_SetCrashObj is used. |
Function Description
OH_HiDebug_GetSystemCpuUsage()
double OH_HiDebug_GetSystemCpuUsage()
Description
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.
Since: 12
Returns
| Type | Description |
|---|---|
| double | Returns the system CPU usage if the operation is successful. Returns 0 if the operation fails. |
OH_HiDebug_GetAppCpuUsage()
double OH_HiDebug_GetAppCpuUsage()
Description
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.
Since: 12
Returns
| Type | Description |
|---|---|
| double | Application CPU usage obtained if the operation is successful. If 0 is returned, the CPU usage of the current application is too low. |
OH_HiDebug_GetAppThreadCpuUsage()
HiDebug_ThreadCpuUsagePtr OH_HiDebug_GetAppThreadCpuUsage()
Description
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.
Since: 12
Returns
| Type | Description |
|---|---|
| HiDebug_ThreadCpuUsagePtr | CPU usage of all threads. For details, see HiDebug_ThreadCpuUsagePtr. If null is returned, the thread data may not be obtained. |
OH_HiDebug_FreeThreadCpuUsage()
void OH_HiDebug_FreeThreadCpuUsage(HiDebug_ThreadCpuUsagePtr *threadCpuUsage)
Description
Releases the HiDebug_ThreadCpuUsagePtr.
Since: 12
Parameters
| Name | Description |
|---|---|
| HiDebug_ThreadCpuUsagePtr *threadCpuUsage | Pointer to the available CPU buffer of all threads of the application. For details, see HiDebug_ThreadCpuUsagePtr. The input parameter is obtained by OH_HiDebug_GetAppThreadCpuUsage(). |
OH_HiDebug_GetSystemMemInfo()
void OH_HiDebug_GetSystemMemInfo(HiDebug_SystemMemInfo *systemMemInfo)
Description
Obtains system memory information.
Since: 12
Parameters
| Name | Description |
|---|---|
| HiDebug_SystemMemInfo *systemMemInfo | Pointer to HiDebug_SystemMemInfo. If the struct data is empty after the function is called, the calling fails. |
OH_HiDebug_GetAppNativeMemInfo()
void OH_HiDebug_GetAppNativeMemInfo(HiDebug_NativeMemInfo *nativeMemInfo)
Description
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.
Since: 12
Parameters
| Name | Description |
|---|---|
| HiDebug_NativeMemInfo *nativeMemInfo | Pointer to HiDebug_NativeMemInfo. If the struct data is empty after the function is called, the calling fails. |
OH_HiDebug_GetAppNativeMemInfoWithCache()
void OH_HiDebug_GetAppNativeMemInfoWithCache(HiDebug_NativeMemInfo *nativeMemInfo, bool forceRefresh)
Description
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.
Since: 20
Parameters
| Name | Description |
|---|---|
| HiDebug_NativeMemInfo *nativeMemInfo | Pointer to HiDebug_NativeMemInfo. If the struct data is empty after the function is called, the calling fails. |
| bool forceRefresh | Whether to ignore the cache validity and forcibly update the cache value. The value true means to directly obtain the current memory data and update the cache value. 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. |
OH_HiDebug_GetAppMemoryLimit()
void OH_HiDebug_GetAppMemoryLimit(HiDebug_MemoryLimit *memoryLimit)
Description
Obtains the memory limit of an application process.
Since: 12
Parameters
| Name | Description |
|---|---|
| HiDebug_MemoryLimit *memoryLimit | Pointer to HiDebug_MemoryLimit. If the struct data is empty after the function is called, the calling fails. |
OH_HiDebug_StartAppTraceCapture()
HiDebug_ErrorCode OH_HiDebug_StartAppTraceCapture(HiDebug_TraceFlag flag, uint64_t tags, uint32_t limitSize, char* fileName, uint32_t length)
Description
Starts application trace collection.
Since: 12
Parameters
| Name | Description |
|---|---|
| HiDebug_TraceFlag flag | Type of the thread (the main thread or all threads of the application) to trace. |
| uint64_t tags | Modules or subsystems to trace. |
| uint32_t limitSize | Maximum size of the trace file (in bytes), which is 500 MB. |
| char* fileName | Buffer for the output trace file. |
| uint32_t length | Length of the buffer for the output trace file. |
Returns
| Type | Description |
|---|---|
| HiDebug_ErrorCode | 0 - The operation is successful. HIDEBUG_INVALID_ARGUMENT 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. 11400102 - A trace is already started. 11400103 - You do not have the permission to start the trace function. 11400104 - An internal system error occurs. |
OH_HiDebug_StopAppTraceCapture()
HiDebug_ErrorCode OH_HiDebug_StopAppTraceCapture()
Description
Stops application trace collection.
Since: 12
Returns
| Type | Description |
|---|---|
| HiDebug_ErrorCode | 0 - The operation is successful. 11400104 - An internal system error occurs. 11400105 - No trace collection is running. |
OH_HiDebug_GetGraphicsMemory()
HiDebug_ErrorCode OH_HiDebug_GetGraphicsMemory(uint32_t *value)
Description
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.
Since: 14
Parameters
| Name | Description |
|---|---|
| uint32_t *value | Pointer to the variable that stores the size (in KB) of the obtained GPU memory. |
Returns
| Type | Description |
|---|---|
| HiDebug_ErrorCode | 0 - The API is obtained successfully. 401 - The parameter is a null pointer, which is invalid. 11400104 - An internal system error occurs. |
OH_HiDebug_BacktraceFromFp()
int OH_HiDebug_BacktraceFromFp(HiDebug_Backtrace_Object object, void* startFp, void** pcArray, int size)
Description
Performs stack back-tracing based on the given fp address. This function is async-signal-safe.
Since: 20
Parameters
| Name | Description |
|---|---|
| HiDebug_Backtrace_Object object | Object obtained by the OH_HiDebug_CreateBacktraceObject API for stack backtracing. |
| void* startFp | Start frame pointer for stack backtracing. |
| void** pcArray | Array of PC addresses obtained from stack backtracing. |
| int size | Length of the PC address array obtained by stack backtracing. |
Returns
| Type | Description |
|---|---|
| int | Number of stack frames that are successfully backtraced and written to pcArray. If 0 is returned, stack backtracing may fail. |
OH_HiDebug_SymbolicAddressCallback()
typedef void (*OH_HiDebug_SymbolicAddressCallback)(void* pc, void* arg, const HiDebug_StackFrame* frame)
Description
If the OH_HiDebug_SymbolicAddress API is successfully called, the parsed stack information is returned to the caller through this function. Note: 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.
Since: 20
Parameters
| Name | Description |
|---|---|
| void* pc | PC address transferred to the OH_HiDebug_SymbolicAddress API for parsing. |
| void* arg | arg value of the OH_HiDebug_SymbolicAddress API. |
| const HiDebug_StackFrame* frame | Pointer to HiDebug_StackFrame, which is obtained by parsing the PC address passed to the OH_HiDebug_SymbolicAddress API. What the pointer points to is valid only in the function scope. |
OH_HiDebug_SymbolicAddress()
HiDebug_ErrorCode OH_HiDebug_SymbolicAddress(HiDebug_Backtrace_Object object, void* pc, void* arg, OH_HiDebug_SymbolicAddressCallback callback)
Description
Obtains detailed symbol information based on the specified PC address. This function is not asyn-signal-safe.
NOTE
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.
Since: 20
Parameters
| Name | Description |
|---|---|
| HiDebug_Backtrace_Object object | Object created by the OH_HiDebug_CreateBacktraceObject API. |
| void* pc | PC address obtained through the OH_HiDebug_BacktraceFromFp API. |
| void* arg | Reserved custom parameter. After the symbol is successfully parsed, this parameter is passed to OH_HiDebug_SymbolicAddressCallback. |
| OH_HiDebug_SymbolicAddressCallback callback | Callback used to return the parsed stack information. |
Returns
| Type | Description |
|---|---|
| HiDebug_ErrorCode | For details, see HiDebug_ErrorCode. HIDEBUG_SUCCESS: The detailed stack information is successfully obtained, and the callback input by the function is called. HIDEBUG_INVALID_ARGUMENT: Invalid parameter. HIDEBUG_INVALID_SYMBOLIC_PC_ADDRESS: Failed to find the corresponding symbol based on the input PC address. |
OH_HiDebug_CreateBacktraceObject()
HiDebug_Backtrace_Object OH_HiDebug_CreateBacktraceObject(void)
Description
Creates an object for stack backtracing and parsing. This function is not asyn-signal-safe.
NOTE
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.
Since: 20
Returns
| Type | Description |
|---|---|
| HiDebug_Backtrace_Object | Pointer to the created object. If the object fails to be created, NULL is returned. |
OH_HiDebug_DestroyBacktraceObject()
void OH_HiDebug_DestroyBacktraceObject(HiDebug_Backtrace_Object object)
Description
Destroys the object created by OH_HiDebug_CreateBacktraceObject to release the resources applied for during stack backtracing and parsing. This function is not asyn-signal-safe.
Since: 20
Parameters
| Name | Description |
|---|---|
| HiDebug_Backtrace_Object object | Object to destroy. |
OH_HiDebug_SetMallocDispatchTable()
HiDebug_ErrorCode OH_HiDebug_SetMallocDispatchTable(struct HiDebug_MallocDispatch *dispatchTable)
Description
Sets the MallocDispatch table in the basic C library to temporarily replace the original memory operation functions (such as malloc, free, calloc, realloc, mmap, and munmap) with the custom memory operation functions. The MallocDispatch table is a struct that encapsulates memory operation functions such as malloc, calloc, realloc, and free in the basic C library. HiDebug_MallocDispatch is only a part of the MallocDispatch struct.
NOTE
Do not directly call memory operation functions such as malloc, free, calloc, realloc, mmap, and munmap in the libc standard library in the custom memory operation functions. Otherwise, a deadlock occurs.
Do not use hilog to print logs in the custom malloc method. Otherwise, a deadlock occurs.
Since: 20
Parameters
| Name | Description |
|---|---|
| struct HiDebug_MallocDispatch *dispatchTable | Pointer to the HiDebug_MallocDispatch struct that contains the custom memory operation functions. |
Returns
| Type | Description |
|---|---|
| HiDebug_ErrorCode | For details, see HiDebug_ErrorCode. HIDEBUG_SUCCESS: The custom memory operation function is set successfully. HIDEBUG_INVALID_ARGUMENT: Invalid parameter. |
OH_HiDebug_GetDefaultMallocDispatchTable()
HiDebug_MallocDispatch* OH_HiDebug_GetDefaultMallocDispatchTable(void)
Description
Obtains the default MallocDispatch table of the system C library. You can call OH_HiDebug_RestoreMallocDispatchTable to restore the table.
Since: 20
Returns
| Type | Description |
|---|---|
| HiDebug_MallocDispatch* | Pointer to the default HiDebug_MallocDispatch struct of the current C library. |
OH_HiDebug_RestoreMallocDispatchTable()
void OH_HiDebug_RestoreMallocDispatchTable(void)
Description
Restores the MallocDispatch table of the system C library.
Since: 20
OH_HiDebug_GetGraphicsMemorySummary()
HiDebug_ErrorCode OH_HiDebug_GetGraphicsMemorySummary(uint32_t interval, HiDebug_GraphicsMemorySummary *summary)
Description
Obtains the detailed GPU memory usage of an application.
Since: 21
Parameters
| Name | Description |
|---|---|
| uint32_t interval | Interval that the cached GPU memory data exists, in seconds. If the duration exceeds the value of interval, the API obtains the latest data and updates the buffer. Otherwise, the API directly returns the cached data. The value range of interval is [2, 3600]. If the passed-in interval is out of the range, 300 is used as the default value. |
| HiDebug_GraphicsMemorySummary *summary | Pointer to HiDebug_GraphicsMemorySummary. |
Returns
| Type | Description |
|---|---|
| HiDebug_ErrorCode | For details, see HiDebug_ErrorCode. HIDEBUG_SUCCESS: The GPU memory information of the application is obtained successfully. HIDEBUG_INVALID_ARGUMENT: Invalid parameter. HIDEBUG_TRACE_ABNORMAL: Internal system error. |
OH_HiDebug_ThreadLiteSamplingCallback()
typedef void (*OH_HiDebug_ThreadLiteSamplingCallback)(const char* stacks)
Description
Triggered for the lightweight Perf sampling stack content. Note: The sampling data is valid only during the execution of this callback. If you need to use the data outside the function, deep copy the sampling stack content.
Since: 22
Parameters
| Name | Description |
|---|---|
| const char* stacks | Content of the sampling call stack. |
OH_HiDebug_RequestThreadLiteSampling()
HiDebug_ErrorCode OH_HiDebug_RequestThreadLiteSampling(HiDebug_ProcessSamplerConfig* config, OH_HiDebug_ThreadLiteSamplingCallback stacksCallback)
Description
Performs Perf sampling on the specified threads and returns the sampling stack content after the call is complete. Note: After this function is called, the current thread is blocked until the sampling process ends. The system strictly limits the number of times that this API is called. If the number of times that this API is called exceeds the upper limit, the error code HIDEBUG_RESOURCE_UNAVAILABLE is returned.
Since: 22
Parameters
| Name | Description |
|---|---|
| HiDebug_ProcessSamplerConfig* config | Pointer to the HiDebug_ProcessSamplerConfig struct. |
| OH_HiDebug_ThreadLiteSamplingCallback stacksCallback | Callback used to return the sampling result when the sampling is complete. |
Returns
| Type | Description |
|---|---|
| HiDebug_ErrorCode | Result code. HIDEBUG_SUCCESS: Sampling successful. HIDEBUG_INVALID_ARGUMENT: Invalid parameter. HIDEBUG_NOT_SUPPORTED: Perf sampling not supported. HIDEBUG_UNDER_SAMPLING: A sampling task is in progress. HIDEBUG_RESOURCE_UNAVAILABLE: Sampling resources are insufficient or the upper call limit is reached. |
OH_HiDebug_SetCrashObj()
uint64_t OH_HiDebug_SetCrashObj(HiDebug_CrashObjType type, void* addr)
Description
Adds debugging information to the crash logs. This function is used together with OH_HiDebug_ResetCrashObj. If a program crashes between OH_HiDebug_SetCrashObj and OH_HiDebug_ResetCrashObj, the debugging information set by OH_HiDebug_SetCrashObj is added to the crash logs.
Since: 23
Parameters
| Name | Description |
|---|---|
| HiDebug_CrashObjType type | Data type of the debugging information. For details, see HiDebug_CrashObjType. |
| void* addr | Address of the debugging information. The address must be valid when a crash occurs. |
Returns
| Type | Description |
|---|---|
| uint64_t | Object of the debugging information that was set last time. If no debugging information is set last time, the value is 0. |
OH_HiDebug_ResetCrashObj()
void OH_HiDebug_ResetCrashObj(uint64_t crashObj)
Description
Resets the debugging information object to the state before OH_HiDebug_SetCrashObj is used.
Since: 23
Parameters
| Name | Description |
|---|---|
| uint64_t crashObj | Return value of the OH_HiDebug_SetCrashObj function. |