目录

hidebug.h

Overview

Defines the debugging functions of the HiDebug module, providing capabilities such as CPU usage monitoring, memory information query, trace capture, stack backtracing, performance sampling, memory export listening, and maintenance and debugging information recording, helping developers perform application performance analysis, resource management, and problem diagnosis.

File to include: <hidebug/hidebug.h>

Library: libohhidebug.so

System capability: SystemCapability.HiviewDFX.HiProfiler.HiDebug

Since: 12

Related module: HiDebug

Summary

[h2]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_RequestTrace(OH_HiDebug_RequestTraceConfig *config, OH_HiDebug_RequestTraceCallback callback) - Requests trace collection based on the configured collection settings.
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 backtracing 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 given pc address. This function is not async-signal-safe and cannot be used in an asynchronous signal handler.

Note: Because this API involves multiple I/O operations and takes a long time, it is recommended not to call it directly in the main thread.
HiDebug_Backtrace_Object OH_HiDebug_CreateBacktraceObject(void) -

Creates an object for stack backtracing and parsing. This function is not async-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 requested during stack backtracing and stack parsing. This function is not async-signal-safe. Because this API involves multiple I/O operations and takes a long time, it is recommended not to call it directly in the main thread.
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.
HiDebug_ErrorCode OH_HiDebug_StartProfiler(OH_HiDebug_ResourceType type, OH_HiDebug_ResProfilerConfig* config, OH_HiDebug_ProfilingCallback callback) -

Asynchronously starts the resource profiler for the current process.

The callback function is called only when the collection is stopped (including when the system automatically stops the collection). It carries the resource type and file path to be collected.

If the collection is abnormal, the file path is NULL.
HiDebug_ErrorCode OH_HiDebug_StopProfiler(void) - Stops resource profiler for the current process. This API can be called after the OH_HiDebug_StartProfiler API and the call duration must be within the maximum duration.
typedef bool (*OH_HiDebug_MemDumpListener)(int32_t fd, OH_HiDebug_MemListenerType tag, bool mayReportToOEM, const char* arg) OH_HiDebug_MemDumpListener Triggered by the memory dump listener. You can write memory data using the file descriptor (FD) in the application and then use the hidumper command to export the data.
HiDebug_ErrorCode OH_HiDebug_RegisterMemDumpListener(const char* name, OH_HiDebug_MemDumpListener listener) -

Registers a memory dump listener. When the memory usage of an application is high or the memory information is exported using the hidumper command, the system automatically calls the registered callback function.

The third-party application framework or developer can use this function to dump the internal memory information of the application to hidumper or upload the information to the OEM vendor through commercial grayscale release.

You can use OH_HiDebug_UnregisterMemDumpListener to unregister the listener.
HiDebug_ErrorCode OH_HiDebug_UnregisterMemDumpListener(const char* name) - Unregisters a memory dump listener that has been successfully registered.
uint64_t OH_HiDebug_AcquireAsyncContext() - Obtains an AsyncContext for subsequent use. This API is an auxiliary API of the profiler. You can use OH_HiDebug_ReleaseAsyncContext to release the context.
void OH_HiDebug_PushAsyncContext(uint64_t ctx) - Pushes an AsyncContext into the running context stack. This API is an auxiliary API of the profiler.
void OH_HiDebug_PopAsyncContext(uint64_t ctx) - Pops an AsyncContext from the running context stack. This API is an auxiliary API of the profiler.
void OH_HiDebug_ReleaseAsyncContext(uint64_t ctx) - Releases an AsyncContext to the system. This API is an auxiliary API of the profiler.

Function Description

[h2]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.

[h2]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.

[h2]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.

[h2]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 buffer of available CPU usage of all threads in the application. See HiDebug_ThreadCpuUsagePtr. The passed-in parameter is obtained by OH_HiDebug_GetAppThreadCpuUsage(). After being passed in, this function releases the pointed-to thread CPU usage data structure, and the pointer cannot be used again after release.

[h2]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.

[h2]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.

[h2]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.

[h2]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.

[h2]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.

[h2]OH_HiDebug_StopAppTraceCapture()

HiDebug_ErrorCode OH_HiDebug_StopAppTraceCapture()

Description

Stops application trace collection.

Since: 12

Returns

Type Description
HiDebug_ErrorCode

0 - Success.

11400104 - System internal error.

11400105 - No trace is currently running.

[h2]OH_HiDebug_RequestTrace()

HiDebug_ErrorCode OH_HiDebug_RequestTrace(OH_HiDebug_RequestTraceConfig *config, OH_HiDebug_RequestTraceCallback callback)

Description

Requests trace collection based on the configured collection settings.

Since: 24

Parameters

Name Description
OH_HiDebug_RequestTraceConfig *config Parameters for trace collection. For details, see OH_HiDebug_RequestTraceConfig.
OH_HiDebug_RequestTraceCallback callback Callback function for trace collection. For details, see OH_HiDebug_RequestTraceCallback.

Returns

Type Description
HiDebug_ErrorCode

Result code.

HIDEBUG_SUCCESS: The collection is successful.

HIDEBUG_TRACE_ABNORMAL: The remote service or status is abnormal.

OH_HIDEBUG_TRACE_STORAGE_LIMIT: The number of stored trace files reaches the upper limit. If the number of trace files stored in the directory is greater than or equal to 3, a failure message is returned.

HIDEBUG_RESOURCE_UNAVAILABLE: The collection resources are unavailable.

[h2]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.

[h2]OH_HiDebug_BacktraceFromFp()

int OH_HiDebug_BacktraceFromFp(HiDebug_Backtrace_Object object, void* startFp, void** pcArray, int size)

Description

Performs stack backtracing 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.

[h2]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 the stack information HiDebug_StackFrame obtained by resolving the PC address passed to the OH_HiDebug_SymbolicAddress API. The content pointed to by this pointer is valid only within the scope of this function.

[h2]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 through the given PC address. This function is not async-signal-safe and cannot be used in an asynchronous signal handler.

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.

[h2]OH_HiDebug_CreateBacktraceObject()

HiDebug_Backtrace_Object OH_HiDebug_CreateBacktraceObject(void)

Description

Creates an object for stack backtracing and parsing. This function is not async-signal-safe.

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.

[h2]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 async-signal-safe.

Since: 20

Parameters

Name Description
HiDebug_Backtrace_Object object Object to destroy.

[h2]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.

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.

[h2]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.

[h2]OH_HiDebug_RestoreMallocDispatchTable()

void OH_HiDebug_RestoreMallocDispatchTable(void)

Description

Restores the MallocDispatch table of the system C library.

Since: 20

[h2]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

When the cached GPU memory data has existed for longer than the set interval (in seconds), the API obtains the latest GPU memory data and updates the cache; otherwise, the API directly returns the cached value.

The value range of interval is [2, 3600]. If the passed interval is out of 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.

[h2]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.

[h2]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 Perf sampling configuration struct HiDebug_ProcessSamplerConfig. The configuration parameters determine the specific sampling behavior, such as the sampling frequency and target threads.
OH_HiDebug_ThreadLiteSamplingCallback stacksCallback Callback function invoked when sampling ends, used to return the sampling result. After sampling is complete, the system calls this function and passes the sampling data as a parameter.

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.

[h2]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 remain valid when a crash occurs. After it is set, if the program crashes, the system reads the debugging information pointed to by this address and records it in the crash log.

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.

[h2]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.

[h2]OH_HiDebug_StartProfiler()

HiDebug_ErrorCode OH_HiDebug_StartProfiler(OH_HiDebug_ResourceType type, OH_HiDebug_ResProfilerConfig* config, OH_HiDebug_ProfilingCallback callback)

Description

Asynchronously starts the resource profiler for the current process.

The callback function is called only when the collection is stopped (including when the system automatically stops the collection). It carries the resource type and file path to be collected.

