Hls

Skill: High-Level Synthesis (HLS)

Invocation

• If invoked by a user presenting an HLS task: immediately spawn the digital-chip-design-agents:hls-orchestrator agent and pass the full user request and any available context. Do not execute stages directly.
• If invoked by the hls-orchestrator mid-flow: do not spawn a new agent. Treat this file as read-only — return the requested stage rules, sign-off criteria, or loop-back guidance to the calling orchestrator.

Spawning the orchestrator from within an active orchestrator run causes recursive delegation and must never happen.

Pre-run Context

Before executing or advising on any stage, read the following files if they exist:

1. memory/hls/knowledge.md — known failure patterns, successful tool flags, PDK/tool quirks. Incorporate its guidance into every stage decision. If absent, proceed without it.
2. memory/hls/run_state.md — current run identity (run_id, design_name, tool, last_stage). Use this to resume correctly after interruption. If absent, a new run is starting; the orchestrator will create this file before the first stage.

This pre-run read applies whether this skill is loaded by a user or called by the orchestrator mid-flow. It ensures the fix database is consulted before any diagnosis step.

Purpose

Convert C/C++/SystemC algorithmic descriptions to synthesisable RTL. Covers algorithm analysis for HLS compatibility, pragma/directive optimisation, and co-simulation to verify RTL matches the golden C model.

Supported EDA Tools

Open-Source

• Bambu HLS (bambu) — open-source HLS from Politecnico di Milano
• LegUp HLS — FPGA-targeted HLS built on LLVM
• Calyx / Futil — infrastructure for HLS compilers (academic)
• MLIR/CIRCT (circt-opt) — compiler infrastructure for hardware design

Proprietary

• Xilinx Vitis HLS (vitis_hls, dialect xilinx) — C/C++ to RTL for AMD/Xilinx devices
• Cadence Stratus (stratus, dialect cadence) — SystemC/C++ HLS for ASIC and FPGA
• Siemens Catapult (catapult, dialect siemens) — algorithmic synthesis from C++/SystemC

Stage: algorithm_analysis

HLS-Hostile Patterns (must fix before synthesis)

1. Dynamic memory (malloc/new) → replace with fixed-size static arrays
2. Recursive functions → convert to iterative with explicit stack
3. Pointer aliasing → use restrict keyword or restructure accesses
4. System calls (printf, file I/O) → wrap in #ifndef __SYNTHESIS__
5. Function pointers → replace with switch/case dispatch
6. Data-dependent loop bounds → add maximum bound + early-exit flag
7. Floating-point → evaluate fixed-point (ap_fixed<W,I> for Vitis HLS)

Analysis Steps

1. Identify innermost critical loop — the performance bottleneck
2. Analyse loop-carried dependencies — limit achievable II
3. Classify memory access: sequential (burst-able) vs random (expensive)
4. Calculate theoretical minimum latency: trip_count × body_latency

QoR Metrics to Evaluate

• All HLS-hostile patterns resolved
• Critical loop identified with dependency graph
• Theoretical II lower bound computed

Output Required

• Algorithm analysis report
• Fixed-point type recommendations (if applicable)
• Critical loop dependency graph

Stage: directive_planning

Pipelining and Throughput

#pragma HLS PIPELINE II=1          // Pipeline loop, target II=1
#pragma HLS DATAFLOW                // Task-level pipelining
#pragma HLS LOOP_FLATTEN            // Flatten nested loops
#pragma HLS LOOP_MERGE              // Merge sequential loops

Latency and Unrolling

#pragma HLS UNROLL factor=4        // Partial unroll (4 parallel copies)
#pragma HLS UNROLL                  // Full unroll (small trip counts only)

Memory and Interfaces

#pragma HLS ARRAY_PARTITION variable=buf cyclic factor=4
#pragma HLS INTERFACE mode=axis port=data       // AXI4-Stream
#pragma HLS INTERFACE mode=m_axi port=mem       // AXI4 master
#pragma HLS INTERFACE mode=s_axilite port=ctrl  // AXI4-Lite registers

Resource Binding

#pragma HLS BIND_OP op=mul impl=dsp      // Force multiply to DSP
#pragma HLS ALLOCATION operation=mul limit=4   // Cap DSP count

Strategy by Target

QoR Metrics to Evaluate

• Achieved II: ≤ design_state.constraints.hls.target_ii (one of target_ii or target_latency_cycles must be set; prefer target_ii if both — see Constraint Validation section)
• Latency: ≤ design_state.constraints.hls.target_latency_cycles cycles (one of target_ii or target_latency_cycles must be set)
• Area: within budget
• No directive synthesis errors

Output Required

• Annotated source with all directives and justifications
• Directive justification table

Stage: hls_synthesis

Domain Rules

1. Synthesise at target clock period
2. Check HLS report: latency, II, resource usage
3. Compare achieved vs target — loop back to directives if miss
4. Flag any warnings: unresolved dependencies, failed II, inferred latches
5. Verify interface protocols match system integration requirements

QoR Metrics to Evaluate

• II: matches or beats design_state.constraints.hls.target_ii (one of target_ii or target_latency_cycles must be set; prefer target_ii if both)
• Latency: within design_state.constraints.hls.target_latency_cycles cycles (one of target_ii or target_latency_cycles must be set)
• Area: within budget
• No latch inference warnings

Output Required

• HLS synthesis report (latency, II, resource summary)
• Generated RTL files
• Unresolved warnings with justification

Stage: rtl_qc

Domain Rules

1. Run lint on HLS-generated RTL using the rtl-design skill's lint_check ERROR and WARNING levels. Generated RTL is linted for correctness — latches, multiple drivers, undriven outputs, width truncation — not for the rtl-design naming and style rules, which a generator will not follow; do not hand-edit generated RTL to satisfy them
2. Verify no latches in generated RTL. With slang this requires full elaboration (slang -Weverything --ignore-unknown-modules <files>); --lint-only skips elaboration and reports zero latches on any input, so it can never fail this check
3. Verify interface signal names match integration requirements
4. Check all registers reset correctly