RTL and simulation¶
A cell can have an RTL view: a Verilog / SystemVerilog file in its library, <cell>.sv (or <cell>.v), defining
the module named like the cell. Create it with New cell (check RTL), or open an existing .sv / .v file's cell
from the library browser (the rtl chip). The file starts from a module template.
Editing¶
The RTL view is a code editor (CodeMirror) with Verilog / SystemVerilog highlighting (keywords, types, numbers, strings, system tasks, macros, comments). It also has:
- line numbers, folding and bracket matching;
- search and replace: Ctrl+F (Ctrl+G for the next match, Ctrl+Alt+G to go to a line);
- Tab to indent by two spaces;
- Ctrl+Z / Ctrl+Y for edits that are not saved yet.
Save (or Ctrl+S) writes the file, and every save is recorded in the library's operation log. So Undo / Redo (the arrows in the editor's header) and proposals work as for the other views: in a proposal the agent's RTL changes appear in the review and are adopted or discarded with the rest. A file a proposal created stays when the proposal is reverted, as created schematics do.
Lint¶
Lint runs Verilator (--lint-only -Wall) with this cell as the top module. The library's other RTL files are
sources too, so a cell that instantiates another one resolves it. Errors and warnings are listed with file and line;
clicking one in this cell's file goes to its line and column. In the editor, problems are underlined where Verilator
points (coral for errors, sand for warnings), the gutter marks their lines, and hovering shows the message. Saving lints
again.
Simulation¶
A testbench is an RTL cell too, for example tb_counter: it instantiates the design, drives it from initial
blocks, reports with $display, checks with $error / assertions, ends with $finish, and writes a waveform with
$dumpfile / $dumpvars. Simulate builds the testbench with Verilator (--binary --timing --trace) and runs it:
- the result is Passed when the run ends without an error; any
$error,$fatal, failed assertion or build error makes it Failed, with the error lines listed; - the testbench's output (
$display), where it finished, and Verilator's build warnings are shown; - the dumped signals are drawn as waveforms (vectors as their integer value; x / z as gaps).
Each run is a job in the project (runs/<id>/) with a copy of the sources it simulated, the log and wave.vcd.
The panel lists earlier runs of the chosen testbench.
RTL from a dependency¶
Verilator turns $c(...) and `systemc_* blocks into C++ that runs in the simulation, $system(...) runs a
shell, a DPI import calls C, and `include, $fopen, $dumpfile, $readmem* and $writemem* read or write files. In a
dependency's library, Undine refuses these until a person
trusts the dependency: Simulate refuses a library with any of them
(and with `define bodies that build them, or a path that is absolute or has a .. or ~); Lint, which
compiles nothing, refuses only such `include paths. Every RTL file of the dependency is read, also in folders.
The refusal names each file and line:
analog_ip/rtl/ctrl.sv (dependency analog_ip 1.2.0, not trusted): line 12: initial $c("init_model();"); a person can trust analog_ip@1.2.0 in this project (undine lib trust demo analog_ip, or Trust... in Undine); an agent cannot
The panel shows it with Trust..., which opens the trust dialog; trusting runs the RTL as it is, so read what the dialog lists first. Your own libraries' RTL is not checked.
Gate-level netlists of standard-cell schematics¶
A cell drawn from the PDK's standard cells (sky130's sky130_stdcells/*.sym) and with no RTL is read by Lint and
Simulate as its gate-level netlist: one Verilog module named like the cell, its ports in the schematic's order and
one instance per standard cell, every pin connected by name. The same holds for such a cell that a testbench
instantiates. The PDK's Verilog models of the cells are read with it (sky130: primitives.v and
sky130_fd_sc_hd.v), as functional models without delay (FUNCTIONAL, UNIT_DELAY empty); their own warnings are
not reported. A standard cell that the RTL defines itself (a stub) is taken from the RTL, and when the RTL defines
every standard cell it uses, no models are read. The power pins are inside `ifdef USE_POWER_PINS, which these runs leave undefined, so a
testbench connects the logic ports only.
LibreLane: RTL to GDS¶
The LibreLane tab builds the cell's layout from its RTL with LibreLane. A
flow configuration in the project (flows/<name>.yaml; Create a flow makes one for the cell) says how: the top
cell, the clock port and period (or none for a combinational design), the core utilisation, and any other LibreLane
variables, passed as they are. The cell's design intent supplies the rest: port sides become LibreLane's pin
order file (let the tool decide leaves a port to the placer), and supply / ground nets become VDD_NETS /
GND_NETS.
Before a run the tab lists what is missing (the clock, a side for each port) and the derived settings: every
setting the run passes to LibreLane with the flow or intent entries it comes from. They are derived again for each run
and kept with it (config.json, pin_order.cfg, constraints.json); change them in the flow or the intent, not in
the run. A run is a job (runs/<id>/): the panel shows LibreLane's log while it runs, then the key results (cells,
area, setup / hold slack and violations, DRC, LVS and antenna counts, max slew / capacitance / fanout violations,
power) and errors. Import layout merges the
final GDS into the cell's library, with the standard cells it uses.
From a schematic of standard cells¶
A flow with source: schematic builds a cell drawn from standard cells from its schematic, with no RTL. The run
writes the schematic's gate-level netlist into src/<cell>.v and LibreLane only reads it: no synthesis, and every
cell stays as drawn (a delay chain, tie cells). The run derives these settings, each with flow.source in the
derived settings, and a flow variable overrides any of them:
| Setting | Why |
|---|---|
SYNTH_ELABORATE_ONLY: true |
Yosys reads the netlist and maps nothing |
RSZ_DONT_TOUCH_RX: ".*" |
every net and instance is don't-touch for the resizer |
RUN_POST_GPL_DESIGN_REPAIR, RUN_POST_GRT_DESIGN_REPAIR: false |
no buffers on long nets or ports, no resizing |
RUN_CTS: false |
no clock tree: the clocks are wired as drawn |
RUN_POST_CTS_RESIZER_TIMING, RUN_POST_GRT_RESIZER_TIMING: false |
no timing repair |
DIODE_ON_PORTS: none, RUN_HEURISTIC_DIODE_INSERTION: false, RUN_ANTENNA_REPAIR: false |
no antenna diodes |
DRT_ANTENNA_REPAIR_JUMPER_ONLY: true |
detailed routing fixes antennas by layer jumps only |
The supplies are the nets on the cells' VPWR / VGND parameters (vdd, vss), which must be ports of the
schematic. They become VDD_NETS / GND_NETS together with the supplies in the intent, if it lists any. Their pins
are the power grid's straps, not pins on one edge: a side that the intent gives a supply port is not used, and the
check lists it under Not used by the run.
Before a run starts, the check refuses what the layout would leave unconnected. LibreLane only reads the netlist and
inserts no tie cell, so an input pin drawn straight on a supply, or an inner net with only inputs on it, would have
no driver. Draw a tie cell (sky130: sky130_fd_sc_hd__conb_1, HI for 1, LO for 0) and take the constant from it.
When a run ends, its result compares the final netlist with the drawn one: the logical cells added, removed or
changed (none when the netlist was kept), and apart from them the fill, tap, decap and diode cells the layout added.
A decap or a diode that the schematic draws is compared like any other cell. The result also lists the max slew,
max capacitance and max fanout violations at signoff, with the corners that have them. With no buffering and no
resizing, they are the schematic's to fix: a stronger driver, or a buffer drawn for a net with many loads. Timing is
checked with LibreLane's generic SDC unless the flow gives its own (PNR_SDC_FILE, SIGNOFF_SDC_FILE); for a
self-timed or asynchronous design, that slack says little.
For a cell that a flow builds from its schematic, the LibreLane panel is on the cell page, below the waterline (Show the flow). In the review, a flow configuration opens that page.
# flows/sar_logic.yaml
top: {lib: sar, cell: sar_logic}
source: schematic
clock: {port: clk, period_ns: 195.3}
floorplan: {die_area_um: [0, 0, 60, 60]}
variables: {RT_MAX_LAYER: met4, FP_PDN_MULTILAYER: false, FP_PDN_VPITCH: 25, FP_PDN_VOFFSET: 5, FP_PDN_VWIDTH: 1.6,
PL_TARGET_DENSITY_PCT: 60}
Once imported, the layout is checked against the schematic like any other (see Verification, "Standard cells in LVS").
LibreLane comes from Nix, its supported installation: install Nix with LibreLane's binary cache, clone LibreLane to
~/librelane, and run nix-shell --run "librelane --smoke-test" there once (the LibreLane installation
guide). Undine then runs it with
nix-shell ~/librelane --run …; UNDINE_LIBRELANE sets another command. Runs use the project's PDK as it is
installed (--manual-pdk).
The agent reads flows (list_flows, check_flow), starts runs (run_librelane) and reads their results
(get_librelane_result). It proposes a flow configuration with write_flow in its changeset: the file is part of
the proposal, the review shows it (view flow, under the top cell), and it reaches the project when you adopt the
proposal. check_flow also checks a configuration that is not saved yet (config). export_verilog shows the
gate-level netlist of a standard-cell schematic.
Caravel: macros into user_project_wrapper¶
For ChipFoundry's Caravel (SKY130), a design is hardened in two flows: the macro, then the wrapper that places it in the 2920 x 3520 um user area.
# flows/counter.yaml: the macro
top: {lib: dig, cell: counter}
clock: {port: clk, period_ns: 25}
floorplan: {die_area_um: [0, 0, 150, 150]}
caravel: {role: macro}
# flows/wrapper.yaml: the wrapper
top: {lib: dig, cell: user_project_wrapper}
caravel:
role: wrapper
template: ~/caravel_user_project
macros:
- {flow: counter, instance: mprj, location: [1400, 1700], orientation: N}
The macro (role: macro).
- It gets the user area's power pins:
vccd1/vssd1, declared in the RTL inside`ifdef USE_POWER_PINS. These pins need no side. - Its power grid has no top-level stripes, and routing stops at met4, so the wrapper's grid reaches it on met4 / met5.
The wrapper (role: wrapper).
- It takes the outline, pins, power rings and stripes, and timing constraints from a checkout of
chipfoundry/caravel_user_project. Undine does not ship it;
openlane/user_project_wrapperandverilog/rtlare all it reads. - Its RTL is the
user_project_wrappercell's rtl view. Start from the template'sverilog/rtl/user_project_wrapper.vand instantiate your macro under the instance name the flow gives it. - Each macro comes from the latest successful run of its flow. The run copies the macro's views into
macros/<flow>/and connects itsvccd1/vssd1to the wrapper's power grid (powernames other nets). - The wrapper has no standard-cell rows, so detailed routing fixes antennas with jumpers only, not diode cells.
Undine's own build of a counter macro into the wrapper passes LibreLane's Magic / KLayout DRC and LVS, and the ChipFoundry target's layout checks (see Tapeout).
The agent¶
The agent reads and writes RTL in its proposals: get_rtl, write_rtl (the whole file; the result includes the lint),
lint_rtl, and run_rtl_sim (the testbench's output, errors, finish and the last changes of each dumped signal), and
create_cell with views [rtl]. As for schematics, it works from the cell's design intent: an RTL cell's intent refers
to the ports of its module. A dependency's RTL that the trust rule refuses is refused for the agent too; it reports
the refusal and asks you, since only a person can trust a dependency.
Installing Verilator¶
pixi install adds Verilator (conda-forge) to Undine's environment. Verilator builds the simulation with a C++
compiler and make (the system's, or the environment's).