Trace Tool

Introduction

The Trace Tool is the official serial port debug tool developed by Realtek. It can be used to communicate with the device over a standard RS-232 port. You can directly input commands into the terminal and view or record logs in real time through Trace Tool.

This chapter illustrates how to use Trace Tool to print logs and send commands. The UI of Trace Tool is shown below. The Trace Tool can display logs when the AGG function of loguart is enabled or disabled. There are two configuration tabs in the upper left corner of UI.

  • Edit: the history logs clear, history commands clear, load and save.

  • Option: Global Settings including row count and timestamp, and Tag Filter is used to attach different tag before logs to distinguish logs from different cores when the AGG function is enabled.

../../_images/tracetool_ui.png

Trace tool UI

By default, the AGG (aggregation) function of loguart is disabled so any serial tool can be used to display logs. When the AGG function is enabled, every packet will be send from UART Tx module with AGG header, which is used for Trace Tool to distinguish multi-path data that from different cores.

  • When the AGG function is enabled, hardware will attach AGG header automatically. TraceTool can separate logs from different paths according to AGG header.

    In this case, logs from BT trace and BT FW will be saved into files separately and other logs will print on screen. Therefore, users must use Trace Tool instead of any other serial port tools because the latter will print disordered logs.

  • When the AGG function is disabled, no AGG header is attached. In this case, users can use other tools to print log as long as there is no BT trace and BT FW logs.

    But disordered logs may appear when more than one CPU are printing logs.

Note

The AGG function can be enabled by setting Boot_Agg_En to TRUE in ameba_bootcfg.c.

Environment Setup

Hardware Connection

The hardware connection is illustrated below.

Note

If external UART is used to download images, the USB to UART dongle must be used.

Software Setup

  • Environment requirements:

    • WinXP above

    • .NET Framework 4.0

  • Software location: {SDK}/tools/ameba/TraceTool/AmebaTraceTool.exe

Note

The host driver for USB to UART adapter (e.g. PL2303GC) on the board shall be installed first; otherwise, the LOGUART port cannot be recognized by the host. Please find the exact driver from the official website of corresponding vendor of the USB to UART adapter.

Usage

Log Print

After setting the environment mentioned in Section Environment Setup, execute the following steps:

  1. Select COM port.

    1. Check your COM through Device Manager in your computer, as shown below. In COM & LPT item, all the COM ports connected to the computer are listed.

      ../../_images/tracetool_port_1.PNG

    2. Select COM port in Port Setting box.

      ../../_images/tracetool_port_2.png

  2. Set the format.

    • Baudrate: default is 1500000bps.

    • Data Bits: default is 8.

    • Parity: default is “None”.

    • Stop Bits: default is 1.

    • Encoding: default is UTF8.

    These settings should not be changed freely. If users have to change the format setting for some reasons, the loguart format needs to be changed accordingly to make sure that the format of loguart matches that of Trace Tool.

  3. Click the Open button, then choose Global Settings to select whether add timestamp.

    Note that the timestamp is not very accurate because log processing takes time so there is a slight time interval between receiving logs and displaying logs.

    • When COM port is open, the Trace Tool starts to receive logs from the device. Log is shown in Log window. By default, the timestamp is inserted at the start of each log.

    • If COM port is closed, the Trace Tool will not display logs and the commands can’t be sent.

    ../../_images/tracetool_log.png

The Trace Tool supports log saving function.

  • After clicking Start button in Logging box, all the receiving logs can be saved in a .txt file in the log folder of the same directory for .exe file.

    Note

    For segmented log, click Option and Global Settings to set log size.

  • After clicking Open Dir button in Logging box, the folder where the log is stored can be opened directly.

The Trace Tool can print logs when the AGG function of loguart is enabled or disabled, because the Trace Tool can automatically detect whether the AGG function is enabled or not and can handle it accordingly. When the AGG function is enabled, chick Option button and choose Tag Filter, log from different cores will be added corresponding tags. There may be a period of disorder logs when the AGG function switches from enable to disable or from disable to enable.

Command Send

