# Vhls Opt > Vitis HLS command execution and code optimization. Use when: (1) running Vitis HLS commands (csim, csynth, cosim, pack, impl) from shorthand like 'run csynth config.cfg workdir', or (2) analyzing HLS C/C++ code for optimization (throughput, latency, II, fmax, resources). Trigger on mentions of 'vhls', 'hls run', 'run csynth/csim/cosim/pack/impl', 'hls optimize', 'baseline', or HLS performance analysis requests. - Skill: `xilinx/vhls-opt` (Agent Skill) - Install (CLI): `npx skillmds@latest add xilinx/vhls-opt` - Raw SKILL.md: https://api.skillmd.com/api/skills/xilinx/vhls-opt/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: xilinx (https://skillmd.com/u/xilinx) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/xilinx/vhls-opt --- # vhls-opt — Vitis HLS Command Runner & Optimizer This skill has two modes: **Run** (command execution) and **Opt** (code optimization analysis). --- ## Mode 1: Run — HLS Command Execution Convert shorthand into Vitis HLS commands and **execute them**. ### Environment Detection Before the first execution in a conversation, verify the environment is set up: 1. Use the Bash tool to run: `which vitis 2>/dev/null && vitis --version 2>&1 | head -5` 2. If `vitis` is NOT found, ask the user to set up their Vitis environment first (e.g., `source /settings64.sh`) and retry. 3. If `vitis` IS found, proceed directly. Cache the result: skip this check on subsequent invocations in the same conversation. ### Shorthand Grammar ``` run ``` - `` : `csim | csynth | cosim | pack | impl` - `` : required, must end with `.cfg` - `` : required - Both paths are relative to the current working directory unless absolute. ### Command Templates | Action | Command | |--------|---------| | csynth | `v++ -c --mode hls --config --work_dir ` | | csim | `vitis-run --mode hls --csim --config --work_dir ` | | cosim | `vitis-run --mode hls --cosim --config --work_dir ` | | pack | `vitis-run --mode hls --package --config --work_dir ` | | impl | `vitis-run --mode hls --impl --config --work_dir ` | ### Execution Rules 1. **All arguments present and validated**: - Verify `` exists using the Read tool or Bash `test -f`. If missing, stop and tell the user. - Verify `` exists (or can be created). If it does not exist, create it with `mkdir -p`. - Show the user the exact command that will be executed. - Execute it using the Bash tool. For long-running actions (`csynth`, `cosim`, `impl`), set `timeout` to 600000 (10 minutes). - After execution, report the result: - **Success**: Print "Completed successfully." and show the last 20 lines of output. - **Failure**: Print the full stderr/stdout and highlight the error. If a log file exists in ``, read the tail of the log for additional context. - For `csynth`: after success, automatically read and display key metrics from `//syn/report/csynth.rpt` (or the first `csynth.rpt` found under ``) — specifically the Performance Estimates and Utilization Estimates sections. 2. **Missing ``**: State it is required, explain that the HLS config file (`.cfg`) contains the component source files, top function, clock period, and device target. Ask the user to provide it. 3. **Missing `` only**: Ask the user for it. 4. **Multiple actions**: The user may chain actions (e.g., `run csim csynth cosim config.cfg workdir`). Execute them sequentially in the given order, stopping on the first failure. ### Post-Run Reporting After any successful action, check for and report: - Warnings count from the output - For `csynth`: latency, II, clock period, and resource utilization from `csynth.rpt` - For `cosim`: pass/fail status from cosim output - For `impl`: timing (WNS/TNS) and utilization from implementation reports --- ## Mode 2: Opt — HLS Code Optimization Analysis Analyze HLS code and provide optimization directions with feasibility assessment. Optimizations are applied **iteratively** — one group at a time — with cosim verification after each round. ### Required Inputs - Optimization goals (throughput / latency / II / fmax / resources) - Current constraints (target device / memory / interfaces) or `.cfg` file - `` and `` — needed to run csynth/cosim during iterations - Code (snippet or file) If the user provides a ``, automatically read: - The `.cfg` file for constraints (clock, part, top function) - Source files referenced in the `.cfg` - `//syn/report/csynth.rpt` for current metrics ### Step 0: Baseline (run when user asks for baseline, or before first optimization) Before any optimization, establish a baseline: 1. Run `csynth` using the command template from Mode 1. 2. Find and read the synthesis report: use Glob `/**/csynth.rpt` to locate it. 3. Extract and display a **Baseline Report** with: - Target clock period and estimated clock (fmax) - Latency (min/max, in cycles and absolute time) - Initiation Interval (II) - Resource utilization (BRAM, DSP, FF, LUT) — counts and percentages - Any timing or resource warnings 4. Save these numbers internally as the baseline for comparison in later iterations. If the user asks for "baseline" or "baseline performance", run this step and stop — do not proceed to optimization unless asked. ### Workflow 1. **Restate** goals and constraints. 2. **Retrieve baseline metrics** (run Step 0 if no baseline exists yet). 3. **Analyze** the code for: - Correctness risks - Performance bottlenecks (loop II, memory bandwidth, dependencies, interfaces) - Pragma opportunities (pipeline, dataflow, array_partition, stream, etc.) 4. **Group improvements** into logical categories. Typical groups: - **Loop optimization**: pipeline, unroll, loop_flatten, loop_merge - **Memory optimization**: array_partition, array_reshape, bind_storage - **Dataflow / streaming**: dataflow, stream depth, FIFO sizing - **Interface optimization**: m_axi burst, interface pragma, port widths - **Algorithmic restructuring**: code refactoring, function inlining, data type changes - Groups may vary based on the specific code and goals. 5. **Present all groups** with rationale, expected impact, and trade-offs for each. Ask the user which group to apply first, or recommend a starting order. ### Iterative Optimization Loop Apply optimizations **one group at a time**. For each iteration: 1. **Apply** the changes for the current group using the Edit tool on the source files. 2. **Run csynth** to get updated metrics. 3. **Run cosim** to verify functional correctness. 4. **Report iteration results**: - cosim pass/fail status — if FAIL, immediately revert the changes (using Edit to restore the original code) and report the failure. Do not proceed to the next group. - Updated metrics vs. baseline and vs. previous iteration: - Latency delta - II delta - fmax delta - Resource utilization delta (BRAM, DSP, FF, LUT) - Summary: whether this group improved, regressed, or was neutral for each metric. 5. **Proceed or stop**: - If cosim passed and metrics improved, confirm with the user before moving to the next group. - If cosim passed but metrics regressed, ask the user whether to keep or revert. - If cosim failed, revert and ask the user how to proceed. Repeat until all groups are applied or the user is satisfied. ### Output Format (per iteration) ``` Iteration N: ───────────────────────── A) Changes Applied - List of edits with rationale B) csynth Results - Latency: (baseline: , delta: <+/->) - II: (baseline: , delta: <+/->) - fmax: (baseline: , delta: <+/->) - BRAM: (baseline: , delta: <+/->) - DSP: (baseline: , delta: <+/->) - FF: (baseline: , delta: <+/->) - LUT: (baseline: , delta: <+/->) C) cosim Result: PASS / FAIL D) Recommendation: Keep / Revert / User decision needed ``` ### Final Summary After all iterations, present a cumulative summary: ``` Optimization Summary ════════════════════ Baseline → Final | Metric | Baseline | Final | Delta | |---------|----------|--------|--------| | Latency | ... | ... | ... | | II | ... | ... | ... | | fmax | ... | ... | ... | | BRAM | ... | ... | ... | | DSP | ... | ... | ... | | FF | ... | ... | ... | | LUT | ... | ... | ... | Groups applied: ... Groups reverted: ... cosim: all PASS / N failures ```

Copyright © 2026 Advanced Micro Devices, Inc

Terms and Conditions