ucs_monitor_run_status.pl

Usage Guide — UCS PnR Run Status Monitor

Key Features

• Run Status Monitoring — Track EDA PnR and ECO flow stage completion, detect running/finished/hang/crash states
• QoR Extraction — Parse timing (WNS/TNS/Violations), routing (DRC/shorts/congestion), utilization, and clock QoR data from reports
• PnR + ECO Flow Support — Auto-detect PERSONALITY from tile.params; PnR uses FxSynthesize→FxReRoute, ECO uses FxApplyEco/FxEcoRoute/PtEcoRoute
• HTML + Excel Reporting — Outlook-optimized HTML (8 themes, flat/merge/split layouts) and XLSX with autofilter
• Multi-Run Comparison — Compare metrics across runs with color-coded diff, scenario name auto-simplification, hierarchical path group shortening

Quick Start

# Minimal — scan current directory, show run time summary
ucs_monitor_run_status.pl --monitor_item summary

# Full report with timing details, emailed to yourself
ucs_monitor_run_status.pl --base_dir /path/to/runs \
    --metrics time timing routing \
    --monitor_item summary timing \
    --to your_userid

# Outlook-optimized with flat tables + Excel export
ucs_monitor_run_status.pl --base_dir /path/to/runs \
    --monitor_item summary timing clock_qor \
    --flat_table --excel

Input Sources

At least one input source is required. If none is specified, defaults to scanning the current working directory.

Filtering Options

Metrics & Monitor Items

--metrics (Summary Table Columns)

Controls which metrics appear in the summary table. repeatable

--monitor_item (Report Sections)

Controls which sections appear in the report. repeatable

Output & Display Options

Table Layout Options (Detail Timing & Clock QoR)

Path Group & Clock Name Display

Timing path groups and clock names can contain hierarchical instance paths with / separators (e.g., from Fusion Compiler instance-based grouping). To keep tables readable, only the last segment is displayed while the full path is preserved internally.

# Real example from acp_t tile:

# Full internal path (used for data keys, filtering, link resolution):
U_acp_core/U_dbg_client_ssb__aon_steer/I_dbg_client_v2_bc_steer/dbg_steer_muxf0_I_dbg_v2_client_ssb__aon_mux_lane0_SSB_balance_INT_CLK
U_acp_core/U_dbg_client_ssb__aon_steer/I_dbg_client_v2_bc_steer/dbg_steer_muxf1_I_dbg_v2_client_ssb__aon_mux_lane1_SSB_balance_INT_CLK

# Displayed in HTML table cell and Excel:
dbg_steer_muxf0_I_dbg_v2_client_ssb__aon_mux_lane0_SSB_balance_INT_CLK
dbg_steer_muxf1_I_dbg_v2_client_ssb__aon_mux_lane1_SSB_balance_INT_CLK

# Simple groups (no hierarchy) — unchanged:
ACLK
VDDCR_SOC_SMNCLK

Email Options

Mirror Options

Mirror Directory Layout

Each run is mirrored under mirror_dir/tile_name/nickname/, where the tile name comes from TILES_TO_RUN in tile.params and the nickname comes from qor_name or NICKNAME in tile.params.

mirror_dir/
├── tile_A/
│   ├── baseline/                ← nickname from tile.params/qor_name
│   │   ├── rpts/
│   │   │   ├── FxPixPlace/
│   │   │   ├── FxPixCts/
│   │   │   └── ...
│   │   ├── logs/
│   │   │   ├── FxPlace.log.gz
│   │   │   └── ...
│   │   ├── tile.params
│   │   ├── target.controls
│   │   ├── comment
│   │   └── notice
│   └── exp_v2/
│       ├── rpts/
│       ├── logs/
│       └── ...
├── tile_B/
│   └── run1/
│       ├── rpts/
│       └── logs/
└── _map.json                    ← original ↔ mirror path mapping

Mirrored Entries Per Run

The following files and directories are synced from each original run directory to its mirror:

Path Map (_map.json)

A JSON file at the mirror root records the mapping between mirror subdirectories and original run directories:

