Small procedures. Clear contracts.

Quick start

Choose one public entrypoint. New scripts do not source implementation files directly.

# Pure Tcl
source /path/to/common/tcl/ucs_common.tcl

# Synopsys collection, Error Browser, and GUI work
source /path/to/common/tcl/ucs_snps_common.tcl

Both entrypoints enforce the standard UCS license rule before registering protected public procedures. The encrypted customer release contains two independent self-contained files: ucs_common.tbc and ucs_snps_common.tbc.

Architecture

Public entrypoints are obvious; implementation modules have one responsibility each.

Procedure catalog

Search by name, purpose, category, or supported tool.

Collections

Separate data access from presentation. Use names when another procedure needs the result; print only for an interactive review.

set names [ucs_collection_names [get_cells -hierarchical *]]

ucs_print_collection [get_cells -hierarchical *]
# Total 2
#    top/u_cpu
#    top/u_gpu

ucs_print_collection returns the collection size, accepts an output channel, and prints the Total line once before iteration.

Error Browser

Checking policy stays in product code. The common procedure validates supplied geometry and writes it through one FC/ICC2 interface.

set violations {
  {{0 0} {10 0} {10 5} {0 5}}
  {{20 20} {30 20} {30 30} {20 30}}
}

set result [ucs_error_mark \
  -cell UCS_FLOORPLAN \
  -name MACRO_OVERLAP \
  -info "Macro overlap" \
  -error_list $violations]

puts "Marked [dict get $result count] polygons"

# Reuse the same Error Browser data for another error type.
ucs_error_mark -cell UCS_FLOORPLAN -name CHANNEL \
  -error_list $channel_violations -incremental

-cell may include the .err suffix; it is added only when absent. An empty -error_list is a no-op. Invalid coordinates and unsupported tools fail before data is changed.

GUI operations

FC and ICC2 share one public interface where commands match. Unsupported tools fail before changing the display.

Select and inspect

ucs_select net  top/u_cpu/n_reset
ucs_select pin  top/u_cpu/U1/A
ucs_select cell top/u_cpu/U1

ucs_zoom_selected
ucs_win

Collection views

# Direct collection
ucs_show_item [get_cells {top/u_cpu/*}] CPU 1

# Related object groups
ucs_show_objects module {top/u_cpu top/u_gpu} 1
ucs_show_objects port   {DATA ADDR}

Window capture

ucs_clean_view
ucs_capture_window ./images/layout.png

# TileBuilder-inspired common operations
ucs_clear_highlights
ucs_zoom_fit [get_cells -physical_context u_cpu]
ucs_layer_visibility only [get_layers {M4 M5 M6}]
change_selection [ucs_get_drivers [get_selection]]
ucs_capture_design ./images/clean_layout.png

The capture procedure uses gui_write_window_image only. Captioning or image conversion is outside common and remains optional in a product layer.

Examples

Pure Tcl formatting

source /path/to/common/tcl/ucs_common.tcl

set runtime [ucs_format_duration 90061]
set title   [ucs_format_field 24 "Route Runtime" center "|" "|"]
ucs_write_line "$title $runtime"

Tool guard

source /path/to/common/tcl/ucs_snps_common.tcl

set tool [ucs_require_tool {fc icc2}]
ucs_write_line "Running in $tool"

Tool support

Support is attached to each action, not assumed for every Synopsys tool.

Scope

Common stays small by defining an explicit boundary.

Testing

Pure Tcl behavior and EDA-facing call contracts are tested separately.

tclsh update/common/tcl/tests/run_all.tcl

Mock tests validate UCS logic and command construction. Real FC, ICC2, and PT smoke tests remain required before promotion to verified.

Migration

The reorganization intentionally removes ambiguous aliases.