Pylibfst: Handle Fast Signal Traces (fst) in Python

Fst, like vcd, is an open format for dumpfiles generated by EDA logic simulation tools. Unlike vcd, fst is a compressed binary format that offers much better performance for very large dumpfiles. Fst was originally developed as part of gtkwave. For more details on the format, see GTKWave 3.3 Wave Analyzer User's Guide.

Pylibfst is a python cffi wrapper for a slightly extended version of the fst C library contained in gtkwave. It was initially created to add support for fst to WAL (Waveform Analysis Language), developed at the Institute for Complex Systems at Johannes Kepler University, Linz.

More details on WAL can be found at https://wal-lang.org.

The latest development version of pylibfst is available on github.

Build & Install

Dependencies

Additional packages that need to be installed on the system:

• cmake build environment (cmake, gcc, ...)
• zlib-dev

Install using PyPi (pip)

Pylibfst is available from PyPi!

pip install pylibfst

Build & Install from Source

The latest development version of pylibfst is available on github.

There are various ways to build and/or install pylibfst:

• Build from Source using Python

python -m pip install --upgrade build
python -m build

• Build from Source using make

make all

• Build & Install from Source using make

make install

Usage

A documentation on how to handle the cffi-style interface (calls, arguments, return values, ...) can be found in the CFFI documentation.

Although the fst format and library are widely used, there is unfortunately no documentation for the libfst library. (more details on this: FST API documentation · Issue #70 · gtkwave/gtkwave · GitHub). However, to support development, pylibfst comes with some documented extensions, helper functions and examples.

• Extensions: see fst/fstext.h
• Helper functions:
  • string(..) .. Converts ffi cdata to a python string
  • get_scopes_signals2(..) .. Iterates the hierarchy and returns a list containing all scope names and a named tuple containing two dictionaries which describe the signals: The by_name dictionary maps from signal names, the by_handle from signal handles to a corresponding named tuple containing signal name, length and handle. Note that signals with different name may have the same handle, therefore by_handle may have less entries than by_name.
  • fstReaderIterBlocks(..) and fstReaderIterBlocks2(..): Wrapped versions of corresponding libfst functions. Allow the use of any normal Python function as a callback (with slight overhead).
• Examples
  • dumpfst.py .. Demonstrates the main calls required to implement an fst reader.
  • IterBlocks_callback.py .. Demonstrates the use of fstReaderIterBlocks and fstReaderIterBlocks2 using cffi-style callbacks
    • Advantage: Most efficient
    • Disadvantage: Only one callback function per program possible
  • IterBlocks_wrapped_callback.py .. Demonstrates the use of fstReaderIterBlocks and fstReaderIterBlocks2 using pythonic callbacks (helper functions above)
    • Advantage: "Normal" Python functions as callbacks (as many as you want)
    • Disadvantage: Slightly more overhead due to wrapper function

Known Problems and TODOs

• Windows and Mac untested

libfst Sources

• Location: fst
• Taken from
  • Repo: https://github.com/gtkwave/gtkwave
  • Path: gtkwave4/src/helpers/fst
  • Commit: 49a2a53caee83890dff503c15815fb53d5ccde74
• Licenses: see COPYING

How to upgrade libfst?

1. Copy most recent sources from gtkwave to directory fst
2. Check and update fst/CMakeLists.txt (see comments in file)
3. Update above section (e.g. commit hash)
4. Update pylibfst/libfstapi_build.py and pylibfst/libfstapi.cdef according to fst/fstapi.h
5. Check and update LICENSE files
6. Check and update fst/fstext.h and fst/fstext.c
7. Check and update pylibfst/helpers.py
8. Check build and install
9. Check and update examples
10. Commit: Must contain the information from section above