{
  "tile_A/baseline": "/nfs/proj1/magnus/runs/run_v1",
  "tile_A/exp_v2": "/nfs/proj2/runs/experiment_v2",
  "tile_B/run1": "/scratch/user/tile_b_run1"
}

This file is updated on every run and is used internally for stale directory cleanup.

URL Rewriting

When --mirror_dir is active, all hyperlinks in the generated HTML report (log viewer links, report links, PNG links) are automatically rewritten to point to the mirror paths instead of the original run directories. This is a post-extraction pass — no changes to individual extract functions are needed.

# Without --mirror_dir:
#   link → https://logviewer-atl.amd.com/nfs/proj1/magnus/runs/run_v1/logs/FxPlace.log.gz

# With --mirror_dir /web/status:
#   link → https://logviewer-atl.amd.com/web/status/tile_A/baseline/logs/FxPlace.log.gz

Incremental Sync

Mirror sync is incremental and efficient. Two strategies are used depending on availability:

Fast path — rsync delegation (preferred): At startup, the script probes for the rsync binary via which rsync. If found, each managed directory sync is delegated to rsync -a --delete src/ dst/, which transfers only changed files and removes stale ones. This is O(changed files) and handles all corner cases natively.

Fallback — Perl mtime guard: If rsync is not available, the script uses a per-directory mtime comparison before descending. On Linux, a directory's mtime advances only when entries are added or removed (not when file contents change in-place). If the source directory mtime matches the mirror directory mtime, the entire subtree is skipped without stat-ing individual files. After a sync pass, the mirror directory mtime is stamped to match the source.

• Unchanged files are skipped — per-file mtime + size comparison; only new/changed files are copied
• Original timestamps preserved — via utime() after copy
• Deleted source files and directories are removed from the mirror
• logs/ always fully rescanned — log files are appended in-place without updating the parent directory mtime; the mtime guard is bypassed for logs/ so every cycle checks each log file individually

Slim Mirror Mode (--mirror_slim)

By default, the full contents of rpts/ and logs/ are synced to the mirror. In projects with many report files or large compressed logs, this can copy far more data than the HTML report actually links to. Slim mirror mode addresses this by syncing only the files that are referenced as hyperlinks in the report.

Which entries are affected

Two-pass execution flow

Because the set of referenced files can only be determined after the HTML is generated, slim mode uses a different execution order compared to full mode:

URL rewriting in slim mode is done as a string replacement pass over the final HTML: original run-directory path prefixes are replaced with their corresponding mirror paths (longest match first to avoid partial substitutions).

Enabling slim mode

Pass --mirror_slim on the CLI, or add mirror_slim = 1 to the config file:

# Example: slim mirror config
base_dir = /path/to/project/runs
mirror_dir = /web/status/myproject
mirror_slim = 1
monitor_item = summary, timing
metrics = time, timing

Stale Directory Cleanup

When a run is removed from monitoring (e.g., run directory deleted or no longer matched by filters), its mirror directory is automatically cleaned up:

1. Previous _map.json is read to identify previously mirrored runs
2. Any mirror subdirectory not in the current active set is removed
3. Empty tile-level directories are cleaned up

Nickname Collision Handling

If two runs for the same tile have identical nicknames (e.g., both called "baseline"), a numeric suffix is appended automatically: baseline, baseline_2, baseline_3, etc. Nicknames are also sanitized for filesystem safety (only a-z A-Z 0-9 . _ - allowed; other characters are replaced with _).

Mirror Usage Examples

# Mirror to a web-accessible directory
ucs_monitor_run_status.pl \
    --base_dir /nfs/proj/runs \
    --mirror_dir /web/status/myproject \
    --monitor_item summary timing \
    --metrics time timing

# Mirror with continuous monitoring (re-syncs every 8 hours)
ucs_monitor_run_status.pl \
    --config_file project.conf \
    --mirror_dir /web/status/daily \
    --interval 8

# Mirror specific runs from different locations
ucs_monitor_run_status.pl \
    --run /nfs/proj1/run_v1 --run /nfs/proj2/run_v2 \
    --mirror_dir /web/mirror \
    --monitor_item summary timing

