ucs_drv_fix.tcl

Usage Guide — UCS DRV Fix ECO Generator

Key Features

• Config-Driven Fix — Map each violation type (data_tran, clock_tran, max_cap, max_fanout) to its own ordered method sequence and per-method parameters via external config files.
• Multiple Fix Methods — size_up (drive strength increase within same VT), swap_vt (VT swap within same drive strength), insert_buffer (nature_on_route / smart_cluster / interface), clone_driver (cluster-based fanout splitting).
• Intelligent Clustering — K-means clustering with k-means++ initialization for buffer insertion and driver cloning. Auto-detects optimal cluster count via elbow method. Small clusters auto-merged.
• Leaf Driver Resolution — Uses all_connected -leaf to correctly identify leaf-level driver cells, even when the net passes through hierarchical boundaries.
• ECO Annotation — Each ECO command is annotated with Net, Type, Limit/Slack, Source, and Driver (current ref), enabling quick review and diff comparison.

Quick Start

# In pt_shell with design loaded:
source /path/to/ucs_drv_fix.tcl

ucs_drv_fix \
    -violations_config /proj/run/drv/violations.config \
    -methods_config    /proj/run/drv/fix_method.config \
    -ref_lib           /proj/run/drv/lib_cell_info.txt.tcl \
    -eco               /proj/run/drv/eco_output.tcl \
    -debug 1

# Minimal — insert_buffer only (no -ref_lib needed)
ucs_drv_fix \
    -violations_config max_cap.violations_config \
    -methods_config    max_cap_bufonly.methods_config \
    -eco               eco_output.tcl

Arguments

Violations Config Format

One violation type per line. Each line maps a type name to its violation list file path. Lines starting with # are comments. Blank lines are ignored.

# violations.config — maps violation types to file paths
data_tran:   /proj/run/drv/data_tran.list
clock_tran:  /proj/run/drv/clock_tran.list
max_cap:     /proj/run/drv/max_cap.list
max_fanout:  /proj/run/drv/max_fanout.list

Violation List File Format

