UCS TSV Plan 使用手册

source ./ucs_tsv_region_flow.tcl
set result [ucs_tsv_region_flow -config ./examples/region_incremental.json]

{
  "flow_mode": "incremental",
  "selected_regions": [
    "region_1"
  ],
  "out_dir": "./out/incremental",
  "debug_level": 4,
  "default": {
    "signal_tsv_ref_names": [
      "TSV_SIGNAL*"
    ],
    "power_tsv_ref_names": [
      "TSV_PG*"
    ],
    "tsv_region_merge_upsize": 50.0,
    "tsv_region_merge_downsize": 50.0,
    "guide_buffer_lib_cell": "YOUR_BUFFER_LIB_CELL",
    "cross_net_mode": "pre_route",
    "skip_clock_nets": true,
    "incremental_search_height_multiplier": 2.0,
    "assignment_strategy": "nearest",
    "shielding_mode": "compact",
    "shape_offset": -2.5,
    "cell_down_y_offset": 0.0,
    "cell_up_y_offset": 0.0,
    "ratio_period_tracks": 100,
    "ratio_reserved_tracks": 5,
    "gap_reserved_tracks": 10,
    "force_gap_every_n_nets": 500,
    "power_tsv_x_guardband": 0.2,
    "shield_net": "VSS",
    "allow_compact_fallback": false,
    "inter_set_gap_multiplier": 5,
    "special_guard_tracks": 1
  },
  "global": {
    "available_layers": [
      "T3M*",
      "T2M*"
    ]
  },
  "regions": {
    "region_1": {
      "search_height": 200,
      "plan_sets": [
        {
          "name": "auto_cross"
        }
      ]
    }
  }
}

# Run in FC from the package directory, after editing the JSON for your design.
source ./ucs_tsv_region_flow.tcl
set result [ucs_tsv_region_flow -config ./examples/region_incremental.json]
# Generation only. Inspect logs, assignments and failures before execution.
dict for {region details} $result {
    puts "Region: $region"
    puts "Geometry log: [dict get $details geometry_log]"
    puts "Assignments: [llength [dict get $details plan assignments]]"
    puts "Failures: [llength [dict get $details plan failures]]"
}
# Separately preview the generated Tcl (replace region_1 if changed in JSON):
# set ::UCS_TSV_DRYRUN 1
# source ./out/incremental/region_1/implement.tcl

{
  "flow_mode": "replan",
  "selected_regions": [
    "region_1"
  ],
  "default": {
    "signal_tsv_ref_names": [
      "TSV_SIGNAL*"
    ],
    "power_tsv_ref_names": [
      "TSV_PG*"
    ],
    "guide_buffer_lib_cell": "YOUR_BUFFER_LIB_CELL",
    "assignment_strategy": "sequential",
    "shielding_mode": "compact",
    "ratio_period_tracks": 100,
    "ratio_reserved_tracks": 5,
    "gap_reserved_tracks": 10,
    "force_gap_every_n_nets": 500,
    "shape_offset": -2.5,
    "cell_down_y_offset": 0.0,
    "cell_up_y_offset": 0.0,
    "power_tsv_x_guardband": 0.2,
    "skip_clock_nets": true,
    "incremental_search_height_multiplier": 2.0,
    "shield_net": "VSS",
    "allow_compact_fallback": false,
    "inter_set_gap_multiplier": 5,
    "special_guard_tracks": 1,
    "tsv_region_merge_upsize": 50.0,
    "tsv_region_merge_downsize": 50.0
  },
  "global": {
    "available_layers": [
      "T3M*",
      "T2M*"
    ]
  },
  "regions": {
    "region_1": {
      "plan_sets": [
        {
          "name": "pins",
          "start_x": 10,
          "plan_objects": [
            [
              "pin",
              "u_data*/D",
              "top_to_bottom"
            ]
          ]
        },
        {
          "name": "control",
          "start_x": 100,
          "ratio_period_tracks": 8,
          "ratio_reserved_tracks": 2,
          "gap_reserved_tracks": 2,
          "force_gap_every_n_nets": 3,
          "plan_objects": [
            [
              "pin",
              "a*b",
              "bottom_to_top"
            ]
          ]
        }
      ]
    }
  },
  "out_dir": "./out/replan",
  "debug_level": 4
}

