Skip to main content

SHDL

A gate-level hardware description language. Describe circuits out of AND, OR, NOT and XOR, compile them to native code, and watch signals ripple through them one gate delay at a time.

Build your first circuitWhat is SHDL?
halfAdder.shdl
component HalfAdder(A, B) -> (Sum, Carry) {
    x1: XOR;  a1: AND;

    connect {
        A -> x1.A;  B -> x1.B;  x1.O -> Sum;
        A -> a1.A;  B -> a1.B;  a1.O -> Carry;
    }
}

Every gate, every cycle

A unit-delay model: each gate takes one cycle, so signals visibly ripple through your design. No tool in the chain collapses or optimizes the structure you wrote.

A small, readable language

Components, multi-bit ports, slices, concatenation, compile-time parameters, generators, when conditionals, named constants, initial state and imports. Four primitive gates underneath.

Compiled, not interpreted

shdlc turns the flat netlist into C and builds a shared library with a six-function ABI you can call from Python, C or anything with an FFI.

One Python class

Circuit runs flatten, compile, build and load in-process, then gives you poke/peek/step, dict-style access, batch runs and full circuit metadata.

Projects and packages

The shdl CLI scaffolds projects, vendors libraries from the Circuit Circus index with a committed lockfile, runs test vectors and opens a live REPL.

Verified end to end

A frozen conformance corpus pins byte-exact flattener output and cycle-by-cycle traces; two independent reference interpreters cross-check the compiler.

Drive it from Python

from SHDL import Circuit

with Circuit("examples/adder8.shdl") as c:
    c["A"] = 100
    c["B"] = 55
    c.settle()          # advance max_depth (17) gate levels
    print(c["Sum"])     # 155

The toolchain

  .shdl source ──► shdl-flatten ──► Base SHDL ──► shdlc ──► C ──► cc ──► shared library
                  (flattener)     netlist of                           reset / poke / peek /
                                  AND OR NOT XOR                       step / step_settle /
                                  + JSON metadata                      run_batch
                                                                             │
                              PySHDL  (from SHDL import Circuit) ◄──────────┘ ctypes

Install with pip install PySHDL (Python 3.14+ and a C compiler). See Installation.