If the collection is abnormal, the file path is NULL.

  1. The current interface can be called 10 times every 24 hours.
  2. The target process for resource collection supports only the process that calls the interface.
  3. When the system CPU usage rate exceeds 70%, or the available memory is less than 15%, or the available storage is less than 15%, the interface call fails and returns the corresponding error code.
  4. When the interface conflicts with a command-line tool or a system collection task, the call fails and returns the corresponding error code.
  5. If an application has multiple processes, this interface can start at most 4 of them simultaneously.
  6. The collection result is saved in the application sandbox directory /data/storage/el2/base/files/, with the file name "resource collection type-process name-process ID-timestamp.htrace".
  7. Since API version 26.0.0, this interface discards the call stack data of released memory as much as possible to reduce the collection file size and further lower the performance overhead during collection.

Since: 24

Parameters

Name Description
OH_HiDebug_ResourceType type Resource collection type, which determines the specific resource category to be collected (such as CPU, memory, and I/O). Different types correspond to different resource collection scenarios: CPU collection is used to analyze CPU performance issues, memory collection is used to analyze memory leaks and memory usage, and I/O collection is used to analyze I/O performance bottlenecks. Select an appropriate resource type based on the analysis requirements.
OH_HiDebug_ResProfilerConfig* config Resource collection configuration parameters. The configuration parameters determine the specific collection behavior, such as the sampling frequency and duration.
OH_HiDebug_ProfilingCallback callback Resource collection callback result function. This callback function is called when collection terminates, passing the collection result and file path.

Returns

Type Description
HiDebug_ErrorCode

Result code.

HIDEBUG_RES_PROF_SUCCESS: Resource profiler started successfully.

HIDEBUG_RES_PROF_INVALID_ARG: Invalid resource profiler argument.

HIDEBUG_RES_PROF_INVALID_MAX_DURATION: Invalid maximum duration.

HIDEBUG_RES_PROF_INVALID_FILTER_SIZE: Invalid filter size.

HIDEBUG_RES_PROF_INVALID_MAX_STACK_DEPTH: Invalid maximum stack depth.

HIDEBUG_RES_PROF_INVALID_STATISTICS_INTERVAL: Invalid statistics interval.

HIDEBUG_RES_PROF_INVALID_SAMPLE_INTERVAL: Invalid sampling interval.

HIDEBUG_RES_PROF_INVALID_RESOURCE_TYPE: Invalid resource type.

HIDEBUG_RES_PROF_PERMISSION_DENIED: Insufficient resource profiling permission. The target process for resource profiling can only be the process that calls this API.

HIDEBUG_RES_PROF_ALREADY_STARTED: Resource profiler already started.

HIDEBUG_RES_PROF_PROCESS_OVERLIMIT: The number of resource profiling processes exceeds 4.

HIDEBUG_RES_PROF_CONFLICT: Resource profiling conflicts with CLI tools or system profiling tasks.

HIDEBUG_RES_PROF_DAILY_QUOTA_EXCEEDED: The daily quota for resource profiling exceeds 10 times.

HIDEBUG_RES_PROF_CPU_OVERLOADED: The system CPU is overloaded, with the CPU usage exceeding 70%.

HIDEBUG_RES_PROF_MEM_PRESSURE_CRITICAL: The available memory space is less than 15%.

HIDEBUG_RES_PROF_STORAGE_PRESSURE_CRITICAL: The available storage space is less than 15%.

HIDEBUG_RES_PROF_FAILURE: Failed to start resource profiler.

[h2]OH_HiDebug_StopProfiler()

HiDebug_ErrorCode OH_HiDebug_StopProfiler(void)

Description

Stops resource profiler for the current process. This API can be called after the OH_HiDebug_StartProfiler API and the call duration must be within the maximum duration.

Since: 24

Returns

Type Description
HiDebug_ErrorCode

Result code.

HIDEBUG_RES_PROF_SUCCESS: Resource profiler stopped successfully.

HIDEBUG_RES_PROF_NOT_STARTED: Failed to stop resource profiler because it is not started.

HIDEBUG_RES_PROF_FAILURE: Failed to stop resource profiler.

[h2]OH_HiDebug_MemDumpListener()

typedef bool (*OH_HiDebug_MemDumpListener)(int32_t fd, OH_HiDebug_MemListenerType tag, bool mayReportToOEM, const char* arg)

Description

