dfx_traceui

dfx_traceui 模块提供图形性能 trace 记录与分析接口，支持同步/异步事件追踪、整数计数器跟踪及日志记录功能，并可将记录数据转换为 perfetto protobuf 格式用于可视化性能分析。

头文件清单

#include "middleware/services/gui/uikit/proprietary/include/dfx/dfx_traceui.h"

接口清单

接口名称	功能简述
TraceuiRecordStart	启动trace记录，指定事件掩码和目标缓冲区
TraceuiRecordStop	停止trace记录，返回已记录数据长度
TraceuiConvertToPerfettoProto	将记录缓冲区转换为perfetto protobuf格式trace文件
TraceuiEventTraceBegin	标记一个同步上下文起始，常用于计时函数执行
TraceuiEventTraceBeginFormat	标记一个带格式化字符串的同步上下文起始
TraceuiEventTraceEnd	标记一个同步上下文结束，与TraceBegin配对
TraceuiEventTraceAsyncBegin	标记一个异步事件起始，通过name和cookie唯一标识
TraceuiEventTraceAsyncEnd	标记一个异步事件结束，与AsyncBegin配对
TraceuiEventTraceInt	记录一个整数值，用于跟踪数值随时间变化
TraceuiEventLog	记录一条日志信息

Functions

TraceuiRecordStart

bool TraceuiRecordStart(uint32_t events, uint8_t *buf, uint32_t bufSize)

头文件清单

#include "middleware/services/gui/uikit/proprietary/include/dfx/dfx_traceui.h"

功能说明

启动图形性能trace记录，将指定事件类型的trace数据写入目标缓冲区
通过事件掩码控制需要记录的事件类型，可使用TRACEUI_EVENTS_ALL记录全部事件或使用TRACEUI_EVENT_MASK组合指定事件
若记录数据超出缓冲区大小，后续数据将被忽略
记录期间会注册任务切换和中断钩子函数以捕获系统事件

前置条件

模块已通过ENABLE_DFX_TRACEUI宏启用（依赖ENABLE_DFX_CMD=1且__LITEOS_M__定义）
入参buf不为NULL，且指向的内存空间已申请成功，长度不小于bufSize规定值
bufSize大于0，满足至少记录一条事件帧的空间需求

入参

名称	参数类型	详细说明	约束取值范围
events	uint32_t	需要记录的事件类型掩码	TRACEUI_EVENTS_ALL或TRACEUI_EVENT_MASK(TraceuiEventType)组合值
buf	uint8_t *	记录目标缓冲区指针	非NULL，缓冲区长度不小于bufSize
bufSize	uint32_t	目标缓冲区大小（字节）	大于0

返回值

返回类型：bool

返回值	文字含义	触发场景
true	启动记录成功	缓冲区初始化成功
false	启动记录失败	-

参考案例

/src/middleware/services/gui/uikit/proprietary/src/ui/frameworks/dfx/dfx_cmd.cpp

Kconfig配置

配置项	宏类型	说明	默认值
ENABLE_DFX_CMD	功能宏	支持DFX命令功能	1
ENABLE_DFX_TRACEUI	功能宏	支持图形性能trace分析功能	1（依赖ENABLE_DFX_CMD=1且__LITEOS_M__）
LOSCFG_BASE_CORE_TSK_MONITOR	特性宏	支持任务切换事件记录特性	-
LOSCFG_HWI_PRE_POST_PROCESS	特性宏	支持中断事件记录特性	-

TraceuiRecordStop

uint32_t TraceuiRecordStop(void)

头文件清单

#include "middleware/services/gui/uikit/proprietary/include/dfx/dfx_traceui.h"

功能说明

停止trace记录，注销任务切换和中断钩子函数
返回已记录数据的字节长度，用于后续转换时指定有效数据大小
调用后缓冲区不再接收新的trace事件

前置条件

已通过TraceuiRecordStart启动trace记录

返回值

