日志工具

资源

下载

概述

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 进行缩进。不应使用空格进行缩进。
= 前后不允许有空格。

故障排查

使用 Trace Tool 过程中遇到问题时，可参考以下常见情况：

无法打开串口

问题： 打开串口时提示错误。

解决方法： 该串口可能已被其他进程占用。请关闭其他可能持有该串口的终端程序（例如 PuTTY、Tera Term、其他 Trace Tool 实例，在线烧录工具或 VS Code 串口监视器），然后重试。

日志乱码

问题： 日志无法识别、出现乱码字符。

解决方法： 确认波特率，编码格式等配置与设备固件配置一致。

蓝牙日志未捕获

问题： 蓝牙主机或固件日志未写入 *.bin / *.log 文件，或外部分析仪无法通过 TCP 连接到 Trace Tool。

解决方法：

确认已在 Chip 菜单中选择当前连接的 SoC。蓝牙 AGG 路径仅在选择具体 SoC 后才会注册，Generic 默认选项不定义蓝牙路径。
Trace Tool 在 TCP 端口 5000（蓝牙上层协议栈）和 5001（蓝牙固件）监听分析仪连接。请关闭可能占用这两个端口的其他 Trace Tool 实例，并确保主机防火墙允许这两个端口的入站连接。

示波器趋势图不更新或显示错误数值

问题： 在 Scope 选项卡中，某个 Y 通道的波形停止更新、显示错误数值，或即使日志中出现了匹配的文本，图表也始终没有数据。

解决方法： 对每一行日志，Trace Tool 会以普通字符串匹配的方式查找所配置的 X/Y1 至 Y6 模式文本，然后在该文本之后、本行结尾之前，提取第一个十进制整数（可带前导 -）作为对应的数值。因此固件日志需符合以下格式，数值才能被正确捕获：

模式文本与其数值需打印在同一行，且数值紧跟在模式文本之后（例如 printf("Temp: %d\n", temp);）。
数值需为普通十进制整数。十六进制（0x1A）、浮点数（3.14）或非数字内容都无法被正确解析——Trace Tool 只提取第一段连续数字，因此 0x1A 会被读取为 1，3.14 会被读取为 3；若模式文本之后没有任何数字，该行会被静默跳过，图表不会更新。
每个模式文本需是该行日志中精确且具有区分度的子串。由于采用子串匹配，过短或相互重叠的模式（例如某个模式名恰好是另一个模式名的前缀）可能匹配到错误的位置。
每个 Y 指标应单独占一行。Trace Tool 在每一行中只会处理第一个匹配到的已配置 Y 模式，同一行中的其他指标会被忽略。

诊断命令执行失败

问题： 点击 Start Diagnose 后，DIAG 选项卡报错 Command 'AT+DIAG=...' execution failed after 5 attempts。

解决方法：

在点击 Start Diagnose 前先打开串口。诊断操作独占串口，无法在串口关闭状态下启动。
确认设备固件支持诊断功能。如果 AT+DIAG=VER 返回的固件版本与 Trace Tool 内置的任何配置文件都不匹配，将无法解析事件。

启动后设置被重置

问题： Trace Tool 启动后使用默认配置（串口、波特率、所选 SoC 等），尽管上一次会话已正确保存。

解决方法： 若 Setting.json 由旧版本 Trace Tool 写入，文件中可能包含当前版本已不再识别的取值。此时 Trace Tool 会回退到默认配置而不会崩溃。请删除 AmebaTraceTool.exe 同级目录下的 Setting.json 文件并重新启动，文件将以当前结构重新生成。