CLI Trace Converter: tband-cli

Compile & Install

The trace converter and CLI is written in rust 🦀. To compile and run tband-cli locally, first you need to download and install rust if you don’t already have it.

Then, open the ./tools/tband-cli folder.

Now you have two options. To compile & install tband-cli, run:

> cargo install --path .

This will compile the tool, and place the finished executable in your local cargo binary direction. Where that is depends on your system. Most likely you will have to add it to your PATH.

To build and run the CLI tool directly from the repository, type:

> cargo run --

Any command line arguments you want to provide need to go after the -- separator.

Commands

The tool features 5 main commands:

> tband-cli --help
Usage: tband-cli [OPTIONS] <COMMAND>

Commands:
  conv        Convert trace recording
  serve       Serve trace file for perfetto
  completion  Print completion script for specified shell
  dump        Dump trace recording
  help        Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...  
  -h, --help        Print help
  -V, --version     Print version

conv

The conv command is where most of the action is. It takes one or more trace files, decodes them, and converts them to the perfetto format:

> tband-cli conv --help
Convert trace recording

Usage: tband-cli conv [OPTIONS] [INPUT]...

Arguments:
  [INPUT]...
          Input files with optional core id.
          
          For split multi-core recording, append core id to file name as such: filename@core_id

Options:
  -f, --format <FORMAT>
          Input format
          
          [default: bin]
          [possible values: hex, bin]

  -m, --mode <MODE>
          TraceMode
          
          [default: free-rtos]
          [possible values: bare-metal, free-rtos]

  -c, --core-count <CORE_COUNT>
          Number of cores of target
          
          [default: 1]

  -o, --output <OUTPUT>
          Location to store converted trace

      --open
          Open converted trace in perfetto

      --serve
          Serve converted trace for perfetto

  -h, --help
          Print help (see a summary with '-h')

It supports both binary and hex trace files, and both bare-metal and FreeRTOS traces. After conversion, the tool can save the result to a file (--output), open it directly in perfetto (--open), or provide a link and host a local server to provide the trace to perfetto (--serve).

The input files must be given last. If converting a multi-core trace split into seperate files, append the core id to each file as follows:

> tband-cli conv --format=bin --core-count=2 --open core0_trace.bin@0 core1_trace.bin@1

dump

The dump command takes a single trace file, decodes it, and dumps its content in human-readable form to stdout.

> tband-cli dump --help
Dump trace recording

Usage: tband-cli dump [OPTIONS] --mode <MODE> <INPUT>

Arguments:
  <INPUT>
          Input file with optional core id.
          
          For split multi-core recording, append core id to file name as such: filename@core_id

Options:
  -f, --format <FORMAT>
          Input format
          
          [default: bin]
          [possible values: hex, bin]

  -m, --mode <MODE>
          TraceMode
          
          [possible values: bare-metal, free-rtos]

  -h, --help
          Print help (see a summary with '-h')

completion

The completion command can generate shell completion scripts for most common shells. How you can install a completion script depends on your shell and system configuration.

> tband-cli completion --help
Print completion script for specified shell

Usage: tband-cli completion <SHELL>

Arguments:
  <SHELL>  Style of completion script to generate [possible values: bash, elvish, fish, powershell, zsh]

Options:
  -h, --help  Print help