SpinalHDL
Foreword
Why moving away from traditional HDL
VHDL/Verilog aren’t Hardware Description Languages
Event driven paradigm doesn’t make any sense for RTL
Recent revisions of VHDL and Verilog aren’t usable
VHDL records, Verilog struct are broken (SystemVerilog is good on this, if you can use it)
VHDL and Verilog are so verbose
Meta Hardware Description capabilities
Introduction
About SpinalHDL
What is SpinalHDL?
What SpinalHDL is not
The Spinal development flow
Advantages of using SpinalHDL over VHDL / Verilog
A simple example
Component
Ports
Internal logic
Projects using SpinalHDL
Repositories
Companies
Universities
Getting in touch
License
Contributing
FAQ
What is the overhead of SpinalHDL generated RTL compared to human written VHDL/Verilog?
What if SpinalHDL becomes unsupported in the future?
Does SpinalHDL keep comments in generated VHDL/verilog?
Could SpinalHDL scale up to big projects?
How SpinalHDL came to be
Why develop a new language when there is VHDL/Verilog/SystemVerilog?
How to use an unreleased version of SpinalHDL (but committed on git)?
Other learning materials
Getting Started
Install and setup
Required/Recommended tools
Linux Installation
Mac OS X Installation
Windows installation
MSYS2 verilator for simulation
MSYS2 for formal verification
OCI Container
Installing SBT in an internet-free Linux environment
Create a first SpinalHDL project
The directory structure of a project
Using Spinal on SpinalHDL code
Using Spinal from CLI with SBT
Using Spinal from VSCodium
Using Spinal from IntelliJ IDEA
Scala Guide
Basics
Types
Variables
Functions
Object
Entry point (main)
Class
Templates / Type parameterization
Coding conventions
Introduction
class vs case class
Interaction
Introduction
How SpinalHDL works behind the API
Everything is a reference
Hardware types
Names of signals in the generated RTL
Scala is for elaboration, SpinalHDL for hardware description
Scala elaboration capabilities (if, for, functional programming)
Scala guide
Introduction
Help for VHDL people
VHDL comparison
Introduction
Process
Implicit vs explicit definitions
Clock domains
Component’s internal organization
Safety
Functions and procedures
Buses and Interfaces
Signal declaration
Component instantiation
Casting
Resizing
Parameterization
Meta hardware description
VHDL equivalences
Entity and architecture
Data types
Signal
Assignments
Literals
Registers
Process blocks
Cheatsheets
Core
Lib
Symbolic
Data types
Bool
Description
Declaration
Operators
Logic
Edge detection
Comparison
Type cast
Misc
MaskedBoolean
Bits
Declaration
Operators
Logic
Comparison
Type cast
Bit extraction
Misc
MaskedLiteral
UInt/SInt
Declaration
Operators
Logic
Arithmetic
Comparison
Type cast
Bit extraction
Misc
FixPoint operations
Lower bit operations
High bit operations
fixTo function
SpinalEnum
Description
Declaration
Encoding
Example
Operators
Comparison
Types
Type cast
Bundle
Description
Declaration
Conditional signals
Operators
Comparison
Type cast
Convert Bits back to Bundle
IO Element direction
in/out
master/slave
Vec
Description
Declaration
Examples
Operators
Comparison
Type cast
Misc
Lib helper functions
UFix/SFix
Description
Declaration
Unsigned Fixed-Point
Signed Fixed-Point
Format
Examples
Assignments
Valid Assignments
From a Scala constant
Raw value
Example
Operators
Arithmetic
Comparison
Type cast
Misc
Floating
Description
IEEE-754 floating format
Recoded floating format
Declaration
IEEE-754 Number
Recoded floating-point number
Operators
Type cast
AFix
Description
Declaration
Mathematical Operations
Inequality Operations
Bitshifting
Saturation and Rounding
Assignment
Structuring
Components and hierarchy
Input / output definition
Pruned signals
Parametrized Hardware (“Generic” in VHDL, “Parameter” in Verilog)
Synthesized component names
Area
Function
RGB to gray
Valid Ready Payload bus
Clock domains
Introduction
Instantiation
Configuration
Internal clock
External clock
Signal priorities in HDL generation
Context
Clock domain crossing
Special clocking Areas
Slow Area
BootReset
ResetArea
ClockEnableArea
Instantiate VHDL and Verilog IP
Description
Defining an blackbox
Generics
Instantiating a blackbox
Clock and reset mapping
io prefix
Rename all io of a blackbox
Add RTL source
VHDL - No numeric type
Preserving names
Nameable base class
Name extraction from Scala
Area in a Component
Area in a function
Composite in a function
Composite chains
Composite in a Bundle’s function
Unnamed signal handling
Verilog expression splitting
Verilog long expression splitting
When statement condition
In last resort
Parametrization
Elaboration time parameters
Optional hardware
Semantic
Assignments
Width checking
Combinatorial loops
CombInit
When/Switch/Mux
When
WhenBuilder
Switch
Example
Additional options
Local declaration
Mux
Bitwise selection
Example
Rules
Concurrency
Last valid assignment wins
Signal and register interactions with Scala (OOP reference + Functions)
Sequential logic
Registers
Instantiation
Reset value
Initialization value for simulation purposes
Register vectors
Transforming a wire into a register
RAM/ROM Memory
Synchronous enable quirk
Read-under-write policy
Mixed-width ram
Automatic blackboxing
Blackboxing policy
Standard memory blackboxes
Design errors
Assignment overlap
Introduction
Example
Clock crossing violation
Introduction
Example
crossClockDomain tag
setSynchronousWith
BufferCC
Combinatorial loop
Introduction
Example
False-positives
Hierarchy violation
Introduction
Example
IO bundle
Introduction
Example
Latch detected
Introduction
Example
Due to mux
No driver on
Introduction
Example
NullPointerException
Introduction
Example
Issue explanation
Out of Range Constant
Introduction
Example
Specifying exceptions
Register defined as component input
Introduction
Example
Scope violation
Introduction
Example
Spinal can’t clone class
Introduction
Example 1
Example 2
Unassigned register
Introduction
Example
Register with only init
Unreachable is statement
Introduction
Example
Width mismatch
Introduction
Assignment example
Operator example
Other language features
Utils
General
Cat
Cloning hardware datatypes
Passing a datatype as construction parameter
The old way
The safe way
Frequency and time
Binary prefix
Stub
Assertions
Report
ScopeProperty
Analog and inout
Introduction
Analog
inout
InOutWrapper
Manually driving Analog bundles
VHDL and Verilog generation
Generate VHDL and Verilog from a SpinalHDL Component
Parametrization from Scala
Parametrization from shell
Generated VHDL and Verilog
Organization
Combinational logic
Sequential logic
VHDL and Verilog attributes
Libraries
Utils
State less utilities
State full utilities
Counter
Timeout
ResetCtrl
Special utilities
Stream
Specification
Semantics
Functions
Utils
StreamFifo
StreamFifoCC
StreamCCByToggle
StreamWidthAdapter
StreamArbiter
StreamJoin
StreamFork
StreamMux
StreamDemux
StreamDispatcherSequencial
StreamTransactionExtender
Simulation support
Flow
Specification
Functions
Code example
Simulation Support
Fragment
Specification
Functions
State machine
Introduction
StateMachine
Entry point
Transitions
State encoding
States
StateDelay
StateFsm
StateParallelFsm
Notes about the entry state
Notes about using state value
VexRiscv (RV32IM CPU)
Bus Slave Factory
Introduction
Functionality
Fiber framework
Simple dummy example
Handle[T]
soon(handle)
BinarySystem
Specification
String to Int/Long/BigInt
Int/Long/BigInt to String
Int/Long/BigInt to Binary-List
Binary-List to Int/Long/BigInt
BigInt enricher
RegIf
Automatic allocation
28 Access Types
Automatic documentation generation
Special Access Usage
Byte Mask
Typical Example
Interrupt Factory
IP level interrupt Factory
SYS level interrupt merge
Spinal Factory
Example
DefaultReadValue
Developers Area
Bus
AHB-Lite3
Configuration and instantiation
Variations
Apb3
Configuration and instantiation
Functions and operators
Axi4
Configuration and instantiation
Variations
Functions and operators
AvalonMM
Configuration and instantiation
Tilelink
Configuration and instantiation
tilelink.fabric.Node
Example Toplevel
Example GpioFiber
Example RamFiber
Example CpuFiber
Example WidthAdapter
Com
SPI XDR
Configuration
Software Driver
UART
Bus definition
UartCtrl
USB device
Architecture
Registers
Descriptors
Usage
USB OHCI
Usage
IO
ReadableOpenDrain
TriState
TriState
TriStateArray
Graphics
Colors
RGB
VGA
VGA bus
VGA timings
VGA controller
EDA
QSysify
Example
tags
Adding new interface support
QuartusFlow
For a single rtl file
For an existing project
Pipeline
Introduction
Simple example
Payload
Node
Links
DirectLink
StageLink
S2mLink
CtrlLink
Other Links
Your custom Link
Builders
StagePipeline
StageCtrlPipeline
Composability
Retiming / Variable length
Simple CPU example
Misc
Plic Mapper
PlicMapper.apply
PlicMapping.sifive
PlicMapping.light
Plugin
Introduction
Execution order
Simple example
Interlocking / Ordering
Simulation
SBT setup for simulation
Backend-dependent installation instructions
Setup and installation of GHDL
Setup and installation of Icarus Verilog
VCS Simulation Configuration
Setup and installation of Verilator
Boot a simulation
Introduction
Configuration
Running multiple tests on the same hardware
Throw Success or Failure of the simulation from a thread
Capturing wave for a given window before failure
Accessing signals of the simulation
Read and write signals
Accessing signals inside the component’s hierarchy
Load and Store of Memory in Simulation
Clock domains
Stimulus API
Wait API
Callback API
Default ClockDomain
New ClockDomain
Thread-full API
Fork and join simulation threads
Sleep and waitUntil
Thread-less API
Sensitive API
Simulator specific details
How SpinalHDL simulates the hardware with Verilator backend
How SpinalHDL simulates the hardware with GHDL/Icarus Verilog backend
How SpinalHDL simulates the hardware with Synopsys VCS backend
How SpinalHDL simulates the hardware with Xilinx XSim backend
Performance
Simulation engine
Examples
Asynchronous adder
Dual clock fifo
Single clock fifo
Synchronous adder
Uart decoder
Uart encoder
Formal verification
General
Formal backend
Installing requirements
Example
External assertions
Internal assertions
External stimulus
More assertions / past
Assuming memory content
Utilities and primitives
Assertions / clock / reset
Specifying the initial value of a signal
Specifying a initial assumption
Memory content (Mem)
Specifying assertion in the reset scope
Formal primitives
Limitations
Naming polices
For Component
For interfaces implement IMasterSlave
Examples
Simple ones
APB3 definition
Introduction
Specification
Implementation
Usage
Carry adder
Color summing
Counter with clear
PLL BlackBox and reset controller
The PLL BlackBox definition
TopLevel definition
RGB to gray
Sinus ROM
Intermediates ones
Fractal calculator
Introduction
Specification
Elaboration parameters (Generics)
Bundle definition
Component implementation
UART
Specification
Data structures
Implementation
Simple usage
Example with test bench
Bonus: Having fun with Stream
VGA
Introduction
Data structures
VGA Controller
Advanced ones
JTAG TAP
Introduction
JTAG bus
JTAG state machine
JTAG TAP
Jtag instructions
User friendly wrapper
Usage demonstration
Memory mapped UART
Introduction
Specification
Implementation
Pinesec
Slots
Introduction
Timer
Introduction
Timer
Bridging function
Getting started
Legacy
RiscV
Features
Base FPGA project
How to generate the CPU VHDL
How to debug
Todo
pinsec
Introduction
Introduction
Board support
Hardware
Introduction
RISCV
AXI4
APB3
Generate the RTL
SoC toplevel (Pinsec)
Introduction
Defining all IO
Clock and resets
Main components
Peripherals
Bus interconnects
Misc
Software
RISCV tool-chain
OpenOCD/GDB/Eclipse configuration
Miscellaneous
Frequent Errors
Exception in thread “main” java.lang.NullPointerException
Hierarchy violation
Signal X can’t be assigned by Y
Input signal X can’t be assigned by Y
Output signal X can’t be assigned by Y
The
spinal.core
components
Clock domains definitions
Clock domain syntax
Clock configuration
External clock
Cross Clock Domain
Assignments
When / Switch
Component/Hierarchy
Area
Function
RGB to gray
Valid Ready Payload bus
VHDL generation
Instantiate VHDL and Verilog IP
Utils
Element
Range
Developers area
Bus Slave Factory Implementation
Introduction
Specification
Implementation
BusSlaveFactory
BusSlaveFactoryDelayed
AvalonMMSlaveFactory
Conclusion
How to use a local SpinalHDL clone as project dependency
Create local git clone of SpinalHDL
Configure buildsystem
Configure sbt (update
build.sbt
)
Configure mill (update
build.sc
)
Done
How to HACK this documentation
Title convention
Wavedrom integration
New section
example
Build through Mill
Compile the library
Run all test suites
Run a specified test suite
Run a specified App
Publish locally
SpinalHDL internal datamodel
Introduction
General structure
Exploring the datamodel
Compilation Phases
Modifying a netlist as a user without plugins
User space netlist analysis
Enumerating every ClockDomain in use
Types
Introduction
Bool
Declaration
Operators
The BitVector family - (
Bits
,
UInt
,
SInt
)
Declaration syntax
Operators
Masked comparison
Bits
UInt, SInt
Bool, Bits, UInt, SInt
Vec
Bundle
Simple example (RGB/VGA)
Interface example (APB)
Enum
Data (Bool, Bits, UInt, SInt, Enum, Bundle, Vec)
Literals as signal declaration
Continuous Assignment Literals as signal declaration
SpinalHDL
Index
Edit on GitHub
Index
Other Versions
v: master
Languages
en
zh_CN
Tags
v1.3.1
v1.3.8
v1.5.0
v1.6.0
v1.8.0
Branches
dev
master
Downloads
HTML
SingleHTML
PDF