Spinal user guide | SpinalHDL documentation

Document purpose and structure

This site presents the Spinal language and how to use it on concrete examples. This documentation also explains how the language is implemented. The documentation is split into different sections:

What is Spinal ?

Spinal is a high-level hardware description language. It can be used as an alternative to VHDL or Verilog and has several advantages over those.

Note: Spinal is fully interoperable with standard VHDL-based EDA tools (simulators and synthetizers) as the output generated by the toolchain is VHDL.

It also enables mixed designs where Spinal components interoperate with VHDL or Verilog IPs.

Advantages of using Spinal over VHDL / Verilog

As Spinal is based on a high-level language, it provides several advantages to improve your hardware coding:

No more endless wiring - Create and connect complex buses like AXI in one single line.
Evolving capabilities - Create your own buses definition and abstraction layer.
Reduce code size - by a high factor, especially for wiring. This enables you to have a better overview of your code base, increase your productivity and create fewer headaches.
Free and user friendly IDE - Thanks to scala world for auto-completion, error highlight, navigation shortcut and many others.
Detailed information about your design - Directly extract information from your digital design and generate reports that contain information about latency and addresses.
Powerful and easy type conversions - Bidirectional translation between any data type and bits. Useful to load a complex data structure from a CPU interface.
Loop detection - Tools check for you that there is no combinatorial loop / latch.
Clock domains safety - The tools inform you that there is no user unintentional cross clock domain.
Generic design - There are no restrictions to the genericity of your hardware description by using Scala constructs.

What are the differences between Chisel VS Spinal ?

It is a very good question ! Why develop a new language when there Chisel has been released 3 years ago ?

Chisel is the project at the origin of Spinal and Chisel it represents a big step forward compared to common HDL. However, it has several drawbacks for large designs that mix multiple clock domain and external IP (black-boxes). In fact, Chisel show some serious conception issue :

Multiple clock support is awkward:

Working into a single block with multiple clock is difficult, you can’t define “ClockingArea”, only creating a module allow it.
Reset wire is not really integrated into the clock domain notion, sub module loose reset of parent, which is really annoying.
No support of falling edge clock or active low reset.
No clock enable support.
Chisel makes the assumption that every clock wire come from the top level inputs, you don’t have access to clock signal.

Black box support is far from perfect:

Generics/Parameters are not really supported.
Specifying clock inputs for a black box is not supported. You have to use a workaround and you don’t have any control on clock signal name that change against your will.

Syntax could be better:

Not pretty literal value syntax, No implicit conversion between Scala and Chisel types.
Not pretty input/output definition.
Assignment operator is only checked when you generate the code, the IDE can’t check it for you. Bundle assignment operator is weak typed.
Switch statement doesn’t have default case.
No “Area” notion to give a better structure to the user code.

Various issue :

You can’t define function without argument into Bundles.
There is no notion of “Area”.
Using when/otherwise is not strict in all case. This allows you to generate an asynchronous signal that is not assigned in every case.
You can’t really write a given range of bit into a bit vector.
The library that is integrated into Chisel and that provides you some utils and useful bus definition is a good intention, but could be so better and more complete

For a lot of the issues mentioned here, an issue/pull request was open on github, without effect. In addition, if we consider the age (3 years at the time of writing) of Chisel, this is a very serious issue and it’s why SpinalHDL was created.

Getting started

Want to try it for yourself? Then jump to the getting started section and have fun!

Tags: