Expand description
! Prelude module defines common symbols to make importing RustHDL easier.
Re-exports§
pub use crate::docs::vcd2svg::vcd_to_svg;
Modules§
Macros§
- bus_
address_ strobe - bus_
write_ strobe - clock
- The [clock!] macro is used to connect a set of devices to a common clock. The macro takes a variable number of arguments:
- declare_
async_ fifo - declare_
expanding_ fifo - declare_
narrowing_ fifo - declare_
sync_ fifo - dff_
setup - hls_
fifo_ read - hls_
fifo_ read_ lazy - hls_
fifo_ write - hls_
fifo_ write_ lazy - hls_
host_ drain - hls_
host_ get_ word - hls_
host_ get_ words - hls_
host_ issue_ read - hls_
host_ noop - hls_
host_ ping - hls_
host_ put_ word - hls_
host_ write - i2c_
begin_ read - i2c_
begin_ write - i2c_
end_ transmission - i2c_
read - i2c_
read_ last - i2c_
write - sim_
assert - sim_
assert_ eq - simple_
sim - target_
path - vcd_
path - wait_
clock_ cycle - wait_
clock_ cycles - wait_
clock_ false - wait_
clock_ true
Structs§
- AD7193
Config - AD7193
Simulator - ADS868X
Simulator - AsyncFIFO
- AsynchronousFIFO
- Auto
Reset - Base
Controller - Bidi
BusD - Bidi
BusM - Bidi
Master - Bidi
Simulated Device - BitSynchronizer
- A BitSynchronizer is used to move signals that are asynchronous to a clock into that clock domain using a pair of back-to-back flip-flops. While the first flip flop may become metastable, the second one is likely to be stable.
- Black
Box - The BlackBox struct provides a way to wrap a blackbox, externally provided IP core.
- Bridge
- Clock
- Fundamentally a Clock signal in RustHDL is simply a transparent wrapper around a boolean valued signal. So it could be thought of as a simple 1-bit wide signal. However, semantically, clocks are rarely treated like other signals, and typically connect only to dedicated clock ports on synchronous logic (like [DFF] or [RAM]).
- Constant
- The Constant wrapper can hold any Synth type
and store it in a circuit for use by the HDL kernel.
This is the easiest way to compute complex constants
in your RustHDL constructors, and then store the
results inside the circuit for later use. Unlike
Signal, Constant does not have a
.nextfield, so you cannot assign to a Constant in the HDL kernel (blocked at compile time). Note that Constant does notimpl Default. You must construct it with the appropriate value when the circuit is built. - Cross
Narrow - Cross
NarrowFIFO - Cross
Widen - Cross
WidenFIFO - DFF
- DFFWith
Init - Delay
Line - Edge
Detector - Expander
- FIFO
ExpanderN - FIFO
Link - FIFO
Read Controller - FIFO
Read Responder - FIFO
Reducer - FIFO
ReducerN - FIFO
Write Controller - FIFO
Write Responder - Fader
With SyncROM - False
Path Regexp - HLSSPI
Master - HLSSPI
Master Dynamic Mode - HLSSPI
MuxMasters - HLSSPI
MuxSlaves - Host
- I2CBus
Driver - I2CBus
Receiver - I2CConfig
- I2CTarget
- I2CTest
Bus - I2CTest
Target - In
- This direction marker is used for a [Signal] that is an input with respect to a circuit. That means that we do not expect to write to the input, but that the value will be set by external components to the circuit.
- InOut
- Input
Timing Constraint - LFSR
Simple - LazyFIFO
Feeder - LazyFIFO
Reader - Local
- MAX31856
Simulator - MISOFIFO
Port - MISO
Port - MISO
Wide Port - MOSIFIFO
Port - MOSI
Port - MOSI
Wide Port - Memory
Timings - Module
Defines - Multiply
Accumulate Symmetric Finite Impulse Response Filter - MuxMasters
- MuxSlaves
- MuxedA
D7193 Simulators - MuxedAD
S868X Simulators - Named
Path - Open
Drain Buffer - Open
Drain Driver - Open
Drain Receiver - Out
- This direction marker is used for a [Signal] that leaves a circuit as an output. That means we expect this circuit to drive the signal using its internal logic. It is an error in RustHDL to leave an output undriven.
- Output
Timing Constraint - Periodic
Timing - PinConstraint
- Pulse
Width Modulator - Pulser
- RAM
- ROM
- Reducer
- RegisterFIFO
- Router
- RouterROM
- SDRAM
Base Controller - SDRAM
Burst Controller - SDRAM
Controller - SDRAM
Controller Tester - SDRAM
Driver - SDRAMFIFO
- SDRAMFIFO
Controller - SDRAM
OnChip Buffer - SDRAM
Simulator - SPIConfig
- SPIConfig
Dynamic Mode - SPIMaster
- SPIMaster
Dynamic Mode - SPISlave
- The SPISlave is mostly meant for testing the [SPIMaster], but you can use it to implement a SPI endpoint in the FPGA if you want to. This SPISlave is not very robust, so be cautious with using it. In particular, with a very badly behaved SPI master, it may not operate as expected.
- SPIWires
Master - SPIWires
Slave - Shot
- Signal
- Signed
- Sim
- The
Simstruct is used to communicate with a simulation. Every testbench will be provided with a copy of this struct, and will use it to communicate with the core simulation. - Simulation
- This type represents a simulation over a circuit
T. To simulate a circuit, you will need to construct one of these structs. - SoCBus
Controller - SoCBus
Responder - SoCPort
Controller - SoCPort
Responder - SoCTest
Chip - Strobe
- A Strobe generates a periodic pulse train, with a single clock-cycle wide pulse
at the prescribed frequency. The argument [N] of the generic Strobe
is used to size the counter that stores the internal delay value. Unfortunately, Rust const generics are currently not good enough to compute [N] on the fly. However, a compile time assert ensures that the number of clock cycles between pulses does not overflow the [N]-bit wide register inside the Strobe. - SyncFIFO
- SyncROM
- Sync
Receiver - A SyncReceiver works together with a SyncSender to transmit data from one clock domain to another (in one direction). To use a SyncReceiver wire up the [sig_cross], [flag_in] and [ack_out] signals between the two.
- Sync
Sender - When you need to send many bits between two clock domains, it is risky to use a vector of BitSynchronizer structs. That is because, you cannot guarantee at any given moment that all of the bits of your multi-bit signal will cross into the new clock domain at once. So to synchronize a multi-bit signal, use a SyncSender and SyncReceiver pair. These widgets will use a set of handshake signals to move a value from one clock domain to another safely. Note that while the state machine is executing, the synchronizer will indicate it is busy. Crossing clock domains with greater ease is best done with an [AsynchronousFIFO].
- SynchronousFIFO
- Timing
Info - TopWrap
- Tristate
Buffer - Tristate Buffer
- Type
Descriptor - Type
Field - Vector
Synchronizer - A VectorSynchronizer uses a SyncSender and SyncReceiver in a matched pair to transmit a vector of bits (or any Synth type from one clock domain to a second clock domain without metastability or data corruption. You can think of a VectorSynchronizer as a single-element asynchronous FIFO, and indeed [AsynchronousFIFO] uses the VectorSynchronizer internally.
- Vivado
Input Timing Constraint - Vivado
Output Timing Constraint - Wrapper
- The Wrapper struct provides a more convenient and flexible way to wrap external IP cores than BlackBox.
Enums§
- Bits
- The Bits type holds a bit array of size [N].
- Constraint
- Output
Buffer - SDRAM
Command - Signal
Type - SimError
- The error type returned by a simulation
- Slew
Type - Synth
Error - Timing
- Timing
Relative - Timing
Relative Edge - Type
Kind - VCDValue
- Verilog
- The Verilog type is used to represent the Verilog translation of a RustHDL kernel. You will only need it if implementing blackbox cores or wrapping external Verilog code.
- Word
Order
Constants§
- AD7193_
REG_ WIDTHS - NANOS_
PER_ FEMTO - The number of nanoseconds per femtosecond.
- SIMULATION_
TIME_ ONE_ SECOND
Traits§
- Block
- The Block trait is required for all circuitry that
can be simulated by RustHDL. If you want to be able
to simulate a circuit, the corresponding struct must
impl Block. Normally, this is done via the
#[derive(LogicBlock)]construct, and you will rarely, if ever, need to impl the Block trait yourself. - HLSNamed
Ports - Logic
- Logic
Join - Logic
Link - Probe
- Synth
- ToBits
- The ToBits trait is used to provide a way to convert Rust standard unsigned
types (currently
u8, u16, u32, u64, u128) into Bits of different lengths. Note that RustHDL will panic if you attempt to convert an unsigned type into a Bits that is too small to hold the value. - ToSigned
Bits - Verilog
Visitor
Functions§
- bit_
cast - Cast from one bit width to another with truncation or zero padding The bit_cast function allows you to convert from one bit width to another. It handles the different widths in the following simplified manner: - if casting to a narrower bit width, the most significant bits are discarded until the new value fits into the specified bits - if casting to a wider bit width, the most significant bits are padded with zeros until the new value occupies the specified bits This may seem a bit counterintuitive, but it fits logical circuitry behavior. Narrowing is usually done by preserving the least significant bits (so that the carry bits are discarded when adding, for example). Widening is also usually done (for unsigned values) by zero extending the most significant bits. The bit_cast operation does both of these operations depending on the arguments.
- bits
- Convenience function to construct Bits from an unsigned literal Sometimes, you know you will be working with a value that is smaller than 128 bits (the current maximum sized built-in unsigned integer in Rust). In those cases, the bits function can make construction slightly simpler.
- bursty_
rand - bursty_
vec - check_
all - This is a helper function used to check a Block for connection, loops, and writes to the inputs.
- check_
connected - Check to see if a circuit is properly connected (no undriven inputs, or multiply-driven outputs). You can call this directly on a circuit of yours if you want to check that it is correctly connected internally.
- check_
timing - clog2
- Compute the minimum number of bits to represent a container with t items.
This is basically
ceil(log2(t))as a constant (compile time computable) function. You can use it where a const generic (bit width) argument is required. - filter_
blackbox_ directives - freq_
hz_ to_ period_ femto - Convert a frequency in Hz to a period in femtoseconds.
- generate_
verilog - generate_
verilog_ unchecked - signed
- signed_
bit_ cast - signed_
cast - simulate
- Update changes to a circuit until it stabilizes
- snore
- unsigned_
bit_ cast - unsigned_
cast - write_
vcd_ change - write_
vcd_ dump - write_
vcd_ header - yosys_
validate
Type Aliases§
- Bit
- A type alias for a simple bool. You can use them interchangeably.
- Literal
Type - The LiteralType is used to set the type for literals that appear in RustHDL expressions. Because of how Rust’s type inference currently works, an expression like