Expand description
** Write FPGA Firmware using Rust! **
RustHDL is a crate that allows you to write FPGA firmware using Rust!
Specifically, rust-hdl
compiles a subset of Rust down to Verilog so that
you can synthesize firmware for your FPGA using standard tools. It also
provides tools for simulation, verification, and analysis along with strongly
typed interfaces for making sure your design works before heading to the bench.
The workflow is very similar to GPU programming. You write everything in Rust,
including an update kernel
that compiles down onto the hardware. You can simulate
and verify everything from the safety and comfort of your Rust environment, and
then head over to standard synthesis tools to get files that program your FPGA.
Links
You may want:
Features
- Safe - have Rust check the validity of your firmware with strongly typed interfaces at compile time, as well as at run time, synthesis, and on the device.
- Fast - Run simulations of your designs straight from your Rust code, with pretty good simulation performance.
- Readable - RustHDL outputs Verilog code for synthesis and implementation, and goes through some effort to make sure that code is readable and understandable, in case you need to resolve timing issues or other conflicts.
- Reusable - RustHDL supports templated firmware for parametric use, as well as a simple composition model based on structs.
- Batteries Included - RustHDL includes a set of basic firmware widgets that provide FIFOs, RAMs and ROMs, Flip flops, SPI components, PWMs etc, so you can get started quickly.
- Free - Although you can use RustHDL to wrap existing IP cores, all of the RustHDL code and firmware is open source and free to use (as in speech and beer).
- Tested - RustHDL has been used to write firmware that is shipping in commercial products. This includes quite complicated designs that use nearly all of a moderately sized FPGA, and take advantage of specialized hardware in the FPGAs themselves.
Quickstart
The definitive example in FPGA firmware land is a simple LED blinker. This typically involves a clock that is fed to the FPGA with a pre-defined frequency, and an output signal that can control an LED. Because we don’t know what FPGA we are using, we will do this in simulation first. We want a blink that is 250 msec long every second, and our clock speed is (a comically slow) 10kHz. Here is a minimal working Blinky! example:
use std::time::Duration;
use rust_hdl::prelude::*;
const CLOCK_SPEED_HZ : u64 = 10_000;
#[derive(LogicBlock)] // <- This turns the struct into something you can simulate/synthesize
struct Blinky {
pub clock: Signal<In, Clock>, // <- input signal, type is clock
pulser: Pulser, // <- sub-circuit, a widget that generates pulses
pub led: Signal<Out, Bit>, // <- output signal, type is single bit
}
impl Default for Blinky {
fn default() -> Self {
Self {
clock: Default::default(),
pulser: Pulser::new(CLOCK_SPEED_HZ, 1.0, Duration::from_millis(250)),
led: Default::default(),
}
}
}
impl Logic for Blinky {
#[hdl_gen] // <- this turns the update function into an HDL Kernel that can be turned into Verilog
fn update(&mut self) {
// v-- write to the .next member v-- read from .val() method
self.pulser.clock.next = self.clock.val();
self.pulser.enable.next = true.into();
self.led.next = self.pulser.pulse.val();
}
}
fn main() {
// v--- build a simple simulation (1 testbench, single clock)
let mut sim = simple_sim!(Blinky, clock, CLOCK_SPEED_HZ, ep, {
let mut x = ep.init()?;
wait_clock_cycles!(ep, clock, x, 4*CLOCK_SPEED_HZ);
ep.done(x)
});
// v--- construct the circuit
let mut uut = Blinky::default();
// v--- run the simulation, with the output traced to a .vcd file
sim.run_to_file(Box::new(uut), 5 * SIMULATION_TIME_ONE_SECOND, "blinky.vcd").unwrap();
vcd_to_svg("/tmp/blinky.vcd","images/blinky_all.svg",&["uut.clock", "uut.led"], 0, 4_000_000_000_000).unwrap();
vcd_to_svg("/tmp/blinky.vcd","images/blinky_pulse.svg",&["uut.clock", "uut.led"], 900_000_000_000, 1_500_000_000_000).unwrap();
}
Running the above (a release run is highly recommended) will generate a vcd
file (which is
a trace file for FPGAs and hardware in general). You can open this using e.g., gtkwave
.
If you have, for example, an Alchitry Cu board you can generate a bitstream for this exampling
with a single call. It’s a little more involved, so we will cover that in the detailed
documentation. It will also render that vcd
file into an svg
you can view with an ordinary
web browser. This is the end result showing the entire simulation:
Here is a zoom in showing the pulse to the LED
The flow behind RustHDL is the following:
- Circuits are modelled using simple
struct
s, composed of other circuit elements and signal wires that interconnect them. - A
#[derive(LogicBlock)]
annotation on the struct adds autogenerated code needed by RustHDL. - You
impl Logic
on yourstruct
, and provide thefn update(&mut self)
method, which is the HDL update kernel. - That gets annotated with a
#[hdl_gen]
attribute to generate HDL from the Rust code - You can then simulate and synthesize your design - either in software, or by using an appropriate BSP and toolchain.
The rest is detail. Some final things to keep in mind.
- RustHDL is a strict subset of Rust. The
rustc
compiler must be satisfied with your design first. That means types, exhaustive enum matching, etc. - The goal is to eliminate a class of mistakes that are easy to make in other HDLs with checks taking place at compile time, via static analysis at run time, and then with testbenches.
- Although the performance can always be improved, RustHDL is pretty fast, especially in release mode.
Types
There are a couple of key types you should be comfortable with to use RustHDL. The first is the Bits type, which provides a compile-time arbitrary width bit vector.
Representing bits
The Bits type is a Copy
enabled type that you can construct from integers,
from the Default
trait, or from other Bits
. Mostly, it is meant to stay out of your way
and behave like a u32
.
let x: Bits<50> = Default::default();
This will construct a length 50 bit vector that is initialized to all 0
.
You can also convert from literals into bit vectors using the From and Into traits,
provided the literals are of the u64
type.
let x: Bits<50> = 0xBEEF.into();
In some cases, Rust complains about literals, and you may need to provide a suffix:
let x: Bits<50> = 0xDEAD_BEEF_u64.into();
However, in most cases, you can leave literals suffix-free, and Rust will automatically determine the type from the context.
You can construct a larger constant using the [bits] function. If you have a literal of up to 128 bits, it provides a functional form
let x: Bits<200> = bits(0xDEAD_BEEE); // Works for up to 128 bit constants.
There is also the [ToBits] trait, which is implemented on the basic unsigned integer types. This trait allows you to handily convert from different integer values
let x: Bits<10> = 32_u8.to_bits();
Operations
The Bits type supports a subset of operations that can be synthesized in hardware. You can perform
- Addition between
Bits
of the same size using the+
operator - Subtraction between
Bits
of the same size using the-
operator - Bitwise logical
AND
betweenBits
of the same size using the&
operator - Bitwise logical
OR
betweenBits
of the same size using the|
operator - Bitwise logical
XOR
(Exclusive Or) betweenBits
of the same size using the^
operator - Bitwise comparisons for equality between
Bits
of the same size using==
and!=
operators - Unsigned comparisons (e.g.,
>,>=,<,<=
) betweenBits
of the same size - these are always treated as unsigned values for comparison purposes. - Shift left using the
<<
operator - Shift right (no sign extension!) using the ‘>>’ operator
- Bitwise logical
NOT
using the!
prefix operator
These should feel natural when using RustHDL, as expressions follow Rust’s rules (and not Verilog’s). For example:
let x: Bits<32> = 0xDEAD_0000_u32.to_bits();
let y: Bits<32> = 0x0000_BEEF_u32.to_bits();
let z = x + y;
assert_eq!(z, 0xDEAD_BEEF_u32.to_bits());
You can, of course, construct expressions of arbitrary complexity using parenthesis, etc. The only real surprise may be at synthesis time, when you try to fit the expression onto hardware.
Signal Type
Signals are software abstractions to represent physical wires. The Signal type is generic over a couple of parameters. The first is meant to indicate the driver of the wire. In RustHDL, every wire must have exactly one driver. It is the hardware equivalent of the single writer principle. You can have as many readers as you want, but only one writer. Unfortunately, there are some subtleties here, and declaring ownership of a wire using the type system is imperfect. Instead, we settle for a signalling mechanism of intent. So you mark a signal as how you intend to use it in your logic. For example, consider the following circuit:
pub struct My8BitAdder {
pub input_1: Signal<In, Bits<8>>,
pub input_2: Signal<In, Bits<8>>,
pub output: Signal<Out, Bits<8>>,
}
In this case, the fields of the adder circuit are marked as pub
so they can be accessed from
outside the circuit. The Direction argument to the [Signal] indicates
how the given circuit intends to utilize the various wires. In this case, input_1
and input_2
should be considered inputs, and output
is, obviously, an output. As such, My8BitAdder
is
promising you that it will drive the output
wire. If it fails to actually do so (by leaving
it undriven), then you will get an error when you try to use it in a design.
RustHDL does not allow undriven nets. They are treated similarly to uninitialized memory in Rust. You must drive every net in the design. Furthermore, you can have only one driver for each net. These two principles are core to RustHDL!
The second part of a [Signal] is that it is typed. In general, the type signature is meant
to convey something about the nature of the data being stored or passed. In the case of
My8BitAdder
, it doesn’t say much - only that the input is an unsigned 8-bit value. But
the types can be more complicated, including collections of signals running in multiple
directions (as is typical for a bus or other complex interface).
Signals can also be bidirectional with the InOut designation. But you typically can only use these types of signals at the edge of your device. More on that elsewhere.
The definition of [Signal] also indicates how it should be used. [Signal]’s cannot be assigned to using usual semantics.
#[derive(Clone, Debug)]
pub struct Signal<D: Direction, T: Synth> {
pub next: T,
pub changed: bool,
// Internal details omitted
}
To change (drive) the value of a signal, you assign to the next
field. To read the
value of the signal (i.e. to get it’s current state without driving it), you use the val()
method.
This is in keeping with the idea that you treat the signal differently if you want to drive
it to some value, versus if you want to read it, as in hardware, these are different functions.
In most cases, you will read from val()
of the input signals, and write to the .next
of the
output signal. For example, in the My8BitAdder
example, you would read from input_1.val()
and from input_2.val()
, and write to output.next
. Like this:
pub struct My8BitAdder {
pub input_1: Signal<In, Bits<8>>,
pub input_2: Signal<In, Bits<8>>,
pub output: Signal<Out, Bits<8>>,
}
impl Logic for My8BitAdder {
fn update(&mut self) {
self.output.next = self.input_1.val() + self.input_2.val();
}
}
In general, this is the pattern to follow. However, there are some exceptions. Sometimes, you will want a “scratchpad” for holding intermediate results in a longer expression. For example, suppose you want to logically OR a bunch of values together, but want to logically shift them into different positions before doing so. Let us assume you have a logical block that looks like this:
pub struct OrStuff {
pub val1: Signal<In, Bit>,
pub val2: Signal<In, Bits<4>>,
pub val3: Signal<In, Bits<2>>,
pub val4: Signal<In, Bit>,
pub combined: Signal<Out, Bits<8>>,
pad: Signal<Local, Bits<8>>,
}
In this case, the pad
field (which is private to the logic) has a direction of Local
,
which means it can be used to write and read from in the same circuit, as long as you write first!
Hence, you can do something like this in the update
method
impl Logic for OrStuff {
fn update(&mut self) {
self.pad.next = 0.into(); // Write first
self.pad.next = self.pad.val() | bit_cast::<8,1>(self.val1.val().into()); // Now we can read and write to it
self.pad.next = self.pad.val() | (bit_cast::<8,4>(self.val2.val()) << 1);
self.pad.next = self.pad.val() | (bit_cast::<8,2>(self.val3.val()) << 5);
self.pad.next = self.pad.val() | (bit_cast::<8,1>(self.val4.val().into()) << 7);
self.combined.next = self.pad.val();
}
}
You can understand this behavior by either “folding” all of the expressions into a single
long expression (i.e., by eliminating self.pad
altogether) and just assigning the output
to an expression consisting of the various inputs OR-ed together. Nonetheless, it is
handy to be able to compute intermediate values and read them back elsewhere in the code.
- Note that
.next
should never appear on the right hand side of an expression! *
The following code will fail to compile, because once we try to derive HDL from the result, RustHDL realizes it makes no sense.
impl Logic for OrStuff {
#[hdl_gen]
fn update(&mut self) {
self.pad.next = 0.into(); // Write first
self.pad.next = self.pad.next | bit_cast::<8,1>(self.val1.val().into()); // Fails! Can only write to .next
self.combined.next = self.pad.val();
}
}
Detecting the case in which you fail to write to a signal before reading from it is more complicated and must be done a run time. The macro processor is not sophisticated enough to detect that case at the moment. However, it can be found when your logic is checked for correctness by the static analyzer.
Normally, the Verilog code generator or the Simulation engine will statically check your design for you. However, you can also check the design yourself using the check_all function. Here is an example of that check being run on a logic block that attempts to write to an input signal being passed into the block. The example panics because
#[derive(LogicBlock, Default)]
struct BadActor {
pub in1: Signal<In, Bit>,
pub in2: Signal<In, Bit>,
pub out1: Signal<Out, Bit>,
}
impl Logic for BadActor {
#[hdl_gen]
fn update(&mut self) {
// This is definitely not OK
self.in1.next = true;
// This is fine
self.out1.next = self.in2.val();
}
}
// This will panic with an error of CheckError::WritesToInputs, pointing to self.in1
check_all(&BadActor::default()).unwrap()
Traits
There is only one trait that you typically need to implement to get things to work in RustHDL with the simulation and synthesis frameworks. That is the Logic trait. Although you will rarely (if ever) need to implement the methods themselves, here is the full definition of the trait:
pub trait Logic {
fn update(&mut self);
fn connect(&mut self) {}
fn hdl(&self) -> Verilog {
Verilog::Empty
}
fn timing(&self) -> Vec<TimingInfo> {
vec![]
}
}
The methods are quite simple:
update
- this updates the state of the logical block based on the inputs and internal state. In general, this is where the action of the logical block takes place.connect
- this is where we claim whatever signals we drive, by callingconnect
on them.hdl
- this method returns the Verilog description for our logical block in the form of an Verilog enum.timing
- this is where specific timing exceptions or requirements are expressed for the logical block.
In almost all cases, you will use the #[derive(LogicBlock)]
macro to derive all of the traits from
your own update
method, written in Rust. If we revisit the Blinky
example, note that
we only provided the update
method, with an attribute of #[hdl_gen]
, which in turn
generated the remaining trait implementations:
#[derive(LogicBlock)]
struct Blinky {
pub clock: Signal<In, Clock>,
pulser: Pulser,
pub led: Signal<Out, Bit>,
}
impl Logic for Blinky {
#[hdl_gen]
fn update(&mut self) {
self.pulser.clock.next = self.clock.val();
self.pulser.enable.next = true.into();
self.led.next = self.pulser.pulse.val();
}
}
There are a couple of other traits that RustHDL uses that you should be aware of.
Synth
- this trait is provided on types that can be represented in hardware, i.e. as a set of bits. You will probably not need to implement this trait yourself, but if you need some special type representationFoo
, andimpl Synth for Foo
, then RustHDL will be able to generate Verilog code for it.Block
- this trait is needed on anystruct
that is a composition of circuit elements (pretty much every struct used to model a circuit). This should be auto-derived.Logic
- Sometimes, you will need to override the default implementations of theLogic
trait. In those cases, (when you are providing a custom simulation model, or wrapping a black box Verilog routine), you will need toimpl
the other methods.
The Synthesizable Subset of Rust and the HDL Kernel
RustHDL uses procedural macros to define a subset of the Rust language that can be used to describe actual hardware. That subset is known as the synthesizable subset of Rust. It is quite limited because the end result is translated into Verilog and ultimately into hardware configuration for the FPGA.
- The HDL kernel must be valid Rust! If you remove the
#[hdl_gen]
attribute, the code must still be accepted byrustc
! That means you must satisfy the type constraints, the private nature of the struct fields, etc. This is one of the major benefits of RustHDL. It takes code that is already been checked byrustc
and then converts it into HDL.
So this will clearly fail to compile.
struct Foo {
bar: Signal<Out, Bits<4>>
}
impl Logic for Foo {
#[hdl_gen]
fn update(&mut self) {
self.bar.next = "Oy!"; // Type issue here...
}
}
- The
#[hdl_gen]
attribute can only be applied to a function (aka HDL Kernel) that takes&mut self
as an argument. In almost all cases, you will write something like:
struct Foo {}
impl Logic for Foo {
#[hdl_gen]
fn update(&mut self) {
// Put your synthesizable subset of Rust here...
}
}
- The body of the
update
function must be a single block, consisting of statements. Local definitions and items are not allowed in HDL kernels. The following, for example, will fail. This is an example of valid Rust that is not allowed in an HDL kernel.
struct Foo {}
impl Logic for Foo {
#[hdl_gen]
fn update (&mut self) {
// Fails because local items are not allowed in HDL kernels.
let x = 32;
}
}
- Assignments are allowed as long as you follow the rules about signals. Types are
still enforced by Rust.
- Indexed assignments are currently not supported
- Signal assignments must be to either
.next
or.next.field
if the signal is struct based.
So valid assignments will be of the form self.<signal>.next = <expr>
, or for structure-valued
signals.
- Expressions support accessing fields of a signal
- Binary operations supported are
+
,-
,*
,&&
,||
,^
,&
,|
,<<
,>>
,==
,<
,<=
,!=
,>
,>=
In general, binary operations require that both arguments are of the same type (e.g. bitwidth) or one of the arguments will be a literal.
struct Foo {
pub sig1: Signal<In, Bits<4>>,
pub sig2: Signal<In, Bits<4>>,
pub sig3: Signal<Out, Bits<4>>,
}
impl Logic for Foo {
#[hdl_gen]
fn update(&mut self) {
self.sig3.next = self.sig1.val() + 4; // Example of binop with a literal
self.sig3.next = self.sig1.val() ^ self.sig2.val(); // Example of a binop with two bitvecs
}
}
- Unary operations supported are
-
and!
The-
operator is only supported forSigned
types. Otherwise, it makes no sense. If you want to compute the 2’s complement of an unsigned value, you need to do so explicitly. The!
operator will flip all of the bits in the bitvector. - Conditionals (
if
) are supported
struct Foo {
pub sig1: Signal<In, Bit>,
pub sig2: Signal<Out, Bits<2>>,
pub sig3: Signal<In, Bits<2>>,
pub sig4: Signal<Out, Bits<2>>,
}
impl Logic for Foo {
#[hdl_gen]
fn update(&mut self) {
self.sig2.next = 0.into(); // Latch prevention!
// Straight `if`s are supported, but beware of latches!
// This `if` statement would generate a latch if not for
// the unconditional assign to `sig2`
if self.sig1.val() {
self.sig2.next = 1.into();
}
// You can use `else` clauses also
if self.sig1.val() {
self.sig2.next = 1.into();
} else {
self.sig2.next = 2.into();
}
// Nesting and chaining are also fine
if self.sig3.val() == 0 {
self.sig4.next = 3.into();
} else if self.sig3.val() == 1 {
self.sig4.next = 2.into();
} else {
self.sig4.next = 0.into(); // <- Fall through else prevents latch
}
}
}
- Literals (provided they implement the
Synth
trait) are supported. In most cases, you can used un-suffixed literals (like1
or0xDEAD
) as add.into()
. - Function calls - RustHDL kernels support a very limited number of function calls, all of
which are ignored in HDL at the moment (they are provided to make
rustc
happy)bit_cast
signed_bit_cast
unsigned_cast
bits
Bits
Type::join
andType::link
used to link and join logical interfaces…
- Method calls - Kernels support the following limited set of method calls
get_bits
- extract a (fixed width) set of bits from a bit vectorget_bit
- extract a single bit from a bit vectorreplace_bit
- replace a single bit in a bit vectorall
- true if all the bits in the bit vector are trueany
- true if any of the bits in the bit vector are truexor
- true if the number of ones in the bit vector is oddval
,into
,index
,to_bits
- ignored in HDL kernels
struct Foo {
pub sig1: Signal<In, Bits<8>>,
pub sig_index: Signal<In, Bits<3>>,
pub sig2: Signal<Out, Bit>,
pub sig3: Signal<Out, Bits<3>>,
pub sig4: Signal<Out, Bit>,
}
impl Logic for Foo {
#[hdl_gen]
fn update(&mut self) {
self.sig2.next = self.sig1.val().get_bit(self.sig_index.val().index()); // <- Selects specified bit out of sig1
self.sig3.next = self.sig1.val().get_bits::<3>(self.sig_index.val().index()); // Selects 3 bits starting at index `sig_index`
// Notice that here we have an output on both the left and right side of the assignment
// That is fine as long we we write to `.next` before we read from `.val`.
self.sig4.next = self.sig3.val().all(); // True if sig3 is all true
}
}
- Matches - Kernels support matching with literals or identifiers
Matches are used for state machines and implementing ROMs.
For now,match
is a statement, not an expression! Maybe that will be fixed in a future version of RustHDL, but for now, the value of thematch
is ignored. Here is an example of amatch
for a state machine:
#[derive(Copy, Clone, PartialEq, Debug, LogicState)]
enum State {
Idle,
Running,
Paused,
}
struct Foo {
pub start: Signal<In, Bit>,
pub pause: Signal<In, Bit>,
pub stop: Signal<In, Bit>,
pub clock: Signal<In, Clock>,
state: DFF<State>,
}
impl Logic for Foo {
#[hdl_gen]
fn update(&mut self) {
dff_setup!(self, clock, state); // <- setup the DFF
match self.state.q.val() {
State::Idle =>
if self.start.val() {
self.state.d.next = State::Running;
}
State::Running =>
if self.pause.val() {
self.state.d.next = State::Paused;
}
State::Paused =>
if !self.pause.val() {
self.state.d.next = State::Running;
}
}
if self.stop.val() {
self.state.d.next = State::Idle;
}
}
}
- Macros - some macros are supported in kernels
println
- this is converted into a comment in the generated HDLcomment
- also a commentassert
- converted to a commentdff_setup
- setup a DFF - this macro is converted into the appropriate HDLclock
- clock a set of components - this macro is also converted into the appropriate HDL
- Loops -
for
loops are supported for code generation- In software parlance, all
for
loops are unrolled at compile time, so they must be of the formfor <ident> in <const>..<const>
. A simple example to consider is a parameterizable mux.
- In software parlance, all
// Mux from N separate signals, using A address bits
// For fun, it's also generic over the width of the
// signals being muxed. So there are 3 generics here:
// - D - the type of those signals
// - N - the number of signals being muxed
// - A - the number of address bits (check that 2^A >= N)
struct Mux<D: Synth, const N: usize, const A: usize> {
pub input_lines: [Signal<In, D>; N],
pub select: Signal<In, Bits<A>>,
pub outsig: Signal<Out, D>,
fallback: Constant<D>,
}
// The impl for this requires a for loop
impl<D: Synth, const N: usize, const A: usize> Logic for Mux<D, N, A> {
#[hdl_gen]
fn update(&mut self) {
self.outsig.next = self.fallback.val();
for i in 0..N {
if self.select.val().index() == i {
self.outsig.next = self.input_lines[i].val();
}
}
}
}
RustHDL is still pretty restrictive about arrays and loops. You can still do great stuff though.
Since an example is instructive, here is the HDL kernel for a nontrivial circuit (the SPIMaster
),
annotated to demonstrate the various valid bits of syntax. It’s been heavily redacted to make
it easier to read.
// Note - you can use const generics in HDL definitions and kernels!
#[derive(LogicBlock)]
struct SPIMaster<const N: usize> {
// The `pub` members are the ones you can access from other circuits.
// These form the official interface of the circuit
pub clock: Signal<In, Clock>,
pub bits_outbound: Signal<In, Bits<16>>,
pub data_outbound: Signal<In, Bits<N>>,
// snip...
// These are private, so they can only be accessed by internal code
register_out: DFF<Bits<N>>,
register_in: DFF<Bits<N>>,
state: DFF<SPIState>,
strobe: Strobe<32>,
pointer: DFF<Bits<16>>,
// snip...
// Computed constants need to be stored in a special Constant field member
cs_off: Constant<Bit>,
mosi_off: Constant<Bit>,
}
impl<const N: usize> Logic for SPIMaster<N> {
#[hdl_gen]
fn update(&mut self) {
// Setup the internals - for Latch avoidance, each digital flip flop
// requires setup - it needs to be clocked, and it needs to connect
// the output and input together, so that the input is driven.
// This macro simply declutters the code a bit and makes it easier to read.
dff_setup!(
self,
clock,
// | equivalent to `self.register_out.clock.next = self.clock.val();`
// v-- `self.register_out.d.next = self.register_out.q.val();`
register_out,
register_in,
state,
pointer,
);
// This macro is shorthand for `self.strobe.next = self.clock.val();`
clock!(self, clock, strobe);
// These are just standard assignments... Nothing too special.
// Note that `.next` is on the LHS, and `.val()` on the right...
self.strobe.enable.next = true;
self.wires.mclk.next = self.clock_state.q.val();
self.wires.msel.next = self.msel_flop.q.val();
self.data_inbound.next = self.register_in.q.val();
self.pointerm1.next = self.pointer.q.val() - 1;
// The `match` is used to model state machines
match self.state.q.val() {
SPIState::Idle => {
self.busy.next = false;
self.clock_state.d.next = self.cpol.val();
if self.start_send.val() {
// Capture the outgoing data in our register
self.register_out.d.next = self.data_outbound.val();
self.state.d.next = SPIState::Dwell; // Transition to the DWELL state
self.pointer.d.next = self.bits_outbound.val(); // set bit pointer to number of bit to send (1 based)
self.register_in.d.next = 0.into(); // Clear out the input store register
self.msel_flop.d.next = !self.cs_off.val(); // Activate the chip select
self.continued_save.d.next = self.continued_transaction.val();
} else {
if !self.continued_save.q.val() {
self.msel_flop.d.next = self.cs_off.val(); // Set the chip select signal to be "off"
}
}
self.mosi_flop.d.next = self.mosi_off.val(); // Set the mosi signal to be "off"
}
SPIState::Dwell => {
if self.strobe.strobe.val() {
// Dwell timeout has reached zero
self.state.d.next = SPIState::LoadBit; // Transition to the loadbit state
}
}
SPIState::LoadBit => {
// Note in this statement that to use the pointer register as a bit index
// into the `register_out` DFF, we need to convert it with `index()`.
if self.pointer.q.val().any() {
// We have data to send
self.mosi_flop.d.next = self
.register_out
.q
.val()
.get_bit(self.pointerm1.val().index()); // Fetch the corresponding bit out of the register
self.state.d.next = SPIState::MActive; // Move to the hold mclock low state
self.clock_state.d.next = self.cpol.val() ^ self.cpha.val();
} else {
self.mosi_flop.d.next = self.mosi_off.val(); // Set the mosi signal to be "off"
self.clock_state.d.next = self.cpol.val();
self.state.d.next = SPIState::Finish; // No data, go back to idle
}
}
SPIState::MActive => {
if self.strobe.strobe.val() {
self.state.d.next = SPIState::SampleMISO;
}
}
}
}
}
Enums
In keeping with Rust’s strongly typed model, you can use enums (not sum types) in your HDL,
provided you derive the LogicState
trait for them. This makes your code much easier to
read and debug, and rustc
will make sure you don’t do anything illegal with your
enums.
#[derive(Copy, Clone, PartialEq, Debug, LogicState)]
enum State {
Idle,
Running,
Paused,
}
Using enums for storing things like state has several advantages:
- RustHDL will automatically calculate the minimum number of bits needed to store the enum in e.g., a register.
For example, we can create a Digital Flip Flop (register) of value State
from the next
example, and RustHDL will convert this into a 2 bit binary register.
#[derive(Copy, Clone, PartialEq, Debug, LogicState)]
enum State {
Idle,
Sending,
Receiving,
Done,
}
struct Foo {
dff: DFF<State>, // <-- This is a 2 bit DFF
}
Now imagine we add another state in the future to our state machine - say Pending
:
#[derive(Copy, Clone, PartialEq, Debug, LogicState)]
enum State {
Idle,
Sending,
Receiving,
Pending,
Done,
}
struct Foo {
dff: DFF<State>, // <-- This is now a 3 bit DFF!
}
RustHDL will automatically choose a 3-bit representation.
- RustHDL will ensure that assignments to
enum
-valued signals are valid at all times
The strong type guarantees ensure you cannot assign arbitrary values to enum
valued
signals, and the namespaces ensure that there is no ambiguity in assignment. This example
won’t compile, since On
without the name of the enum
means nothing, and State1
and
State2
are separate types. They cannot be assigned to one another.
#[derive(Copy, Clone, PartialEq, Debug, LogicState)]
enum State1 {
On,
Off,
}
#[derive(Copy, Clone, PartialEq, Debug, LogicState)]
enum State2 {
Off,
On,
}
struct Foo {
pub sig_in: Signal<In, State1>,
pub sig_out: Signal<Out, State2>,
}
impl Logic for Foo {
#[hdl_gen]
fn update(&mut self) {
self.sig_out.next = On; // << This won't work either.
self.sig_out.next = self.sig_in.val(); // << Won't compile
}
}
If for some reason, you needed to translate between enums, use a match
:
impl Logic for Foo {
#[hdl_gen]
fn update(&mut self) {
match self.sig_in.val() {
State1::On => self.sig_out.next = State2::On,
State1::Off => self.sig_out.next = State2::Off,
}
}
}
Interfaces
One area you will encouter as your circuits become more complex is that the interfaces to those circuits will become increasingly complicated. To demonstrate, suppose you have a circuit that consumes a sequence of 16-bit integers via a FIFO interface. The circuit has some flow control signals because it cannot consume them every clock cycle (For Reasons). Suppose also that you have a data producer circuit that will produce 16-bit integers and you want to connect these two together. A natural FIFO interface would look like this
struct MyFIFO {
pub data_to_fifo: Signal<In, Bits<16>>,
pub write: Signal<In, Bits<16>>,
pub full: Signal<Out, Bit>,
pub overflow: Signal<Out, Bit>,
}
struct DataWidget {
pub data_to_fifo: Signal<Out, Bits<16>>,
pub write: Signal<Out, Bits<16>>,
pub full: Signal<In, Bit>,
pub overflow: Signal<In, Bit>,
}
struct Foo {
producer: DataWidget,
consumer: MyFIFO,
}
Now, we want to connect the output of the DataWidget (all 4 signals!) to the corresponding
signals on MyFIFO
. Keep in mind that the order of assignment is irrelevant, but which
signal appears on the LHS vs RHS is important. In the impl Logic
block for Foo
,
our HDL kernel will look like this:
impl Logic for Foo {
#[hdl_gen]
fn update(&mut self) {
self.consumer.data_to_fifo.next = self.producer.data_to_fifo.val();
self.consumer.write.next = self.producer.write.val();
self.producer.full.next = self.consumer.full.val();
self.producer.overflow.next = self.consumer.overflow.val();
}
}
This is basically boilerplate at this point, and typing that in and getting it right
is error prone and tedious. Fortunately, RustHDL can help! RustHDL includes the
concept of an Interface
, which is basically a bus. An Interface
is generally a
pair of structs that contain signals of complementary directions and a #[derive]
macro that autogenerates a bunch of boilerplate. To continue on with our previous
example, we could define a pair of struct
s for the write interface of the FIFO
#[derive(LogicInterface)] // <- Note the LogicInterface, not LogicBlock
#[join = "MyFIFOWriteSender"] // <- Name of the "mating" interface
struct MyFIFOWriteReceiver {
pub data_to_fifo: Signal<In, Bits<16>>,
pub write: Signal<In, Bit>,
pub full: Signal<Out, Bit>,
pub overflow: Signal<Out, Bit>,
}
#[derive(LogicInterface)] // <- Also here
#[join = "MyFIFOWriteReceiver"] // <- Name of the "mating" interface
struct MyFIFOWriteSender {
pub data_to_fifo: Signal<Out, Bits<16>>,
pub write: Signal<Out, Bit>,
pub full: Signal<In, Bit>,
pub overflow: Signal<In, Bit>
}
The names of the fields must match, the types of the fields must also match, and the directions of the signals must be complementary. So in general:
- Each field in struct
A
must have a matching named field in structB
- The types of those fields must match
- The direction of those signals must be opposite
- Order of the fields is immaterial
- The
join
attribute tells the compiler which interface to mate to this one.
So what can we do with our shiny new interfaces? Plenty of stuff. First, lets rewrite our FIFO circuit and data producer to use our new interfaces.
struct MyFIFO {
// The write interface to the FIFO - now only one line!
pub write_bus: MyFIFOWriteReceiver,
}
struct DataWidget {
// The output interface from the DataWidget!
pub data_out: MyFIFOWriteSender,
}
That is significantly less verbose! So what happens to our
impl Logic for Foo
? Well, RustHDL autogenerates 2 methods for each LogicInterface
. The first
one is called join
. And it, well, joins the interfaces.
impl Logic for Foo {
#[hdl_gen]
fn update(&mut self) {
// Excess verbosity eliminated!!
MyFIFOWriteSender::join(&mut self.producer.data_out, &mut self.consumer.write_bus);
}
}
This is exactly equivalent to our previous 4 lines of hand crafted code, but is now automatically
generated and synthesizable. But wait! There is more. RustHDL also generates a link
method, which allows you to forward a bus from one point to another. If you think in terms
gendered cables, a join
is a cable with a Male connector on one end and a Female connector
on the other. A link
is a cable that is either Male to Male or Female to Female. Links
are useful when you want to forward an interface to an interior component of a circuit, but
hide that interior component from the outside world. For example, lets suppose that
DataWidget
doesn’t actually produce the 16-bit samples. Instead, some other FPGA component
or circuit generates the 16-bit samples, and DataWidget
just wraps it along with some
other control logic. So in fact, our DataWidget
has an internal representation that looks
like this
struct DataWidget {
pub data_out: MyFIFOWriteSender,
secret_guy: CryptoGenerator,
running: DFF<Bit>,
}
struct CryptoGenerator {
pub data_out: MyFIFOWriteSender,
// secret stuff!
}
In this example, the DataWidget
wants to present the outside world that it is a MyFIFOWriteSender
interface, and that it can produce 16-bit data values. But the real work is being done internally
by the secret_guy
. The manual way to do this would be to connect up the signals manually. Again,
paying attention to which signal is an input (for DataWidget
), and which is an output.
impl Logic for DataWidget {
#[hdl_gen]
fn update(&mut self) {
// Yawn...
self.data_out.data_to_fifo.next = self.secret_guy.data_out.data_to_fifo.val();
self.data_out.write.next = self.secret_guy.data_out.write.val();
self.secret_guy.data_out.full.next = self.data_out.full.val();
self.secret_guy.data_out.overflow.next = self.data_out.overflow.val();
}
}
In these instances, you can use the link
method instead. The syntax is
Interface::link(&mut self.outside, &mut self.inside)
, where outside
is the
side of the interface going out of the circuit, and inside
is the side of the interface
inside of the circuit. Hence, our interface can be forwarded
or linked
with a single line
like so:
impl Logic for DataWidget {
#[hdl_gen]
fn update(&mut self) {
// Tada!
MyFIFOWriteSender::link(&mut self.data_out, &mut self.secret_guy.data_out);
}
}
As a parting note, you can make interfaces generic across types. Here, for example is the FIFO interface used in the High Level Synthesis library in RustHDL:
#[derive(Clone, Debug, Default, LogicInterface)]
#[join = "FIFOWriteResponder"]
pub struct FIFOWriteController<T: Synth> {
pub data: Signal<Out, T>,
pub write: Signal<Out, Bit>,
pub full: Signal<In, Bit>,
pub almost_full: Signal<In, Bit>,
}
#[derive(Clone, Debug, Default, LogicInterface)]
#[join = "FIFOWriteController"]
pub struct FIFOWriteResponder<T: Synth> {
pub data: Signal<In, T>,
pub write: Signal<In, Bit>,
pub full: Signal<Out, Bit>,
pub almost_full: Signal<Out, Bit>,
}
You can then use any synthesizable type for the data bus, and keep the control signals as single bits! Neat, eh? 🦑
Simulation
Now that you have a shiny new circuit implemented as a struct, what do you do with it? Typically, in hardware design, the first thing you do (after static analysis) is to simulate the circuit. Simulation allows you to verify the proper behavior of the circuit in software before heading over to the bench to test on the physical hardware. There is a saying in hardware design “success in simulation is necessary, but not sufficient for correct operation”. Or something like that.
In any case, RustHDL makes it easy to simulate your designs by allowing you to create and write complex test benches in Rust instead of in an HDL like Verilog or VHDL. Furthermore, the simulator is built in, so you do not need to use external tools for simulation. Occasionally, you may need to or want to simulate using external tools. Currently, RustHDL can’t help much there. You can convert your design to Verilog and then import it into standard simulation tools, but the testbench won’t go with the design. Maybe in the future…
The simulator that is built into RustHDL is pretty basic, and easy to use. To use it, you need a circuit to simulate. Let’s create a basic 8 bit adder with a clocked register for the output (and no carry):
use rust_hdl::prelude::*; // <- shorthand to bring in all definitions
// v--- Required by RustHDL
#[derive(LogicBlock, Default)]
struct MyAdder {
pub sig_a: Signal<In, Bits<8>>,
pub sig_b: Signal<In, Bits<8>>,
pub sig_sum: Signal<Out, Bits<8>>,
pub clock: Signal<In, Clock>,
my_reg: DFF<Bits<8>>,
}
impl Logic for MyAdder {
#[hdl_gen] // <--- don't forget this
fn update(&mut self) {
// Setup the DFF.. this macro is handy to prevent latches
dff_setup!(self, clock, my_reg);
self.my_reg.d.next = self.sig_a.val() + self.sig_b.val();
self.sig_sum.next = self.my_reg.q.val();
}
}
At this point, we can convert MyAdder
into Verilog and use a standard toolchain to generate
a bitfile. However, we want to verify that the circuit operates properly. The simplest way
to do that would be to feed it a vector of random inputs, and make sure that the output
matches the sum of the inputs. Setting up a simulation can be a little verbose, so there
is a handy macro [simple_sim!] that works if you have only a single (top level) clock,
and only need one test bench.
** An aside on ownership **
We haven’t talked about the borrow checker much. And that is because by and large, RustHDL
does not use references. So how do the testbenches work? The key points for those of you
familiar with Rust are:
- The circuit must be Send. All RustHDL components are Send.
- The simulation uses a Box to hold the circuit.
- Each testbench runs in it’s own thread.
- The circuit is moved to each testbench as it runs via the endpoint.
- The testbench then updates the circuit inputs, and checks outputs. It is the
sole owner of the circuit at this point.
- The techbench then passes the circuit back to the simulation (moves) along with some
indication of when it needs to see it again.
- If a testbench is complete, it signals that it does not need to see the circuit again.
- When all testbenches are complete (or any of them report an error), the simulation
halts.
It takes a little getting used to, but the design allows you to write concurrent testbenches without worrying about shared mutable state.
So back to our adder. The testbench should look something like this
- set input A to some known value x
- set input B to some known value y
- wait a clock cycle
- check that the output matches the sum x + y
- loop until complete.
Here is a complete example:
use rand::{thread_rng, Rng};
use std::num::Wrapping;
// Build a set of test cases for the circuit. Use Wrapping to emulate hardware.
let test_cases = (0..512)
.map(|_| {
let a_val = thread_rng().gen::<u8>();
let b_val = thread_rng().gen::<u8>();
let c_val = (Wrapping(a_val) + Wrapping(b_val)).0;
(
a_val.to_bits::<8>(),
b_val.to_bits::<8>(),
c_val.to_bits::<8>(),
)
})
.collect::<Vec<_>>();
// The clock speed doesn't really matter here. So 100MHz is fine.
let mut sim = simple_sim!(MyAdder, clock, 100_000_000, ep, {
let mut x = ep.init()?; // Get the circuit
for test_case in &test_cases {
// +-- This should look familiar. Same rules as for HDL kernels
// v Write to .next, read from .val()
x.sig_a.next = test_case.0;
x.sig_b.next = test_case.1;
// Helpful macro to delay the simulate by 1 clock cycle (to allow the output to update)
wait_clock_cycle!(ep, clock, x);
// You can use any standard Rust stuff inside the testbench.
println!(
"Test case {:x} + {:x} = {:x} (check {:x})",
test_case.0,
test_case.1,
x.sig_sum.val(),
test_case.2
);
// The `sim_assert_eq` macro stops the simulation gracefully.
sim_assert_eq!(ep, x.sig_sum.val(), test_case.2, x);
}
// When the testbench is complete, call done on the endpoint, and pass the circuit back.
ep.done(x)
});
// Run the simulation - needs a boxed circuit, and a maximum duration.
sim.run(MyAdder::default().into(), sim_time::ONE_MILLISECOND)
.unwrap();
The above should write the following to your console (your numbers will be different)
Test case 5d + 98 = f5 (check f5)
Test case 3b + 44 = 7f (check 7f)
Test case 5d + b0 = 0d (check 0d)
Test case f8 + 38 = 30 (check 30)
Test case 73 + b5 = 28 (check 28)
Test case 1b + e5 = 00 (check 00)
Test case c1 + 89 = 4a (check 4a)
etc...
You can also generate a trace of the circuit using the vcd
(Value Change Dump) format, and
read the output using gtkwave
or some other vcd
viewer. RustHDL includes a simple
vcd
renderer for convenience, but its pretty basic, and mostly for creating documentation
examples. It does have the advantage of being callable directly from your testbench in case
you need some visual verification of your circuit.
We can make a one line change to our previous example, and generate a vcd
.
// Run the simulation - needs a boxed circuit, and a maximum duration.
sim.run_to_file(
MyAdder::default().into(),
sim_time::ONE_MILLISECOND,
&vcd_path!("my_adder.vcd"),
)
.unwrap();
vcd_to_svg(
&vcd_path!("my_adder.vcd"),
"images/my_adder.svg",
&[
"uut.clock",
"uut.sig_a",
"uut.sig_b",
"uut.my_reg.d",
"uut.my_reg.q",
"uut.sig_sum",
],
0,
100 * sim_time::ONE_NANOSECOND,
)
.unwrap()
The result of that simulation is here.
Note that the digital flip flop copies it’s input from d
to q
on the leading edge of the clock.
Generating Verilog
At some point, you will want to generate Verilog so you can send your design to other tools. This is pretty simple. You call [generate_verilog] and pass it a reference to the circuit in question. The [generate_verilog] function will check your circuit, and then return a string that contains the Verilog equivalent. It’s pretty simple.
Here is an example. We will reuse the MyAdder
circuit from the testbench section,
but this time, generate the Verilog for the circuit instead of simulating it.
use rust_hdl::prelude::*; // <- shorthand to bring in all definitions
// v--- Required by RustHDL
#[derive(LogicBlock, Default)]
struct MyAdder {
pub sig_a: Signal<In, Bits<8>>,
pub sig_b: Signal<In, Bits<8>>,
pub sig_sum: Signal<Out, Bits<8>>,
pub clock: Signal<In, Clock>,
my_reg: DFF<Bits<8>>,
}
impl Logic for MyAdder {
#[hdl_gen] // <--- don't forget this
fn update(&mut self) {
// Setup the DFF.. this macro is handy to prevent latches
dff_setup!(self, clock, my_reg);
self.my_reg.d.next = self.sig_a.val() + self.sig_b.val();
self.sig_sum.next = self.my_reg.q.val();
}
}
let mut uut = MyAdder::default();
uut.connect_all();
println!("{}", generate_verilog(&uut));
You should get the following generated code in your console:
module top(sig_a,sig_b,sig_sum,clock);
// Module arguments
input wire [7:0] sig_a;
input wire [7:0] sig_b;
output reg [7:0] sig_sum;
input wire clock;
// Stub signals
reg [7:0] my_reg$d;
wire [7:0] my_reg$q;
reg my_reg$clock;
// Sub module instances
top$my_reg my_reg(
.d(my_reg$d),
.q(my_reg$q),
.clock(my_reg$clock)
);
// Update code
always @(*) begin
my_reg$clock = clock;
my_reg$d = my_reg$q;
my_reg$d = sig_a + sig_b;
sig_sum = my_reg$q;
end
endmodule // top
module top$my_reg(d,q,clock);
// Module arguments
input wire [7:0] d;
output reg [7:0] q;
input wire clock;
// Update code (custom)
initial begin
q = 8'h0;
end
always @(posedge clock) begin
q <= d;
end
endmodule // top$my_reg
A few things about the Verilog generated.
- It is hierarchical (scoped) by design. The scopes mimic the scopes inside the RustHDL circuit. That makes it easy to map the Verilog back to the RustHDL code if needed when debugging.
- The code is readable and formatted.
- The names correspond to the names in RustHDL, which makes it easy to see the details of the logic.
- RustHDL (at least for this trivial example) is a pretty thin wrapper around Verilog. That’s good for compatibility with tooling.
While most FPGAs will require you to use a proprietary and closed source toolchain to synthesize your design, you can use the open source [Yosys] compiler (if you have it installed) to check your designs. For that, you can use the [yosys_validate] function, which runs the Verilog through some checks and reports on potential errors. At the moment, [Yosys] is far more thorough in it’s checking than RustHDL, so I highly recommend you install it and use the [yosys_validate] function on your generated Verilog.
Struct valued signals
We have seen how Enums and Interfaces can help make your code more compact and readable. There
is another abstraction you can use to simplify your code. Interfaces allow you to group together
signals that are logically related into a named bundle (like a bus). You can also group
together bits
into a logically related bundle that can be treated as a single entity.
While this is supported in RustHDL, it’s not frequently that useful. Nonetheless.
Suppose you have a set of signals to your circuit that all travel in the same direction, but are different widths. Any maybe some of the elements are enums. Something like this
struct Foo {
pub in_red: Signal<In, Bits<5>>,
pub in_green: Signal<In, Bits<8>>,
pub in_blue: Signal<In, Bits<8>>,
pub in_alpha: Signal<In, Bits<6>>,
}
Instead, we can define a struct and annotate it with [LogicStruct], which makes it into a type that can be used for a signal.
#[derive(Default, PartialEq, LogicStruct, Copy, Clone, Debug)]
struct Color {
pub red: Bits<5>,
pub green: Bits<8>,
pub blue: Bits<8>,
pub alpha: Bits<6>,
}
struct Foo {
pub in_color: Signal<In, Color>,
pub local_color: Signal<Local, Color>,
pub out_color: Signal<Out, Color>,
}
impl Logic for Foo {
#[hdl_gen]
fn update(&mut self) {
self.local_color.next = self.in_color.val(); // Copy the struct as a single atom
// v-- Extract a single field using standard `.field` notation
if self.local_color.val().alpha.get_bit(4) {
self.local_color.next.red = 16.into(); // Assign to a single field of the struct
}
self.out_color.next = self.local_color.val();
}
}
From within the HDL kernel, you can access the fields of the struct as you normally would. You can also assign entire structs to one another, as well as individual fields of a struct. The generated Verilog is messy, and I don’t use struct valued signals much. But if you need to use them they are there.
Loops and Arrays
A frequently useful feature of hardware is to be able to handle a variable number of inputs or outputs based on some parameter. Examples might include:
- A processing stage with a variable number of passes
- A mux with a variable number of inputs
- A bank of identical state machines, where the number of banks is variable
In all of these cases, the tool to reach for is an array in RustHDL. Including an array
of subcircuits is pretty simple. You simply use a static sized array (via a const generic
parameter) or a vec
. Here is an example of a circuit that contains a configurable number
of subcircuits, each of which is an instance of the Pulser
circuit (a standard RustHDL
widget)
struct PulserSet<const N: usize> {
pub outs: Signal<Out, Bits<N>>,
pub clock: Signal<In, Clock>,
pulsers: [Pulser; N]
}
In this case, as long as the members of the array implement Block
(i.e., are circuits),
everything will work as expected, including simulation and synthesis.
Frequently, though, having an array of subcircuits means you need a way to loop over them
in order to do something useful with their inputs or outputs. Loops are were software-centric
thinking can get you into trouble very quickly. In hardware, it’s best to think of loops
in terms of unrolling. A for
loop in RustHDL does not actually loop over anything in
the hardware. Rather it is a way of repeating a block of code multiple times with a varying
parameter.
So the impl Logic
HDL kernel of the [PulserSet] example above might look something like this:
impl<const N: usize> Logic for PulserSet<N> {
#[hdl_gen]
fn update(&mut self) {
// Connect all the clocks & enable them all
for i in 0..N {
self.pulsers[i].clock.next = self.clock.val();
self.pulsers[i].enable.next = true.into();
}
// Connect the outputs...
self.outs.next = 0.into();
for i in 0..N {
self.outs.next = self.outs.val().replace_bit(i, self.pulsers[i].pulse.val());
}
}
}
Note that we are both reading and writing from self.outs
in the same kernel, but we write
first, which makes it OK. Reading first would make this latching behavior, and RustHDL (or
yosys
) would throw a fit.
You can do some basic manipulations with the index (like using 3*i+4
, for example), but
don’t get carried away. Those expressions are evaluated by the HDL kernel generator and
it has a limited vocab.
High Level Synthesis
RustHDL supports it’s own version of High Level Synthesis (HLS). Normally, this is some kind of strange drag-and-drop based entry or visual programming paradigm. Worse, still, it could be some kind of macro meta-language that you build complex designs out of using a graphical editor.
But that is not the case here! RustHDL’s HLS approach is much simpler. Essentially, even though [Interfaces] are so great, you may not want to use them. So the core widgets, like the [AsynchronousFIFO] do not use Interfaces. That leads to some pretty gnarly circuit definitions. Here is the [AsynchronousFIFO] for example:
pub struct AsynchronousFIFO<D: Synth, const N: usize, const NP1: usize, const BLOCK_SIZE: u32> {
// Read interface
pub read: Signal<In, Bit>,
pub data_out: Signal<Out, D>,
pub empty: Signal<Out, Bit>,
pub almost_empty: Signal<Out, Bit>,
pub underflow: Signal<Out, Bit>,
pub read_clock: Signal<In, Clock>,
pub read_fill: Signal<Out, Bits<NP1>>,
// Write interface
pub write: Signal<In, Bit>,
pub data_in: Signal<In, D>,
pub full: Signal<Out, Bit>,
pub almost_full: Signal<Out, Bit>,
pub overflow: Signal<Out, Bit>,
pub write_clock: Signal<In, Clock>,
pub write_fill: Signal<Out, Bits<NP1>>,
// Internals ommitted...
}
Using an [AsynchronousFIFO] requires up to 14 separate signals! With mixed directions and types! Fortunately, there is an HLS wrapper type you can use instead. It’s much simpler
pub struct AsyncFIFO<T: Synth, const N: usize, const NP1: usize, const BLOCK_SIZE: u32> {
pub bus_write: FIFOWriteResponder<T>,
pub write_clock: Signal<In, Clock>,
pub bus_read: FIFOReadResponder<T>,
pub read_clock: Signal<In, Clock>,
fifo: AsynchronousFIFO<T, N, NP1, BLOCK_SIZE>,
}
In this case, it has only 4 signals, and using it is also much easier. You can use the [FIFOWriteResponder] and [FIFOWriteController] busses to send and receive data from the asynchronous fifo. Even better is the fact that this HLS construct is just a thin wrapper around the [AsynchronousFIFO], so when you synthesize it, or plot signals, there is nothing extra under the hood.
The HLS library also includes a sort of System-on-chip model in case you want to use it. It allows you to connect a set of widgets to a single controller, and route data to them over a fixed bus using a very simple protocol. It won’t replace AXI or WishBone, but it can be used to build some pretty complicated designs and remain readable. The test cases are a good place to look for some runnable examples of the different SoC widgets.
Wrapping IP Cores
Occasionally in RustHDL, you will need to wrap an external IP core or logic primitive supported
by your hardware, but that is not supported directly in RustHDL. There best method for wrapping
Verilog code is to use the Wrapper struct and provide your own implementation
of the hdl
method for your logic.
Here is a minimal example of a clock buffer primitive (that takes a differential clock input and provides a single ended clock output). The Verilog module declaration for the clock buffer is simply:
module IBUFDS(I, B, O);
input I;
input B;
output O;
endmodule
Since the implementation of this device is built into the FPGA (it is a hardware primitive), the module definition is enough for the toolchain to construct the device. Here is a complete example of a wrapped version of this for use in RustHDL.
#[derive(LogicBlock, Default)]
pub struct ClockDriver {
pub clock_p: Signal<In, Clock>,
pub clock_n: Signal<In, Clock>,
pub sys_clock: Signal<Out, Clock>,
}
impl Logic for ClockDriver {
// Our simulation simply forwards the positive clock to the system clock
fn update(&mut self) {
self.sys_clock.next = self.clock_p.val();
}
// RustHDL cannot determine what signals are driven based on the declaration
// alone. This method identifies `sys_clock` as being driven by the internal
// logic of the device.
fn connect(&mut self) {
self.sys_clock.connect();
}
// Normally the `hdl` method is generated by the `derive` macro. But in this
// case we implement it ourselves to wrap the Verilog code.
fn hdl(&self) -> Verilog {
Verilog::Wrapper(Wrapper {
code: r#"
// This is basically arbitrary Verilog code that lives inside
// a scoped module generated by RustHDL. Whatever IP cores you
// use here must have accompanying core declarations in the
// cores string, or they will fail verification.
//
// In this simple case, we remap the names here
IBUFDS ibufds_inst(.I(clock_p), .B(clock_n), .O(sys_clock));
"#.into(),
// Some synthesis tools (like [Yosys] need a blackbox declaration so they
// can process the Verilog if they do not have primitives in their
// libraries for the device. Other toolchains will strip these out.
cores: r#"
(* blackbox *)
module IBUFDS(I, B, O);
input I;
input B;
output O;
endmodule"#.into(),
})
}
}
Re-exports
pub use rust_hdl_hls as hls;
pub use rust_hdl_core as core;
pub use rust_hdl_sim as sim;
pub use rust_hdl_widgets as widgets;
Modules
- ! Tools for documenting RustHDL designs, including the generation of SVGs from simulation waveforms.
- ! Prelude module defines common symbols to make importing RustHDL easier.