Each line defines one violation. Three formats are supported. Comments (#) and blank lines are ignored. Inline comments after data fields are stripped.

# max_cap.list — real example
TCDX/tcdx_ctrl/TDATQCHAN0/FxPlace_HFSNET_50445 75.800000 -19.824252
pin TCDX/tcdx_ctrl/TREQQ/FxOptCts_ctmTdsLR_1_1567216/A2 75.800000 -10.605518
TCDX/tcdx_ctrl/TREQQ/SHIFTQ/tmp_net1578978 75.800000 -10.411594

Methods Config Format

One block per violation type. Each block contains key: value pairs controlling fix behavior. Lines starting with # are comments. Unknown keys trigger a warning.

# fix_method_fallback.config — Multi-type with fallback mode
# Try methods left to right, stop at first success

data_tran {
    fix_method:      size_cell,insert_buffer,clone_driver
    fix_method_mode: fallback
    fix_level:       2
    size_level:      1
    dont_touch_inst: /proj/cfg/dont_touch_inst.txt
    dont_size_ref:   *ISO*,*LS*
    insert_buffer_list:             BUFX4,BUFX8
    insert_buffer_cluster:          nature_on_route
    insert_buffer_first_distance_ratio:    0.5
    insert_buffer_repeater_distance_ratio: 0.9
    insert_buffer_exclude_hardmacro:       1
    enable_clone:    1
    clone_threshold: 8
}

clock_tran {
    fix_method:      insert_buffer
    fix_method_mode: fallback
    insert_buffer_list:    CKBUFX4,CKBUFX8
    insert_buffer_cluster: nature_on_route
    insert_buffer_first_distance_ratio:    0.3
    insert_buffer_repeater_distance_ratio: 0.8
}

max_cap {
    fix_method:      size_cell,swap_vt,insert_buffer
    fix_method_mode: fallback
    fix_level:       2
    dont_size_ref:   *ISO*,*LS*,*TIE*
    dont_swap_ref:   *ISO*,*LS*,*TIE*
    insert_buffer_list:    BUFX4,BUFX8,BUFX12
    insert_buffer_cluster: smart_cluster
    cluster_max_groups:    0
    cluster_min_fanout:    4
    cluster_min_group_pins: 3
}

max_fanout {
    fix_method:      clone_driver,insert_buffer
    fix_method_mode: fallback
    enable_clone:    1
    clone_threshold: 12
    insert_buffer_list:    BUFX8,BUFX12
    insert_buffer_cluster: smart_cluster
}

# max_cap.methods_config — Pipeline mode with all methods
# All methods run sequentially regardless of success

max_cap {
    fix_method:     size_up,swap_vt,insert_buffer,clone_driver
    fix_method_mode: pipeline
    insert_buffer_list:  BUFFD1BWP136P5M156H3P48CPDLVT
    insert_buffer_cluster: nature_on_route
    insert_buffer_first_distance_ratio:    0.4
    insert_buffer_repeater_distance_ratio: 0.7
    insert_buffer_exclude_hardmacro:       1
    cluster_min_fanout:  4
    clone_threshold:     4
    fix_level: 2
}

Method Sequence & Modes

fix_method

Comma-separated ordered list of method names. Methods are tried in order. Supported values:

fix_method_mode

Cumulative Sizing Chain

When fix_level is specified and consecutive sizing methods (size_up, size_cell, swap_vt) appear in the method list, they share a cumulative sizing budget. The first method consumes as many steps as it can, and remaining budget passes to the next sizing method. Only one size_cell ECO command is emitted for the final result.

# Example: fix_level: 3, methods: size_cell,swap_vt,insert_buffer
# Step 1: size_cell uses 2 steps (INVD2→INVD4, remaining budget = 1)
# Step 2: swap_vt uses 1 step (INVD4_HVT→INVD4_LVT, remaining budget = 0)
# Result: single ECO: size_cell inst INVD4_LVT
# Step 3: insert_buffer runs independently (not a sizing method)

Config Key Reference

Common Keys

Size_up / Size_cell Keys

Swap_vt Keys

Insert_buffer Keys

Insert Buffer Sub-Modes

Clone_driver Keys

Cluster Control Keys

Used by both insert_buffer_cluster: smart_cluster and clone_driver.

Success / Failure Rules

Output Files

ECO File Structure

################################################################################
# UCS DRV Fix ECO Commands (ONE METHOD PER VIOLATION)
################################################################################
# Generated by: UCS DRV Fix UCS-1.2.0
# Date: Sat Apr 11 06:32:28 EDT 2026
# Host: atlsers0281.amd.com
# Total ECO commands: 6
# Fixed violations: 3
################################################################################

################################################################################
# Violation Type: max_cap
# Number of ECO commands: 6
################################################################################

################################################################################
# Net: TCDX/tcdx_ctrl/TDATQCHAN0/FxPlace_HFSNET_50445
# Type: max_cap, Limit: 75.8, Slack: -19.824252
# Source: net TCDX/tcdx_ctrl/TDATQCHAN0/FxPlace_HFSNET_50445
# Driver: TCDX/tcdx_ctrl/TDATQCHAN0/FxPlace_HFSINV_102_445802 (INVD2SPG1AMDBWP136P5M156H3P48CPDLVT)
################################################################################
size_cell TCDX/tcdx_ctrl/TDATQCHAN0/FxPlace_HFSINV_102_445802 INVD4SPG1AMDBWP136P5M156H3P48CPDLVT
add_buffer_on_route [get_nets TCDX/tcdx_ctrl/TDATQCHAN0/FxPlace_HFSNET_50445] BUFFD1BWP136P5M156H3P48CPDLVT -first_distance_length_ratio 0.4 -repeater_distance_length_ratio 0.7 -no_legalize

ECO Execution in FC / ICC2

ECO files generated in PrimeTime are sourced in Fusion Compiler or ICC2 for implementation. The require_primetime check only runs inside the ucs_drv_fix proc, not when the script is sourced. So sourcing ucs_drv_fix.tcl in FC/ICC2 is safe — it only loads the proc definitions and ECO executor commands.

# In fc_shell or icc2_shell with design loaded:
source /path/to/ucs_drv_fix.tcl           ;# loads ucs_cluster_insert_buffer, ucs_cluster_clone_driver procs
source eco_output.20260413.06.tcl          ;# executes ECO commands
legalize_placement                          ;# legalize inserted buffers and clones

ECO Executor Commands

These procs are defined as top-level Tcl commands (via define_proc_attributes) for use inside ECO files:

ucs_cluster_insert_buffer

ucs_cluster_insert_buffer \
    -net {net_name} \
    -lib_cell {BUFFD1BWP136P5M156H3P48CPDLVT} \
    [-max_groups 0] \
    [-min_fanout 4] \
    [-min_group_pins 3] \
    -execute

Clusters net sink pins using k-means, inserts one buffer per cluster at the weighted centroid location. -execute is required for actual execution; without it, the command is a no-op.

ucs_cluster_clone_driver

ucs_cluster_clone_driver \
    -net {net_name} \
    [-max_groups 0] \
    [-min_fanout 4] \
    [-min_group_pins 3] \
    -execute

Clusters net sink pins, creates one clone of the driver per cluster. Each clone is connected to its cluster's sinks. The original driver keeps cluster_0. Clone instances are named <driver>_ECO_CLONE_<date>_<NN>.

Ref Lib File Format

A Tcl file that defines ::cell_library_dict as a dict. Each entry maps a cell ref name to its attributes. The file is sourced by the cellsizer during library loading.

set ::cell_library_dict {
    BUFFD1BWP136P5M156H3P48CPDLVT {
        area            0.029952
        base_name       "BUFFD"
        size_base_name  "BUFFDSPG1AMDBWP136P5M156H3P48CPD"
        swap_base_name  "BUFFDSPG1AMDBWP136P5M156H3P48CPD"
        vt_type         "LVT"
        drive_strength  1
        pin_count       2
        resistance {
            average 2.633
            fall    2.682
            rise    2.583
        }
    }
    BUFFD2BWP136P5M156H3P48CPDLVT {
        area            0.044928
        base_name       "BUFFD"
        size_base_name  "BUFFDSPG1AMDBWP136P5M156H3P48CPD"
        swap_base_name  "BUFFDSPG1AMDBWP136P5M156H3P48CPD"
        vt_type         "LVT"
        drive_strength  2
        pin_count       2
        resistance {
            average 1.316
            fall    1.341
            rise    1.291
        }
    }
}

Cell Attribute Fields

Dependencies

The script sources 5 common library files at startup. Libraries are auto-located by searching upward from the script directory for a common/lib/tcl_lib/ directory.

Debug & Diagnostics

Log file: Automatically created as ucs_drv_fix_<YYYYMMDD_HHMMSS>.log in the current directory. Every log entry includes: timestamp, level, script name, run_id, PID, user, stage, and message.

[2026-04-11 06:32:28] [DEBUG] [ucs_drv_fix] [20260411_063227] [pid:1647017] [user:huiyinli] [20_analyze]       Driver: TCDX/tcdx_ctrl/TDATQCHAN0/FxPlace_HFSINV_102_445802 (INVD2SPG1AMDBWP136P5M156H3P48CPDLVT)
[2026-04-11 06:32:28] [DEBUG] [ucs_drv_fix] [20260411_063227] [pid:1647017] [user:huiyinli] [20_analyze]       Shared fix_level: 2
[2026-04-11 06:32:28] [DEBUG] [ucs_drv_fix] [20260411_063227] [pid:1647017] [user:huiyinli] [20_analyze]       size_up moved 1 step(s): INVD2SPG1AMDBWP136P5M156H3P48CPDLVT -> INVD4SPG1AMDBWP136P5M156H3P48CPDLVT

Workflow Diagram

  pt_shell (design loaded)
        |
        v
  +------------------+
  | source script    |  <-- loads procs + common libs
  +------------------+
        |
        v
  +------------------+
  | ucs_drv_fix      |  <-- CLI arguments
  +------------------+
        |
        v
  +------------------+
  | License Check    |  <-- .ucs_license.conf (RSA+AES)
  +------------------+
        |
        v
  +------------------+
  | Load Ref Lib     |  <-- cell_library_dict (if -ref_lib)
  | Build Sort Lists |      build_size_up_lists, build_swap_vt_lists
  +------------------+
        |
        v
  +------------------+
  | Parse Configs    |  <-- violations.config + methods.config
  +------------------+
        |
        v
  +------------------+
  | Load Violations  |  <-- per-type violation list files
  +------------------+
        |
        v  (per violation)
  +------------------+
  | Resolve Driver   |  <-- all_connected -leaf (handles hierarchy)
  +------------------+
        |
        v
  +------------------+     +------------------+     +------------------+
  | size_up/swap_vt  |     | insert_buffer    |     | clone_driver     |
  | (sizing chain)   |     | (route/cluster)  |     | (k-means clone)  |
  +------------------+     +------------------+     +------------------+
        |                         |                         |
        +-------------------------+-------------------------+
                                  |
                                  v
                        +------------------+
                        | ECO File Save    |  <-- grouped by violation type
                        +------------------+
                                  |
                                  v
                        +------------------+
                        | Statistics &     |
                        | Summary Report   |
                        +------------------+

  -------- Execution Phase (separate session) --------

  fc_shell / icc2_shell (design loaded)
        |
        v
  +------------------+
  | source script    |  <-- loads ECO executor procs
  +------------------+
        |
        v
  +------------------+
  | source ECO file  |  <-- size_cell, add_buffer_on_route,
  +------------------+      ucs_cluster_insert_buffer,
        |                    ucs_cluster_clone_driver
        v
  +------------------+
  | legalize_placement|
  +------------------+

Usage Examples

Conservative Data-Transition Repair

ucs_drv_fix \
    -violations_config data_tran.violations_config \
    -methods_config data_tran_conservative.methods_config \
    -ref_lib lib_cell_info.txt.tcl \
    -eco eco_data_tran.tcl

Config: fix_method: size_cell,swap_vt — try upsizing, then VT swap. No buffer insertion.

Buffer-First Repair (No Ref Lib Needed)

ucs_drv_fix \
    -violations_config max_cap.violations_config \
    -methods_config max_cap_bufonly.methods_config \
    -eco eco_max_cap.tcl

Config: fix_method: insert_buffer + insert_buffer_cluster: nature_on_route — route-based buffer insertion only. No -ref_lib required.

Aggressive Fallback (All Methods)

ucs_drv_fix \
    -violations_config all_violations.config \
    -methods_config full_fallback.methods_config \
    -ref_lib lib_cell_info.txt.tcl \
    -eco eco_aggressive.tcl \
    -debug 1

Config: fix_method: size_cell,swap_vt,insert_buffer,clone_driver + fix_method_mode: fallback — try all methods, stop at first success.

Combined Sizing + Buffering (Pipeline)

ucs_drv_fix \
    -violations_config max_cap.violations_config \
    -methods_config max_cap_pipeline.methods_config \
    -ref_lib lib_cell_info.txt.tcl \
    -eco eco_pipeline.tcl \
    -debug 2

Config: fix_method: size_cell,insert_buffer + fix_method_mode: pipeline — both methods run for every violation, maximizing fix coverage.

Cluster-Oriented Fanout Fix

ucs_drv_fix \
    -violations_config max_fanout.violations_config \
    -methods_config max_fanout.methods_config \
    -eco eco_fanout.tcl \
    -investigate

Config: fix_method: clone_driver,insert_buffer + insert_buffer_cluster: smart_cluster + clone_threshold: 12. With -investigate, clustering assignments are visualized via gui_add_annotation.

Deep Debugging

ucs_drv_fix \
    -violations_config violations.config \
    -methods_config methods.config \
    -ref_lib lib_cell_info.txt.tcl \
    -eco eco_debug.tcl \
    -debug 4

Full diagnostic output. Check ucs_drv_fix_*.log and debug/run_*/ for driver resolution, sizing chain trace, clustering coordinates, and raw state dumps.