Sootty

Sootty is a graphical command-line tool for visualizing waveforms from hardware simulations, as a substitute for waveform visualizers like Verdi and GTKWave. It is designed with a focus on being lightweight and easy to use, and takes advantage of modern terminals’ capabilities to provide a clean graphical display. Current features include:

• Customizable display style
• Search and highlight events using a simple query language

And here's an example of how sootty can be used directly from the terminal:

Getting Started

1. Install sootty using pip:

pip install sootty

2. Display a waveform file to the terminal:

sootty "waveform.vcd" -o > image.svg

Optional arguments include:

• -s | --start FORMULA Specify the start of the window.
• -e | --end FORMULA Specify the end of the window.
• -l | --length N Specify the number of ticks in the window (mutually exclusive with -e).
• -o | --output Print svg data to stdout rather than display on terminal.
• -w | --wires LIST Comma-separated list of wires to include in the visualization (default to all wires).
• -b | --break FORMULA Specify the formula for the points in time to be highlighted.
• -r | --radix N Display values in radix N (default 10).
• -S | --save SAVENAME Saves current query for future reuse.
• -R | --reload SAVENAME Loads a saved query. Requires query name as string.
• --btable Print the wire value table at breakpoints to stdout (-b is required).

*Note: For more detailed information on the query language, check out syntax.md

Examples

Below are some more examples that take advantage of some of the features sootty has to offer:

• Display all wires starting at time 4 and ending at wire clk's tenth tick:

sootty "example/example3.vcd" -s "time 4" -e "acc clk == const 10" -w "clk,rst_n,pc,inst"

• Display wires Data and D1 for 8 units of time starting when Data is equal to 20:

sootty "example/example1.vcd" -l 8 -s "Data == const 20" -w "D1,Data"

• Saving a query for future use:

sootty "example/example2.vcd" -s "rdata && wdata == const 22" -l 10 -w "rdata, wdata" -S "save.txt"

• Reloading a saved query:

sootty -R "save.txt"

• Add breakpoints at time 9, 11, and 16 - 17 and print wire values at breakpoints:

sootty "example/example5.evcd" -b "time 9 || time 11 || after time 15 && before time 18" --btable

Running with python

Sootty can also be run from within a python program:

from sootty import WireTrace, Visualizer, Style
from sootty.utils import evcd2vcd

# Create wiretrace object from vcd file:
wiretrace = WireTrace.from_vcd_file("example/example1.vcd")

# Convert wiretrace to svg:
image = Visualizer(Style.Dark).to_svg(wiretrace, start=0, length=8)

# Display to stdout:
image.display()

# Manually convert EVCD file to VCD file:
with open('myevcd.evcd', 'rb') as evcd_stream:
    vcd_reader = evcd2vcd(evcd_stream)
    with open('myvcd.vcd', 'wb') as vcd_stream:
        vcd_stream.write(vcd_reader.read())

Note: You can view and modify the save files for the queries in the ~/.config/sootty/save directory.

Dependencies

As of the current release, Sootty can only display images in certain terminals with builtin graphics support. This currently includes the following terminal replacements:

• iTerm2
• kitty

The following external dependencies are also needed to properly display images within the terminal:

• viu

  # From source (rust package manager)
  cargo install viu
  # MacOS
  brew install viu
  # Arch Linux
  pacman -S viu

• rsvg-convert

  # Ubuntu
  apt install librsvg2-bin
  # MacOS
  brew install librsvg

Contributing

If you are interested in contributing to this project, feel free to take a look at the existing issues and submit a PR. Beginners are encouraged to focus on issues with the "good first issue" label. This project has also been involved with Google Summer of Code through the FOSSi Foundation. Check out our project idea for GSoC '23: https://www.fossi-foundation.org/gsoc23-ideas#enhancing-the-sootty-terminal-based-graphical-waveform-viewer