返回类型：uint32_t

返回值	文字含义	触发场景
uint32_t	已记录数据长度（字节）	记录停止后返回缓冲区已使用大小

参考案例

/src/middleware/services/gui/uikit/proprietary/src/ui/frameworks/dfx/dfx_cmd.cpp

Kconfig配置

配置项	宏类型	说明	默认值
ENABLE_DFX_CMD	功能宏	支持DFX命令功能	1
ENABLE_DFX_TRACEUI	功能宏	支持图形性能trace分析功能	1（依赖ENABLE_DFX_CMD=1且__LITEOS_M__）
LOSCFG_BASE_CORE_TSK_MONITOR	特性宏	支持任务切换钩子注销特性	-
LOSCFG_HWI_PRE_POST_PROCESS	特性宏	支持中断钩子注销特性	-

TraceuiConvertToPerfettoProto

bool TraceuiConvertToPerfettoProto(const uint8_t *buf, uint32_t bufSize, const char *outPath)

头文件清单

#include "middleware/services/gui/uikit/proprietary/include/dfx/dfx_traceui.h"

功能说明

将记录缓冲区中的trace数据转换为perfetto protobuf格式并写入文件
输出文件可使用perfetto UI工具打开进行可视化性能分析
转换过程包含时钟快照、ftrace事件和日志事件等protobuf编码

前置条件

已通过TraceuiRecordStop停止记录，并获取有效数据长度
入参buf不为NULL，bufSize为TraceuiRecordStop返回的有效数据长度
入参outPath不为NULL，指向可写的文件路径

入参

名称	参数类型	详细说明	约束取值范围
buf	const uint8_t *	输入记录缓冲区指针	非NULL
bufSize	uint32_t	输入缓冲区有效数据大小	等于TraceuiRecordStop返回值
outPath	const char *	输出trace文件路径	非NULL，可写路径

返回值

返回类型：bool

返回值	文字含义	触发场景
true	转换成功	protobuf编码完成且文件写入成功
false	转换失败	参数为NULL或文件打开失败或编码错误

参考案例

/src/middleware/services/gui/uikit/proprietary/src/ui/frameworks/dfx/dfx_cmd.cpp

Kconfig配置

配置项	宏类型	说明	默认值
ENABLE_DFX_CMD	功能宏	支持DFX命令功能	1
ENABLE_DFX_TRACEUI	功能宏	支持图形性能trace分析功能	1（依赖ENABLE_DFX_CMD=1且__LITEOS_M__）

TraceuiEventTraceBegin

void TraceuiEventTraceBegin(const char *name)

头文件清单

#include "middleware/services/gui/uikit/proprietary/include/dfx/dfx_traceui.h"

功能说明

标记一个同步trace上下文的起始，常用于计时函数执行耗时
name字符串指针在trace转换完成前必须保持有效（建议使用字符串字面量）
可通过宏TRACEUI_BEGIN(nameStaticStr)调用

前置条件

已通过TraceuiRecordStart启动trace记录

入参

名称	参数类型	详细说明	约束取值范围
name	const char *	标识上下文的静态字符串	非NULL，字符串指针在trace转换前保持有效

参考案例

Kconfig配置

配置项	宏类型	说明	默认值
ENABLE_DFX_CMD	功能宏	支持DFX命令功能	1
ENABLE_DFX_TRACEUI	功能宏	支持图形性能trace分析功能	1（依赖ENABLE_DFX_CMD=1且__LITEOS_M__）

TraceuiEventTraceBeginFormat

void TraceuiEventTraceBeginFormat(const char *name, const char *fmt, ...)

头文件清单

#include "middleware/services/gui/uikit/proprietary/include/dfx/dfx_traceui.h"

功能说明

标记一个带格式化字符串的同步trace上下文起始，name与格式化字符串共同标识上下文
fmt格式与printf一致，格式化结果追加到name后用于标识上下文
可通过宏TRACEUI_BEGIN_FORMAT(nameStaticStr, fmt, ...)调用

