pylibfst 0.1.2

Handling of Fast Signal Traces (fst) in Python

Pylibfst: Handle Fast Signal Traces (fst) in Python

Pylibfst is a python cffi wrapper for the slightly extended libfst (Fast Signal Trace) from gtkwave.

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

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_signals(..) .. Iterates the hierarchy and returns a list containing all scopes names and a dictionary containing all signal names with corresponding handles.
  • get_signal_name_by_handle(..): Returns the first matching signal name from the given signals dictionary for the given handle.
  • 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

• TODO: Automated tests
• 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 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