# Run in FC from the package directory, after editing the JSON for your design.
source ./ucs_tsv_region_flow.tcl
set result [ucs_tsv_region_flow -config ./examples/region_replan.json]
# Generation only. Inspect logs, assignments and failures before execution.
dict for {region details} $result {
    puts "Region: $region"
    puts "Geometry log: [dict get $details geometry_log]"
    puts "Assignments: [llength [dict get $details plan assignments]]"
    puts "Failures: [llength [dict get $details plan failures]]"
}
# Separately preview the generated Tcl (replace region_1 if changed in JSON):
# set ::UCS_TSV_DRYRUN 1
# source ./out/replan/region_1/implement.tcl

filter_collection $connected "object_class == pin && port_type == signal || object_class == port"

set ::UCS_TSV_DRYRUN 1
source ./out/replan/region_1/implement.tcl
# 检查后另行执行：
set ::UCS_TSV_DRYRUN 0
source ./out/replan/region_1/implement.tcl

# 在包目录下，加载一个已经打开设计的 FC session
source ./ucs_tsv_plan_proc.tcl
# 若需要 JSON 批处理入口，改为加载下面这个文件（它会加载 proc 文件）
source ./ucs_tsv_plan.tcl

plan_nets -help
check_track_occupancy -help

set objects {
    {net data_bus[0] top_to_bottom}
    {pin u_hier/data_in top_to_bottom}
    {port DATA_OUT bottom_to_top}
}
# 花括号内的 bus [0] 是字面名字，不会发生 Tcl 命令替换。

# objects.txt
type name direction
net {data_bus[0]} top_to_bottom
pin u_hier/data_in top_to_bottom
port DATA_OUT bottom_to_top

# Source from the package directory in an FC design session.
# Replace all object names, layers, bbox, lib_cell and row_height first.
# Generating the plan does not execute connectivity/placement edits.
source ./ucs_tsv_plan_proc.tcl

# The relevant cells must already be placed.
# data_down: driver above y=1100; far loads below y=1000.
# data_up: driver below y=1000; far loads above y=1100.
# u_load/A is an input/load pin: insert directly on this pin.
# Supply selected objects needing assignment; this example does not filter
# already-planned objects automatically.
set incremental_objects {
    {net data_down top_to_bottom}
    {net data_up bottom_to_top}
    {pin u_load/A top_to_bottom}
}

# To use a three-column file instead, replace plan_objects below with:
#     plan_objects_file ./objects_incremental.txt
# The file contains: type name direction (one object per line).
set incremental_sets [list [dict create \
    name incremental_set \
    plan_objects $incremental_objects \
    layer {T3M1 T3M2} \
    start_x 10 offset -2.5 \
    ratio_period 10 ratio_reserved 2 \
    force_gap_every 4 gap_tracks 1]]

file mkdir ./out_incremental
set incremental_plan [plan_nets \
    -bbox {0 1000 500 1100} \
    -sets $incremental_sets \
    -flow_mode incremental -mode nearest \
    -shield_mode strict -fallback off \
    -lib_cell YOUR_BUFFER_LIB_CELL -row_height 0.2 \
    -cell_down_offset 0 -cell_up_offset 0 \
    -row_pitch 2 -row_reset per_x \
    -buffer_marker_size {1 1} \
    -out_file ./out_incremental/assignments.txt \
    -tcl_file ./out_incremental/implement.tcl \
    -debug 4]

puts "Report: [dict get $incremental_plan file]"
puts "Log:    [dict get $incremental_plan log_file]"
puts "Tcl:    [dict get $incremental_plan tcl_file]"
if {[llength [dict get $incremental_plan failures]]} {
    error "Some objects could not be assigned. Inspect the plan failures before executing."
}

# STEP 2: run these interactively to preview the generated operations:
# set ::UCS_TSV_DRYRUN 1
# source ./out_incremental/implement.tcl
# puts $::UCS_TSV_FAILED
#
# STEP 3: after checking the preview, run these to change the current design:
# set ::UCS_TSV_DRYRUN 0
# source ./out_incremental/implement.tcl
# puts $::UCS_TSV_FAILED
#
# Width and track pitch derive separately from each layer.
# No routing is excluded by default; add -ignore_nets / -ignore_nets_file
# only for routing shapes that should not count as blockers.

# Source from the package directory in an FC design session.
# Replace all object names, layers, bbox, lib_cell and row_height first.
# Generating the plan does not execute connectivity/placement edits.
source ./ucs_tsv_plan_proc.tcl

# Ordinary cells may be unplaced. Direction is explicitly supplied.
# No fanout/side check: insert directly on the requested net/pin/port.
# PORT DATA_OUT is fixed; plan nearest its actual port X before ordinary nets.
# This mode does not delete old guide buffers from previous implementations.
set replan_objects {
    {net data_down top_to_bottom}
    {pin u_hier/data_in top_to_bottom}
    {port DATA_OUT bottom_to_top}
}