前置条件

已通过TraceuiRecordStart启动trace记录

入参

名称	参数类型	详细说明	约束取值范围
name	const char *	标识上下文的静态字符串	非NULL，字符串指针在trace转换前保持有效
fmt	const char *	格式化字符串，与printf格式一致	非NULL
...	...	格式化参数	与fmt匹配

Kconfig配置

配置项	宏类型	说明	默认值
ENABLE_DFX_CMD	功能宏	支持DFX命令功能	1
ENABLE_DFX_TRACEUI	功能宏	支持图形性能trace分析功能	1（依赖ENABLE_DFX_CMD=1且__LITEOS_M__）

TraceuiEventTraceEnd

void TraceuiEventTraceEnd(void)

头文件清单

#include "middleware/services/gui/uikit/proprietary/include/dfx/dfx_traceui.h"

功能说明

标记一个同步trace上下文的结束，与TraceuiEventTraceBegin配对使用
可通过宏TRACEUI_END()调用

前置条件

已通过TraceuiRecordStart启动trace记录
之前已调用TraceuiEventTraceBegin或TraceuiEventTraceBeginFormat

参考案例

Kconfig配置

配置项	宏类型	说明	默认值
ENABLE_DFX_CMD	功能宏	支持DFX命令功能	1
ENABLE_DFX_TRACEUI	功能宏	支持图形性能trace分析功能	1（依赖ENABLE_DFX_CMD=1且__LITEOS_M__）

TraceuiEventTraceAsyncBegin

void TraceuiEventTraceAsyncBegin(const char *name, int cookie)

头文件清单

#include "middleware/services/gui/uikit/proprietary/include/dfx/dfx_traceui.h"

功能说明

标记一个异步事件起始，通过name和cookie唯一标识同一异步事件
结束时必须使用相同的name和cookie调用TraceuiEventTraceAsyncEnd
可通过宏TRACEUI_ASYNC_BEGIN(nameStaticStr, cookieInt)调用

前置条件

已通过TraceuiRecordStart启动trace记录

入参

名称	参数类型	详细说明	约束取值范围
name	const char *	标识异步事件的静态字符串	非NULL，字符串指针在trace转换前保持有效
cookie	int	唯一标识同一异步事件的cookie值	整数值

Kconfig配置

配置项	宏类型	说明	默认值
ENABLE_DFX_CMD	功能宏	支持DFX命令功能	1
ENABLE_DFX_TRACEUI	功能宏	支持图形性能trace分析功能	1（依赖ENABLE_DFX_CMD=1且__LITEOS_M__）

TraceuiEventTraceAsyncEnd

void TraceuiEventTraceAsyncEnd(const char *name, int cookie)

头文件清单

#include "middleware/services/gui/uikit/proprietary/include/dfx/dfx_traceui.h"

功能说明

标记一个异步事件结束，与TraceuiEventTraceAsyncBegin配对使用
name和cookie必须与对应AsyncBegin调用一致
可通过宏TRACEUI_ASYNC_END(nameStaticStr, cookieInt)调用

前置条件

已通过TraceuiRecordStart启动trace记录
之前已调用TraceuiEventTraceAsyncBegin且name和cookie一致

入参

名称	参数类型	详细说明	约束取值范围
name	const char *	标识异步事件的静态字符串	非NULL，与对应AsyncBegin的name一致
cookie	int	唯一标识同一异步事件的cookie值	与对应AsyncBegin的cookie一致

Kconfig配置

配置项	宏类型	说明	默认值
ENABLE_DFX_CMD	功能宏	支持DFX命令功能	1
ENABLE_DFX_TRACEUI	功能宏	支持图形性能trace分析功能	1（依赖ENABLE_DFX_CMD=1且__LITEOS_M__）

TraceuiEventTraceInt

void TraceuiEventTraceInt(const char *name, int value)

头文件清单

#include "middleware/services/gui/uikit/proprietary/include/dfx/dfx_traceui.h"

功能说明

记录一个整数值，用于跟踪某个数值随时间的变化趋势
name用于标识计数器，同一name的多次调用形成时间序列
可通过宏TRACEUI_INT(nameStaticStr, valueInt)调用

前置条件

已通过TraceuiRecordStart启动trace记录

入参

名称	参数类型	详细说明	约束取值范围
name	const char *	标识计数器的静态字符串	非NULL，字符串指针在trace转换前保持有效
value	int	当前时刻的整数值	整数范围

Kconfig配置

配置项	宏类型	说明	默认值
ENABLE_DFX_CMD	功能宏	支持DFX命令功能	1
ENABLE_DFX_TRACEUI	功能宏	支持图形性能trace分析功能	1（依赖ENABLE_DFX_CMD=1且__LITEOS_M__）

TraceuiEventLog

void TraceuiEventLog(const char *fmt, ...)

头文件清单

#include "middleware/services/gui/uikit/proprietary/include/dfx/dfx_traceui.h"

功能说明

记录一条日志信息，格式与printf一致
为节省记录内存，日志内容应尽量简短
可通过宏TRACEUI_LOG(fmt, ...)调用

前置条件

已通过TraceuiRecordStart启动trace记录

入参

名称	参数类型	详细说明	约束取值范围
fmt	const char *	格式化字符串，与printf格式一致	非NULL
...	...	格式化参数	与fmt匹配

Kconfig配置

配置项	宏类型	说明	默认值
ENABLE_DFX_CMD	功能宏	支持DFX命令功能	1
ENABLE_DFX_TRACEUI	功能宏	支持图形性能trace分析功能	1（依赖ENABLE_DFX_CMD=1且__LITEOS_M__）

Enumerations

TraceuiEventType

typedef enum {
    TRACEUI_EVENT_TASK_SWITCH,
    TRACEUI_EVENT_TASK_WAKEUP,
    TRACEUI_EVENT_HWI_ENTER,
    TRACEUI_EVENT_HWI_EXIT,
    TRACEUI_EVENT_TRACE_BEGIN,
    TRACEUI_EVENT_TRACE_BEGIN_FORMAT,
    TRACEUI_EVENT_TRACE_END,
    TRACEUI_EVENT_TRACE_ASYNC_BEGIN,
    TRACEUI_EVENT_TRACE_ASYNC_END,
    TRACEUI_EVENT_TRACE_INT,
    TRACEUI_EVENT_LOG,

    TRACEUI_EVENT_MAX
} TraceuiEventType;

枚举成员	取值	描述
TRACEUI_EVENT_TASK_SWITCH	0	任务切换事件
TRACEUI_EVENT_TASK_WAKEUP	1	任务唤醒事件
TRACEUI_EVENT_HWI_ENTER	2	中断进入事件
TRACEUI_EVENT_HWI_EXIT	3	中断退出事件
TRACEUI_EVENT_TRACE_BEGIN	4	同步trace上下文起始事件
TRACEUI_EVENT_TRACE_BEGIN_FORMAT	5	带格式化字符串的同步trace上下文起始事件
TRACEUI_EVENT_TRACE_END	6	同步trace上下文结束事件
TRACEUI_EVENT_TRACE_ASYNC_BEGIN	7	异步事件起始事件
TRACEUI_EVENT_TRACE_ASYNC_END	8	异步事件结束事件
TRACEUI_EVENT_TRACE_INT	9	整数值跟踪事件
TRACEUI_EVENT_LOG	10	日志事件
TRACEUI_EVENT_MAX	11	事件类型上限值

Macros

TRACEUI_EVENTS_ALL

TRACEUI_EVENT_MASK

#define TRACEUI_EVENTS_ALL         0xFFFFFFFF
#define TRACEUI_EVENT_MASK(event)  (1 << (event))