All code/text in this repo was generated by a coding agent following my direction, with the exception of this disclaimer.
Rhodium is an experimental hardware description language built for explicit hardware and extensible abstractions. Hosted by Rhombus, it combines programmable hardware generation with typed connections and composable language layers. Domain-specific types, library operators, and user-defined notation can feel like native language features while remaining inspectable down to the hardware they describe.
Every layer builds the same small, verified hardware IR. Connectivity and priority are explicit, without last-connect semantics or competing drivers. That shared foundation supports protocol-aware flow composition, transaction tracing, clock-crossing checks, and validated network generation. Rhodium emits SystemVerilog directly or through CIRCT, and Rsim generates native C++ simulation models. Each backend has an explicit supported subset.
The comparison guide
explains the principles that distinguish Rhodium, what its layers and libraries
make possible, and how those choices compare with other hardware languages.
Contributors should start with DEVELOPING.md.
Moon is the standard entry point for repository builds, examples, and tests. Rhodium itself runs on Racket/Rhombus. See the contributor quick start for change validation and configured simulator or benchmark workflows.
- Racket 9.2 or a compatible current release
- Rhombus 1.1
- Moon 2.6.5 for repository builds and tests
- Device Tree Compiler for DTB interoperability tests and FESVR simulations
- CIRCT for the CIRCT-to-SystemVerilog route; direct SystemVerilog emission does not require it
- Verilator and a C++ toolchain for Verilator-based simulations; standalone Rsim models require a C++17 toolchain but neither CIRCT nor Verilator
- Rosette only for optional equivalence, reachability, and output-property tests
On a Homebrew-based macOS setup:
brew install minimal-racket dtc
raco pkg install --auto rhombusPut Moon on PATH, then prepare its task catalog from the checkout root:
python3 -m tools.ci.catalogFor the CIRCT route on x86-64 Linux or Apple Silicon macOS, install the pinned
release into the ignored .tools directory:
moon run rhodium:setup-circtFor Verilator-based simulation, build the pinned Verilator 5.048 (requires a C++ toolchain, Autoconf, Bison, Flex, Make, Perl, Python 3, and zlib/LZ4 development libraries):
moon run rhodium:setup-verilator
export PATH="$PWD/.tools/verilator/bin:$PATH"Moon test tasks prefer this installation automatically.
On other platforms, install CIRCT separately and set CIRCT_OPT to the path of
circt-opt when using the CIRCT route. See the
backend guide for route-specific coverage and usage.
Start with a parameterized combinational adder:
#lang rhodium
/* Defines a fixed-width combinational adder. */
/* Adds two inputs, wrapping the result to the selected width. */
circuit Adder(width :: PosInt):
input(a, b): Bits(width)
output sum: Bits(width)
sum <== a + b
def program = elaborate(Adder(8))
export:
Adder
program
width is chosen during elaboration; a, b, and sum are runtime hardware
signals. Here, the generated circuit adds two eight-bit inputs.
#lang rhodium
/* Shares one ALU datapath among buffered clients, with a result FIFO for downstream stalls. */
import:
lib("flow/main.rhdl") open
hardware_enum Operation:
Add
Xor
And
/* Keeps each operation and its operands together through buffering. */
bundle ALURequest(width :: PosInt):
op: Operation
a: Bits(width)
b: Bits(width)
/* Builds the selected fixed-width operation on this request's operands. */
method evaluate(request) :: Bits(width):
mux_lookup(request.op):
Operation.Add: request.a + request.b
Operation.Xor: request.a ^ request.b
Operation.And: request.a & request.b
/* Identifies the client that owns a computed ALU result. */
bundle ALUResponse(width :: PosInt, clients :: PosInt):
client: Bits(index_width(clients))
value: Bits(width)
/* Chooses the datapath width and client count during elaboration. */
sync_circuit SharedALU(width :: PosInt, clients :: PosInt):
def Request = ALURequest(width)
interface ingress[clients](Decoupled(Request), ~role: consumer)
interface egress(Irrevocable(ALUResponse(width, clients)), ~role: producer)
/* Generates one two-entry FIFO per client, preserving each client's request order. */
def buffered = ingress |> parallel_handles(
for Array (_ in 0..clients): Request |> queue(2)
)
inst arbiter(RRArbiter(Request, clients))
buffered <=> arbiter.ingress
/* |> connects hardware stages. Requests stay ordered within each client;
round-robin arbitration sets result order. Evaluation after arbitration
creates one shared datapath; the selected client index tags each result.
Backpressure propagates upstream; the output FIFO holds stalled results stable. */
(
arbiter.egress |> map_flow(request):
ALUResponse(width, clients):
client: arbiter.chosen
value: request.evaluate()
) |> queue(2) |> egress
/* Instantiates three clients sharing a 16-bit datapath. */
def program = elaborate(SharedALU(16, 3))
export:
SharedALU
program
See Flow for the composition and protocol contracts.
Run the language-oriented programming examples (requires the CIRCT setup above):
moon run rhodium:examples-lopRun all canonical examples, including CIRCT-backed SystemVerilog reference checks (requires the CIRCT setup above):
moon run rhodium:examplesThe test runner guide explains the available validation
levels. Contributor setup and change validation are in
DEVELOPING.md.
A Rhodium source file contains two kinds of computation:
- Host computation is ordinary Rhombus. Host values, functions, loops, and conditionals decide what hardware is generated during elaboration.
- Hardware computation describes runtime signals, state, memories, and hierarchy. Hardware values have explicit types and cannot control ordinary host conditionals.
Calling elaborate runs the host program and returns the selected hardware as
a DesignElaboration containing the completed RTL design and explicit top.
Pass that program to compile_program(program, target);
the selected target owns verification, lowering, and emission. Macro expansion
and frontend layers share the same public core IR.
| Profile | Intended use | Provides |
|---|---|---|
#lang rhodium |
Normal design work | Rhombus, the foundational circuit surface, and the curated frontend layers |
#lang rhodium/base |
Language composition and focused extensions | Rhombus and the foundation; the program explicitly imports any additional layers |
The foundation supplies circuits, ports, connections, elaboration, and basic hardware types. Selectable layers add notation, types, static information, and authoring policy. Ordinary standard and domain libraries build on the public language; they are not compiler layers.
This diagram illustrates the shared hardware model and available output routes; it is not the implementation dependency graph.
flowchart TB
standard["#lang rhodium<br/>foundation + curated layers"]
base["#lang rhodium/base<br/>foundation + explicit layer imports"]
libraries["Standard and domain libraries<br/>ordinary public Rhodium code"]
frontend["Frontend notation, types,<br/>static information, and policy"]
kernel["Elaboration kernel<br/>context-sensitive construction"]
core["Verified public core IR<br/>types, values, places, operations, and resources"]
analysis["Analysis and diagrams"]
formal["Formal engine"]
circt["Optional CIRCT backend"]
direct["Direct SystemVerilog backend"]
rsim["Rsim backend"]
sv["SystemVerilog"]
cpp["C++ simulation model"]
standard --> frontend
base --> frontend
libraries --> frontend
frontend --> kernel
kernel --> core
core --> analysis
core --> formal
core --> circt
core --> direct
core --> rsim
circt --> sv
direct --> sv
rsim --> cpp
The architectural boundary is semantic rather than syntactic. A concept belongs in core only when verification and every backend must preserve its hardware meaning. Notation, organization, reusable host descriptions, and policy over existing operations belong in frontend layers or ordinary libraries. Optional derived facts and reports belong in analysis packages.
The public package map is in rhodium/README.md. Its
enforced implementation graph and direct-dependency inventories are maintained
in rhodium/DEVELOPING.md.
- One public, inspectable hardware IR rather than frontend-specific IRs.
- Explicit widths and conversions, fixed-width arithmetic, and deterministic host elaboration.
- Readable values and driveable places with exactly one effective driver.
- Frontend-defined types and notation that reuse core semantics whenever possible.
- Backends consume verified IR and never import frontend syntax.
- Explicit compilation targets own lowering and emission, with documented backend-specific coverage.
The Rhodium comparison guide places these choices alongside construction languages, rule-based and functional HDLs, timing-typed research languages, compiler IRs, multi-level modeling systems, and SystemVerilog.
examples/README.md— executable language walkthrough and example catalogrhodium/frontend/README.md— elaboration, profiles, and extension boundariesrhodium/frontend/layers/README.md— frontend feature and syntax guiderhodium/std/README.md— host utilities, protocols, and reusable circuit generatorsrhodium/compile/README.md— target selection, compilation results, and ordered RTL instrumentation
DEVELOPING.md— contributor entry point and change workflowrhodium/README.mdandrhodium/DEVELOPING.md— public package map and enforced implementation architecturerhodium/core/README.mdandrhodium/core/DEVELOPING.md— public IR semantics and core implementation guidancerhodium/analysis/README.md— clock/reset inventory, temporal provenance, and CDC diagnosticsrhodium/diagram/README.md— logical hierarchy, interface, and flow diagramsrhodium/event/README.md— event dependency inference and compiler instrumentationrheg/README.md— C++ event collection and streaming or standalone Perfetto exportrhodium/backend/README.md— CIRCT lowering, direct SystemVerilog emission, and Rsim C++ simulationrhodium/formal/README.md— Rosette equivalence, reachability, and output propertiestools/testing/README.mdandtools/testing/DEVELOPING.md— running validation and maintaining the test architecture
flow/README.md— streaming buffers, arbitration, routing, packet adapters, and typed pipeline compositiondevicetree/README.md— validated host-side device trees with native DTS and DTB encodingnoc/README.md— graph-validated NoC authoring and hardware bridgeriscv/README.md— RISC-V instruction model and Rhodium adapterhardfloat/README.md— Berkeley HardFloat portchi/README.mdanddevices/README.md— AMBA CHI and platform devicescores/README.mdandsocs/README.md— reusable processors and SoC compositionsims/README.md— executable SoC simulation harnessessw/README.md— pinned target software, bare-metal ports, and workload builders
rfpl/README.md— physical views over existing Rhodium circuitssram/README.md— technology-independent SRAM mappingvlsi/README.md— physical integration and mapped simulationsupport/README.md— dependency-neutral Rhombus refinementstools/emacs/README.md— project-aware Emacs integration
Read DEVELOPING.md before changing implementation packages,
tests, generated references, or documentation ownership. Package-level
DEVELOPING.md files refine that repository-wide workflow without redefining
their sibling README's public contract. Contributions must carry the
Signed-off-by certification described in the contribution and provenance
policy.
Except where noted otherwise, original Rhodium content is licensed under the Apache License 2.0. The Berkeley HardFloat port retains its upstream BSD terms, and Git submodules retain the licenses of their pinned upstream repositories; see third-party notices.
Rhodium's license applies to Rhodium itself, not to a user's input design merely because the compiler processes it. Generated output is not automatically placed under Apache-2.0 for that reason. Portions copied from or derived from bundled Rhodium library or hardware-IP implementations remain subject to their applicable licenses and notices.
Current capabilities include:
- A public, backend-independent IR with explicit-width types, structural aggregates, state, memories, assertions, DPI simulation operations, single-driver verification, and combinational-cycle detection.
- Standard and compositional profiles with host-only generation, frontend-defined scalar and aggregate types, combinational and sequential constructs, hierarchy, directional interfaces, and reusable protocols.
- CIRCT and direct SystemVerilog routes, Rsim C++ simulation models, and Verilator-based simulation harnesses, within each backend's supported subset.
- Ordered RTL instrumentation passes, including event tracing, with verified output graphs and preserved top-level interfaces and instance paths.
- Optional Rosette-backed equivalence, reachability, and universal output properties over verified IR.
- Backend-independent clock/reset inventory, temporal-provenance reports, CDC violations, and structurally verified stable-level crossing evidence.
- Logical diagrams plus RFPL physical annotations that leave logical IR and generated RTL unchanged.
- RV5Stage, a five-stage RV32/RV64 processor with floating point, optional vector
support, privilege and trap state, coherent L1 caches, CHI integration, and
experimental RV64 hypervisor support. See
cores/rv5stage/README.mdfor its current contract.