vyges-opendb — CLI reference

Generated from vyges-opendb --help. Do not edit by hand — run scripts/gen-cli-reference.sh.

vyges-opendb — OpenROAD's OpenDB (libodb) design database

usage:
  vyges-opendb <command> [options]

commands:
  info                --input <f.odb>
                      Print a one-line summary: block name + inst/net/bterm counts.

  insert-eco-buffers  --input <in.odb> --output <out.odb> [--config <eco.json>]
                      Insert ECO buffers (INSERT_ECO_BUFFERS in the config) into the design.

  insert-eco-diodes   --input <in.odb> --output <out.odb> [--config <eco.json>]
                      Tie antenna diodes (INSERT_ECO_DIODES in the config) onto target nets.

  manual-global-placement  --input <in.odb> --output <out.odb> [--config <cfg.json>]
                      Set instance origins (MANUAL_GLOBAL_PLACEMENT in the config).

  manual-macro-placement   --input <in.odb> --output <out.odb> [--config <cfg.json>]
                      Place + orient macros (MANUAL_MACRO_PLACEMENT in the config).

  diodes-on-ports     --input <in.odb> --output <out.odb> [--config <cfg.json>]
                      Tie antenna diodes onto I/O port nets (DIODES_ON_PORTS in the config).

  cell-frequency-tables     --input <f.odb>
                      Print a JSON table of instance count per master cell (report).

  report-disconnected-pins  --input <f.odb>
                      Print a JSON list of pins/ports with no net (report).

  set-power-connections     --input <in.odb> --output <out.odb> [--config <cfg.json>]
                      Wire instance pins to (power) nets (SET_POWER_CONNECTIONS in the config).

  add-obstructions          --input <in.odb> --output <out.odb> [--config <cfg.json>]
                      Add routing/PDN obstruction rects (OBSTRUCTIONS in the config).

  remove-obstructions       --input <in.odb> --output <out.odb>
                      Remove all obstructions.

  write-verilog-header      --input <f.odb> [--output <f.v>]
                      Emit a Verilog module header (ports + directions).

  report-wire-length        --input <f.odb>
                      Print the total routed wire length as JSON (report).

  report-connectivity       --input <f.odb>
                      Dump the netlist connectivity graph as JSON (report).

  read-3dblox               --input <f.3dbx> --output <out.odb> [--into <in.odb>]
                      Read a 3Dblox assembly (the 2.5D/3D interchange format) into a
                      database, so it can be linted or queried. Reports anything the
                      format expresses and the database cannot.
  view-3dblox               --input <f.3dbx|f.odb> --output <out.svg|out.png> [--heatmap]
                            [--top <chip>] [--scale <n>]
                      Draw the assembly: cross-section + plan, with any check-3dblox
                      findings listed on it. Format follows the output extension.
                      --heatmap shades MEASURED die-to-die misalignment onto the
                      plan view (from check-d2d); it is not a yield prediction.
  check-d2d                 --input <stack.3dbx> | --top <a.bmap> --bottom <b.bmap>
                            [--offset-x <um>] [--offset-y <um>] [--flip-x]
                            [--tolerance <um>]
                      Check a die-to-die interface: unmated bumps, misalignment, net
                      and bump-cell mismatch across the bond. Emits JSON.
  check-3d-nets             --input <stack.3dbx> [--tolerance <um>] [--no-tsv-inference]
                      Check net continuity across the whole stack: a net a die cannot
                      carry from one face to the other, and nets the bonding shorts
                      together. Emits JSON.
  check-3dblox              --input <f.odb>
                      3D/chiplet structural sign-off lint; reports violations as JSON (check).

  apply-eco-plan            --input <in.odb> --plan <plan.json> --output <out.odb>
                      Replay a timing-repair plan (all-or-nothing) into the design.

  custom-io-placement       --input <in.odb> --output <out.odb> [--config <cfg.json>]
                      Place I/O port pins (CUSTOM_IO_PLACEMENT in the config).

  write-def                 --input <f.odb> --output <f.def>
                      Export the design to a DEF 5.8 file (libodb v1 LEF/DEF I/O).

  read-def                  --input <in.odb> --def <f.def> --output <out.odb>
                      Import a DEF into the design (libodb v1 LEF/DEF I/O).

  apply-def-template        --input <in.odb> --template <f.def> --output <out.odb>
                      Apply a template DEF's floorplan (Odb.ApplyDEFTemplate).

  fields              [--class <dbClass>] [--writable]
                      List the generated instrumentation fields (discovery; JSON).

  get                 --input <f.odb> --class <dbClass> --field <name> [--key <k>]...
                      Read any generated field by (class, field) + addressing keys (JSON).

  set                 --input <in.odb> --output <out.odb> --class <dbClass> --field <name>
                      [--key <k>]... [--value <v>]...
                      Apply a generated setter (requires a build with --features gen-write).

  --version, -V       Print the version.
  --help,    -h       Print this help.

Step contracts

Generated from vyges-opendb <step> --describe.

insert-eco-buffers

Splice ECO buffers into a placed .odb (database surgery; legalization is a separate step).

LibreLane step: Odb.InsertECOBuffers · Unix only

