Surfer

A waveform viewer with a focus on a snappy usable interface, and extensibility.

Documentation

There are automatically generated source documentation and an extremely early version of user documentation.

Development Discussion

Contributions are more than welcome! The easiest way is to just create an issue to discuss a change, or just make merge request with your changes directly. If you want more in-depth discussion we have bi-weekly meetings to coordinate development, see meeting notes for more details. You can also hop in our matrix channel for asynchronous discussions.

Installation

If you just want to try things out, you can try surfer right in the web-browser at https://app.surfer-project.org/. However, performance is a bit worse than native, and some features are missing so for day-to-day use it is recommended to install the native version.

The primary way to install surfer to build it from source which should work on Linux, Mac and Windows. For convenience we also provide pre-built Linux and Windows binaries.

If you want to include the AccessKit integration from eframe, add --features accesskit at the end of any cargo build or cargo install command. This is enabled by default for the pre-built binaries.

See Documentation for further instructions.

WSL support

It is possible to run Surfer in WSL (Windows Subsystem for Linux). However, there are several issues reported that most likely are caused by the gui framework used (as in, Surfer cannot really affect it). These are the suggested solutions if it does not work for you:

1. There is a script, surfer.sh in the repository, that can be used to start the Windows version from WSL, avoiding the second caveat mentioned below. Read the instructions in the script. This is the preferred way as the Windows version is faster.
2. Start the Surfer server surver, see below, in WSL and open the Windows version using the URL provided from running the previous command.
3. Start Surfer with the environment variable WAYLAND_DISPLAY cleared. For example, WAYLAND_DISPLAY= surfer.
4. Compile Surfer with a change in Cargo.toml as below (replace the line defining eframe version, using the current version if the line below has an older version). Installing libgtk-3-dev and/or zenity may be required if errors remain (although most likely it is a dependency of that package that is really required).

  eframe = { version="0.31.1",  features = ["glow", "x11", "default_fonts"], default-features = false}

5. Install the VS Code extension. This will allow you to just write code filename.vcd and start the Windows version of VS Code with the WASM-version of Surfer (if it opens the VCD as text, make sure that you trust the containing folder)

Configuration

Many aspects of Surfer can be configured. To learn more about configuration, have a look at our wiki.

Server Mode (Surver)

It is possible to run Surfer in client-server mode, where the server, surver is started on one computer with one or more waveform files and the waveform viewer is opened on another computer. This avoids having to copy the waveform files. To do this, run

surver waveform.vcd/fst/ghw

and follow the instructions.

It is also possible to start Surfer in server mode, although there are plans to drop this at some stage and only support surver

surfer server --file waveform.vcd/fst/ghw

Development Information

Contributions to Surfer are very welcome! See the list of issues if you do not have any suggestions on your own. Some basic development information is available.

Integration

Surfer is designed to be easy to integrate in other projects, especially web applications. The easiest way to do so is to embed the viewer as an <iframe>, either the publicly hosted app.surfer-project.org or a local copy.

A pre-compiled web-assembly build can be downloaded from https://gitlab.com/surfer-project/surfer/-/jobs/artifacts/main/download?job=pages_build

To control the embedded waveform viewer, use the postMessage function on the iframe. Information about the API for this can be found in surfer/assets/integration.js. Note that these functions can only be run after Surfer has been loaded. To ensure this, modify the HTML to replace /*SURFER_SETUP_HOOKS*/ with JavaScript which notifies your application that it has loaded, for example, the VSCode plugin does this using the following snippet

const load_notifier = `
    (function() {
        const vscode = acquireVsCodeApi();

        vscode.postMessage({
            command: 'loaded',
        })
    }())`
html = html.replaceAll("/*SURFER_SETUP_HOOKS*/", `${load_notifier}`)

It is also possible to embed surfer without an iframe. An example of this can be found in https://gitlab.com/surfer-project/orconf2024#. However, note that the API for messages is unstable.

Project Status

Surfer is in a usable state. In fact, if you are able to take advantage of the extensibility such as with the Spade integration, you may even prefer it to the alternatives.

As an indication of the status of the project, here is an incomplete list of supported and planned features

• Basic rendering of waves
• Snappy zooming, panning and general interaction
• Waveform file format support
  • VCD loading
  • FST loading
  • GHW loading
• Memory transaction file format support
  • FTR loading
• Fuzzy completion based command line interface
• Bit-vector translation
  • Raw bits
  • Hexadecimal values
  • Unsigned values
  • Spade values
  • Signed values
  • Octal values
  • VHDL nine-valued std_ulogic support
  • ASCII
  • Fixed-point based on bit-index (fixed_pkg)
  • Floating-point
    • IEEE 754 binary128 (quad), use feature f128, using f128 (requires gcc)
    • IEEE 754 binary64 (double)
    • IEEE 754 binary32 (single)
    • IEEE 754 binary16 (half), using half
    • bfloat16, using half
    • 8-bit E5M2
    • 8-bit E4M3
    • Based on bit-inded (float_pkg)
  • Posit, using softposit
    • 32-bit, two exponent bits
    • 16-bit, one exponent bit
    • 8-bit, no exponent bit
    • Quire for 32-bit, two exponent bits
    • Quire for 16-bit, one exponent bit
    • Quire for 8-bit, no exponent bit
  • Instruction decoding using instruction-decoder
    • RV32
    • RV64
    • MIPS
    • LoongArch64 (LA64)
    • Arm
  • Compressed integers
    • LEB128 (also for other bitwidths than 128)
  • Number of ones
  • Leading/trailing zeros/ones
  • Identical MSBs
  • Custom translation via Python API
  • Custom translation via WASM API
• Dividers
• Wave file reloading
• Saving and loading selected waves
• Cursors for measuring time
• Mouse gesture control
• Keyboard commands
  • Configurable keyboard commands
• WAL integration
• VS Code extension
• Remote support
  • Serving wave forms from remote server
  • Multi-file support for remote server
  • Remote control of Surfer
• Scripting
  • Loading of commands on startup
  • Loading of script file/commands in running instance
  • Logging of commands (generation of log file to be executed later)
• Grouping of variables
• Computed variables, e.g., a >= 100
• Clock period time unit
• Configurable color schemes
• Analog drawing

License

Surfer is licensed under the EUPL-1.2 license.