0% found this document useful (0 votes)

144 views258 pages

FPGA Design with Migen & LiteX

Uploaded by

Stefan

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

144 views258 pages

FPGA Design with Migen & LiteX

Uploaded by

Stefan

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 258

V1.

Introduction to digital design with Migen and Litex

Franck Jullien
@fjullien06
https://github.com/fjullien
What are we going to talk about ?

▶
Description of FPGAs
▶
Digital design challenges
▶
Migen: introduction and workshops
▶
LiteX: introduction and workshops
▶
LiteX: advanced topics

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 2

Digital Design – Base elements

Hardware consist of a few simple building blocks

1. Combinatorial
▶
“Instant” state changes, e.g.:

Classical gates (especially NAND & NOR)

Multiplexer (MUX)

A Scientist’s Guide to FPGAs – Alexander Ruede – iCSC 2019

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 3

Digital Design – Truth table

A B C E
0 0 0 0
0 0 1 0
0 1 0 0
0 1 1 1
1 0 0 0
1 0 1 1
1 1 0 0
1 1 1 1

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 4

Digital Design – 8 bits adder

Design of an 8 bits adder

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 5

Digital Design – 8 bits counter

Design of an 8 bits counter

A
OUTPUT
Adder
B

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 6

Digital Design – 8 bits counter

Design of an 8 bits counter

A = Increment = 1
OUTPUT
Adder
B

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 7

Digital Design – 8 bits counter

Design of an 8 bits counter

A = Increment = 1
OUTPUT
Adder
B

We have a infinite loop (combinatorial loop) !!

We need a way to save the previous result and slow down the
counter.

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 8

Digital Design – 8 bits counter

Design of an 8 bits counter

A = Increment = 1
OUTPUT
Adder
B

Q D

CLK

We need a way to save the previous result (a register) and

slow down the counter (a clock).

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 9

Digital Design – Base elements

Hardware consist of a few simple building blocks

1. Combinatorial
▶
“Instant” state changes, e.g.:

Classical gates (especially NAND & NOR)

Multiplexer (MUX)

2. Synchronous
▶
“Clocked” state changes, e.g.:

Flip Flop (e.g. D-FF, register)

A Scientist’s Guide to FPGAs – Alexander Ruede – iCSC 2019

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 10

Digital Design – LUT

ROM
A0 DATA

A2 (LUT)

A B C E ADDR DATA
0 0 0 0 000 0
0 0 1 0 001 0
0 1 0 0 = 010 0
0 1 1 1 011 1
1 0 0 0 100 0
1 0 1 1 101 1
1 1 0 0 110 0
1 1 1 1 111 1

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 11

Anatomy of FPGAs - CLB

FPGA are made of Configurable Logic Block (CLB)

(Also “logic cell” or “logic element”)

▶
LUT configuration is flexible
▶
D-type flip-flops configuration is flexible
▶
Flip-flops can take input from outside the
CLB or from the LUT

Simplified example CLB with one

4-input LUT and one flip-flop

A Scientist’s Guide to FPGAs – Alexander Ruede – iCSC 2019

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 12

Anatomy of FPGAs - SLICE example (Xilinx)

Flip-flops
LUT

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0

ug474_7series_CLB.pdf 13
Anatomy of FPGAs - Matrix

▶
CLB: Configurable Logic Block
▶
PIC: Programmable Interconnect
▶
IOB: Input-Output Block [1]
▶
Clock Management [2]
▶
Hardened Cores

A Scientist’s Guide to FPGAs – Alexander Ruede – iCSC 2019

▶
Programming a FPGA is configuring its interconnection matrix and basic blocks (IOB, CLB,...)

[1] ug471_7series_SelectIO.pdf
[2] ug472_7series_Clocking.pdf

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 14

Anatomy of FPGAs - Hardened cores

Hardened Cores (Also called “IP cores”)

Specialized tasks (e.g. multiplication) take up a lot of logic cells

Hardened cores in silicon for more effective use of resources

Typical cores found in modern FPGAs:

▶
Memory (Block RAM [1])
▶
DSP blocks
▶
Clocking (Programmable PLL)
▶
Communication interfaces (e.g. PCIe)
▶
Serializer/Deserializer (SerDes) Exemplary DSP block with multiplier,
accumulator and pipeline stages
▶
CPU
A Scientist’s Guide to FPGAs – Alexander Ruede – iCSC 2019

[1] ug473_7Series_Memory_Resources.pdf
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 15
Anatomy of FPGAs - Classical Design Flow

▶
Create an FPGA design is:
●
Describing the interface between the FPGA and the electronic board
→ Configuration of IOB

●
Describing the modules (Adder, Multiplier, CPU, FFT,etc…) and how to
connect them together.
●
Transforming this description (RTL) in a machine description called
bitstream (LUT’s configuration, Interconnection Matrix’s configuration,
etc…)
→ Configuration of LUTs, PIC

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 16

Anatomy of FPGAs - Classical Design Flow

▶
Functional description
▶
Interface description
▶
Behavioral Simulation

▶
Synthesis tool converts hardware
description into netlist (building
blocks and interconnect)
▶
Can perform logic optimization
Find best location of primitives for
all elements in netlist

Generating bitstream for direct

FPGA programming or for
external memory configuration

A Scientist’s Guide to FPGAs – Alexander Ruede – iCSC 2019

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 17

Anatomy of FPGAs - Classical Design Flow

synthesis

P&R

Bitstream

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 18

Anatomy of FPGAs - What we’ve learnt

▶
FPGA are made of configurable logic blocks and dedicated
blocks surrounded by I/Os, interconnected by a switch
matrix
▶
Programming the FPGA is basically writing values into LUTs
and configuring the interconnection matrix
▶
The hardware description is translated into a netlist by the
synthesizer
▶
The P&R finds the best locations for the primitives and
interconnects the components

▶
Software / CPU specify a sequence of instructions
▶
HDL / FGPA describe structure and behavior of digital components

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 19

Anatomy of FPGAs - FPGA vs CPLD

FPGA CPLD
▶
Configuration is volatile. Bitstream is ▶
Bitstream is stored in flash memory.
stored in an external memory (SPI →Instant ON
flash) and loaded.
→Delay of several milliseconds at ▶
Very small amount of logic resources
power ON.
▶
No on-die hard IPs available (RAM, PLL,…)
▶
Variety of on-die dedicated
hardware such as Block RAM, DSP ▶
Only one voltage rail
blocks, PLL, DCMs, Memory
Controllers, Multi-Gigabit ▶
Available in TQFP package
Transceivers
▶
PCB cost much higher (BGA,
multiple voltage rails, external SPI
flash)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 20

Agenda

▶
Description of FPGAs
▶
Digital design challenges
▶
Migen: introduction and workshops
▶
LiteX: introduction and workshops
▶
LiteX: advanced topics

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 21

Flip-Flops - Description

