# 开发指导
#### 使用场景
- 通过Trace了解系统运转的轨迹，理解系统。
 
- 通过Trace分析系统发生异常前的操作，定位死机问题。
#### 功能
Huawei LiteOS的Trace模块为用户提供下面几种功能，接口详细信息可以查看API参考。
表1功能列表 
| 功能分类           | 接口名                       | 描述                |
|:---|:---|:---|
| 配置Trace缓冲区     | LOS_TraceInit             | 配置Trace缓冲区的地址和大小  |
| 开启/停止Trace事件记录 | LOS_TraceStart            | 开启事件记录            |
| 开启/停止Trace事件记录 | LOS_TraceStop             | 停止事件记录            |
| 操作Trace记录的数据   | LOS_TraceRecordDump       | 输出Trace缓冲区数据      |
| 操作Trace记录的数据   | LOS_TraceRecordGet        | 获取Trace缓冲区的首地址    |
| 操作Trace记录的数据   | LOS_TraceReset            | 清除Trace缓冲区中的事件    |
| 过滤Trace记录的模块   | LOS_TraceEventMaskSet     | 设置事件掩码，仅记录某些模块的事件 |
| 屏蔽某些中断号事件      | LOS_TraceHwiFilterHookReg | 注册过滤特定中断号事件的钩子函数  |
| 插桩函数           | LOS_TRACE_EASY            | 简易插桩              |
| 插桩函数           | LOS_TRACE                 | 标准插桩              |
   
![](https://support.huaweicloud.com/maintenance-LiteOS/public_sys-resources/note_3.0-zh-cn.png)
1. 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);
     ```
     
    
2. 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)
       LOS_TRACE(FS_READ, fp, fd, flag, size); // 读文件的代码桩，#TYPE#之后的入参就是上面3中的FS_READ_PARAMS函数的入参
     ```
     
    
3. 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时，缓冲区申请失败      | 解决方案有两个： - 减小Trace缓冲区的大小，可以修改los_config.h中的LOS_TRACE_BUFFER_SIZE  - 配置LOSCFG_BASE_CORE_TSK_LIMIT减少最大任务数   |
| 3  | LOS_ERRNO_TRACE_BUF_TOO_SMALL | 0x02001402 | 初始化Trace时，缓冲区size设置过小  | 增大Trace缓冲区的大小，可以修改los_config.h中的LOS_TRACE_BUFFER_SIZE                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
   
![](https://support.huaweicloud.com/maintenance-LiteOS/public_sys-resources/notice_3.0-zh-cn.png)
错误码定义见[错误码简介](https://support.huaweicloud.com/maintenance-LiteOS/zh-cn_topic_0175230332.html#ZH-CN_TOPIC_0175230332__section29852515161)。8\~15位的所属模块为Trace模块，值为0x14。
#### 开发流程
Trace的典型开发流程：
1. 执行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                   |
      
   
2. (可选)预置事件参数和事件桩（或使用系统默认的事件参数配置和事件桩）。
3. (可选)调用LOS_TraceStop停止Trace后，清除缓冲区LOS_TraceReset（系统默认已启动trace）。
4. (可选)调用LOS_TraceEventMaskSet设置需要追踪的事件掩码（系统默认的事件掩码仅使能中断与任务切换）。
5. 在需要记录事件的代码起始点调用LOS_TraceStart。
6. 在需要记录事件的代码结束点调用LOS_TraceStop。
7. 调用LOS_TraceRecordDump输出缓冲区数据（函数的入参为布尔型，FALSE表示格式化输出，TRUE表示输出到windows客户端）。
 
#### 平台差异性
无。