# PL Optimizer Compatibility Layer

This layer makes RepoKey's PL optimization path version-aware.

Primary target:

```text
Vivado/Vitis 2020.2
```

Compatibility targets:

```text
Vivado/Vitis 2023.2
Vivado 2025.1 upstream fpl26 reference
```

## Policy

Use 2020.2 as the default production profile. Start with Vivado-only evidence
and low-risk implementation experiments. Treat RapidWright as optional until a
DCP roundtrip passes.

Mode order:

1. `vivado_only`: report collection, strategy sweep, `phys_opt_design`, route
   experiments, before/after QoR comparison.
2. `rapidwright_read_only_after_probe`: read DCP and analyze nets/cells/paths
   without writing design changes.
3. `rapidwright_writeback_after_roundtrip`: allow ECO writeback only after
   Vivado can reopen the RapidWright-written DCP and rerun timing.

## AI Rule

The compatibility layer does not decide optimizations. It reports which actions
are available and safe for the detected toolchain. AI still decides from local
evidence, AMD Doc MCP official semantics, and project context.

## Validation

Run the safe probe:

```powershell
python scripts\repokey_pl_qor.py probe
```

Run a deeper probe only with an isolated DCP:

```powershell
python scripts\compat_probe.py --profile profiles\vivado_2020_2.json --vivado D:\Xilinx\vivado2020.2\Vivado\2020.2\bin\vivado.bat --dcp D:\path\to\isolated.dcp
```

## Unified Adapter

AI agents should use `scripts/repokey_pl_qor.py` as the stable entry point:

```powershell
python scripts\repokey_pl_qor.py probe
python scripts\repokey_pl_qor.py collect-baseline --dcp D:\path\to\routed.dcp --name baseline
python scripts\repokey_pl_qor.py decide --qor-dir .vivado_ai_mcp\qor\baseline
python scripts\repokey_pl_qor.py compare --before .vivado_ai_mcp\qor\baseline --after .vivado_ai_mcp\qor\trial
python scripts\repokey_pl_qor.py make-experiment --experiment phys_opt_default --dcp D:\path\to\routed.dcp --name phys_opt_trial
```

The adapter delegates to the lower-level scripts. Use the lower-level scripts
only when changing or debugging the adapter.

Collect Vivado-only QoR evidence from a routed DCP:

```powershell
python scripts\vivado_qor_collect.py --vivado <vivado.bat> --dcp <project>\<project>.runs\impl_1\top_routed.dcp --out-root .vivado_ai_mcp\qor --name baseline
```

Generate a safe experiment Tcl without executing it:

```powershell
python scripts\vivado_safe_experiment.py --experiment phys_opt_default --dcp D:\path\to\input.dcp --out-root .vivado_ai_mcp\qor --name phys_opt_trial
```

Do not run generated experiment Tcl when baseline timing already meets
constraints unless there is a documented engineering reason.

Generate an AI decision record from collected evidence:

```powershell
python scripts\qor_decision.py .vivado_ai_mcp\qor\sample_top_routed_baseline
```

Compare two QoR captures:

```powershell
python scripts\qor_compare.py .vivado_ai_mcp\qor\baseline .vivado_ai_mcp\qor\trial --out .vivado_ai_mcp\qor\trial\compare_to_baseline.json
```
