erie-hls-generator

name	erie-hls-generator
description	Use when working on HLS development, HLS design, HLS modification, HLS debug, HLS debugging, Chinese-language HLS requests, high-level synthesis, Vitis HLS, AMD/Xilinx HLS, C/C++ HLS kernels, pragmas/directives, interfaces, DATAFLOW, array partition/reshape, hls_config.cfg, Tcl flow, csim/cosim, HLS reports, or HLS-generated RTL/Verilog interface, export, cosim, or debug issues.

Erie HLS Generator

Use this skill for local AMD-Xilinx/Vitis HLS C/C++ kernel generation. The bundled runtime lives in runtime/hls_generator, and the stable local facade is integration/hls_adapter.py.

Workflow

1. On first trigger in a Codex session, run python -m runtime.hls_generator deps check --json from this skill directory. If it reports blocked_dependency, ask the user whether to install the listed dependencies before continuing; do not degrade or continue past missing required or recommended dependencies.
2. Start from a confirmed HLS JSON spec or create one with the scaffold command.
3. Use the facade for local integrations:
   • run_hls_workflow(...) for full staged execution or resume.
   • render_hls_prompt(...) when a caller owns the model call.
   • validate_hls_artifacts(...) before using generated files downstream.
4. Require a confirmed requirement contract before generation: pipeline_required, streamability, interface_family, interface_profile, confirmed_by_user, and confirmation_notes. When throughput targets, numeric strategy, task parallelism, or device portability are in scope, confirm those constraints before code generation.
5. Run the fixed HLS pipeline: requirements -> codegen_plan -> tests -> python -> hls -> report_review -> remote_acceptance.
6. Keep final hardware-facing artifacts limited to HLS C/C++ headers, sources, C++ testbenches, .cfg files, and reports. Python models and vectors are validation intermediates.
7. Validate with AMD-Xilinx tooling. The validator prefers vitis-run and falls back to vitis_hls; missing local tools block with a remote-server request so the caller can ask the user to choose an erie-remote-ssh server with Vitis available.
8. For Vitis development, simulation, cosim, and debug guidance, follow runtime_config.json skill routing: prefer vitis-developer when installed, otherwise fall back to vitis-hls-synthesis.

Local Commands

Run the bundled smoke validator from this skill directory:

python .\smoke\run_smoke.py

Use the runtime CLI:

python -m runtime.hls_generator config --path
python -m runtime.hls_generator deps check --json
python -m runtime.hls_generator deps request --out .\reports\skill_dependency_request.json
python -m runtime.hls_generator scaffold --target hls --name vector_scale --out .\reports\hls\spec.json
python -m runtime.hls_generator prompt --target hls --spec .\reports\hls\spec.json --out .\reports\hls\prompt.md
python -m runtime.hls_generator validate --target hls --spec .\reports\hls\spec.json --path .\reports\hls\generated --readiness static --no-external

When local vitis-run/vitis_hls is missing, inspect the workflow's remote_toolchain_request.json, ask the user to choose a configured erie-remote-ssh build server and, when needed, a separate validation server, then use the remote acceptance helper:

python .\scripts\remote_vitis_acceptance.py --mode link --server <erie-server>
python .\scripts\remote_vitis_acceptance.py --mode vitis --server <erie-server> --profile <configured-profile> --readiness <execute|implement|cosim>
python .\scripts\remote_vitis_acceptance.py --mode vitis --build-server <erie-build-server> --validate-server <erie-validate-server> --vitis-version <shared-version> --readiness <execute|implement|cosim>

Remote Vitis acceptance refreshes erie software scan data. If multiple Vitis versions are detected and no version has been saved for that server in ~/.hls-generator/config.json, ask the user to choose a version and rerun with --vitis-version <version>.

If no remote Vitis profile has been configured and no previously saved remote selection provides the required tool path, expected tool, and target part, stop and ask the user to configure those values before continuing. Do not guess or fall back to a package default path.

