hidebug.h
概述
定义HiDebug模块的调试功能。
引用文件： <hidebug/hidebug.h>
库： libohhidebug.so
系统能力： SystemCapability.HiviewDFX.HiProfiler.HiDebug
起始版本： 12
相关模块： HiDebug
汇总
函数
函数说明
OH_HiDebug_GetSystemCpuUsage()
double OH_HiDebug_GetSystemCpuUsage()
描述
获取系统的CPU资源占用情况百分比。注意：由于该接口涉及跨进程通信，耗时较长，建议不要在主线程中直接调用。
起始版本： 12
返回：
| 类型 | 说明 |
|---|---|
| double | 返回系统CPU资源占用情况百分比。如果返回结果为0，可能的原因是获取失败。 |
OH_HiDebug_GetAppCpuUsage()
double OH_HiDebug_GetAppCpuUsage()
描述
获取进程的CPU使用率百分比。注意：由于该接口涉及跨进程通信，耗时较长，建议不要在主线程中直接调用。
起始版本： 12
返回：
| 类型 | 说明 |
|---|---|
| double | 返回进程的CPU使用率百分比。如果返回结果为0，可能因当前应用的CPU使用率过低导致。 |
OH_HiDebug_GetAppThreadCpuUsage()
HiDebug_ThreadCpuUsagePtr OH_HiDebug_GetAppThreadCpuUsage()
描述
获取应用所有线程CPU使用情况。注意：由于该接口涉及跨进程通信，耗时较长，建议不要在主线程中直接调用。
起始版本： 12
返回：
| 类型 | 说明 |
|---|---|
| HiDebug_ThreadCpuUsagePtr | 返回所有线程CPU使用情况，见HiDebug_ThreadCpuUsagePtr。 若返回结果为null，可能因未获取到线程相关数据所致。 |
OH_HiDebug_FreeThreadCpuUsage()
void OH_HiDebug_FreeThreadCpuUsage(HiDebug_ThreadCpuUsagePtr *threadCpuUsage)
描述
释放线程数据结构。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| HiDebug_ThreadCpuUsagePtr *threadCpuUsage | 应用的所有线程可用CPU使用缓冲区指针，见HiDebug_ThreadCpuUsagePtr。传入的参数是要由OH_HiDebug_GetAppThreadCpuUsage()得到的。 |
OH_HiDebug_GetSystemMemInfo()
void OH_HiDebug_GetSystemMemInfo(HiDebug_SystemMemInfo *systemMemInfo)
描述
获取系统内存信息。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| HiDebug_SystemMemInfo *systemMemInfo | 表示指向HiDebug_SystemMemInfo。函数调用后，若结构体数据为空，则表明调用失败。 |
OH_HiDebug_GetAppNativeMemInfo()
void OH_HiDebug_GetAppNativeMemInfo(HiDebug_NativeMemInfo *nativeMemInfo)
描述
获取应用程序进程的内存信息。注意：由于该接口需要读取/proc/{pid}/smaps_rollup节点信息，耗时较长，建议不要在主线程中直接调用。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| HiDebug_NativeMemInfo *nativeMemInfo | 表示指向HiDebug_NativeMemInfo。函数调用后，若结构体数据为空，则表明调用失败。 |
OH_HiDebug_GetAppNativeMemInfoWithCache()
void OH_HiDebug_GetAppNativeMemInfoWithCache(HiDebug_NativeMemInfo *nativeMemInfo, bool forceRefresh)
描述
获取应用程序进程的内存信息，该接口存在缓存机制以提高接口性能。缓存值的有效期为5分钟。注意：由于该接口需要读取/proc/{pid}/smaps_rollup节点信息，耗时较长，建议不要在主线程中直接调用。
起始版本： 20
参数：
| 参数项 | 描述 |
|---|---|
| HiDebug_NativeMemInfo *nativeMemInfo | 表示指向HiDebug_NativeMemInfo。函数调用后，若结构体数据为空，则表明调用失败。 |
| bool forceRefresh | 是否需要无视缓存有效性，强制更新缓存值。 当为true时，直接获取当前内存数据并更新缓存值； 当为false时，缓存有效时，直接返回缓存值，缓存失效时，获取当前内存数据并更新缓存值。 |
OH_HiDebug_GetAppMemoryLimit()
void OH_HiDebug_GetAppMemoryLimit(HiDebug_MemoryLimit *memoryLimit)
描述
获取应用程序进程的内存限制。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| HiDebug_MemoryLimit *memoryLimit | 表示指向HiDebug_MemoryLimit。函数调用后，若结构体数据为空，则表明调用失败。 |
OH_HiDebug_StartAppTraceCapture()
HiDebug_ErrorCode OH_HiDebug_StartAppTraceCapture(HiDebug_TraceFlag flag, uint64_t tags, uint32_t limitSize, char* fileName, uint32_t length)
描述
启动应用trace采集。
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| HiDebug_TraceFlag flag | 采集线程trace方式。 |
| uint64_t tags | 采集trace场景标签。 |
| uint32_t limitSize | trace文件的最大大小（以字节为单位），最大为 500MB。 |
| char* fileName | 输出trace文件名缓冲区。 |
| uint32_t length | 输出trace文件名缓冲区长度。 |
返回：
| 类型 | 说明 |
|---|---|
| HiDebug_ErrorCode | 0 - 成功。 HIDEBUG_INVALID_ARGUMENT 401 - fileName参数为空指针或者传入的length参数过小或者limitSize参数小于等于0。 11400102 - 已经开启了一个trace。 11400103 - 没有权限去开启trace。 11400104 - 系统内部错误。 |
OH_HiDebug_StopAppTraceCapture()
HiDebug_ErrorCode OH_HiDebug_StopAppTraceCapture()
描述
停止采集应用程序trace。
起始版本： 12
返回：
| 类型 | 说明 |
|---|---|
| HiDebug_ErrorCode | 0 - 成功。 11400104 - 系统内部错误。 11400105 - 当前没有trace正在运行 |
OH_HiDebug_GetGraphicsMemory()
HiDebug_ErrorCode OH_HiDebug_GetGraphicsMemory(uint32_t *value)
描述
获取应用GPU显存大小。注意：由于该接口涉及多次跨进程通信，其耗时可能超过1秒，建议不要在主线程中直接调用该接口。
起始版本： 14
参数：
| 参数项 | 描述 |
|---|---|
| uint32_t *value | 指向用来保存接口获取到的应用显存大小（单位KB）的变量的指针。 |
返回：
| 类型 | 说明 |
|---|---|
| HiDebug_ErrorCode | 0 - 接口获取成功。 401 - 无效参数，所传递参数为空指针。 11400104 - 系统内部错误。 |
OH_HiDebug_BacktraceFromFp()
int OH_HiDebug_BacktraceFromFp(HiDebug_Backtrace_Object object, void* startFp, void** pcArray, int size)
描述
根据给定的fp地址进行栈回溯，该函数异步信号安全。
起始版本： 20
参数：
| 参数项 | 描述 |
|---|---|
| HiDebug_Backtrace_Object object | 由OH_HiDebug_CreateBacktraceObject接口获取到的用来栈回溯的对象。 |
| void* startFp | 栈回溯的起始栈帧地址。 |
| void** pcArray | 保存栈回溯得到的pc地址的数组。 |
| int size | 保存栈回溯得到的pc地址的数组长度。 |
返回：
| 类型 | 说明 |
|---|---|
| int | 成功回溯并写入到pcArray中的栈帧数量。如果返回结果为0，原因可能是栈回溯失败。 |
OH_HiDebug_SymbolicAddressCallback()
typedef void (*OH_HiDebug_SymbolicAddressCallback)(void* pc, void* arg, const HiDebug_StackFrame* frame)
描述
若OH_HiDebug_SymbolicAddress接口调用成功，将通过该函数将解析后的栈信息返回给调用者。注意：由于该接口涉及多次IO操作，耗时较长，建议不要在主线程中直接调用。
起始版本： 20
参数：
| 参数项 | 描述 |
|---|---|
| void* pc | 传入OH_HiDebug_SymbolicAddress接口的需要解析的pc地址。 |
| void* arg | 传入OH_HiDebug_SymbolicAddress接口的arg值。 |
| const HiDebug_StackFrame* frame | 由传入OH_HiDebug_SymbolicAddress接口的pc地址解析后的得到栈信息HiDebug_StackFrame指针，该指针指向内容仅在该函数作用域内有效。 |
OH_HiDebug_SymbolicAddress()
HiDebug_ErrorCode OH_HiDebug_SymbolicAddress(HiDebug_Backtrace_Object object, void* pc, void* arg, OH_HiDebug_SymbolicAddressCallback callback)
描述
通过给定的pc地址获取详细的符号信息，该函数非异步信号安全。
起始版本： 20
参数：
| 参数项 | 描述 |
|---|---|
| HiDebug_Backtrace_Object object | 由OH_HiDebug_CreateBacktraceObject接口创建的对象。 |
| void* pc | 由OH_HiDebug_BacktraceFromFp接口获取到的pc地址。 |
| void* arg | 保留的自定义参数，符号解析成功后系统内部会将该参数传递给回调函数OH_HiDebug_SymbolicAddressCallback。 |
| OH_HiDebug_SymbolicAddressCallback callback | 用于返回解析后栈信息的回调函数。 |
返回：
| 类型 | 说明 |
|---|---|
| HiDebug_ErrorCode | 返回结果具体可参考HiDebug_ErrorCode： HIDEBUG_SUCCESS 成功获取到详细的栈信息，且该函数传入的callback被调用。 HIDEBUG_INVALID_ARGUMENT 无效参数。 HIDEBUG_INVALID_SYMBOLIC_PC_ADDRESS 无法根据传入的pc地址找到对应的符号。 |
OH_HiDebug_CreateBacktraceObject()
HiDebug_Backtrace_Object OH_HiDebug_CreateBacktraceObject(void)
描述
创建一个用于栈回溯及栈解析的对象，该函数非异步信号安全。
起始版本： 20
返回：
| 类型 | 说明 |
|---|---|
| HiDebug_Backtrace_Object | 返回创建的对象的指针，当创建失败时返回NULL。 |
OH_HiDebug_DestroyBacktraceObject()
void OH_HiDebug_DestroyBacktraceObject(HiDebug_Backtrace_Object object)
描述
销毁由OH_HiDebug_CreateBacktraceObject创建的对象，以释放栈回溯及栈解析过程中申请的资源，该函数非异步信号安全。
起始版本： 20
参数：
| 参数项 | 描述 |
|---|---|
| HiDebug_Backtrace_Object object | 需要被销毁的对象。 |
OH_HiDebug_SetMallocDispatchTable()
HiDebug_ErrorCode OH_HiDebug_SetMallocDispatchTable(struct HiDebug_MallocDispatch *dispatchTable)
描述
设置基础库C库MallocDispatch表，用于替换开发者自定义的内存操作函数（例如：malloc/free/calloc/realloc/mmap/munmap)。MallocDispatch表是基础库C库中封装malloc/calloc/realloc/free等内存操作函数的结构体。HiDebug_MallocDispatch只是MallocDispatch结构体的一部分。
起始版本： 20
参数：
| 参数项 | 描述 |
|---|---|
| struct HiDebug_MallocDispatch *dispatchTable | 指向开发者自定义内存操作函数HiDebug_MallocDispatch结构体指针。 |
返回：
| 类型 | 说明 |
|---|---|
| HiDebug_ErrorCode | 返回结果具体可参考HiDebug_ErrorCode： HIDEBUG_SUCCESS 成功设置自定义内存操作函数。 HIDEBUG_INVALID_ARGUMENT 无效参数。 |
OH_HiDebug_GetDefaultMallocDispatchTable()
HiDebug_MallocDispatch* OH_HiDebug_GetDefaultMallocDispatchTable(void)
描述
获取基础库C库当前默认MallocDispatch表，调用OH_HiDebug_RestoreMallocDispatchTable可恢复。
起始版本： 20
返回：
| 类型 | 说明 |
|---|---|
| HiDebug_MallocDispatch* | 当前C库默认的HiDebug_MallocDispatch结构体指针。 |
OH_HiDebug_RestoreMallocDispatchTable()
void OH_HiDebug_RestoreMallocDispatchTable(void)
描述
恢复基础库C库MallocDispatch表。
起始版本： 20
OH_HiDebug_GetGraphicsMemorySummary()
HiDebug_ErrorCode OH_HiDebug_GetGraphicsMemorySummary(uint32_t interval, HiDebug_GraphicsMemorySummary *summary)
描述
获取应用显存占用的详细数据。
起始版本： 21
参数：
| 参数项 | 描述 |
|---|---|
| uint32_t interval | 当显存数据缓存值存在时间超过设定间隔interval（单位：秒）时，接口会获取最新的显存数据并更新缓存；否则，接口将直接返回缓存值。 interval的取值范围为[2，3600]，若传入的interval超出取值范围时，将使用300作为默认值。 |
| HiDebug_GraphicsMemorySummary *summary | 表示指向HiDebug_GraphicsMemorySummary的指针。 |
返回：
| 类型 | 说明 |
|---|---|
| HiDebug_ErrorCode | 返回结果具体可参考HiDebug_ErrorCode： HIDEBUG_SUCCESS 成功获取到应用显存数据。 HIDEBUG_INVALID_ARGUMENT 无效参数。 HIDEBUG_TRACE_ABNORMAL 系统内部错误。 |
OH_HiDebug_ThreadLiteSamplingCallback()
typedef void (*OH_HiDebug_ThreadLiteSamplingCallback)(const char* stacks)
描述
轻量级Perf采样栈内容的回调函数定义。注意：采样数据仅在该回调函数执行期间有效，若需在函数外使用，务必对采样栈内容进行深拷贝。
起始版本： 22
参数：
| 参数项 | 描述 |
|---|---|
| const char* stacks | 采样得到的调用栈内容。 |
OH_HiDebug_RequestThreadLiteSampling()
HiDebug_ErrorCode OH_HiDebug_RequestThreadLiteSampling(HiDebug_ProcessSamplerConfig* config, OH_HiDebug_ThreadLiteSamplingCallback stacksCallback)
描述
对指定的数个线程进行Perf采样，并在调用结束后返回采样栈内容。注意：调用该函数后会阻塞当前线程，直至采样过程完全结束。系统对该接口的调用次数有严格限制，频繁调用超出限额后，将返回HIDEBUG_RESOURCE_UNAVAILABLE错误码。
起始版本： 22
参数：
| 参数项 | 描述 |
|---|---|
| HiDebug_ProcessSamplerConfig* config | 指向Perf采样配置结构体HiDebug_ProcessSamplerConfig的指针。 |
| OH_HiDebug_ThreadLiteSamplingCallback stacksCallback | 采样结束时的回调函数，用于返回采样结果。 |
返回：
| 类型 | 说明 |
|---|---|
| HiDebug_ErrorCode | 返回结果码： HIDEBUG_SUCCESS：采样成功完成。 HIDEBUG_INVALID_ARGUMENT：无效参数。 HIDEBUG_NOT_SUPPORTED：当前设备不支持Perf采样。 HIDEBUG_UNDER_SAMPLING：已有采样任务正在执行中。 HIDEBUG_RESOURCE_UNAVAILABLE：采样资源不足或已达调用上限。 |