Torii Backends¶

Warning

The Torii API reference is a work in progress and we are actively working on improving it, however it may be deficient or missing in places.

Torii has 3 primary backends, RTLIL, Verilog, and CXXRTL, each takes a Torii Fragment or Elaboratable and produces an RTL netlist in the given output format.

The primary lingua franca of the Torii backends is RTLIL, the Verilog and CXXRTL backends first convert the IR into it, and then use Yosys to convert the RTLIL netlist into their respective output formats

RTLIL Backend¶

torii.back.rtlil.convert_fragment(fragment: Fragment, name: str = 'top', *, emit_src: bool = True) → tuple[str, SignalDict]¶

Recursively lower the given Torii Fragment into RTLIL text and a signal map.

Parameters:

fragment (torii.hdl.ir.Fragment) – The Torii fragment hierarchy to lower.
name (str) – The name of the root fragment module. (default: ‘top’)
emit_src (bool) – Emit source line attributes in the resulting RTLIL text. (default: True)

Returns:

The RTLIL text and signal dictionary of the lowered fragment.

Return type:

tuple[str, torii.hdl.ast.SignalDict]

torii.back.rtlil.convert(elaboratable, name: str = 'top', platform=None, *, ports, emit_src=True, missing_domain=<function <lambda>>) → str¶

Convert the given Torii Elaboratable into RTLIL text.

Parameters:

elaboratable (torii.hdl.ir.Elaboratable) – The Elaboratable to lower into RTLIL.
name (str) – The name of the resulting RTLIL module. (default: ‘top’)
platform (torii.build.plat.Platform) – The platform to use for Elaboratable evaluation.
ports (list[]) – The list of ports on the top-level module.
emit_src (bool) – Emit source line attributes in the final RTLIL text. (default: True)

Returns:

The resulting RTLIL.

Return type:

str

Verilog Backend¶

torii.back.verilog.convert_fragment(fragment: Fragment, name: str = 'top', emit_src: bool = True, strip_internal_attrs: bool = False) → tuple[str, SignalDict]¶

Recursively lower the given Torii Fragment into Verilog text and a signal map.

Parameters:

fragment (torii.hdl.ir.Fragment) – The Torii fragment hierarchy to lower.
name (str) – The name of the root fragment module. (default: ‘top’)
emit_src (bool) – Emit source line attributes in the resulting Verilog text. (default: True)
strip_internal_attrs (bool) – Remove Torii-specific attributes that were emitted into the resulting Verilog text.

Returns:

The Verilog text and signal dictionary of the lowered fragment.

Return type:

tuple[str, torii.hdl.ast.SignalDict]

torii.back.verilog.convert(elaboratable: ~torii.hdl.ir.Fragment | ~torii.hdl.ir.Elaboratable, name: str = 'top', platform=None, *, ports, emit_src: bool = True, strip_internal_attrs: bool = False, missing_domain=<function <lambda>>) → str¶

Convert the given Torii Elaboratable into Verilog text.

Parameters:

elaboratable (torii.hdl.ir.Elaboratable) – The Elaboratable to lower into Verilog.
name (str) – The name of the resulting Verilog module. (default: ‘top’)
platform (torii.build.plat.Platform) – The platform to use for Elaboratable evaluation.
ports (list[]) – The list of ports on the top-level module.
emit_src (bool) – Emit source line attributes in the final Verilog text. (default: True)
strip_internal_attrs (bool) – Remove Torii-specific attributes that were emitted into the resulting Verilog text.

Returns:

The resulting Verilog.

Return type:

str

CXXRTL Backend¶

torii.back.cxxrtl.convert_fragment(fragment: Fragment, name: str = 'top', emit_src: bool = True, black_boxes: dict[str, str] | None = None) → tuple[str, SignalDict]¶

Recursively lower the given Torii Fragment into CXXRTL text and a signal map.

Parameters:

fragment (torii.hdl.ir.Fragment) – The Torii fragment hierarchy to lower.
name (str) – The name of the root fragment module. (default: ‘top’)
emit_src (bool) – Emit source line attributes in the resulting CXXRTL text. (default: True)
black_boxes (dict[str, str]) – A map of CXXRTL blackboxes to use in the resulting design.

Returns:

The CXXRTL text and signal dictionary of the lowered fragment.

Return type:

tuple[str, torii.hdl.ast.SignalDict]

torii.back.cxxrtl.convert(elaboratable: ~torii.hdl.ir.Elaboratable, name: str = 'top', platform=None, black_boxes: dict[str, str] | None = None, *, ports, emit_src: bool = True, missing_domain=<function <lambda>>) → str¶

Convert the given Torii Elaboratable into CXXRTL text.

Parameters:

elaboratable (torii.hdl.ir.Elaboratable) – The Elaboratable to lower into Verilog.
name (str) – The name of the resulting Verilog module. (default: ‘top’)
platform (torii.build.plat.Platform) – The platform to use for Elaboratable evaluation.
ports (list[]) – The list of ports on the top-level module.
emit_src (bool) – Emit source line attributes in the final CXXRTL text. (default: True)
black_boxes (dict[str, str]) – A map of CXXRTL blackboxes to use in the resulting design.

Returns:

The resulting CXXRTL.

Return type:

str

Example¶

Lets say you have the following Torii design you would like to convert to Verilog:

class Blinky(Elaboratable):
    def elaborate(self, platform) -> Module:
        led   = Signal()
        timer = Signal(20)

        m = Module()
        m.d.sync += timer.eq(timer + 1)
        m.d.comb += led.eq(timer[-1])
        return m

You can do so by importing the torii.back.verilog.convert() method and then passing an instance of the elaboratable to it, like so:

from torii.back.verilog import convert

verilog = convert(Blinky(), name = 'blinker', ports = [])

That will result in the following Verilog code in verilog:

(* top =  1  *)
(* generator = "Torii" *)
module blinker(clk, rst, led);
  reg \$auto$verilog_backend.cc:2355:dump_module$1  = 0;
  (* src = "<python-input-8>:7" *)
  wire [20:0] \$1 ;
  (* src = "<python-input-8>:7" *)
  wire [20:0] \$2 ;
  (* src = "torii/hdl/ir.py:541" *)
  input clk;
  wire clk;
  (* src = "<python-input-17>:1" *)
  input led;
  wire led;
  (* src = "<python-input-8>:3" *)
  wire \led$4 ;
  (* src = "torii/hdl/ir.py:541" *)
  input rst;
  wire rst;
  (* src = "<python-input-8>:4" *)
  reg [19:0] timer = 20'h00000;
  (* src = "<python-input-8>:4" *)
  reg [19:0] \timer$next ;
  assign \$2  = timer + (* src = "<python-input-8>:7" *) 1'h1;
  always @(posedge clk)
    timer <= \timer$next ;
  always @* begin
    if (\$auto$verilog_backend.cc:2355:dump_module$1 ) begin end
    \timer$next  = \$2 [19:0];
    (* src = "torii/hdl/xfrm.py:576" *)
    if (rst) begin
      \timer$next  = 20'h00000;
    end
  end
  assign \$1  = \$2 ;
  assign \led$4  = timer[19];
endmodule