# To use a three-column file instead, replace plan_objects below with:
#     plan_objects_file ./objects_replan.txt
# The file contains: type name direction (one object per line).
set replan_sets [list [dict create \
    name replan_set \
    plan_objects $replan_objects \
    layer {T3M1 T3M2} \
    start_x 10 offset -2.5 \
    ratio_period 10 ratio_reserved 2 \
    force_gap_every 4 gap_tracks 1]]

file mkdir ./out_replan
set replan_plan [plan_nets \
    -bbox {0 1000 500 1100} \
    -sets $replan_sets \
    -flow_mode replan -mode sequential \
    -shield_mode strict -fallback off \
    -lib_cell YOUR_BUFFER_LIB_CELL -row_height 0.2 \
    -cell_down_offset 0 -cell_up_offset 0 \
    -row_pitch 2 -row_reset per_x \
    -buffer_marker_size {1 1} \
    -out_file ./out_replan/assignments.txt \
    -tcl_file ./out_replan/implement.tcl \
    -debug 4]

puts "Report: [dict get $replan_plan file]"
puts "Log:    [dict get $replan_plan log_file]"
puts "Tcl:    [dict get $replan_plan tcl_file]"
if {[llength [dict get $replan_plan failures]]} {
    error "Some objects could not be assigned. Inspect the plan failures before executing."
}

# STEP 2: run these interactively to preview the generated operations:
# set ::UCS_TSV_DRYRUN 1
# source ./out_replan/implement.tcl
# puts $::UCS_TSV_FAILED
#
# STEP 3: after checking the preview, run these to change the current design:
# set ::UCS_TSV_DRYRUN 0
# source ./out_replan/implement.tcl
# puts $::UCS_TSV_FAILED
#
# Width and track pitch derive separately from each layer.
# No routing is excluded by default; add -ignore_nets / -ignore_nets_file
# only for routing shapes that should not count as blockers.

set BBOX {0 1000 500 1100}
set cross [extract_cross_nets -region_bbox $BBOX -search_height 200 \
    -check_mode pre_route -plan_objects_file ./cross_objects.txt -debug 4]

# cross 是 list of dict，不是包含 file/names 的 dict。
set candidates {}
foreach record $cross {
    set clk [check_net_clock -net [dict get $record net] -debug 0]
    if {![dict get $clk clock]} {lappend candidates [dict get $record net]}
}

set layer T3M1
set width [get_attribute [get_layers $layer] min_width]
set unplan [extract_unplan_nets -nets $candidates -bbox $BBOX \
    -layer $layer -width $width -lower_y 1002.5 -upper_y 1097.5 \
    -shield_mode strict -out_file ./unplanned.txt -debug 4]
set selected {}
foreach record $cross {
    if {[dict get $record net] in [dict get $unplan unplanned]} {
        lappend selected $record
    }
}
# selected 可直接交给 plan_nets -plan_objects $selected
# 注意：这里的 planned 筛选只针对 T3M1；若允许多个已规划层，
# 应逐层 check_net_planned，并按你的“任一层合格即保留”规则合并判断。

set sets [list \
    [dict create name data layer {T3M1 T3M2} start_x 10 offset -2.5 \
        plan_objects {{net n_data top_to_bottom}} \
        ratio_period 10 ratio_reserved 2 force_gap_every 4 gap_tracks 1] \
    [dict create name control layer {T3M2 T3M3} start_x 100 offset -2 \
        plan_objects_file ./control_objects.txt inter_set_gap 2]]

set plan [plan_nets -bbox {0 1000 500 1100} -sets $sets \
    -flow_mode incremental -mode sequential -shield_mode strict -fallback off \
    -lib_cell YOUR_BUFFER_LIB_CELL -row_height 0.2 \
    -buffer_marker_size {1 1} -tcl_file ./implement_sets.tcl -debug 4]

set ranges [list [dict create name keep_clock_channel \
    x_range {120 150} guard_tracks 2]]
check_track_occupancy -bbox {0 1000 500 1100} -layer {T3M1 T3M2} \
    -special_ranges $ranges -ignore_nets {ignored_route_net} -debug 4

# 第一个对象的附加偏移为 0。
# 下一对 buffer 的附加偏移 = 上一对偏移 + 上一对 row_pitch * row_height。
down_y = bbox_y1 - cell_down_offset - y_extra
up_y   = bbox_y2 + cell_up_offset   + y_extra

# 与 create_shape 一致，width = 该 layer 实际使用的线宽：
x_left  = signal_or_shield_x - width/2
x_right = signal_or_shield_x + width/2
y_low   = bbox_y1 - offset - width/2
y_high  = bbox_y2 + offset + width/2