▶
There are a few different types of flip-flops (JK, T, D) but the one that is used most frequently is
the D Flip-Flop.
▶
Sequential logic operates on the transitions of a clock. When a Flip-Flop sees a rising edge of the
clock, it registers (copy and hold) the data from the Input D to the Output Q.
▶
Flip-flops are the main components in an FPGA that are used to keep the state inside of the chip.

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 22

Flip-Flops – Timing considerations

▶
Because of the construction of a flip-flop [1], the input must be held steady in a period around the
rising edge of the clock.
▶
Setup time is the minimum amount of time the data input should be held steady before the clock
event, so that the data is reliably sampled by the clock.
▶
Hold time is the minimum amount of time the data input should be held steady after the clock
event, so that the data is reliably sampled by the clock.

[1] https://www.edn.com/understanding-the-basics-of-setup-and-hold-time/
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 23
Flip-Flops – Metastability

▶
If setup and hold time are not respected, flip-flops are subject to a problem called
metastability
▶
The result is that the output may behave unpredictably, taking many times longer than
normal to settle to one state or the other, or even oscillating several times before settling.

https://youtu.be/5PRuPVIjEcs
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 24
Three main reasons for metastability problem (1/3)
▶
An external signal (user input) is read inside the FPGA:

OUTSIDE FPGA

D Q

CLK

D doesn’t change during the

aperture.

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 25

Three main reasons for metastability problem (1/3)
▶
An external signal (user input) is read inside the FPGA:

OUTSIDE FPGA

D Q

CLK

D changes during the aperture→Metastability

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 26

Three main reasons for metastability problem (2/3)

▶
Too much logic (delay) between flip-flops (setup violation):

In this case, the delay

induced by the logic is short
ts th ts th enough

CLK

D-FF1

Q-FF1

D-FF2

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 27

Three main reasons for metastability problem (2/3)

▶
Too much logic (delay) between flip-flops (setup violation):

In this case, the delay

induced by the logic is too
ts th ts th long

CLK

D-FF1

Q-FF1

Setup violation
D-FF2

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 28

Three main reasons for metastability problem (3/3)

▶
Multiple clock domains

CLKA

IN
ts th

CLKB

Setup violation

Because clk_A and clk_B are asynchronous, A can change anytime with regards to clk_B rising edge.
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 29
Who is responsible ?

▶
You are responsible for this. Designers must prevent timing
problems:

●
External asynchronous signals must be handled properly with
synchronizers,

●
when using multiple clock domains, use proper clock domain
crossing (CDC) circuits,

●
look at static timing analysis report from your synthesis tool and
take care (at least evaluate) of every (most) warnings.

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 30

Synchronizer

▶
Use a sequence of registers in the destination clock domain
to resynchronize the signal to the new clock domain.
▶
Allows additional time for a potentially metastable signal to
resolve to a known value before the signal is used in the rest
of the design.

Must be kept close each other

https://trilobyte.com/pdf/golson_snug14.pdf
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 31
Clock Domain Crossing

▶
Used when transferring datas (busses) across clock domain
boundaries.

▶
Two methods:
●
Control based data synchronizers
●
FIFO based data synchronizers

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 32

Control based data synchronizers

▶
The enable signal is responsible to inform the receiving
domain that data is stable and ready to be captured.
Do Di
D Q
D Q
D Q D Q

En’
Do
En
D Q D Q D Q
En’

▶
Control based data synchronizer has limited bandwidth.
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 33
FIFO based data synchronizers

▶
Data is pushed into the FIFO with transmitter clock and
pulled out from FIFO with receiver clock.

wr clock domain rd clock domain

Asynchronous
FIFO
write_clock read_clock

write_data read_data

write read

write_full read_empty

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 34

Static Timing Analysis

▶
Performed by the implementation tool
▶
Needs constraints (SDC files)
▶
Verify every path and detect potential failures at every corners
▶
Gives Fmax

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 35

Static Timing Analysis

▶
Performed by the implementation tool
▶
Needs constraints (SDC files)
▶
Verify every path and detect potential failures at every corners
▶
Gives Fmax

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 36

Static Timing Analysis

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 37

Static Timing Analysis

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 38

Agenda

▶
Description of FPGAs
▶
Digital design challenges
▶
Migen: introduction and workshops
▶
LiteX: introduction and workshops
▶
LiteX: advanced topics

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 39

Agenda

▶
Migen: introduction and workshops
●
Concepts, Modules and signals
●
Blinker example
●
Attributes of Module()
●
Example of verilog output
●
Operators (If/Else and FSM)
●
Minimum project requirement (Migen/LiteX)
●
Workshop 1/2
●
Records
●
Simulation
●
Workshop 2/2
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 40
What is Migen

▶
An alternative HDL based on Python

▶
FHDL is a Python DSL (Domain Specific Language) defined by Migen and
allow generating Verilog or instantiating Verilog/VHDL from Python code

▶
It basically uses Python to create a list of combinatorial and
synchronous assignments and generate a Verilog file from these
assignments.

▶
Migen has an integrated simulator that allows test benches to be written
in Python

https://m-labs.hk/gateware/migen

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 41

Migen – Concepts

▶
A module (as in verilog) is a block containing a functional
description (Migen code) that uses input/outputs

CLOCK

WRITE MyModule LEDS

BTN

FPGA

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 42

Migen – Concepts

▶
Migen uses Python classes
▶
The most important class is Module
▶
A module has input / output signals and parameters
▶
The direction of signals in the interface is not explicit

WRITE LEDS
MyModule
BTN

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 43

Migen – Concepts

▶
Interfaces of modules are defined by attributes
▶
All attributes with the type Signal() are considered
interfaces of the module
▶
In our case:

write leds
MyModule
btn

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 44

Migen – Concepts

▶
Every signal assignment is either:
- combinatorial (continuous assignments)
- synchronous (at the edge of the clock signal)

▶
Module() has a sync and a comb attributes (lists)

▶
Assignment are added to the chosen type using the in-
place addition operation (+=)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 45

Migen – Concepts

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 46

Migen – Signal

▶
Signal object represents a value that is expected to change
in a circuit. It does exactly what Verilog’s “wire” and “reg” and
VHDL’s “signal” do.
▶
They are assigned using the eq() method

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 47

Agenda

▶
Migen: introduction and workshops
●
Concepts, Modules ans signals
●
Blinker example
●
Attributes of Module()
●
Example of verilog output
●
Operators (If/Else and FSM)
●
Minimum project requirement (Migen/LiteX)
●
Workshop 1/2
●
Records
●
Simulation
●
Workshop 2/2
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 48
Migen – Blinker module

▶
Functional block with input and outputs
▶
Signals of the interface are attributes of the class
▶
A module has important attributes (comb, sync,…)
▶
As any other Python class, parameters can be passed to modules

WRITE LEDS
Blink
BTN

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 49

Migen – Blinker module

