日志工具

资源

下载

概述

Trace Tool 是由 Realtek 官方开发的串口调试工具。该工具能够通过 LOGUART 端口实现与设备的通信。用户可以在终端中输入命令，并使用 Trace Tool 实时查看或记录设备的日志信息。

与通用串口工具相比，Trace Tool 支持以下增强功能：

支持 AGG 功能，即支持 LOGUART AGG 功能开启时多核日志的解析，会在每条日志前附加对应的核标签。该解析会根据所选 SoC 自动分发，只需选择当前连接的芯片，即可配置正确的核标签与各 AGG 路径的路由
支持示波器功能，即以波形的形式显示特定格式日志中的数据信息
支持自动化脚本，即支持解析自动化脚本，自动发送命令并捕获日志中的特定字符串信息
支持 Wi-Fi 相关寄存器访问和调试功能
支持获取 BT 相关日志

如无须使用上述功能，可用通用串口工具替代 Trace Tool。

Trace Tool 的用户界面如下图所示：

菜单栏提供以下选项：

Chip 菜单（红色显示）：选择当前连接的 SoC，详情参考 SoC 选择。
Edit：提供 Clear Log、Clear Auto Log 以及 History Commands 子菜单（Clear / Save / Load），用于管理历史命令列表。
Option：提供 Global Settings，用于配置日志显示行数、日志文件大小以及时间戳显示。

硬件设置

Trace Tool 的硬件设置如下所示：

软件设置

环境要求：
- Windows XP 及以上版本
- .NET Framework 4.6.1 及以上版本
软件位置： {SDK}/tools/ameba/TraceTool/AmebaTraceTool.exe

备注

使用前需在主机安装板上 USB 转 UART 适配器（如 PL2303GC）的官方驱动程序，确保系统正确识别 LOGUART 端口。

SoC 选择

建议在打开串口前，在 Chip 菜单中选择当前连接的 SoC。该选择会被保存，并在下次启动时自动恢复。

Trace Tool 完全依据所选 SoC 来分发 AGG 日志。选择当前连接的 SoC 后，各核标签、Tag Filter 面板中的条目以及每条 AGG 路径的分发方式都会自动配置，无需进一步手动设置。

所选 SoC 决定了：

LOGUART AGG 启用时附加到每条日志前的核标签；
Tag Filter 面板中显示的条目，用于显示或隐藏各个核的日志；
每条 AGG 路径的分发方式：文本路径显示在 Log 选项卡，蓝牙及其他二进制路径则写入文件或 TCP 端口。各 SoC 的路径映射关系参考 AGG 支持。

备注

Generic 为默认选项。当未选择当前连接的 SoC，或接收到未识别的路径时，Trace Tool 会回退到通用核标签 [Core0] / [Core1] / [Core2] 来标记文本路径，以保证日志仍可显示。请选择实际的 SoC 以获得正确的核标签。
RTL872xD、RTL8195X 和 RTL871XB 为不支持 AGG 功能的 SoC。其 LOGUART 不会插入 AGG 头部信息，因此不会附加核标签，选择这些 SoC 时 Tag Filter 面板将被隐藏。

日志显示

基本用法

在根据硬件设置部分完成环境配置后，请执行以下步骤：

在 COM 框中选择设备 LOGUART 对应的 COM 端口：
配置串口参数：
- Baudrate：波特率，默认设定为 1500000
- Data Bits：数据位，默认设定为 8
- Parity：校验位，默认设定为 None
- Stop Bits：停止位，默认设定为 1
- Encoding：编码方式，默认设定为 UTF-8，可正确显示多字节字符（如中文）；同时也支持 ASCII
上述参数的设定需要与设备端 LOGUART 参数的设定保持一致。

另外，Trace Tool 提供了 Close in download mode 选项框，勾选后，Trace Tool 将在检测到芯片进入烧录模式时，自动关闭串口。
点击 Open 按钮打开 COM 端口，来自设备端的日志即可显示在 Log 选项卡区域，Open 按钮上的文字会切换为 Close。
当不需要显示日志时，点击 Close 关闭 COM 端口，Trace Tool 将停止显示日志与发送命令。

