fst-tools

Tools for manipulating Fast Signal Trace (FST) format waveforms.

FST is an open source file format for storing digital waveforms from HDL simulations. It was created by the author of GTKWave in 2014, as an alternate to the VCD (Value Change Dump) format.

For more details, please see:

• The source code of GTKWave.
• The documentation of GTKWave.
• An unofficial specification for FST format.

Available Tools

• readfst: tool for displaying information about the contents of FST waveform, like readelf.
• findfst: tool for finding values of signals from FST waveform, like fstminer tool that comes with GTKWave but more powerful.
• clipfst: tool for clipping from FST waveform.

Building on Windows

Windows requires additional setup due to dependencies that are not readily available:

Prerequisites

• Rust (latest stable version)
• vcpkg package manager
• Visual Studio Build Tools or Visual Studio Community

Build Instructions

1. Install vcpkg:

   It comes preinstalled with Visual Studio, but if you don't have it yet, you can install it by running the following commands in PowerShell:

   git clone https://github.com/Microsoft/vcpkg.git
   cd vcpkg
   .\bootstrap-vcpkg.bat

   (tested with vcpkg version 2025-02-11-bec4296bf5289dc9ce83b4f5095943e44162f9c2)

2. Install required packages:

   vcpkg install zlib:x64-windows-static-md
   vcpkg install pthreads:x64-windows-static-md
   vcpkg install mman:x64-windows-static-md

   (adjust vcpkg path as necessary, depending on whether it is on your PATH or not)

3. Build

   cargo build

Note: The build requires the x64-windows-static-md triplet for vcpkg packages to ensure compatibility with Rust's MSVC toolchain.

Troubleshooting

  thread 'main' panicked at fstapi\build.rs:19:8:
  called `Result::unwrap()` on an `Err` value: LibNotFound("package zlib is not installed for vcpkg triplet x64-windows-static-md")
  note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

This error indicates that the zlib package is not found for the specified vcpkg triplet. Ensure that you have installed zlib using the correct triplet as shown in step 2 above. Similarly for pthreads or mman packages.

Note that we're using pthreads (with an s) instead of pthread (without s) because the latter is deprecated in vcpkg.

Rust Wrapper for FST C API

This repository contains a Rust wrapper for the FST C API provided by GTKWave. See the fstapi directory.

All of the tools in the repo are written in Rust using this wrapper.

Changelog

See CHANGELOG.md.

License

Copyright (C) 2023-2025 MaxXing. Licensed under either of Apache 2.0 or MIT at your option.