Config keys

• INSERT_ECO_BUFFERS (array) — buffers to insert; each rewires the target pin’s driver through a new buffer
  • target (string) — instance/pin to buffer, e.g. inst42/A
  • buffer (string) — library cell master, e.g. sky130_fd_sc_hd__buf_2

insert-eco-diodes

Tie antenna diodes onto target nets in a placed .odb (database surgery; a diode is a leaf, no rewiring).

LibreLane step: Odb.InsertECODiodes · Unix only

Config keys

• INSERT_ECO_DIODES (array) — diodes to insert; each ties an antenna diode onto the target pin’s net (no rewiring)
  • target (string) — instance/pin whose net gets a diode, e.g. inst42/A
  • diode (string) — antenna-diode master, e.g. sky130_fd_sc_hd__diode_2

manual-global-placement

Set instance origins in a .odb before global placement (database surgery).

LibreLane step: Odb.ManualGlobalPlacement · Unix only

Config keys

• MANUAL_GLOBAL_PLACEMENT (array) — instances to fix at an origin
  • instance (string) — instance name
  • x (integer) — origin x in DBU
  • y (integer) — origin y in DBU

manual-macro-placement

Place + orient macros in a .odb (database surgery).

LibreLane step: Odb.ManualMacroPlacement · Unix only

Config keys

• MANUAL_MACRO_PLACEMENT (array) — macros to place + orient
  • instance (string) — macro instance name
  • x (integer) — origin x in DBU
  • y (integer) — origin y in DBU
  • orient (string) — R0/R90/R180/R270/MX/MY/MXR90/MYR90 (optional)

diodes-on-ports

Tie antenna diodes onto I/O port nets in a placed .odb (database surgery).

LibreLane step: Odb.DiodesOnPorts · Unix only

Config keys

• DIODES_ON_PORTS (object) — tie an antenna diode onto each selected port’s net
  • diode (string) — antenna-diode master, e.g. sky130_fd_sc_hd__diode_2
  • ports (array) — specific port names; omitted/empty = all ports

cell-frequency-tables

Report instance count per master cell as JSON (read-only).

LibreLane step: Odb.CellFrequencyTables · Unix only

Output: JSON array of { master, count } on stdout, most-used first

report-disconnected-pins

Report instance pins + ports that carry no net, as JSON (read-only).

LibreLane step: Odb.ReportDisconnectedPins · Unix only

Output: JSON array of strings on stdout: “inst/pin” and “port:name”

set-power-connections

Wire instance pins to (power) nets in a .odb (database surgery).

LibreLane step: Odb.SetPowerConnections · Unix only

Config keys

• SET_POWER_CONNECTIONS (array)
  • instance (string) — instance name
  • pin (string) — power/ground pin, e.g. VPWR
  • net (string) — net to connect it to, e.g. VDD

add-obstructions

Add routing/PDN obstruction rectangles to a .odb (database surgery).

LibreLane step: Odb.AddPDNObstructions / Odb.AddRoutingObstructions · Unix only

Config keys

• OBSTRUCTIONS (array)
  • layer (string) — tech layer name, e.g. met1
  • llx (integer) — lower-left x (DBU)
  • lly (integer) — lower-left y (DBU)
  • urx (integer) — upper-right x (DBU)
  • ury (integer) — upper-right y (DBU)

write-verilog-header

Emit a Verilog module header (ports + directions) from a .odb (read-only).

LibreLane step: Odb.WriteVerilogHeader · Unix only

Output: Verilog module header text

report-wire-length

Report the total routed wire length (DBU) as JSON (read-only).

LibreLane step: Odb.ReportWireLength · Unix only

Output: JSON { total_wire_length_dbu } on stdout

read-3dblox

read a 3Dblox 2.5D/3D assembly description into an OpenDB database

Maturity: experimental

read-3dblox --input {input} --output {output}

Artifacts: odb (output)

Provenance limitations

• Nested instance paths and virtual bonds (bot: ~) are read and reported as unrepresented.
• Polygonal regions collapse to their bounding rectangle; each loss is reported by name.
• One technology per database: a stack whose dies use different processes cannot be fully represented.

view-3dblox

draw a chiplet assembly as SVG or PNG: cross-section, plan, linter findings, and an optional die-to-die misalignment heat map

Maturity: experimental

view-3dblox --input {input} --output {output}

Artifacts: drawing (output)

Provenance limitations

• The Z axis is exaggerated so the stack is legible; the factor is printed on the drawing and dimensions must not be measured off it.
• Geometry only: no routing, no bumps drawn individually, no per-die layer stack.
• –heatmap shows MEASURED die-to-die misalignment, not predicted yield. Yield needs process inputs (particle density, Cu recess, surface roughness) that no layout carries; this is the layout-side input such a model consumes.
• –heatmap needs a .3dbx input with bump maps on both mating faces; without them the drawing is produced without a map and a note is written to stderr.
• Heat-map samples are drawn at a legible minimum size, so a dense bump field merges into regions rather than resolving individual bumps.
• A .odb input needs –top because the database has no top-chip getter.

check-d2d