日志存储

Trace Tool 支持将日志保存为文本文件。

点击 Logging 框中的 Start 按钮后，所有接收到的日志将保存到与 .exe 文件同目录的 log 文件夹中的 .txt 文件中。

备注

对于分段日志，请点击 Option 和 Global Settings 来设置日志大小。
点击 Logging 框中的 Open Dir 按钮后，可以直接打开保存日志的文件夹。

AGG 支持

Trace Tool 可自动识别 LOGUART 的 AGG 功能是否启用，并进行相应的处理。

当 AGG 功能启用时

固件会将多个核的日志流复用到单条 LOGUART 引脚上，并为每个数据包附加用于标识来源的路径号。Trace Tool 会解析每个数据包的 AGG 头部信息，并根据 Chip 菜单中所选的 SoC 自动进行分发，无需进一步手动配置。

各 AGG 路径在不同 SoC 上承载的核或数据流如下：

SoC	路径 1	路径 2	路径 3	路径 4	路径 5
RTL8721Dx	KM4	KM0	BT upper stack	—	BT FW
RTL8721F	KM4TZ	KM4NS	BT upper stack	—	BT FW
RTL8720F	KM4TZ	KM4NS	BT upper stack	SDN	—
RTL8720E	KM4	KR4	BT upper stack	—	BT FW
RTL8710E	KM4	KR4	BT upper stack	—	BT FW
RTL8726E	KM4	KR4	BT upper stack	DSP	BT FW
RTL8713E	KM4	KR4	BT upper stack	DSP	BT FW
RTL8730E	KM4	KM0	BT upper stack	CA32	BT FW
RTL8735C	KM4NP	CA32	BT upper stack	KM0	BT FW

文本日志会显示在 Log 选项卡中，并在每条日志前附加对应的核标签（例如 [KM4] 或 [CA32]）。如需显示或隐藏各个核的日志，可在 Tag Filter 面板中勾选或取消勾选相应的核；每次更改 Chip 选择时，该面板都会重新生成，以列出所选 SoC 的各个核。

其余数据流（BT upper stack、BT FW 和 SDN）为二进制流，不会显示在 Log 选项卡中，而是以对应的文件名保存至文件，或转发至 TCP 端口：

蓝牙主机（上层协议栈）日志会保存至 BT_*.bin 文件，或转发至连接在 TCP 端口 5000 的蓝牙分析工具。
蓝牙固件日志会保存至 BT_FW_*.log 文件，或转发至 TCP 端口 5001。
SDN 日志会保存至 SDN_*.bin 文件。

当 LOGUART AGG 功能开启时，如使用其它串口工具，因无法解析 AGG 头部信息，会显示乱码。

当 AGG 功能禁用时
- 日志中不会附加 AGG 头部信息。
- Trace Tool 不会在日志前附加核标签。
在这种情况下：
- 当多个核同时打印日志时，可能会出现日志混乱的情况。
- 如无获取蓝牙主机日志和蓝牙固件日志的需求，用户也可以使用其他串口工具来打印日志。
备注
- 默认情况下，LOGUART 的 AGG 功能处于禁用状态，如需使能，参考开发者设置。
- 当 LOGUART AGG 功能在开启状态和禁用状态间切换时，可能会出现短期的日志显示混乱。

时间戳支持

依次点击 Option > Global Settings，可以设定是否为日志的开头添加时间戳。

备注

时间戳显示的时间较设备发送日志的时间存在一定的滞后，因为 Trace Tool 接收、解析、显示日志需要耗费一定的时间。

命令发送

命令发送的步骤如下：

在命令框中输入命令，如红色框所示。

备注

指令格式需符合命令前缀规范。
按下 Enter 键执行命令。

历史命令框记录了之前输入的命令。

单击命令，该命令将会显示在命令框中。
双击命令，该命令将会发送到芯片。
点击命令然后点击 Delete，该命令将从历史命令框中删除。

