# Fast Simulation - AI Workflow

`simulation_acceleration` is a fast functional verification layer that lets the
AI verify RTL/testbenches with open-source simulators (Icarus / Verilator /
cocotb) before entering Vivado.

## When to Use

- When the task is mainly RTL/testbench functional verification.
- When you need to iterate quickly on a module and confirm behavior before synthesis.
- Do not use it as a replacement for Xilinx-integrated simulation (xsim) or for
  producing bitstreams / timing.

## Install-Guide Rules (required reading for the AI; prevents repeated GUI installs)

**The AI must never auto-launch a GUI install wizard unattended** (e.g. the
iverilog installer). A GUI wizard requires manual clicking; the AI cannot see or
click it, and cannot sense "which step / finished / which path", which leads to
restarting the install repeatedly.

When a missing runtime is detected (e.g. Icarus Verilog), have the **user
choose**, and do not auto-launch an install:

1. List the missing item + official download URL + three options:
   - **[A] User installs manually**: the user downloads and runs the wizard,
     then tells the AI the install path, or has the AI re-run the check to confirm.
   - **[B] User authorizes the AI to install silently**: after explicit consent,
     the AI installs via a **non-GUI** package manager, and **only once**:
     `winget install -e --id Icaros.iverilog` (or `choco install iverilog`).
   - **[C] User provides an existing path**: already installed but not on PATH;
     let the AI confirm with `check_fast_sim.ps1 -IverilogDir "<bin dir>"`.
2. Install only when the user explicitly chooses B, and only silently; **never
   restart the install repeatedly**.
3. Whatever the option (A/B/C), verify afterwards with `check_fast_sim.ps1`; the
   AI obtains the actual path via `where`/the check.
4. After a manual install and the user provides the path, record that path in the
   project manifest/evidence and call it by absolute path afterward; do not re-check.

## AI Steps

1. Check runtimes first:
   ```powershell
   powershell -File <REPOKEY_HOME>\tools\simulation_acceleration\scripts\check_fast_sim.ps1
   ```
   When a runtime is missing (cocotb / iverilog), follow the "Install-Guide
   Rules" above and let the user choose; do not force-run or auto-launch a GUI install.

2. Run the example to confirm the toolchain:
   ```powershell
   powershell -File <REPOKEY_HOME>\tools\simulation_acceleration\scripts\run_smoke_counter.ps1
   ```

3. Run fast simulation on the user's RTL/testbench and record evidence:
   ```powershell
   python <REPOKEY_HOME>\tools\simulation_acceleration\scripts\run_with_evidence.py `
     --project-root <user project> --run-name <name> --tool iverilog --timeout 300 `
     -- iverilog -g2012 -s <tb_top> -o sim.out <tb.v> <dut.v>
   ```

4. Read `<user project>\.vivado_ai_mcp\simulation\runs\*\summary.json` /
   `failures.json` and give the user a compact conclusion (pass/fail, error line,
   duration) instead of a full log dump.

## Red Lines

- Do not treat fast simulation as a substitute for Vivado/xsim.
- Do not silently fail when a runtime is missing; clearly prompt for install.
- **Never auto-launch a GUI install wizard**; the install method must be chosen
  by the user.
- Do not restart the install repeatedly; install once and verify with the check script.