Triggered by the memory dump listener. You can write memory data using the file descriptor (FD) in the application and then use the hidumper command to export the data.

Since: 26.0.0

Parameters

Name Description
int32_t fd File descriptor of the application that writes data to the memory.
OH_HiDebug_MemListenerType tag Type of the memory listener callback. You can process the related logic based on the callback type.
bool mayReportToOEM ID of the OEM vendor to which data is reported. true indicates that the data will be uploaded to the OEM vendor. Pay attention to data privacy and security. false indicates that the data will not be reported.
const char* arg Pointer to the callback parameter. Different data content is carried based on the callback type for you to use.

Returns

Type Description
bool

Operation result:

true: Memory data is successfully written.

false: Memory data fails to be written.

[h2]OH_HiDebug_RegisterMemDumpListener()

HiDebug_ErrorCode OH_HiDebug_RegisterMemDumpListener(const char* name, OH_HiDebug_MemDumpListener listener)

Description

Registers a memory dump listener. When the memory usage of an application is high or the memory information is exported using the hidumper command, the system automatically calls the registered callback function.

The third-party application framework or developer can use this function to dump the internal memory information of the application to hidumper or upload the information to the OEM vendor through commercial grayscale release.

You can use OH_HiDebug_UnregisterMemDumpListener to unregister the listener.

Since: 26.0.0

Parameters

Name Description
const char* name

Pointer to the name of the listener, which uniquely identifies the listener to be registered. The same name must be passed during listener underegistration.

A listener with the same name can be registered only once. If you attempt to register a listener with the same name again, HIDEBUG_INVALID_ARGUMENT will be returned. To update a listener, unregister the original listener first.
OH_HiDebug_MemDumpListener listener Callback triggered for listening.

Returns

Type Description
HiDebug_ErrorCode

Result code.

HIDEBUG_SUCCESS: Operation succeeded.

HIDEBUG_INVALID_ARGUMENT: Invalid parameter.

[h2]OH_HiDebug_UnregisterMemDumpListener()

HiDebug_ErrorCode OH_HiDebug_UnregisterMemDumpListener(const char* name)

Description

Unregisters a memory dump listener that has been successfully registered.

Since: 26.0.0

Parameters

Name Description
const char* name Pointer to the unique name of the listener. The value must be the same as the name passed during registration.

Returns

Type Description
HiDebug_ErrorCode

Result code.

HIDEBUG_SUCCESS: Operation succeeded.

HIDEBUG_INVALID_ARGUMENT: Invalid parameter.

[h2]OH_HiDebug_AcquireAsyncContext()

uint64_t OH_HiDebug_AcquireAsyncContext()

Description

Obtains an AsyncContext for subsequent use. This API is an auxiliary API of the profiler. You can use OH_HiDebug_ReleaseAsyncContext to release the context.

This API supports only the ARM64 architecture and can be used only in debug version applications.

Since: 26.0.0

Returns

Type Description
uint64_t AsyncContext, which is the asynchronous thread context information.

[h2]OH_HiDebug_PushAsyncContext()

void OH_HiDebug_PushAsyncContext(uint64_t ctx)

Description

Pushes an AsyncContext into the running context stack. This API is an auxiliary API of the profiler.

Since: 26.0.0

Parameters

Name Description
uint64_t ctx Asynchronous thread context obtained by OH_HiDebug_AcquireAsyncContext().

[h2]OH_HiDebug_PopAsyncContext()

void OH_HiDebug_PopAsyncContext(uint64_t ctx)

Description

Pops an AsyncContext from the running context stack. This API is an auxiliary API of the profiler.

Since: 26.0.0

Parameters

Name Description
uint64_t ctx Asynchronous thread context obtained by OH_HiDebug_AcquireAsyncContext().

[h2]OH_HiDebug_ReleaseAsyncContext()

void OH_HiDebug_ReleaseAsyncContext(uint64_t ctx)

Description

Releases an AsyncContext to the system. This API is an auxiliary API of the profiler.

Since: 26.0.0

Parameters

Name Description
uint64_t ctx Asynchronous thread context obtained by OH_HiDebug_AcquireAsyncContext().