当 SoC 中的多个 MCU 承担不同角色时，需要使用特定的命令前缀来向不同的 MCU 发送命令。

RTL8721Dx:

MCU	角色	命令前缀
KM4	AP	无
KM0	NP	@

寄存器访问

寄存器访问功能用于读取和写入特定寄存地址的寄存器值。

Type：寄存器类型选择。Wifi MAC/Wifi BB/Wifi RF 选项针对的是 Wi-Fi 功能，各自拥有不同的基地址。请根据实际需求进行选择。
Read/Write/Dump：输入寄存器地址以 Read 或 Write 寄存器值， Dump 仅支持 Wifi MAC/Wifi BB/Wifi RF 寄存器的批量打印。
Bit Value：基于地址按位访问寄存器。

示波器

示波器功能用于在日志中捕获特定数据并动态展示其波形。此功能自版本 v2.1.28 起开始支持。

输入 X 和 Y 模式， X 的默认值为时间。
点击 Start 按钮。

在示波器界面中，波形将同步展示。

Wi-Fi 调试

DIG_MARGIN：设置 Wi-Fi DIG 余量，可用地址：[0x00,0x3c]。
EDCCA：设置 MAC EDCCA 模式，可用值：0/1/9。
DBG：设置 Wi-Fi RA 调试，可用地址：[0,0xff]，并展示 CCK_FA 和 OFDM_FA 的平均值。
Power Save：启用或禁用 Wi-Fi 省电模式。

诊断

诊断功能用于读取设备固件记录的诊断事件，将其显示在表格中，并支持删除或导出。该功能需要设备固件支持诊断特性。

自动化脚本

AUTO 选项卡提供了对自动化脚本的支持。

点击 Browse 按钮选择需要执行的脚本。
点击 Execute 按钮以执行所选脚本。

自动化脚本的格式如下：

CMD1
CMD2
CMD3
…

如果需要多次执行命令，可以使用循环结构：
```
loop=10
loop_start
CMD1
CMD2
sleep 1000
…
loop_end
```
循环结构中的关键字及其规则如下：
- Loop: loop= 后面的数字表示循环次数。
- loop_start: 用于标记循环的开始。
- loop_end: 用于标记循环的结束。
- loop_start 和 loop_end 必须成对出现。
- sleep: 用于在命令之间延迟一段时间，单位为毫秒。 sleep 1000 表示延迟 1000 毫秒。 sleep 和延迟时间之间需要有一个空格。

支持嵌套循环，如下所示：

loop=2
loop_start
CMD1
sleep 1000
loop=3
loop_start
CMD2
sleep 2000
loop_end
loop_end

支持捕获特定模式（如 pass_pattern 或 fail_pattern）以指示特定 CMD 执行的结果，格式如下：
```
loop=10
loop_start
timeout=1000
pass_pattern=xxx
fail_patern=xxx
CMD1
if fail/pass/timeout
break
fi
CMD2
…
loop_end
```
- 关键词 pass_pattern， fail_pattern 和 timeout 仅对下一个命令 CMD1 有效，用于捕获 CMD1 执行后的字符。
  
  当匹配到目标字符时，可以使用关键词 if...fi 执行后续操作，目前仅支持 break 操作，用于跳出循环。
- timeout= 后面的数字表示等待匹配字符的最大时间，超出该时间即停止获取。可以根据实际需要进行设置（单位：毫秒），默认值为 5000。
- pass_pattern= 用于指示 CMD 执行成功的字符。
- fail_pattern= 用于指示 CMD 执行失败的字符。
在 CMD 执行过程中，可能出现以下三种结果：
- Pass: 表示 CMD 执行成功， pass_pattern 在超时时间内被成功匹配。
- Fail: 表示 CMD 执行失败， fail_pattern 在超时时间内被成功匹配。
- Timeout: 表示 CMD 执行过程中，超时时间内未匹配到 pass_pattern/fail_pattern 。

小心

每行只能有一条命令。
每个嵌套层次请使用一个 TAB 进行缩进。不应使用空格进行缩进。
= 前后不允许有空格。