SUS Language

SUS is a new RTL Hardware Design Language, similar to Verilog or VHDL, that focuses on simplifying the development of high-performance computing FPGA accelerators, without sacrificing any design freedom at the altar of abstraction.

Installation

Installation is done through Rust's package manager cargo (cargo installation info). ¹

cargo install sus_compiler

Supported Editors

• VSCode: SUS Hardware Design Language (source: (sus-lsp))
• VIM: papeg/sus.vim. It supports vim and neovim and brings in syntax highlighting and lsp support. For vim it depends on prabirshrestha/vim-lsp. Install with your favorite plugin manager, like vim-plug:

call plug#begin()
  if !has('nvim')
      Plug 'prabirshrestha/vim-lsp'
  endif
  Plug 'papeg/sus.vim'
call plug#end()

Useful Libraries

Some libraries we maintain here at PC2 might be of use to you:

• sus-float: Xilinx floating point IP wrappers.
• sus-xrt: AXI masters & slaves for working with XRT.
• sus-tapasco: AXI interfaces for Tapasco.
• aie_reflasher: Dynamic Reflashing of Versal AI Engines from the FPGA fabric.

Learning SUS

Use SUS with:

sus_compiler myFile.sus -o outFile.sv --top MyTopModule

To get started with learning SUS, have a look at this (mildly outdated) talk. In 40 minutes it goes over most language features through examples. For the changes, please look at the Changelog.

A full language reference can be found here:

For an example project to tinker with, see VonTum/mandelbrotFPGA.

Core philosophy

SUS is meant to be a direct competitor to Synthesizeable Verilog and VHDL. Its main goal is to be an intuitive and thin syntax for building netlists, such that traditional synthesis tools can still be used to analyze the resulting hardware. SUS shall impose no paradigm on the hardware designer, such as requiring specific communication protocols or iteration constructs. In other words, SUS is not there to abstract away complexity, but rather to make the inherent complexity of hardware design more manageable.

The one restriction SUS does impose over Verilog and VHDL is that it requires the hardware to be synchronous over one or more clocks. Asynchronous hardware is therefore unrepresentable making SUS less suitable for ASIC development.

There are three main features that set SUS apart from the rest:

• Generative Variables and Types can be freely combined. Any "Dependent Types" headaches that are caused by this are sidestepped by doing the main type checking after instantiation.
• Easy Pipelining through an orthogonal language construct called "Latency Counting". 'Orthogonal' means that adding pipeline registers does not interfere with other language features such as generative or conditional code.
• Separation of pipelines with interfaces. This keeps the user from accidentally crossing signals that have no logical relationship. At this level Clock Domain Crossings are implemented.

Finally, an important consideration of SUS is the user interface. SUS comes with a VSCode IDE plugin that allows the copiler to be used fully in-IDE. Compiling, typechecking and instantiation is done as the user writes code, leading to a very tight development feedback loop.

What SUS gives you

• A direct 1-to-1 mapping from code to netlist
• Hardware domain separation with explicit crossing primitives
• A built-in syntax for pipelining that does not impose structural constraints
• In-IDE compilation errors & warnings
• Metaprogramming for hardware generation
• Type safety with Bounded Integers
• Syntactic sugar for common constructs like valid signals, resets and submodule communication

Planned

• Multi-Clock modules
• Formal Verification Integration
• Moving some² timing constraints to the source file

Example of some SUS code in the SUS VSCode Language Server.

Comparison to other HDLs

There's a few categories of HDLs as I see it nowadays. I shall visit them in turn:

Footnotes

1. By default, the standard library is stored in the $XDG_DATA_HOME folder, but it can be overwritten with INSTALL_SUS_HOME=/path/to/sus_home/ cargo install sus_compiler. ↩

2. Some timing constraints affect the cycle-by-cycle functioning of the design, such as the relative speeds of synchronous clocks and False/Multi-Cycle Path constraints. Because they affect the cycle-wise behaviour of the design, they should be provided as part of the language and incorporated in simulation. Of course, timing constraints like real clock speeds, edge patterns and external component timings still rightfully belong in the Timing Constraints file. It should not be possible to express SUS code that behaves differently between Simulation and Synthesis. ↩

This is the beginning of the README. Read the rest at the original. Read the full README ↗