Debug & Diagnostics

Log file: Automatically created as ucs_monitor_run_status_<YYYYMMDD_HHMMSS>.log in the current directory. Contains timestamped entries with level, script name, stage, PID, user, and run ID.

ECO Flow Support

The script automatically detects the flow type from the PERSONALITY field in each run's tile.params and selects the appropriate stages.

ECO Summary Metrics

Mixed PnR + ECO Reports

When monitoring both PnR and ECO runs together, the summary table shows columns for both flow types. PnR runs display ---- under ECO columns and vice versa. The detail timing table only shows stages applicable to each run's personality.

# Mixed PnR + ECO monitoring
ucs_monitor_run_status.pl \
    --run /proj/tiles/rel_NLD/tile_a/latest \
    --run /proj/tiles/rel_ECO/tile_b/latest \
    --metrics time routing --monitor_item summary timing

Scenario Name Simplification

Scenario names from Fusion Compiler and PrimeTime reports are automatically simplified for display. The full name is used internally for filtering and data processing.

Config File Format (.conf)

Config files use key = value format. Lines starting with # are comments.

Array fields (comma or space separated): run, tiles, skip_tiles, owner, stage, ignore_groups, select_group, scenario, no_scenario, clocks, metrics, monitor_item, to

Scalar fields: all others (base_dir, check, subject, flat_table, etc.)

# Example: PnR monitoring config
base_dir = /path/to/project/runs
tiles = tile_a, tile_b
metrics = time, timing, routing
monitor_item = summary, timing, notice
check = setup
scenario = FuncTT, FuncFF
to = johndoe teamlead
subject = [MyProject] Daily Status
flat_table = 1
excel = 1
compare = 1

# Mirror options (optional)
mirror_dir = /web/status/myproject
mirror_slim = 1    # sync only HTML-referenced files from rpts/ and logs/

# Example: Multiple explicit runs (space-separated)
run = /proj/tiles/rel_NLD/tile_a/latest /proj/tiles/rel_NLD/tile_b/latest
metrics = time, timing, routing
monitor_item = summary, timing
flat_table = 1

# Example: ECO monitoring
run = /proj/tiles/rel_ECO/tile_a/latest /proj/tiles/rel_ECO/tile_b/latest
metrics = time, routing
monitor_item = summary, timing
subject = [ECO] Daily Status

Usage Examples

Basic Summary

ucs_monitor_run_status.pl --monitor_item summary

Scans current directory for runs, shows run time per step.

Full Report with Email

ucs_monitor_run_status.pl \
    --base_dir /proj/magnus/runs \
    --metrics time timing routing utilization \
    --monitor_item summary timing notice \
    --to pd_team \
    --subject "[Magnus] Daily Status"

Outlook-Optimized with Excel

ucs_monitor_run_status.pl \
    --base_dir /proj/runs \
    --metrics time timing clock_qor \
    --monitor_item summary timing clock_qor \
    --flat_table --excel \
    --to userid

Continuous Monitoring (every 8 hours)

ucs_monitor_run_status.pl \
    --config_file /proj/configs/daily_check.conf \
    --interval 8

Filtered Timing: Setup Only, Specific Scenarios

ucs_monitor_run_status.pl \
    --base_dir /proj/runs \
    --monitor_item timing \
    --check setup \
    --scenario FuncTT FuncFF \
    --slack_less_than -0.01 \
    --compare

Multi-Config Directory

ucs_monitor_run_status.pl \
    --config_dir /proj/status_configs/ \
    --flat_table --excel --debug 1

Specific Runs with Merge Table

ucs_monitor_run_status.pl \
    --run /proj/run_v1 --run /proj/run_v2 --run /proj/run_v3 \
    --metrics time timing \
    --monitor_item summary timing \
    --merge_table --compare \
    --use_link

ECO Run Monitoring

ucs_monitor_run_status.pl \
    --run /proj/tiles/rel_PRE_BTO_SOC/usbadp0_s0_t/latest \
    --run /proj/tiles/rel_PRE_BTO_SOC/acp_t/latest \
    --metrics time routing --monitor_item summary timing \
    --flat_table --excel