If the user chooses a split build/validate topology, keep the server choice in runtime arguments or user-local configuration only. Do not encode real server ids, hostnames, usernames, ports, or board-specific server defaults into the skill package.

Vitis remote acceptance keeps the remote validation directory by default and reports remote_dir relative to the selected erie server workdir. Pass --cleanup-remote only when the user explicitly wants that remote project deleted after a successful run.

Reference Loading

• Load references/integration.md when wiring the local facade into another script.
• Load references/workflow-contracts.md when handling run directories, statuses, resume behavior, or traces.
• Load references/configuration.md before changing generated roots, protected paths, Vitis tool commands, or timeouts.
• Load references/vitis-hls-2024-2-script-guide.md before changing Vitis HLS .cfg parsing, Tcl rendering, pragma rules, report handling, or compatibility checks.
• Load references/hls-optimization-patterns.md before changing optimization examples, prompt pragma policy, report-driven tuning rules, or reusable HLS pattern guidance.
• Load references/hls-report-driven-optimization.md before changing performance-goal framing, synthesis-report interpretation, or optimization-step sequencing.
• Load references/hls-modeling-strategy.md before changing loop-bound handling, numeric-type guidance, pointer modeling, template/vector usage, or conditional pragma policy.
• Load references/hls-memory-burst-and-layout.md before changing AXI4 burst policy, local memory layout, lane packing, or reusable buffer guidance.
• Load references/hls-task-parallel-strategy.md before changing task-level parallelism guidance, channel semantics, restart behavior, or stream/dataflow positioning.
• Load references/hls-stencil-reduction-gemm-patterns.md before changing stencil/window, reduction-tree, or tiled-GEMM guidance and templates.
• Load references/hls-advanced-library-patterns.md before changing hls_task, hls_streamofblocks, hls_directio, or hls_fence guidance and validation.
• Load references/hls-device-migration-strategy.md before changing target-part migration guidance, QoR comparison rules, or floating-point/fixed-point portability advice.
• Load references/hls-library-policy.md before changing HLS include choices, advanced HLS library usage, or generated library examples.
• Load references/hls-comment-style.md before changing generated C/C++ comment language, comment coverage, or comment validation rules.
• Use assets/examples/ for minimal HLS memory, burst, stencil, reduction, tiled-GEMM, lane-packed, task-graph, stream-of-blocks, free-running, fence-ordering, stream, partition, dataflow, multi-m_axi, and numeric-strategy specs.
• Use assets/templates/ for reusable HLS JSON skeletons that already include design_requirements, interface_profile, performance, hls_profile, and confirmation notes.

Boundaries

• Do not generate handwritten Verilog or SystemVerilog.
• HLS-generated RTL/Verilog interface, export, cosim, and debug issues are in scope when they trace back to Vitis HLS code, pragmas, configuration, or reports.
• Pure handwritten Verilog/SystemVerilog debug is not led by this skill; use vivado-debug, vivado-sim, vivado-analysis, or RTL-focused skills for those tasks.
• Do not use local non-HLS hardware tools as validation substitutes.
• Do not modify files outside this skill directory.
• Keep path and Vitis-tool policy in runtime/hls_generator/runtime_config.json; update references/configuration.md when the policy changes.
• Keep skill dependencies in runtime/hls_generator/runtime_config.json; missing required or recommended dependencies are blocking. Install only after the user confirms, then restart Codex so new skill metadata is loaded.
• If vitis-developer is installed, dependency installation must not install vitis-hls-synthesis from FPGA-Agent-Skills; the remaining Vivado skills are still required.
• Use erie-remote-ssh for remote SSH checks; do not copy server-list details into this skill.
• If local Vitis tools are unavailable, prefer requesting a remote erie server over weakening validation or substituting non-HLS tools. Discover and present erie server choices before connecting.
• When comment language is auto, use the user's ~/.hls-generator/config.json; if it has no saved language, ask the user to choose English (en) or Chinese (zh) before generation.
• Do not claim Vitis validation passed unless vitis-run or vitis_hls actually ran.