WRITE LEDS
Blink
BTN

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 50

Migen – Blinker module

WRITE LEDS
Blink
BTN

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 51

Migen – Blinker module

WRITE LEDS
Blink
BTN

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 52

Agenda

▶
comb → a list of combinatorial assignments
▶
sync → a list of synchronous assignments
▶
submodules → a list of modules used by this module
▶
specials → a list of Platform specific modules, Verilog
instances, memories,…

▶
clock_domains → clock domains used by this module

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 54

Migen – Attributes of Modules: comb

▶
comb → a list of combinatorial assignments

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 55

Migen – Attributes of Modules: sync

▶
sync → a list of synchronous assignments

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 56

Migen – Attributes of Modules: sync

▶
sync → a list of synchronous assignments

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 57

Migen – Attributes of Modules: sync

▶
sync → a list of synchronous assignments
test_b == 0, set a to 0

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 58

Migen – Attributes of Modules: sync

▶
sync → a list of synchronous assignments
test_b == 0, set a to 0

a is now 0, a == 0 is true
so set out to 1

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 59

Migen – Attributes of Modules: sync

▶
sync → a list of synchronous assignments
test_b == 0, set a to 0

a is now 0, a == 0 is true
so set out to 1

Finally, out is now equal to 1

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 60

Migen – Attributes of Modules: submodules

▶
submodules → a list of modules used by this module

We have access to
the interface of m2

▶
Can be named (self.submodules.m2 = m2)
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 61
Migen – Attributes of Modules: special

▶
special → a list of Platform specific modules, Verilog
instances, memories,...

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 62

Agenda

WRITE LEDS
M1
BTN

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 64

Migen – Combinatorial example

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 65

Migen – Synchronous example

WRITE LEDS
M1
BTN

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 66

Migen – Synchronous example

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 67

Migen – Synchronous example

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 68

Agenda

▶
Migen doesn’t use Python’s if/else.
▶
If is implemented as a Class. Else and Elif are methods.
▶
Assignments under If are separated by comas
▶
Can be used in comb or sync blocks

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 70

Migen – FSM

▶
Finite State Machine is a way to implement sequential
execution
▶
FSM() is a module, it needs to be added to submodules
▶
States are defined with fsm.act
▶
Assignments are separated by a coma

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 71

Migen – FSM

▶
NextState() is used to move to another state

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 72

Migen – FSM

▶
NextValue(a, value) is used make a synchronous
assignment. It is equivalent to self.sync += a.eq(value)
▶
The signal keep it’s value outside the state it has been
assigned

a will be equal to 5
on the next clock
cycle

Coming from “WAIT”,

a is equal to 5

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 73

This is equivalent to
this (pseudo code)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 74

Migen – FSM

▶
Direct assignment .eq() is used make a combinatorial
assignment. It is equivalent to self.comb += a.eq(value)

a is equal to 5 as
long as we are in this
state

▶
a is equal to 5 when in “START” state and 0 in other states

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 75

Migen – FSM

This is equivalent to
this (pseudo code)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 76

Migen - Libraries

Migen has a library (genlib) with most of the base elements

required to digital logic:
●
Records (group signals together with direction),
●
FSM (Finite State Machine),
●
Clock Domain Crossing,
●
Memory,
●
Instance (reuse Verilog/VHDL),
●
FIFO,
●
...

Most of the useful functions are grouped in the Migen

Cheatsheet
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 77
Agenda

▶
Declare IO resources
▶
Choose a platform and gives it the IO list
▶
Request platform resources (IOs)
▶
Assign requested resources to Module’s interface
▶
Add timing constraints
▶
Let the platform build system do its job (build the
bitstream)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 79

Migen/LiteX – IO resources

▶
Declare IO resources (as a python list of tuples)

▶
Look all available options in the documentation

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 80

Migen/LiteX – IO resources

▶
Declare IO resources (as a python list of tuples)

▶
Look all available options in the documentation
No documentation (for now)
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 81
Migen/LiteX – Platform

▶
Choose a platform and pass it the IO list

▶
Litex provides infrastructure for:
●
altera,
●
efinix,
●
gowin,
●
lattice,
●
microsemi,
●
quicklogic,
●
xilinx
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 82
Migen/LiteX – Request resources

▶
Request platform resources (IOs)

▶
Returns Signal() from platform resources

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 83

Migen/LiteX – Minimum project code

▶
Assign requested resources to Module’s interface

Once requested, signals

can be used in the
design

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 84

Migen/LiteX – Minimum project code

▶
Assign requested resources to Module’s interface
cd_sys is mandatory. At
some point it has to be
created

The clock signal has to

be assigned

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 85

Migen/LiteX – Minimum project code

▶
Assign requested resources to Module’s interface

Add and use a module

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 86

Migen/LiteX – Minimum project code

▶
Add timing constraints

This is the requested

clock signal

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 87

Migen/LiteX – Minimum project code

▶
Build the bitstream
Configured platform

Top level Module

Ask LiteX to build the

bitstream

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 88

Migen hands-on

Now, let’s practice !

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 89

Step0 – Led blinker

What you’ll see:

▶
Platform definition
▶
Resources assignment
▶
Submodules
▶
Simulation
▶
Build

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 90

Step1 – Introduction

VCC

FPGA
GND
DATA

BOARD

▶
Addressable LED ring
▶
Control over a single wire
▶
24 bits per LED

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 91

Step1 – LED protocol

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 92

Step1 – Instructions

▶
Control the first LED
▶
Send 24 “Ones” pulses (equivalent to 0xFFFFFF, white
color)

▶
Test with ./workshop_step1.py sim
▶
gtkwave sim.vcd &
▶
CTRL-R in gtkwave to update waveform after a new
simulation

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 93

Step1 – Tip

