开发指导
使用场景
- 通过Trace了解系统运转的轨迹，理解系统。
- 通过Trace分析系统发生异常前的操作，定位死机问题。
功能
Huawei LiteOS的Trace模块为用户提供下面几种功能，接口详细信息可以查看API参考。
功能分类 |
接口名 |
描述 |
|---|---|---|
配置Trace缓冲区 |
LOS_TraceInit |
配置Trace缓冲区的地址和大小 |
开启/停止Trace事件记录 |
LOS_TraceStart |
开启事件记录 |
LOS_TraceStop |
停止事件记录 |
|
操作Trace记录的数据 |
LOS_TraceRecordDump |
输出Trace缓冲区数据 |
LOS_TraceRecordGet |
获取Trace缓冲区的首地址 |
|
LOS_TraceReset |
清除Trace缓冲区中的事件 |
|
过滤Trace记录的模块 |
LOS_TraceEventMaskSet |
设置事件掩码，仅记录某些模块的事件 |
屏蔽某些中断号事件 |
LOS_TraceHwiFilterHookReg |
注册过滤特定中断号事件的钩子函数 |
插桩函数 |
LOS_TRACE_EASY |
简易插桩 |
LOS_TRACE |
标准插桩 |
- LOS_TRACE_EASY(TYPE, IDENTITY, params...) 简易插桩。
- 一句话插桩，用户在目标源代码中插入该接口即可。
- TYPE有效取值范围为[0, 0xF]，表示不同的事件类型。
- IDENTITY类型UINTPTR，表示事件操作的主体对象。
- Params类型UINTPTR，表示事件的参数。
- 示例：
LOS_TRACE_EASY(1, userId0, userParam1, userParam2); LOS_TRACE_EASY(2, userId0); LOS_TRACE_EASY(1, userId1, userParam1, userParam2); LOS_TRACE_EASY(2, userId1);
- LOS_TRACE(TYPE, IDENTITY, params...) 标准插桩。
- 相比简易插桩，支持动态过滤事件和参数裁剪，但使用上需要用户按规则来扩展。
- TYPE用于设置具体的事件类型，可以在头文件los_trace.h中的enum LOS_TRACE_TYPE中自定义事件类型。定义方法和规则可以参考其他事件类型。
- IDENTITY和Params的类型及含义同简易插桩。
- 示例：
1.在enum LOS_TRACE_MASK中定义事件掩码，即模块级别的事件类型。定义规范为TRACE_#MOD#_FLAG，#MOD#表示模块名，例如： TRACE_FS_FLAG = 0x2000 2.在enum LOS_TRACE_TYPE中定义具体事件类型。定义规范为#TYPE# = TRACE_#MOD#_FLAG | NUMBER，例如： FS_READ = TRACE_FS_FLAG | 0; // 读文件 FS_WRITE = TRACE_FS_FLAG | 1; // 写文件 3.定义事件参数。定义规范为#TYPE#_PARAMS(IDENTITY, parma1...) IDENTITY, ... 其中的#TYPE#就是上面2中的#TYPE#，例如： #define FS_READ_PARAMS(fp, fd, flag, size) fp, fd, flag, size 宏定义的参数对应于Trace缓冲区中记录的事件参数，用户可对任意参数字段进行裁剪； 当定义为空时，表示不追踪该类型事件： #define FS_READ_PARAMS(fp, fd, flag, size) // 不追踪文件读事件 4.在适当位置插入代码桩。定义规范为LOS_TRACE(#TYPE#, #TYPE#_PARAMS(IDENTITY, parma1...)) LOS_TRACE(FS_READ, fp, fd, flag, size); // 读文件的代码桩，#TYPE#之后的入参就是上面3中的FS_READ_PARAMS函数的入参
- Huawei Liteos预置的Trace事件及参数均可以通过上述方式进行裁剪，参数详见kernel\include\los_trace.h。
Trace错误码
对Trace存在失败可能性的操作，包括初始化Trace、启动Trace 均需要返回对应的错误码，以便快速定位错误原因。其他无返回值的接口如停止Trace、清除与dump Trace 数据均为Trace状态不合法，系统会直接打印错误原因。
序号 |
定义 |
实际数值 |
描述 |
参考解决方案 |
|---|---|---|---|---|
1 |
LOS_ERRNO_TRACE_ERROR_STATUS |
0x02001400 |
初始化Trace或启动Trace时状态不正确 |
禁止重复初始化Trace，未初始化Trace前禁止启动Trace |
2 |
LOS_ERRNO_TRACE_NO_MEMORY |
0x02001401 |
初始化Trace时，缓冲区申请失败 |
解决方案有两个：
|
3 |
LOS_ERRNO_TRACE_BUF_TOO_SMALL |
0x02001402 |
初始化Trace时，缓冲区size设置过小 |
增大Trace缓冲区的大小，可以修改los_config.h中的LOS_TRACE_BUFFER_SIZE |
错误码定义见错误码简介。8~15位的所属模块为Trace模块，值为0x14。
开发流程
Trace的典型开发流程：
- 执行make menuconfig命令，进入Kernel ---> Enable Extend Kernel ---> Enable Trace Feature菜单，完成Trace的配置。
配置项
含义
取值范围
默认值
依赖
LOSCFG_KERNEL_TRACE
Trace模块的裁剪开关
YES/NO
NO
LOSCFG_KERNEL_EXTKERNEL
LOSCFG_RECORDER_MODE_OFFLINE
Trace工作模式为离线模式
YES/NO
YES
LOSCFG_KERNEL_TRACE
LOSCFG_RECORDER_MODE_ONLINE
Trace工作模式为在线模式
YES/NO
NO
LOSCFG_KERNEL_TRACE
LOSCFG_TRACE_CLIENT_INTERACT
使能与Trace IDE （Huawei LiteOS Studio）的交互，包括数据可视化和流程控制
YES/NO
NO
LOSCFG_KERNEL_TRACE
LOSCFG_TRACE_PIPELINE_SERIAL
选择串口作为IDE数据可视化通道
YES/NO
YES
LOSCFG_TRACE_CLIENT_INTERACT
LOSCFG_TRACE_CONTROL_VIA_SHELL
选择shell作为IDE流程控制的方式
YES/NO
YES
LOSCFG_TRACE_CLIENT_INTERACT && LOSCFG_SHELL
LOSCFG_TRACE_CONTROL_AGENT
选择agent作为IDE流程控制的方式
YES/NO
NO
LOSCFG_TRACE_CLIENT_INTERACT
LOSCFG_TRACE_NO_CONTROL
不启用IDE的流程控制
YES/NO
NO
LOSCFG_TRACE_CLIENT_INTERACT
- (可选)预置事件参数和事件桩（或使用系统默认的事件参数配置和事件桩）。
- (可选)调用LOS_TraceStop停止Trace后，清除缓冲区LOS_TraceReset（系统默认已启动trace）。
- (可选)调用LOS_TraceEventMaskSet设置需要追踪的事件掩码（系统默认的事件掩码仅使能中断与任务切换）。
- 在需要记录事件的代码起始点调用LOS_TraceStart。
- 在需要记录事件的代码结束点调用LOS_TraceStop。
- 调用LOS_TraceRecordDump输出缓冲区数据（函数的入参为布尔型，FALSE表示格式化输出，TRUE表示输出到windows客户端）。
平台差异性
无。
