日志工具

资源

概述

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

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

  • 支持 AGG 功能，即支持 LOGUART AGG 功能开启时多核日志的解析，会在每条日志前附加对应的核标签

  • 支持示波器功能，即以波形的形式显示特定格式日志中的数据信息

  • 支持自动化脚本，即支持解析自动化脚本，自动发送命令并捕获日志中的特定字符串信息

  • 支持 Wi-Fi 相关寄存器访问和调试功能

  • 支持获取 BT 相关日志

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

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

../../rst_tools/trace_tool/figures/tracetool_ui.png

菜单栏选项卡：

  • Edit：用于清除历史日志、清除历史命令、加载和保存操作。

  • Option：

    • Global Settings：日志行数限制与时间戳显示配置。

    • Option: Tag Filter：用于在 LOGUART AGG 启用时，在日志前添加不同标签。

硬件设置

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

../../rst_tools/trace_tool/figures/tracetool_hardware_setup.svg

软件设置

  • 环境要求：

    • Windows XP 及以上版本

    • .NET Framework 4.0

  • 软件位置： {SDK}/tools/ameba/TraceTool/AmebaTraceTool.exe

备注

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

日志显示

基本用法

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

  1. 在 COM 框中选择设备 LOGUART 对应的 COM 端口：

    ../../rst_tools/trace_tool/figures/tracetool_port.png

  2. 配置串口参数：

    • Baudrate：波特率，默认设定为 1500000

    • Data Bits：数据位，默认设定为 8

    • Parity：校验位，默认设定为 None

    • Stop Bits：停止位，默认设定为 1

    • Encoding：编码方式，默认设定为 UTF8

    上述参数的设定需要与设备端 LOGUART 参数的设定保持一致。

    另外，Trace Tool 提供了 Close in download mode 选项框，勾选后，Trace Tool 将在检测到芯片进入烧录模式时，自动关闭串口。

  3. 点击 Open 按钮打开 COM 端口，来自设备端的日志即可显示在 Log 选项卡区域，Open 按钮上的文字会切换为 Close。

  4. 当不需要显示日志时，点击 Close 按钮关闭 COM 端口，Trace Tool 将无法显示日志，亦无法发送命令。

日志存储

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

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

    备注

    对于分段日志，请点击 Option 和 Global Settings 来设置日志大小。

  • 点击 Logging 框中的 Open Dir 按钮后，可以直接打开保存日志的文件夹。

AGG 支持

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

  • 当 AGG 功能启用时，Trace Tool 支持解析 AGG 头部信息，并在日志前附加 MCU 标签

    点击 Option 按钮并选择 Tag Filter 下与当前连接的 SoC 对应的标签组合，即可在日志前附加对应的 MCU 标签。 各 SoC 支持的 MCU 标签如下：

    MCU 标签：KM0、KM4

    此外，BT 跟踪日志和 BT 固件日志也会通过 AGG 标识，Trace Tool 会将相关日志自动保存至文件中。 当 LOGUART AGG 功能开启时，如使用其它串口工具，因无法解析 AGG 头部信息，会显示乱码。

  • 当 AGG 功能禁用时，日志中不会附加 AGG 头部信息，Trace Tool 不会在日志前附加 MCU 标签

    在这种情况下，当多个 CPU 同时打印日志时，可能会出现日志混乱的情况。 如无获取 BT 跟踪日志和 BT 固件日志的需求，用户也可以使用其他串口工具来打印日志。

备注

  • 默认情况下，LOGUART 的 AGG 功能处于禁用状态，如需使能 LOGUART AGG，参考 开发者设置。

  • 当 LOGUART AGG 功能在开启状态和禁用状态间进行切换时，可能会出现短期的日志显示混乱。

时间戳支持

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

../../rst_tools/trace_tool/figures/tracetool_log.png

备注

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

命令发送

命令发送的步骤如下：

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

    ../../rst_tools/trace_tool/figures/tracetool_command_box.png

    备注

    指令格式需符合 命令前缀 规范。

  2. 按下 Enter 键执行命令。

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

  • 单击命令，该命令将会显示在命令框中。

  • 双击命令，该命令将会发送到芯片。

  • 点击命令然后点击 Delete，该命令将从历史命令框中删除。

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

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：基于地址按位访问寄存器。

    ../../rst_tools/trace_tool/figures/tracetool_register_access.png

示波器

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

  1. 输入 X 和 Y 模式， X 的默认值为时间。

  2. 点击 Start 按钮。

../../rst_tools/trace_tool/figures/tracetool_scope_log.png

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

../../rst_tools/trace_tool/figures/tracetool_scope.png

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 省电模式。

../../rst_tools/trace_tool/figures/tracetool_wifi_debug.png

自动化脚本

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

  1. 点击 Browse 按钮选择需要执行的脚本。

  2. 点击 Execute 按钮以执行所选脚本。

../../rst_tools/trace_tool/figures/tracetool_auto_script_ui.png

自动化脚本的格式如下：

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 操作，用于跳出循环。

      ../../rst_tools/trace_tool/figures/tracetool_auto_script_execution.png

    • timeout= 后面的数字表示等待匹配字符的最大时间，超出该时间即停止获取。可以根据实际需要进行设置（单位：毫秒），默认值为 5000。

    • pass_pattern= 用于指示 CMD 执行成功的字符。

    • fail_pattern= 用于指示 CMD 执行失败的字符。

    在 CMD 执行过程中，可能出现以下三种结果：

    • Pass: 表示 CMD 执行成功， pass_pattern 在超时时间内被成功匹配。

    • Fail: 表示 CMD 执行失败， fail_pattern 在超时时间内被成功匹配。

    • Timeout: 表示 CMD 执行过程中，超时时间内未匹配到 pass_pattern/fail_pattern 。

小心

  • 每行只能有一条命令。

  • 每个嵌套层次请使用一个 TAB 进行缩进。不应使用空格进行缩进。

  • = 前后不允许有空格。