plan_nets -bbox $BBOX -plan_objects $objects -layer {T3M1 T3M2} \
    -flow_mode replan -row_height 0.2 -buffer_marker_size {1 1} -debug 4
# 没有 -tcl_file 也会画 marker。
# 缺少 row_height 时只能画精确 routing shape，不能计算 buffer Y marker。

set plan [plan_nets -bbox $BBOX -plan_objects $objects \
    -layer {T3M1 T3M2} -flow_mode incremental -mode nearest -debug 4]
puts [dict get $plan log_file]
puts [dict get $plan placed]
puts [dict get $plan failures]
foreach a [dict get $plan assignments] {
    puts "[dict get $a object_name]: [dict get $a insertion_method]"
    puts "opposite loads: [dict get $a far_loads]"
    puts "remaining loads: [dict get $a near_loads]"
}

{
  "default": {
    "flow_mode": "replan",
    "mode": "sequential",
    "layer": ["T3M1", "T3M2"],
    "shield_mode": "none",
    "lib_cell": "YOUR_BUFFER_LIB_CELL",
    "row_height": 0.2,
    "offset": -2.5
  },
  "regions": {
    "region_1": {
      "bbox": [0, 1000, 500, 1100],
      "plan_sets": [
        {
          "name": "data",
          "start_x": 10,
          "plan_objects": [
            ["net", "data_bus[0]", "top_to_bottom"],
            ["pin", "u_macro/D", "bottom_to_top"]
          ]
        },
        {
          "name": "ports",
          "offset": -2,
          "plan_objects": [["port", "DATA_IN", "top_to_bottom"]]
        }
      ]
    }
  }
}

source ./ucs_tsv_plan.tcl
set result [ucs_tsv_plan -config ./config.json -out_dir ./out_json \
    -debug 4 -keep_going 0]
puts [dict get $result errors]
foreach entry [dict get $result regions] {
    set plan [dict get $entry plan]
    puts "[dict get $entry region]: [dict get $plan tcl_file]"
}

set cfg [parse_json -json_file ./config.json -debug 4]
puts [dict get $cfg default]
puts [dict keys [dict get $cfg regions]]

set g [derive_plan_geometry -json_file ./incremental_assign.json \
    -region region_1 -layer T3M1 -region_bbox {0 1000 500 1100} -debug 4]
puts [dict get $g route_width]
puts [dict get $g row_height]
puts [dict get $g special_ranges]

set regions [extract_region \
    -signal_tsv_patterns {TSV_SIG_* TSV_SIGNAL_*} \
    -pg_tsv_patterns {TSV_PG_*} -size_value 5 -debug 4]
foreach r $regions {puts "[dict get $r name]: [dict get $r bbox]"}

set r [check_net_clock -net data_bus -debug 2]
if {[dict get $r clock]} {puts "skip clock net"}
puts [dict get $r reason]

set r [check_net_cross -net data_bus -region_box {0 1000 500 1100} \
    -check_mode pre_route -debug 4]
puts [dict get $r cross]
puts [dict get $r reason]
# 对已有 routing 再运行 post_route：
set routed [check_net_cross -net data_bus -region_box {0 1000 500 1100} \
    -check_mode post_route -debug 4]

set cross [extract_cross_nets -region_bbox {0 1000 500 1100} \
    -search_height 200 -check_mode pre_route \
    -out_file ./cross_nets.txt -plan_objects_file ./cross_objects.txt -debug 4]
foreach r $cross {
    puts "[dict get $r type] [dict get $r name] [dict get $r direction]"
}

set r [check_net_planned -net data_bus -bbox {0 1000 500 1100} \
    -layer T3M1 -lower_y 1002.5 -upper_y 1097.5 \
    -shield_mode strict -shield_net VSS -debug 4]
puts [dict get $r planned]
puts [dict get $r reason]

set r [extract_unplan_nets -nets {n1 n2} -bbox {0 1000 500 1100} \
    -layer T3M1 -width 0.04 -lower_y 1002.5 -upper_y 1097.5 \
    -shield_mode strict -out_file ./unplanned.txt -debug 4]
puts [dict get $r unplanned]
puts [dict get $r file]

set occ [check_track_occupancy -bbox {0 1000 500 1100} \
    -layer {T3M1 T3M2} -ignore_nets {test_route} \
    -ignore_nets_file ./ignored_nets.txt \
    -signal_tsv_pattern TSV_SIG_* -pg_tsv_pattern TSV_PG_* \
    -pg_tsv_guard 0.2 -debug 4]