self.sync += [
if (pulse_cnt < 24) {
if (pulse_high) {
output = 1
cnt_high = cnt_high + 1
if (cnt_high == t1h) {
pulse_high = 0
cnt_high = 0
}
} else {
output = 0
cnt_low = cnt_low + 1
if (cnt_low == t1l) {
pulse_high = 1
cnt_low = 0
pulse_cnt = pulse_cnt + 1
}
}
}

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 94

Step1 – Observations

▶
Synchronous assignments take effect on the next cycle
▶
If a signal is assigned multiple time in the same clock cycle,
the last assignment is taken into account
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 95
Step2 – Instructions

▶
Simplify code from step1 using WaitTimer module from migen/genlib
▶
timer = WaitTimer(period)
●
Period is expressed in clock cycles
●
Two control signals: wait and done

▶
Compute timers period from time and frequency. Pure Python code can be
used here.

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 96

Step2 - Observations

▶
Don’t forget to add your module to submodules.
Migen won’t complain !
▶
Pure Python code can be used in Migen modules
(configuration, genericity,...)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 97

Step3 - Instructions

▶
Use Finite State Machine (FSM) to simplify your code

▶
NextState(state) selects the next state

▶
NextValue(a, b) is equivalent to self.sync += a.eq(b) when the FSM is in the given state.

▶
a.eq(b) is equivalent to self.comb += a.eq(b) when the FSM is in the given state. When
it’s not, a.eq(0)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 98

Step3 - Observations

▶
Direct assignment in FSM are combinatorial

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 99

Step4 - Instructions
▶
Design a RingSerialCtrl module
leds(12)

colors(24) do(1)
RingSerialCtrl
nb_leds

▶
leds is a 12 bits input, each bit controls a led (on/off)
▶
colors is a 24 bits input that controls the ring color
▶
nb_leds is a parameters to configure how much LED the ring has

Note:
You can access individual bits in a Signal() using Python indexes and slices:

●
led[1] is the second bit of led,
●
led[-1] is the MSB,
●
led[0:3] are the 3 lower bits of led.
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 100
Step4 - Tip

fsm.act("RST",
# wait for trst
# when done, init variables and go to LED-SHIFT
)
fsm.act("LED-SHIFT",
# init bit counter
# increment led_count counter
# shift led pattern
# check if led should be lit (assign 0 or color)
# if next led go to BIT-TEST else RST
)
fsm.act("BIT-TEST",
# if data(MSB) == 1 go to ONE_SEND
# else go to ZERO_SEND
# data = data << 1

)
fsm.act("ZERO-SEND",
# send bit zero pattern (timer)
# go to BIT-SHIFT

)
fsm.act("ONE-SEND",
# send bit one pattern (timer)
# go to BIT-SHIFT
)
fsm.act("BIT-SHIFT",
# shift color data
# check if 24 bits sent
# if yes go to LED-SHIFT
# else go to BIT-TEST
)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 101
Step4 - Observations

▶
You can access individual bits in a Signal using Python indexes
and slices:
●
led[1] is the second bit of leds,
●
led[-1] is the MSB,
●
led[0:3] are the 3 lower leds bits. Bit 3 is excluded !

Different with V*HDL where bit vectors are represented from MSB
to LSB:
●
my_vhdl_signal(11 downto 0)
●
my_verilog_signal[11:0]

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 102
Step5 - Instructions

▶
Create a new module RingControl to control RingSerialCtrl and
make LEDs spins
▶
Put both modules in a separate file named ring.py

Bonus1:
▶
Use Array([a, b, …]) to light LED following the pattern defined in
this array of values

Bonus2:
▶
Add a build time option to use simple LED spin or array mode
(using pure Python syntax)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 103
Step5 - Tips

Python statement can be used inside Modules:

if (something == True):
self.comb += out.eq(test1)
else:
self.comb += out.eq(test2)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 104
Step5 - Observation

▶
Organize your files as much as possible
▶
Use Python to configure your design

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 105
Agenda

▶
Description of FPGAs
▶
Digital design challenges
▶
Migen: introduction and workshops
●
Records
●
Simulation
▶
LiteX: introduction and workshops
▶
LiteX: advanced topics

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 106
Migen/LiteX – Records

▶
Records are structures of Signal() objects
▶
Records are described with a layout (list of tuples)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 107
Migen/LiteX – Records

▶
IO Resources can be Records (often, they are)
▶
Subsignal is used

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 108
Migen/LiteX – Records

▶
Signals of a Record are attributes of it
▶
Testing attributes can be part of the configuration

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 109
Agenda

▶
Description of FPGAs
▶
Digital design challenges
▶
Migen: introduction and workshops
●
Records
●
Simulation
▶
LiteX: introduction and workshops
▶
LiteX: advanced topics

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 110
Migen/LiteX – Simulation

Generates
Inputs
(generator)
Module Check
(DUT, Device Under Test) outputs

Generates
Inputs
(generator)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 111
Migen/LiteX – Simulation

▶
Migen has an integrated simulator
▶
Test benches (generators) execute concurrently
▶
Use yield to communicate with the simulator. There are four basic patterns:

●
Reads: state of a signal can be read using (yield signal)
●
Writes: state of a signal after next clock is set with yield signal.eq(value)
●
Clocking: simulation can be advanced one clock cycle using yield
●
Composition: control can be transferred to another function using yield from run_other()

▶
Run with run_simulation(dut, bench) where dut is the module under test and
bench are the generators functions.
▶
Can generate a VCD file containing a dump of the signals inside dut

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 112
Migen/LiteX – Simulation

Module under test

Test Bench (generator)

Simulation

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 113
Migen/LiteX – Simulation

Module under test

subroutine

Test Bench (generator)

Simulation

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 114
Migen/LiteX – Simulation

▶
Multiple generators can run in parallel
▶
Can be multiple clock domains
▶
Don’t forget yield, yield from (Migen won’t complain)
▶
Signals must not be driven concurrently

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 115
Step6 – Write a testbench for RingSerialCtrl

What you’ll learn:

▶
Use generators
▶
Write complex test benches

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 116
Step6 – Write a testbench for RingSerialCtrl

▶
Write a generator to set a random color to a random LED
▶
Write a generator to detect the timeout condition
▶
Write a generator to print which value is set on each LED

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 117
Agenda

▶
Description of FPGAs
▶
Digital design basics
▶
Migen: introduction and workshops
▶
LiteX: introduction and workshops
●
Presentation of SoCs and LiteX
●
Examples of peripherals integration
●
How to build a SoC
●
Software in LiteX
●
LiteX tools
●
Workshop
▶
Litex: advanced topics
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 118
System On Chip - SoC

SRAM

Instruction ROM
cache Crossbar

CPU
External
Data Memory Interface
cache

Peripherals

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 119
System On Chip - SoC

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 120
System On Chip - SoC

▶
Bus adaptation (width, type) 0x10000000
▶
Arbitration

32-bit slave
SRAM
▶
Address mapping
0x10080000

SoC interconnection bus

32-bit slave
32-bit master
Instruction ROM
cache

0x40000000
CPU

64-bit slave
External

32-bit master
Memory Interface
Data
cache
0x20000000

32-bit slave
PERIPH1

0x20001000
PERIPH2

32-bit master
DMA

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 121
What is LiteX

11 Open sources IP 104 Supported boards

litepcie, litedram, liteiclink, - Platform definition
liteeth, litesdcard, litevideo,
- Target example
litescope, litesata, litejesd204b

litehyperbus, litespi
supports

supports
Uses 16 Softcores litex-boards
Extends supports
Migen LiteX serv, mor1kx,
vexriscv,picorv32...
platforms
targets
provides

build tools soc

gpio
i2s
altera server cores
spi
anlogic term interconnect
pwm
efinix client integration
led
gowin ... software
tmds
lattice doc
...
microsemi
quicklogic
xilinx

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 122
LiteX’s key features

▶
Extends Migen with new concepts and libraries

▶
Build and configure SoC easily

●
Scale from no CPU to Linux capable SoC
●
Open sources IP
●
Easy interconnection of modules
●
Flexible SoC configuration
●
Unified build system across vendors

▶
Portability (abstraction of technology implementation)
▶
Debug infrastructure with LiteX Server, LiteScope and other tools
▶
BIOS with command line interface for system bring-up

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 123
LiteX – Busses

▶
SoC interconnections are made with Wishbone buses (open sources
standard). It can be configured to use AXI-Lite (AXI is a royalty free
protocol available from ARM)
▶
CSR (Control and Status Registers) bus is a simple bus protocol used
to handle low bandwidth transactions
▶
Litex streams is an interface to connect streaming components (data
flow exchange)
▶
Bridges are available to interconnect all supported bus
▶
The CSR bus is automatically bridged to the Wishbone address space

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 124
LiteX – SoC classes

SoC(Module)→LiteXSoC→SoCCore→SoCMini→LiteXCore

▶
SoC is where busses, RAM, ROM, CPU and timer are added
(via methods) as submodules,
▶
LiteXSoc has a set of methods to add features to SoCCore:
add_identifier, add_uart, add_sdram, add_ethernet,…
▶
SoCCore takes a set of arguments that defines a SoC based
on LiteXSoc and provides methods to extends this SoC.
This is the class that you might use to create a SoC.
▶
SoCMini is a version of SoCCore with minimum features
enabled (by default: no CPU, no RAM, no UART, no TIMER)
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 125
LiteX – Example

WB↔CSR
Ident
bridge
WB master Wishbone
UART UARTBone
Crossbar
ledring

ctrl

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 126
LiteX – SoCCore

▶
Configuration of core functions with arguments

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 127
LiteX – SoCCore

▶
Add peripherals with methods from SoCCore:

●
add_csr
●
add_wb_master
●
add_wb_slave

▶
Add peripherals with methods from LiteXSoc:
●
add_spi_flash
●
add_sdram
●
add_ethernet
●
….
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 128
Agenda

▶
Description of FPGAs
▶
Digital design basics
▶
Migen: introduction and workshops
▶
Litex: introduction and workshops
●
Presentation of SoCs and LiteX
●
Examples of peripherals integration
●
How to build a SoC
●
Software in LiteX
●
LiteX tools
●
Workshop
▶
Litex: advanced topics
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 129
LiteX – SDRAM

▶
Add DRAM memory to the system
▶
Use LiteDRAM and supports SDR, DDR2, DDR3, DDR4 and LPDDR
▶
Needs a PHY module
▶
Signals have to be named a certain way

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 130
LiteX – Ethernet

▶
Add Ethernet to the system
▶
Use LiteETH and supports MII, RMII, GMII, RGMII, 1000BASEX, XGMII
▶
Needs a PHY module
▶
Signals have to be named a certain way

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 131
LiteX – Others

▶
add_spi_flash
▶
add_spi_sdcard
▶
add_sdcard
▶
add_sata
▶
add_pcie
▶
add_video_colorbars
▶
add_video_terminal
▶
add_video_framebuffer

▶
Once again, there is no documentation :(

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 132
Agenda

▶
Description of FPGAs
▶
Digital design basics
▶
Migen: introduction and workshops
▶
LiteX: introduction and workshops
●
Presentation of SoCs and LiteX
●
Examples of peripherals integration
●
How to build a SoC
●
Software in LiteX
●
LiteX tools
●
Workshop
▶
LiteX: advanced topics
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 133
LiteX – Add a SoC to the project

▶
Create a class that inherits from SoCCore or SoCMini
▶
Set parameters
▶
Don’t forget to add a .crg submodule !

▶
All other submodules will be added in this class
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 134
LiteX – Build a SoC

▶
Add your own arguments (used locally)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 135
LiteX – Build a SoC

▶
Builder has a set of arguments

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 136
LiteX – Builder arguments

▶
--csr-csv generates a file with CSR addresses and is
used by all LiteX tools

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 137
LiteX – Build a SoC

▶
SoCCore has a set of arguments

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 138
LiteX – SoCCore arguments

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 139
Agenda

▶
Description of FPGAs
▶
Digital design basics
▶
Migen: introduction and workshops
▶
LiteX: introduction and workshops
●
Presentation of SoCs and LiteX
●
Examples of peripherals integration
●
How to build a SoC
●
Software in LiteX
●
LiteX tools
●
Workshop
▶
LiteX: advanced topics
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 140
LiteX – Software, BIOS

▶
Built-in BIOS with low level
commands to test the SoC
▶
Uses picolibc
▶
Several boot sources (RAM,
flash, ROM, serial, tftp, sata,
sdcard)
▶
Not a full featured bootloader.
Think of a first stage bootloader.

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 141
LiteX – Software, baremetal

▶
Build your own baremetal application using provided
software libraries (spi, fatfs, sata, ethernet,...)
▶
BIOS can load the application
▶
Application can be loaded in ROM during build:

--integrated-rom-init=”myfile.bin”

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 142
LiteX – Software, generated files

▶
csr.h provides helper functions and definitions for all CSR peripherals

▶
git.h provides the git hash of the Litex version used to build the SoC

▶
mem.h definition of memory map as C defines

▶
output_format.ld and regions.ld are for the linker script

▶
soc.h provides the configuration of the SoC

▶
variables.mak are used by Makefiles

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 143
LiteX – Software, linker script

▶
Memory regions defined in generated/regions.ld

▶
An example of linker script can be found in
litex/soc/software/demo
▶
In general, your program will be placed in the main RAM
before execution (by the BIOS)
▶
Program can also replace the BIOS in rom
▶
Need to adapt the linker script
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 144
Agenda

▶
Description of FPGAs
▶
Digital design basics
▶
Migen: introduction and workshops
▶
LiteX: introduction and workshops
●
Presentation of SoCs and LiteX
●
Examples of peripherals integration
●
How to build a SoC
●
Software in LiteX
●
LiteX tools
●
Workshop
▶
LiteX: advanced topics
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 145
LiteX - Tools

▶
litex_server →proxy between tools and SoC
interconnection crossbar
▶
litex_term →terminal emulator with SFL (Serial Flash
Loader) capabilities
▶
litex_cli →simple read/write access to SoC
interconnection crossbar
▶
litescope_cli →control tool for an embedded logic
analyzer

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 146
LiteX – Tools, litex_server

▶
Allows simultaneous access to the SoC interconnect from tools
▶
Needs a bridge (UART, Ethernet, PCIe)
▶
Uses Etherbone protocol (“standardized” wishbone over IP)

litex_term
SoC
UART
CPU
(crossover)
Wishbone
litexscope_cli Crossbar
WB
litex_server UART UARTBone master
litex_cli

my_cli

HOST

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 147
LiteX – Tools, litex_term

▶
Can interface the Serial Flash Loader (SFL) of the BIOS
▶
Only binary files (no elf)
▶
Default loading address is 0x40000000 (main_ram)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 148
LiteX – Tools, litex_cli

▶
Can read/write to arbitrary address
▶
Knows SoC registers (read from csr.csv file)
▶
Needs to connect to litex_server

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 149
LiteX– Tools, litescope_cli

▶
litescope can be integrated to the design to observe internal
signals
▶
litescope_cli can control litescope through litex_server (trigger)
▶
Needs analyzer.csv generated during build

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 150
Agenda

▶
Description of FPGAs
▶
Digital design basics
▶
Migen: introduction and workshops
▶
LiteX: introduction and workshops
●
Presentation of SoCs and LiteX
●
Examples of peripherals integration
●
How to build a SoC
●
Software in LiteX
●
LiteX tools
●
Workshop
▶
LiteX: advanced topics
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 151
LiteX – Workshop / Lessons

step7 – Build a simple SoC

step8 – Add CSR to RingControl and use litex_cli to control the leds
step9 – Add add use LiteScope and litescope_cli
step10 – Write a C program to control the leds and run it from the BIOS then
run it from ROM
step11 – Add a PLL and clock the RingControl faster than the system
step12 – Add a wishbone interface to RingControl and use it

Now, let’s practice !

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 152
Step7 – Build a SoC

What you’ll see:

▶
Derive and configure a SoC class
▶
Setup argument for local usage
▶
Use Build class
▶
Use of programmer

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 153
Step7 – Build a SoC

▶
Use --help to see all available arguments
▶
Try to build without a crg
▶
Load the bitstream and run litex_server and use litex_cli
to reads the available registers and the SoC’s identifier

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 154
Step7 – Observations

▶
self.submodule.crg is mandatory

▶
Look at build logs

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 155
Step8 – Add CSR

What you’ll learn:

▶
What CSR are
▶
Add and use CSR in a module
▶
Read/Write CSR from litex_cli

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 156
Step8 – What CSR are

▶
Control and Status Registers
▶
Registers placed on a simple bus accessible
from Wishbone (bridged)
▶
Not aimed to do fast data transfers

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 157
Step8 – How to use CSR
▶
Inherit from AutoCSR

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 158
Step8 – How to use CSR
▶
Inherit from AutoCSR

▶
CSRConstant → Optimized away, values are set in generated software files

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 159
Step8 – How to use CSR
▶
Inherit from AutoCSR

▶
CSRConstant → Optimized away, values are set in generated software files

▶
CSRStorage → Register read/written by the CPU

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 160
Step8 – How to use CSR
▶
Inherit from AutoCSR

▶
CSRConstant → Optimized away, values are set in generated software files

▶
CSRStorage → Register read/written by the CPU

▶
CSRStatus → Register read only from the CPU

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 161
Step8 – How to use CSR

▶
CSRStorage and CSRStatus values must be accessed using
their storage attribute

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 162
Step8 – How to use CSR

▶
CSRStorage and CSRStatus values must be accessed using
their storage attribute
▶
CSRField are structured representation of a CSR
▶
CSRField is a Signal() and can be used directly

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 163
Step8 – How to use CSR

▶
CSR regions must be added to the SoC with add_csr()

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 164
Step8 – Documentation

▶
Documentation can be generated from CSR definition (- -doc)

▶
Fields can improve code readability and documentation

▶
You can add documentation for a module if you inherit from AutoDoc

Example of a generated doc

https://github.com/enjoy-digital/litex/wiki/SoC-Documentation
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 165
Step8 – Let’s get to work

▶
Add a CSR to RingControl to control LED’s color
▶
Add RingControl to the SoC
▶
Use litex_cli to change the color of the LEDs
Bonus:
▶
Add a command line argument to control the mode at
build time

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 166
Step8 – Observation
▶
submodules must be named to have CSR
▶
Default csr paging is 0x800 (2048 bytes), 32 bits, big
endian and mapped at address 0xF0000000

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 167
Step9 – Add / configure / use Litescope

What you’ll learn:

▶
Add Litescope to your design
▶
Use litescope_cli to configure trigger and dump
waveforms

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 168
Step9 – Add / configure / use Litescope

▶
Needs a bridge to the SoC (uartbone, etherbone,…)
▶
Signals to be observed need to be listed in the source
code (add accessible from the top level module)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 169
Step9 – Add / configure / use Litescope

▶
Samples are stored in embedded block rams. Resources
are limited !

▶
depth configures how many samples are captured
▶
clock_domain tells which clock domain is used
▶
The current configuration is stored in analyzer.csv
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 170
Step9 – Add / configure / use Litescope

▶
litex_server needs to be started
▶
litescope_cli is used to control the capture

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 171
Step9 – Let’s get to work

▶
Add a Litescope instance
▶
Configure Litescope to visualize:
●
bit_count and trst_timer.wait in RingSerialCtrl,
●
Index in RingControl

▶
Triggers on trst_timer.wait rising edge
▶
Visualize the result

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 172
Step9 – Observation

▶
Signals that you want to watch must be part of the
Module’s interface
▶
Don’t forget to add self.add_csr("analyzer")
▶
Several instances of LiteScopeAnalyzer can be used at
the same time (e.g several clock domains)

Each litescope_cli needs to read the correct (- -csv)

analyzer CSV file
https://github.com/enjoy-digital/litex/wiki/Use-LiteScope-To-Debug-A-SoC

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 173
Step10 – Write a baremetal software

What you’ll learn:

▶
Create a baremetal software for your SoC
▶
Download and run your software using the litex_term
▶
Embedded your software in ROM

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 174
Step10 – Write a baremetal software

▶
Need to use SoCCore (was SoCMini until now)
▶
We need some RAM since the code will be upload from
the host (in case we don’t replace the BIOS in ROM)

▶
Write a makefile that uses the generated variables from
the SoC definition
▶
Provide a linker script

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 175
Step10 – Workshop

▶
Build the SoC with some integrated main ram
▶
Complete the provided main.c to control the color of the LEDs
▶
Load and run the program using litex_term
▶
Build the program to target the ROM
▶
Initialize the ROM with your program and load the bitstream

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 176
Step10 – Workshop

▶
Booting from ROM require a change in the Linker script

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 177
Step11 – PLL and ClockDomains

What you’ll learn:

▶
What is a ClockDomain
▶
Use a PLL
▶
Use ClockDomainsRenamer

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 178
Migen – Attributes of Modules: clock_domains

▶
clock_domains → clock domains used by this module
▶
Clock domains object contains:
●
a the name for the clock domain
●
a clock signal
●
an optional reset signal
▶
Default clock domain is sys (implicit)
▶
A module can have more than
one clock domain

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 179
Migen – Attributes of Modules: clock_domains

Create a new clock domain and

assign a clock signal

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 180
Migen – Attributes of Modules: clock_domains

This assignment takes place in the

“pix” clock domain

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 181
Migen – Attributes of Modules: clock_domains

Assignment to cd_sys is implicit

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 182
Migen – Attributes of Modules: clock_domains

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 183
Step11 – ClockDomainsRenamer

▶
Change the clock domain of a module
▶
Used while adding a submodule
▶
Can change several clock domains at the same time

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 184
Step11 – ClockDomainsRenamer - Example

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 185
Step11 – ClockDomainsRenamer

Usage:

self.submodules.descrambler = Descrambler(“gtp0_rx”)

And:

sync = getattr(self.sync, clock_domain)

Is equivalent to:

self.sync.gtp0_rx += [
...
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 186
Step11 – ClockDomainsRenamer

▶
CSR are always in cd_sys

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 187
Step11 – PLL

▶
Phase Locked Loop
▶
One clock input, several clock output
▶
Clock multiplication, phase shift

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 188
Step11 – PLL

▶
PLL code is in litex→soc→cores→clock
▶
Constructor can be slightly different between platforms

▶
You still need to get an idea what your PLL is capable of

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 189
Step11 – Workshop

▶
Add a PLL and clock the design as shown here after
100MHz

cd_led
50MHz
PLL RingControl

cd_sys
60MHz

SoC

▶
Change the color of the LEDs using the BIOS (there is no
uart_bone anymore)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 190
Step11 – Observations

▶
Reset signal of clock domains is automatically handled
▶
CSR are in sys clock domain

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 191
Step12 – Use the wishbone bus

What you’ll learn:

▶
How Wishbone works
▶
Add and use a wishbone slave
▶
Add and use a wishbone master

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 192
Step12 – Wishbone description

▶
Open source hardware bus definition
▶
8 – 64 bits data bus
▶
Supports single transfers and bursts MASTER SLAVE
ADR ADR
▶
Two version are used: B3 and B4 (DAT_O)
(DAT_I)
DAT_W DAT_W (DAT_O)
DAT_R DAT_R (DAT_I)
SEL SEL
▶
B4 introduces pipelined transfers CYC
STB
CYC
STB
ACK ACK

▶
LiteX uses the Wishbone B3 WE
CTI
WE
CTI
BTE BTE
ERR ERR

https://cdn.opencores.org/downloads/wbspec_b3.pdf
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 193
Step12 – Wishbone simple read

MASTER SLAVE
ADR ADR CLK
(DAT_O) DAT_W DAT_W (DAT_O)
CYC
(DAT_I) DAT_R DAT_R (DAT_I)
SEL SEL STB
CYC CYC
ACK
STB STB
ACK ACK ADR VALID

WE WE
DAT_R VALID
CTI CTI
BTE BTE WE
ERR ERR

▶
ERR can finish a cycle (like ACK)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 194
Step12 – Wishbone simple write

MASTER SLAVE
ADR ADR CLK
(DAT_O) DAT_W DAT_W (DAT_O)
CYC
(DAT_I) DAT_R DAT_R (DAT_I)
SEL SEL STB
CYC CYC
ACK
STB STB
ACK ACK ADR VALID

WE WE
DAT_W VALID
CTI CTI
BTE BTE WE
ERR ERR

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 195
Step12 – Wishbone wait states

WAIT STATE WAIT STATE

(SLAVE) (MASTER)

CLK

CYC

STB

ACK

ADR N N+1

DAT_W VALID VALID

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 196
Step12 – Wishbone SEL

▶
Indicates where valid data is on the bus
▶
Used when a granularity smaller than the bus width is
needed (write a 8-bit value on a 32-bit bus)

ADR 0x20001000

DAT_W 0x11223344

SEL 0b0010

▶
In this example, 0x33 is written at address 0x20001001
▶
Depends on ENDIANNESS
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 197
Step12 – Wishbone burst cycles

▶
Increase bandwidth (1 transfer per cycle)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 198
Step12 – Wishbone burst cycles

▶
Use CTI (Cycle Type Idenfier)
▶
Use BTE (Burst Type Extension)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 199
Step12 – Wishbone burst cycles

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 200
Step12 – Use Wishbone slave with LiteX

▶
add_slave method from SoCCore

▶
IO Regions are non-cacheable

▶
Origin can be specified
▶
Address to the module is adr[2:32] and is not relative to
the base address
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 201
Step12 – Exercise

▶
Add a wishbone interface slave to RingControl
▶
Use this bus to control the ring’s color
▶
Use this bus to read a version number
▶
Read and write values from the BIOS

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 202
Step12 – Observation

▶
The address is expressed in 4 bytes words
▶
The address is not relative to the base address of the
module

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 203
Step12bis – Use Wishbone master with LiteX

▶
add_master method from SoCCore
▶
Address from the module is adr[2:32]

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 204
Step12bis – Exercise

▶
A DDR3 controller has been added as main_ram
mapped at address 0x40000000
▶
Add a wishbone master to RingControl
▶
Read LEDs color from the DRAM using the wishbone
master interface
▶
Color will be written to memory from the BIOS

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 205
Agenda

▶
Description of FPGAs
▶
Digital design basics
▶
Migen: introduction and workshops
▶
LiteX: introduction and workshops
▶
LiteX: advanced topics
●
Streams / workshop
●
Usage of Verilog/VHDL modules in LiteX / workshop
●
Verilator / workshop

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 206
LiteX – Streams

▶
Streams are groups of signals (Migen’s record)
used to exchange data between Modules
▶
There is no “addresses” on this “bus”
▶
Transfers are from the Source to the Sink
▶
Stream nodes are called Endpoints
CLK

VALID VALID

READY READY

FIRST FIRST

LAST LAST

PAYLOAD PAYLOAD

PARAM PARAM
SOURCE SINK

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 207
LiteX – Streams

VALID VALID

READY READY

FIRST FIRST

LAST LAST

PAYLOAD PAYLOAD

PARAM PARAM
SOURCE SINK

▶
valid indicates data from source are valid

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 208
LiteX – Streams

VALID VALID

READY READY

FIRST FIRST

LAST LAST

PAYLOAD PAYLOAD

PARAM PARAM
SOURCE SINK

▶
valid indicates data from source are valid
▶
ready is high when sink is ready to receive

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 209
LiteX – Streams

VALID VALID

READY READY

FIRST FIRST

LAST LAST

PAYLOAD PAYLOAD

PARAM PARAM
SOURCE SINK

▶
valid indicates data from source are valid
▶
ready is high when sink is ready to receive

Sink is not ready.

The Source keeps the current Payload
until Sink is ready again

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 210
LiteX – Streams

VALID VALID

READY READY

FIRST FIRST

LAST LAST

PAYLOAD PAYLOAD

PARAM PARAM
SOURCE SINK

▶
valid indicates data from source are valid
▶
ready is high when sink is ready to receive
▶
first and last mark packets boundaries

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 211
LiteX – Streams

VALID VALID

READY READY

FIRST FIRST

LAST LAST

PAYLOAD PAYLOAD

PARAM PARAM
SOURCE SINK

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 212
LiteX – Streams

VALID VALID

READY READY

FIRST FIRST

LAST LAST

PAYLOAD PAYLOAD

PARAM PARAM
SOURCE SINK

▶
valid indicates data from source are valid
▶
ready is high when sink is ready to receive
▶
first and last mark packets boundaries
▶
payload is a Record with its own layout, it can change on every
valid/ready transaction
▶
param is a Record with its own layout, it can evolve at each start of
packet
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 213
LiteX – Streams usage

▶
Streams are Endpoint() classes
▶
Defined from a layout
▶
param_layout is optional
▶
valid, ready, first, last are added automatically

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 214
LiteX – Streams example

Input and output Streams are added to the Module

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 215
LiteX – Streams example

Add a stream FIFO with its own layout

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 216
LiteX – Streams example

connect() is used to connect a sink to a source.

Always use source.connect(sink)

Connect self.source to fifo.sink but don’t

connect valid, ts and error (omit).They will be
controlled in the module.

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 217
LiteX – Streams components

▶
stream.SyncFIFO
▶
stream.AsyncFIFO
▶
stream.ClockDomainCrossing
▶
stream.Multiplexer
▶
stream.Demultiplexer
▶
stream.StrideConverter
▶
stream.Pipeline
▶
...

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 218
step13 – Streams workshop

What you will learn:

▶
Connect and control sinks / sources
▶
Use Ethernet UDP streamer
▶
Use WishboneDMAWriter

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 219
step13 – Streams workshop
PC add_etherbone()

netcat -u 192.168.1.98 5678 < test.bin

echo 'test' > /dev/udp/192.168.1.98/5678

litex_server

LiteEthUDPIPCore

LiteEthEtherbone LiteEthUDPStreamer

YourModuleHere

SRAM WishboneDMAWriter

▶
Receive UDP payload and write it in DRAM
▶
Check received payload using the BIOS

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 220
step13 – Streams workshop

▶
The SoC has an etherbone and an LiteEthUDPStreamer
▶
An SRAM memory (sram_udp) is present at 0x20000000
▶
LiteEthUDPStreamer provides a stream from UDP
received frames
▶
WishboneDMAWriter takes a stream (address, data) and
converts it to Wishbone transfers

▶
Write a module to prepare the stream from
LiteEthUDPStreamer to WishboneDMAWriter
▶
See further instructions in the code

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 221
step13 – Obervations

▶
Always use xxx.from.connect(yyy.to)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 222
Agenda

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 223
LiteX – Reuse Verilog/VHDL modules

▶
Verilog/VHDL cores can be integrated to Migen/LiteX
▶
Other description languages (Spinal-HDL, nMigen) can
be reused through Verilog
▶
Migen’s Instance() is used to instantiate the core

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 224
LiteX – Reuse Verilog/VHDL modules

▶
Prefixes are used to specify the type of interface

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 225
LiteX – Reuse Verilog/VHDL modules

▶
LiteX automatically determines the language based on the
file extension

▶
It is possible to pass multiple sources at once

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 226
step14 – Reuse Verilog/VHDL modules

What you will learn:

▶
Use an external verilog core
▶
Use litex_read_verilog

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 227
step14 – Reuse Verilog/VHDL modules
PC

netcat -u 192.168.1.20 1200 < test.bin

litex_server

LiteEthUDPIPCore

LiteEthEtherbone LiteEthUDPStreamer

stream_adder.v

SRAM WishboneDMAWriter S2DMA

▶
Create StreamAddOne module from stream_adder.v and
add it to the system
▶
Check received payload using the BIOS
COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 228
step14 – Reuse Verilog/VHDL modules

▶
Use litex_read_verilog to generate a Migen class
from the verilog file

▶
Create a StreamAddOne module with a sink and a
source stream port and connect your stream_adder
inside this module

▶
Insert StreamAddOne between the udp_streamer
and S2DMA

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 229
Agenda

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 230
LiteX – What is Verilator ?

▶
Verilog / SystemVerilog simulator
▶
Accept only synthesizable structures
▶
Converts Verilog into multithreaded C++ or SystemC model
▶
Generates a .cpp and .h file, the Verilated code
▶
Write a test bench with an instance of the Verilated model
▶
Get an executable that runs the simulation
▶
Very fast

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 231
LiteX – Verilator infrastructure

▶
LiteX provides a Verilator simulation framework
▶
Verilator models for DRAM, SPI Flash, SD-Card
▶
Verilator models for Ethernet and serial (interactive)
▶
Modular conception. Modules can easily be added
▶
litex_sim is a ready to use simulated SoC (with all available
simulated peripherals)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 232
LiteX – Simulation model

▶
System simulation needs model for external interfaces
Two ways:
▶
Write a synthesizable model

Synthesizable Verilog The simulated peripheral is written in

Migen like any other Module.
Peripheral
model
Peripheral
controller
Only build time configuration

No user interaction
Verilated SoC

No runtime interaction
with the simulation

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 233
LiteX – Simulation model

▶
System simulation needs model for external interfaces
Two ways: The simulated peripheral is written in
C++ and it will not be part of the
Verilated code
▶
Write a synthesizable model
Can use host’s resources
▶
Write a C++ model
Signals must be present on the top
level of your SoC
Synthesizable Verilog C++

Peripheral
Host resources
model
Peripheral
controller

Verilated SoC Host

Runtime interaction with the simulation is possible.

The model can use host’s resources

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 234
LiteX – Writing a model, synthesizable

▶
Writing a model with Migen code is not specific to simulation
▶
The model is synthesizable but resources are not important
▶
In general, fully equivalent to the real interface
▶
See LiteSPIPHYModel in litespi/litespi/phy/model.py

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 235
LiteX – Writing a C++ model

▶
Simulation can be at pins level or interface level

SPI SPI SPI

controller PHY device Non simulated configuration

SoC

SPI interface
LiteX streams (rx/tx)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 236
LiteX – Writing a C++ model

▶
Simulation can be at pins level or interface level
C++

SPI SPI
SPI
controller Device
PHY
model SPI device is simulated at
pin level
SoC

SPI interface
LiteX streams (rx/tx)

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 237
LiteX – Writing a C++ model

▶
Simulation can be at pins level or interface level
C++

SPI
SPI
PHY SPI
Device
SPI device is simulated at
controller
model interface level

Easier, faster
SoC

LiteX streams (rx/tx)

SPI PHY is just a
pass-through module
to expose the LiteX
streams to the SoC
interface

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 238
LiteX – Writing a C++ model, structure

▶
New modules must be declared during build:

▶
Must provides and register a struct ext_module_s
Name of this module.

Will be used to add it to the

simulation.

COLLSHADE - Introduction to digital design with Migen and Litex – v1.0 239
LiteX – Writing a C++ model, structure