RustHDL

RustHDL is a crate designed for writing FPGA firmware using the Rust programming language. It works by compiling a subset of Rust into Verilog, enabling you to use standard FPGA synthesis tools with your Rust-based designs.

Key capabilities include:

• Synthesis: Compiles a subset of Rust to Verilog for FPGA synthesis.
• Simulation & Verification: Provides tools for testing and verifying hardware logic.
• Analysis: Includes tools for analyzing designs.
• Strongly Typed Interfaces: Uses Rust's type system to ensure design correctness before hardware deployment.

RustHDL integrates with or is inspired by several key hardware description and FPGA toolchains:

• YoSys: Used by RustHDL for Verilog synthesis and static analysis to check designs for potential errors.
• Icarus Verilog: A software-based, open-source Verilog simulator used for design verification.
• Verilator: A professional-grade simulation tool. RustHDL aims to generate Verilog compatible with Verilator for high-performance simulation.
• OpalKelly FrontPanel API: RustHDL provides bindings to the OpalKelly FrontPanel API, making it easy to interface with OpalKelly FPGA modules.
• MyHDL: A Python-based HDL generation approach that influenced some of RustHDL's conceptual design.
• LucidHDL & AlchitryLabs: Projects from Alchitry that served as early inspirations for the development of RustHDL.

RustHDL provides guidance and support for several different FPGA programming models. You can choose an approach based on your familiarity with hardware description languages or your preference for high-level programming languages:

• Verilog: A traditional approach adapted from simulating circuits to describing them.
• Lucid: An approach focused on improving ergonomics and Developer Experience (DX) compared to Verilog.
• Python-based (MyHDL/MiGen/Python): Approaches that use Python to describe firmware and hardware logic.

RustHDL is a hardware description language (HDL) implemented in Rust that provides several core benefits for firmware and hardware design:

• Safety: Uses Rust's strongly typed interfaces to check validity at compile time, run time, synthesis, and on the device.
• Performance: Allows running simulations of designs directly from Rust code with high performance.
• Readability: Generates readable Verilog code for synthesis and implementation, facilitating timing and conflict resolution.
• Reusability: Supports parametric firmware via templates and a composition model based on Rust structs.
• Batteries Included: Provides a library of basic firmware widgets including FIFOs, RAMs, ROMs, Flip-flops, SPI components, and PWMs.
• Open Source: All RustHDL code and firmware are open source and free to use.

RustHDL is a crate that allows you to write FPGA firmware using a subset of Rust. It compiles your Rust code into Verilog, which can then be synthesized using standard FPGA tools.

Core Workflow

1. Model Circuits: Use Rust structs to represent circuits, composed of sub-circuits (widgets) and signal wires.
2. Define Logic: Implement the Logic trait for your struct and provide an update(&mut self) method. This method acts as the HDL kernel.
3. Annotate: Use #[derive(LogicBlock)] on your struct and #[hdl_gen] on your update method to enable simulation and Verilog generation.
4. Simulate & Synthesize: Run simulations directly in Rust or use a Board Support Package (BSP) to generate bitstreams for specific hardware.

RustHDL provides High Level Synthesis (HLS) wrappers to simplify the connection of complex core widgets. While core widgets like AsynchronousFIFO expose many individual signals (e.g., 14 separate signals for a FIFO), HLS wrappers group these into manageable bus-like structures.

These HLS constructs are thin wrappers; they do not add overhead during synthesis or signal plotting, as they map directly to the underlying core signals.

# use rust_hdl::prelude::*;
// The HLS wrapper simplifies the 14 signals of AsynchronousFIFO into 4 signals
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>,
}

Loops in RustHDL follow hardware design principles rather than software execution principles. A for loop does not represent a temporal loop in the hardware. Instead, it is used for unrolling: it is a way to repeat a block of code multiple times during the HDL kernel generation process with a varying parameter.

When you use a for loop in an impl Logic block, the generator unrolls the loop to create the corresponding hardware connections or logic for each iteration.

impl<const N: usize> Logic for PulserSet<N> {
    #[hdl_gen]
    fn update(&mut self) {
        // This loop is unrolled by the generator to connect N clocks
        for i in 0..N {
           self.pulsers[i].clock.next = self.clock.val();
           self.pulsers[i].enable.next = true.into();
        }
    }
}

In RustHDL, you can handle a variable number of inputs, outputs, or subcircuits by using arrays. You can implement these using a statically sized array (via a const generic parameter) or a vec.

As long as the members of the array implement the Block trait (meaning they are circuits), they will work correctly during both simulation and synthesis. This is useful for creating processing stages with variable passes, muxes with variable inputs, or banks of identical state machines.

# use rust_hdl::prelude::*;

struct PulserSet<const N: usize> {
    pub outs: Signal<Out, Bits<N>>,
    pub clock: Signal<In, Clock>,
    pulsers: [Pulser; N]
}

RustHDL's simulation model is designed to allow concurrent testbenches without shared mutable state by leveraging Rust's ownership system:

1. Threaded Execution: Each testbench runs in its own thread.
2. Circuit Ownership: The simulation engine holds the circuit in a Box.
3. The Endpoint (ep): The circuit is moved to the testbench via an endpoint. The testbench becomes the sole owner of the circuit during its execution phase.
4. Handover: The testbench updates inputs and checks outputs, then moves the circuit back to the simulation engine using ep.done(x).
5. Termination: The simulation halts when all testbenches are complete or any testbench reports an error.