Auto-detects PERSONALITY=eco from tile.params. Summary shows FxApplyEco (time) and FxEcoRoute (time+routing). Detail timing shows PtEcoRoute only.

Mixed PnR + ECO Comparison

ucs_monitor_run_status.pl \
    --run /proj/tiles/rel_NLD/df_tcdxg_t/latest \
    --run /proj/tiles/rel_ECO/usbadp0_s0_t/latest \
    --metrics time timing routing \
    --monitor_item summary timing \
    --merge_table --flat_table --compare

Both PnR and ECO columns appear in the merged summary. Each run shows data only under its applicable stages.

Mirror Mode (Full Sync)

ucs_monitor_run_status.pl \
    --base_dir /proj/runs \
    --mirror_dir /web/mirror/proj \
    --monitor_item summary timing \
    --metrics time timing

Slim Mirror Mode (Referenced Files Only)

# Sync only the rpts/ and logs/ files actually linked in the HTML report.
# All other entries (tune/, tile.params, comment, notice, etc.) sync in full.
ucs_monitor_run_status.pl \
    --base_dir /proj/runs \
    --mirror_dir /web/mirror/proj \
    --mirror_slim \
    --monitor_item summary timing \
    --metrics time timing

# Equivalent config file usage:
#   mirror_dir  = /web/mirror/proj
#   mirror_slim = 1
#   monitor_item = summary, timing
#   metrics = time, timing

Slim mode is especially useful for projects with large rpts/ trees where only a fraction of reports are linked in the status HTML (e.g., only the final routing and timing summary reports).

Workflow Diagram

  CLI / Config File
        |
        v
  +------------------+
  | Parse Arguments  |
  +------------------+
        |
        v
  +------------------+
  | License Check    |
  +------------------+
        |
        v
  +------------------+       +-------------------+
  | Load Configs     |------>| Config Dir Scan   |
  | (CLI / files)    |       | (.conf files)     |
  +------------------+       +-------------------+
        |
        v  (per config)
  +------------------+
  | Find Run Dirs    |  <-- base_dir / run_list / --run
  +------------------+
        |
        v
  +------------------+
  | Extract Tile     |  <-- summary metrics, timing, clock_qor, notices
  | Information      |
  +------------------+
        |
        +-- if --mirror_dir ----------------------------------------+
        |                                                            |
        |   Full mode (default)          Slim mode (--mirror_slim)  |
        |   +------------------+         +------------------+       |
        |   | Mirror Sync      |         | Generate HTML    |       |
        |   | (full rpts/logs) |         | (original paths) |       |
        |   +------------------+         +------------------+       |
        |          |                              |                  |
        |   +------------------+         +------------------+       |
        |   | Rewrite URLs     |         | Extract href     |       |
        |   | in tile_info     |         | referenced files |       |
        |   +------------------+         +------------------+       |
        |          |                              |                  |
        |          |                     +------------------+       |
        |          |                     | Mirror Sync      |       |
        |          |                     | (refs only +     |       |
        |          |                     |  always entries) |       |
        |          |                     +------------------+       |
        |          |                              |                  |
        |          v                     +------------------+       |
        |   +------------------+         | Rewrite HTML     |       |
        |   | Generate HTML    |         | URL strings      |       |
        |   +------------------+         +------------------+       |
        |          |                              |                  |
        +----------+--------------+---------------+------------------+
                                  |
                                  v
                   Stale mirror cleanup (both modes)
                                  |
                                  v
  +------------------+     +------------------+     +------------------+
  | HTML Report      |     | Excel Report     |     | QoR via fc_shell |
  | (web + email)    |     | (.xlsx)          |     | (if --qor)       |
  +------------------+     +------------------+     +------------------+
        |
        v
  +------------------+
  | Send Email       |  <-- if --to is set
  +------------------+
        |
        v
  +------------------+
  | Sleep / Repeat   |  <-- if --interval
  +------------------+

Output Files