Skip to content
jerryz123Public

About

An HDL built on Rhombus/Racket

Resources

Stars

11 stars

Watchers

1 watching

Forks

Repository files navigation

Rhodium

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.

Quick start

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.

Requirements

  • 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 rhombus

Put Moon on PATH, then prepare its task catalog from the checkout root:

python3 -m tools.ci.catalog

For the CIRCT route on x86-64 Linux or Apple Silicon macOS, install the pinned release into the ignored .tools directory:

moon run rhodium:setup-circt

For 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.

First circuit

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.

Composing a shared ALU

#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-lop

Run all canonical examples, including CIRCT-backed SystemVerilog reference checks (requires the CIRCT setup above):

moon run rhodium:examples

The test runner guide explains the available validation levels. Contributor setup and change validation are in DEVELOPING.md.

Mental model

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.

Authoring profiles

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.

Hardware and compilation model

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
Loading

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.

Design commitments

  • 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.

Explore the project

Learn the language

Inspect or extend the implementation

Explore hardware libraries, systems, and software

Physical and development tooling

Contributing

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.

License

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 status

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.md for its current contract.

About

An HDL built on Rhombus/Racket

Resources

Stars

11 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages