vyges physical dpl — CLI reference

Generated from vyges physical dpl --help — this page is the tool’s own output, verbatim.

vyges physical dpl — detailed placement: legality checking and legalization over the design database

USAGE:
  vyges physical dpl check-placement    <design.odb> [--json] [-o FILE] [--padding-* ...] [--pdn-aware]
  vyges physical dpl detailed-placement <design.odb> [--out-odb FILE] [--dry-run] [OPTIONS]
  vyges physical dpl filler-placement   <design.odb> PATTERN... [--prefix P] [--out-odb FILE]
  vyges physical dpl remove-fillers     <design.odb> [--out-odb FILE]
  vyges physical dpl optimize-mirroring <design.odb> [--out-odb FILE] [--pdn-aware]
  vyges physical dpl improve-placement  <design.odb> [--out-odb FILE] [--random-seed N] [--max-displacement X[,Y]]
                                        (in progress: mis/gs/vs/ro not built; --rng-skip N stands in)
  vyges physical dpl --describe | --help | --version

OPTIONS:
  --out-odb FILE            write the legalized database here (default: nothing is written)
  --dry-run                 legalize and report, write no database
  --use-diamond-legalizer   use the diamond search instead of negotiation (the reference's flag)
  --max-displacement N[,M]  cap the move at N sites and M rows (default: 500,100)
  --site-search-window N    base search width along the row, in sites (default: 20)
  --row-search-window N     base search height, in rows (default: 5)
  --drc-penalty F           cost added per DRC violation at a candidate site (default: 5)
  --disable-window-extension  do not widen the search window past a macro or a wall
  --pdn-aware               keep cells clear of fixed supply (PDN) vias; also accepted by
                            check-placement and optimize-mirroring, which then check them too
                            (the reference's -pdn_aware, which later commands inherit)
  -o FILE                   write the report to FILE instead of stdout
  --json                    emit JSON (the default)
  --describe                print a machine-readable JSON description of the command

EXIT STATUS:
  0  legalized   every cell was seated; the database was written unless --dry-run
  0  clean       check-placement found no violation
  0  vacuous     the run placed nothing -- NOT a completed legalization; read the count
  1  failed      a cell could not be seated, or a check family found violations
  2  error       usage error, an unreadable database, or a failed write

⛔ SCOPE: legalization runs the NEGOTIATION legalizer, which is the reference's default path;
   `--use-diamond-legalizer` selects the diamond one, as the reference's own flag does. Whichever
   runs, what it does NOT implement is named in `not_done` on every run rather than omitted,
   and every instance the model filter excluded is named in `filtered_out`.

⚠️ All nine of the reference's check families are evaluated. A family that cannot run on a design
   is reported in `not_checked` rather than passed over in silence, and a family that ran under
   a restriction says so in `limitations`.

ℹ️ `-disallow_one_site_gaps` has no equivalent here ON PURPOSE: the reference deprecated it and
   derives the setting from `hasOneSiteMaster()`, so the flag cannot change the result.
   `-incremental` is not implemented and is named in `not_done`.

Contract

Generated from vyges physical dpl --describe.

dpl

detailed placement: legality checking and legalization over the design database

Maturity: structured

check-placement {odb}

Consumes: odb

Artifacts: placement_check (report_path), odb (out_odb)

Assertion: placement-legal — passes when status equals clean

Provenance limitations

• input_hash covers the argument vector, not the content of the .odb it names.
• LEGALIZATION is implemented and is the default path: the NEGOTIATION legalizer, which is what the reference’s detailed_placement runs when -use_diamond_legalizer is absent. --use-diamond-legalizer selects the other one. The two produce DIFFERENT placements, so the report names which ran.
• At pin 4155ac31, detailed_placement matches the reference on 83 of 83 comparable cases (log 71 of 71), including the six pdn_via cases run with -pdn_aware (fixed supply vias: a pin or obstruction of the cell may not come within the via layer’s spacing of a supply via, unless the pin is on the via’s own net). Earlier, at pin 27288f5c90265ae5296b2f5a9fa6e8714fa191ad, detailed_placement matched the reference on 78 of 78 comparable cases, including the 2 cases the reference added in that window for pins under power-via-stack metal (blocked_via_layers; blocked_via_pins, decided by optimize_mirroring): a pin shape that would touch power via or patch metal outside the stripes, grown by the layer’s min spacing less one, is a blocked-layers violation in the legalizer, the checker and mirroring alike. Earlier, at pin da9f29f18b6487825aa880597176e0fa97110b31, with placement padding modelled, detailed_placement matched the reference on 67 of 67 comparable cases – a case with no archived golden is scored against a fresh reference run of its own flow – including aes (21340 components), cases followed by filler_placement or remove_fillers and scored with them, eight region (fence) designs on both legalizers, and every optimize_mirroring case (mirror1-3 on gcd, 138-140 cells flipped; mirror_edge_spacing, where the edge-spacing rule vetoes a flip). Skipped, and named: the 9 cases that run only improve_placement (NOT implemented), and 3 whose input file is not in the reference checkout. Earlier, at pin 7d490b8ecd357199c0c0e9f3e32becd5eb507c34, it matched 28 of 28 comparable cases from its own regression suite, including aes (21340 components), ibex (34184) and gcd (549). The agreement is SWEEP-LEVEL, not final-placement only – the reference’s per-iteration debug trace and this engine’s match line for line, every cell, every iteration, on simple05, simple07, gcd (574 lines) and hybrid_cells.
• It read 18 of 28 when the pin first moved from 945a9f48dc6e5cc91d865daa92c45a1094cb682c, because the reference reworked the negotiation legalizer’s INITIAL SNAPPING across 7 commits and refreshed 24 of its own goldens. Four mechanisms were transcribed to recover it: Grid::gridRoundX (initial x ROUNDS to the nearest site rather than truncating), displacementInSites/rowDispInSites replacing the deleted NegCell::displacement() so displacement is site widths on BOTH axes, initialSnap()’s diamond search in place of a four-direction scan, and – the one that mattered most – running that snap as its OWN pass after every fixed cell is blockaded, testing grid CAPACITY rather than merely whether a site exists.
• BUT 35 of the reference’s 63 detailed_placement cases are OUTSIDE that number and are not scored at all: 12 ship no golden, 8 need filler placement, 7 declare REGIONS/GROUPS, 7 need placement padding values, 1 needs both. 18 of 28 is a claim about what the corpus asks, not about every design.
• AND THE DENOMINATOR IS SHORT: the reference ships 69 .tcl cases calling detailed_placement, not 63. Five of them – report_failures, fragmented_row03, pad02, fillers8, obstruction2 – wrap the call as catch { detailed_placement }, so the harness’s command filter does not see them and they are scored by nothing. All five are error-path cases.
• All four of countDRCViolations terms are evaluated by the legalizer: edge spacing, padding, one-site gaps and checkBlockedLayers – both its stages, the vertical M2/M3 stripe mask against the layers a cell’s pins use (and the one above, for via access), and the power via / patch metal against each pin shape placed at the candidate position and orientation. checkEdgeSpacing reads each master’s LEF58 cell edges and the technology’s cell-edge spacing table from the database; the reference’s edge_spacing case matches component for component, its sweep trace identical.
• Every instance the model filter excluded is named and counted in filtered_out on every run. A filter that drops instances silently is indistinguishable from a design that has none of them.
• -disallow_one_site_gaps is NOT accepted: the reference deprecated it (DPL-3/DPL-4) and derives the setting from hasOneSiteMaster(), so the flag cannot change the result. -incremental is not implemented and is named in not_done.
• All NINE of the reference’s check families are evaluated: site alignment, placed, overlap, in_rows, region_placement, padding, edge_spacing, blocked_layers and one_site_gap. A family that cannot run on a design is named in the report’s not_checked field, because a clean verdict from a partial checker must not read as a complete one. Families that ran under a restriction are named in limitations rather than left to be inferred.
• Site alignment is CORE-RELATIVE: the reference compares cell->getLeft() % siteWidth where getLeft() is relative to core_.xMin(). Measured on aes.defok, reading it as an absolute coordinate reports every one of 21340 cells misaligned on a design the reference calls clean.
• A site-alignment failure removes the cell from the overlap comparison entirely. That is a side effect of the reference’s continue, not a separate rule: checkOverlap is what paints a cell into its pixels, so a cell that was skipped is never there for a later cell to collide with.
• OVERLAP is the reference’s pixel walk, in the reference’s visit order (instances sorted by NAME): a cell fails only when a square it covers already holds an EARLIER cell it genuinely overlaps, so only the later cell of a pair is reported. An earlier rectangle sweep reported both, and its claim that the failing set matched was wrong – the checker gate measured it on check2.
• status is one of clean, violations, vacuous or error. VACUOUS IS NOT CLEAN: it means the run examined no cell, and a design with no instances is an absent placement rather than a legal one.
• check-placement is scored by a gate over every reference case that calls check_placement: the reference places the design, our checker reads that database, and its failing cells per family are compared with a fresh reference run’s own warnings. At pin 4155ac31, 85 of 85 comparable cases agree, and 85 of 85 with –raw; –pdn-aware adds the fixed supply vias family. At pin 27288f5c90265ae5296b2f5a9fa6e8714fa191ad, 77 of 78 comparable cases agree; in the one that differs, blocked_via_layers (added to the reference in that window), the reference reports 2 blocked-layer cells and this checker none, because the reference now also blocks pins under power-via-stack metal. At pin da9f29f18b6487825aa880597176e0fa97110b31, 76 of 76 comparable cases agreed, set_placement_padding passed as –padding-* flags. Skipped, and named: 3 whose input file is not in the reference checkout. Every case is legalized before it is checked, so a second run (–raw) checks the INPUT placement instead, where the families actually fail: 76 of 76 agree there too, region_placement failing on all 8 region designs. One-site gaps are checked in a second pass after every cell is painted, with the checker’s own checkOneSiteGaps; no comparable case reports one, so that rule is pinned by constructed cases only. Earlier, at pin 945a9f48dc6e5cc91d865daa92c45a1094cb682c, it was correlated by hand on three designs.

dpl.detailed_placement

legalize the placement – negotiated congestion by default

detailed-placement {odb}

Assertion: placement-legalized — passes when status equals legalized

dpl.filler_placement

fill every empty site run with filler masters

filler-placement {odb} {patterns}

Assertion: placement-filled — passes when status equals filled

dpl.remove_fillers

destroy every filler instance (an unlocked CORE_SPACER)

remove-fillers {odb}

Assertion: fillers-removed — passes when status equals removed

dpl.optimize_mirroring

flip placed cells about Y where that does not lengthen their nets

optimize-mirroring {odb}

Assertion: mirroring-optimized — passes when status equals optimized

dpl.improve_placement

detailed placement improvement (mis, global/vertical swap, reorder, random moves, orient)

improve-placement {odb}

Assertion: placement-improved — passes when status equals improved