Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Ben1152000/sootty
A command-line tool for displaying vcd waveforms.
https://github.com/Ben1152000/sootty
Last synced: 3 months ago
JSON representation
A command-line tool for displaying vcd waveforms.
- Host: GitHub
- URL: https://github.com/Ben1152000/sootty
- Owner: Ben1152000
- License: bsd-3-clause
- Created: 2021-08-06T01:05:59.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-02-19T10:52:44.000Z (9 months ago)
- Last Synced: 2024-07-16T07:39:49.757Z (4 months ago)
- Language: Python
- Size: 460 KB
- Stars: 44
- Watchers: 4
- Forks: 12
- Open Issues: 25
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-opensource-hardware - sootty
README
# 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 languageAnd here's an example of how sootty can be used directly from the terminal:
## Getting Started
1. Install sootty using pip:
```bash
pip install sootty
```2. Display a waveform file to the terminal:
```bash
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](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:
```bash
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:
```bash
sootty "example/example1.vcd" -l 8 -s "Data == const 20" -w "D1,Data"
```- Saving a query for future use:
```bash
sootty "example/example2.vcd" -s "rdata && wdata == const 22" -l 10 -w "rdata, wdata" -S "save.txt"
```- Reloading a saved query:
```bash
sootty -R "save.txt"
```- Add breakpoints at time 9, 11, and 16 - 17 and print wire values at breakpoints:
```bash
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:
```python
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](https://iterm2.com/)
- [kitty](https://sw.kovidgoyal.net/kitty/)The following external dependencies are also needed to properly display images within the terminal:
- [viu](https://github.com/atanunq/viu)
```bash
# From source (rust package manager)
cargo install viu
# MacOS
brew install viu
# Arch Linux
pacman -S viu
```
- rsvg-convert
```bash
# 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](https://www.fossi-foundation.org/). Check out our project idea for GSoC '23: https://www.fossi-foundation.org/gsoc23-ideas#enhancing-the-sootty-terminal-based-graphical-waveform-viewer