check a die-to-die interface from two bump maps: unmated bumps, misalignment, net and cell mismatch

Maturity: experimental

check-d2d --input {input}

Output: JSON on stdout. Two shapes: with –input, { interfaces: […], interfaces_checked, interfaces_skipped, violations }; with –top/–bottom, one interface object directly. An interface carries { violations, by_kind, top_bumps, bottom_bumps, matched, tolerance_um, tolerance_source, frame, transform, findings, parse_errors }. Every finding is DATA, not only prose: { kind, message, x_um, y_um } always, plus distance_um and signed dx_um/dy_um for ‘misaligned’, and top/bottom bump objects { inst, cell, x_um, y_um, port, net } for every paired kind. Exits non-zero when violations > 0.

Provenance limitations

• With –input the frame comes from the assembly. In the two-file form the relative placement is NOT inferred — pass –offset-x/–offset-y/–flip-x. Either way the frame used is echoed in the report.
• A bonded pair whose regions declare no bmap is listed under interfaces_skipped, not counted as clean.
• Compares bump maps, not extracted layout: it checks what the maps claim, not what was fabricated.
• Default tolerance is half the smaller bump pitch, derived from the maps; –tolerance overrides.

check-3d-nets

check net continuity across a whole chiplet stack: a net a die cannot carry from one face to the other, and nets the bonding shorts together

Maturity: experimental

check-3d-nets --input {input}

Output: JSON { violations, by_kind, nets, bumps, groups, unnetted_bumps, net_source, tsv_inference, interfaces_checked, bonds, interfaces_skipped, regions_skipped, findings, parse_errors } on stdout. Finding kinds: severed and net-merged are violations; unresolved and tsv-unused are informational. Exits non-zero when violations > 0.

Provenance limitations

• Net names come from the .bmap files the assembly points at, not from a netlist or a loaded database — the report always states net_source.
• A netName belongs to its own die’s netlist, so net identity comes from the graph (same name within one die, plus whatever the bonding mates) and never from name equality across unbonded dies. Anything needing an assembly netlist is declined rather than guessed.
• A through-path inside a TSV die is inferred from net names matching across the die’s two faces. 3Dblox and odb’s 3D chip schema carry only a per-die tsv boolean, no TSV positions; odb can hold TSV shapes on a dbTechLayer of LEF58 type TSV/TSVMETAL, but that is the LEF_file/DEF_file leg this reader does not read. –no-tsv-inference turns the inference off.
• A bond whose surfaces declare no bmap, a virtual bond, and a nested instance path are listed under interfaces_skipped, not counted as clean.
• Read-only: it never modifies the assembly or any database.

check-3dblox

3D/chiplet structural sign-off lint over a multi-die assembly: logical connectivity, floating chips, overlapping dies, unused internal_ext regions, connection-region overlap and mating-surface gap vs connection thickness, bump alignment, and alignment markers. Read-only: reports violations as markers, never modifies the design.

Unix only

Output: JSON { violations, categories: [{ category, count, markers: [{ name, comment }] }] } on stdout; exit 0 regardless of findings

apply-eco-plan

Replay a timing-repair ECO plan (vyges-eco-plan-v1, as emitted by vyges-sta-si) into the design. All-or-nothing: any failing fix rolls the whole plan back. Does NOT legalize — run detailed placement, re-extract parasitics and re-time afterwards.

Unix only

Output: JSON { applied, inserted: [names] } on stdout

report-connectivity

Dump the netlist connectivity graph (per-net sig-type, special flag, and pins) as JSON, highest-degree net first (read-only).

Unix only

Output: JSON array of { net, sig_type, special, iterms, bterms, degree } on stdout

custom-io-placement

Place I/O port pins at fixed locations/layers in a .odb (database surgery).

LibreLane step: Odb.CustomIOPlacement · Unix only

Config keys

• CUSTOM_IO_PLACEMENT (array)
  • port (string) — port (bterm) name
  • layer (string) — tech layer, e.g. met3
  • llx (integer) — lower-left x (DBU)
  • lly (integer) — lower-left y (DBU)
  • urx (integer) — upper-right x (DBU)
  • ury (integer) — upper-right y (DBU)

write-def

Export a placed design to a DEF 5.8 file (libodb v1 LEF/DEF I/O).

LibreLane step: odb write_def · Unix only

read-def

Import a DEF into an existing design (its tech/libs) — libodb v1 LEF/DEF I/O.

LibreLane step: odb read_def · Unix only

apply-def-template

Apply a template DEF’s floorplan (DIEAREA/TRACKS/ROWS/COMPONENTS/PINS) to a design.

LibreLane step: Odb.ApplyDEFTemplate · Unix only

fields

List the generated instrumentation fields (class, field, value/keys) for discovery.

Unix only

Output: JSON array of { class, field, value|values, keys } on stdout

get

Read any generated field by (class, field) with string-encoded addressing keys.

Unix only

Output: the field value as JSON on stdout

set

Apply a generated setter by (class, field). Requires a –features gen-write build (L2/write).

Unix only

Output: writes the edited .odb; a one-line confirmation on stderr

No published contract: info, remove-obstructions — run vyges-opendb <step> --help for these.