When COM port is open, you can send commands to the device through Trace Tool. The steps are shown below:

  1. Input a command in command box as shown in the red block.

    ../../_images/tracetool_command_box.png

    Note

    Refer to Command Prefix to decide whether a command prefix is needed to add before the command.

  2. Press the Enter key.

The history command box records the commands have been sent before.

  • Click the command, it will be displayed in the command box.

  • Double-click the command, it will be sent to the chip.

  • Click the command then click delete, the command will be deleted from the history command box.

Command Prefix

Debug

Register Access

The REG function is used to read and write registers by register address.

  • Type: used to select the register type. Wifi MAC/Wifi BB/Wifi RF options are used for Wi-Fi function, which have different base addresses. Select the corresponding options according to your needs.

  • Read/Write Register: enter the register address to Read or Write the register value. Dump means batch printing register values, only Wifi MAC/Wifi BB/Wifi RF registers are supported to be dump.

  • Bit Value: bitwise accessing the register specified by address.

    ../../_images/tracetool_register.png

Scope Illustration

The scope function is used to capture specific data in log and illustrate waveform dynamically.

  1. Enter X and Y pattern, X default value is time.

  2. Click Start button.

../../_images/tracetool_scope_1.png

In the scope interface, waveform will be illustrated synchronously.

../../_images/tracetool_scope_2.png

WiFi Debug

  • DIG_MARGIN: set WiFi DIG margin, available address: [0x00,0x3c].

  • EDCCA: set MAC EDCCA mode, available value: 0/1/9.

  • DBG: set Wi-Fi RA debug, avilable address: [0,0xff], and illustrate CCK_FA and OFDM_FA average value.

  • Power Save: enable or disable Wi-Fi power saving mode.

../../_images/tracetool_wifi_debug.png

AUTO Script

Usage

The AUTO feature is used for automatic script execution.

  1. Click Browse button to choose the script you want to execute.

  2. Click Execute button to execute the script.

../../_images/tracetool_auto_script_1.png

Script Format

The format of script.txt which is used in auto mode is as follows:

CMD1
CMD2
CMD3
…

  • If commands are required to be repeated multiple times, loop can be used:

    loop=10
loop_start
CMD1
CMD2
sleep 1000
…
loop_end

    For a loop, three key words are necessary:

    • Loop: The number after loop= means loop times.

    • loop_start: Used to mark the beginning of the loop.

    • loop_end: Used to mark the end of the loop.

    • loop_start and loop_end have to appear in pairs.

    • sleep: Used to delay some time between commands, and unit is millisecond. sleep 1000 means to delay 1000ms. There should be a blank space between sleep and sleep time.

  • Nested loop is supported as below:

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

  • Catching certain patterns, like pass_pattern or fail_pattern, to indicate that the result of specific CMD execution is supported, the format is as below:

    loop=10
loop_start
timeout=1000
pass_pattern=xxx
fail_patern=xxx
CMD1
if fail/pass/timeout
break
fi
CMD2
…
loop_end

    • The key word pass_pattern, fail_pattern and timeout are only valid for the next command CMD1, used to catch patterns in CMD1 execution.

      When catching the patterns, key word if...fi can be used to perform subsequent operation, now only the break operation is supported, which is used to jump out of the loop.

      ../../_images/tracetool_auto_script_2.png

    • The number after timeout= means the time frame you want to catch log to match the pattern. It can be set to different values according to needs (unit: millisecond), and default value is 5000.

    • The string after pass_pattern= means the pass_pattern, and the string after fail_pattern= means the fail_pattern, which is used to indicate the result of the CMD execution.

    When the corresponding pattern is matched or not during CMD execution, there will be three results:

    • Pass: pass_pattern matched within timeout in CMD execution results.

    • Fail: fail_pattern matched within timeout in CMD execution results.

    • Timeout: no pass_pattern/fail_pattern matched within timeout in CMD execution results.

Caution

  • One command in a single line.

  • TAB is used to indent a line. Only TAB can be used, WHITE SPACE is not allowed.

  • WHITE SPACE before or after = is not allowed.