foreach layer [dict get $occ layers] {
    puts "$layer available=[dict get $occ by_layer $layer available]"
}

set rows [parse_plan_objects -plan_objects {
    {net data_bus[0] top_to_bottom}
    {pin u_hier/A bottom_to_top}
}]
# 或：set rows [parse_plan_objects -plan_objects_file ./objects.txt]
puts [dict get [lindex $rows 0] name]

set record [lindex [parse_plan_objects -plan_objects {
    {net data_bus top_to_bottom}
}] 0]
set r [resolve_plan_object -object $record -flow_mode incremental \
    -bbox {0 1000 500 1100}]
puts [dict get $r insertion_method]
puts [dict get $r insertion_name]
puts [dict get $r far_loads]
puts [dict get $r near_loads]

set p [plan_nets -bbox {0 1000 500 1100} \
    -plan_objects {{net n_data top_to_bottom}} \
    -layer {T3M1 T3M2} -flow_mode incremental -mode nearest \
    -shield_mode strict -fallback off -lib_cell YOUR_BUFFER_LIB_CELL \
    -row_height 0.2 -buffer_marker_size {1 1} \
    -out_file ./assignments.txt -tcl_file ./implement.tcl -debug 4]
puts [dict get $p failures]
puts [dict get $p state]
puts [dict get $p log_file]

set e [evaluate_plan -plan $p -label incremental_candidate -debug 2]
puts [dict get $e status]
puts [dict get $e objective]

set preview [remove_plan_routing -nets {n1 n2} -confirm 0 -debug 4]
puts [dict get $preview rows]
# 只有确实需要清理这些完整 nets 时才执行：
# set done [remove_plan_routing -nets {n1 n2} -confirm 1 -debug 4]

set written [write_plan_tcl -assignments [list \
    [dict create net n_data signal_x 10 shield_xs {9.9 10.1}]] \
    -bbox {0 1000 500 1100} -layer T3M1 -width 0.04 \
    -lib_cell YOUR_BUFFER_LIB_CELL -row_height 0.2 \
    -cell_down_offset 0 -cell_up_offset 0 -shape_offset -2.5 \
    -row_pitch 2 -row_reset per_x -remove_routing 0 \
    -tcl_file ./legacy_implement.tcl -debug 3]
puts $written

set r [ucs_net_list -nets {n1 n2 n3}]
# 或：set r [ucs_net_list -net_file ./nets.txt]
puts [dict get $r names]
puts [dict get $r source]

set rectangle {{9 999} {11 999} {11 1001} {9 1001}}
set n [ucs_error_mark -cell UCS_CUSTOM_DEBUG -name BUFFER_LOCATION \
    -info "rectangle center is planned location" \
    -error_list [list $rectangle] -incremental 0]

source ./ucs_tsv_plan.tcl
set result [ucs_tsv_plan -config ./examples/typed_plan_objects.json \
    -out_dir ./out -debug 4 -keep_going 0]

set path [ucs_log open manual_flow 4 .]
ucs_log INFO input "start region_1"
ucs_log DEBUG geometry "bbox={0 1000 500 1100}" 4
# 在这里调用各个检查 proc。
puts [ucs_log level]
set saved [ucs_log close]
puts $saved

set ea [evaluate_plan -plan $plan_a]
set eb [evaluate_plan -plan $plan_b]
if {[ucs_plan_better $ea $eb]} {
    set chosen $plan_a
} else {
    set chosen $plan_b
}

set ::UCS_TSV_DRYRUN 1
set ::UCS_TSV_MAX_NETS 10
source ./implement.tcl
puts "done=$::UCS_TSV_DONE skipped=$::UCS_TSV_SKIPPED"
puts $::UCS_TSV_FAILED

# 核对命令、对象与坐标后再实际执行：
set ::UCS_TSV_DRYRUN 0
set ::UCS_TSV_MAX_NETS 99999
source ./implement.tcl
puts $::UCS_TSV_FAILED

# 开发树内的 mock 回归（邮件包不含测试目录；不是 FC 功能验收）
for f in t/test_*.tcl; do tclsh "$f"; done

# FC 中逐层定位：
# 1. parse_plan_objects -> 查看名字和方向
# 2. resolve_plan_object -> 查看 driver / far_loads / near_loads
# 3. check_track_occupancy -debug 4 -> 检查资源
# 4. plan_nets -debug 4 -> 检查用途和几何 marker
# 5. UCS_TSV_DRYRUN=1 -> 检查生成命令
# 6. 在选定基线上真实执行并检查 FAILED、连接和位置