Silinx · User's guideTry Silinx

Silinx HLS: C and C++ to HDL (high-level synthesis)

User's guide · Designing · English

A C function as a design source: Silinx turns it into a VHDL or Verilog module, as AMD's Vitis HLS (formerly Vivado HLS, user guide UG1399) does for AMD's newer parts. The C file is the module's base; its HDL is generated from it, read-only, as a drawing's is. The plan and its phases: issue #1532.

Silinx HLS is a subset of what Vitis HLS accepts: a source Silinx takes also goes through Vitis HLS (as C++), with the same ports and the same behaviour at them. Vitis HLS does not target the Spartan-3E, so it is not Silinx's oracle: the C itself is (see Checking it below).

The source

Types

CBitsSigned
bool1no
char, signed char / unsigned char8char signed (as -fsigned-char)
short / unsigned short16
int / unsigned32
long, long long and their unsigned64
int8_t … int64_t, uint8_t … uint64_tas named
ap_int<W> / ap_uint<W>Wyes / no
float (#1768), double (#1773)32, 64 (their IEEE-754 bits)

float and double in hardware (#1768, #1773): a synthesized function's floating-point variables, arguments, arrays and results are their IEEE-754 bits (32- and 64-bit ports, as Vitis HLS's), and each operation (+ - *, the comparisons, ?:, -x, !x, the conversions to and from the integers and between float and double) is a circuit of the soft-float library (core/c-softfloat.js: round to nearest even, subnormals, infinities, a quiet NaN), inlined where it is: the hardware gives the C simulation's bits. C's usual conversions: a double operand, a double constant (0.5) too, makes an operation a double's; write 0.5f to keep it a float's. A table computed at synthesis (#1779): a call of a function that only writes its arrays from constants (no argument read, no global but a constant, no call but math.h's), as for (i…) t[i] = sin(…), is run by the C simulation at synthesis, its values the arrays' (a ROM), as Vitis HLS computes one; so is such a loop in the function's own body, its writes depending only on constants and its own index, the array used only by reading its elements after it (#2151: the loop is not made); math.h and a division of constants are folded the same way. Of other values: a division (/), sqrt / sqrtf and fabs / fabsf are made (#1783), and floor, ceil, trunc, round, fmin, fmax, copysign (and their …f) on the value's bits (#1843); exp, log, sin, cos, tan, pow, log2, log10, exp2, atan, asin, acos, sinh, cosh, tanh, cbrt, hypot, fmod (and their …f) by Silinx's own algorithms, the same in the hardware and the C simulation (core/c-mathlib.js, #1761).

ap_fixed<W, I, Q, O> / ap_ufixed (#include "ap_fixed.h", #1643) run in the C simulation as AMD's ap_fixed.h computes them: full-precision results, the quantization modes (AP_TRN, AP_TRN_ZERO, AP_RND, AP_RND_ZERO, AP_RND_MIN_INF, AP_RND_INF, AP_RND_CONV) and overflow modes (AP_WRAP, AP_SAT, AP_SAT_ZERO, AP_SAT_SYM) of a conversion, to_double(), to_int() (toward zero), cout of a value. In hardware a fixed value is its raw bits: an operation aligns its operands' points with shifts in the type AMD gives its result; a conversion drops bits with its quantization's rounding (an adder) and handles its overflow (a wrap a truncation, a saturation two comparisons and a multiplexer). A double constant is only an ap_fixed's value (a_t c = 0.25;, a table of coefficients, a comparison x < 1.5). x.range(hi, lo) = v assigns those bits. The test bench may use float and double (#1641): C's arithmetic and conversions, math.h, printf's %f %e %g printed exactly as C's library prints them, C++'s cout of a double (6 significant digits, or as fixed, scientific, setprecision set the stream), ap_int's to_double(). const is kept; volatile is accepted on arguments and has no effect (as in Vitis HLS's default).

Arithmetic

C++ (.cpp sources)

The C above, plus the C++ Vitis HLS synthesizes (#1590). Each construct becomes C before the checks, so its hardware is the C's:

Not synthesizable, as in Vitis HLS: new / delete, exceptions, RTTI, virtual functions, recursion, the STL (but the headers above). Not yet: operators other than ().

Structs and enums (C and C++)

A struct is disaggregated, as Vitis HLS does with the structs inside the code: each member is a variable of its own, named by the variable and the member (p.x is p_x, line[2].a.b is line_a_b[2]); an array of structs is an array per member; a member array of an array of structs is one array of both sizes (a[i].v[j] is a_v[i * 4 + j]). So each member is a register, or a memory when its array is large, of its own.

What can be synthesized (UG1399's rules)

  1. The whole functionality in the top function and the functions it calls.
  2. No system calls: printf, fprintf, puts are ignored by synthesis (a note); malloc, free, exit, file I/O, time, rand are refused.
  3. Fixed sizes: no dynamic memory, no recursion (direct or through other functions). A loop whose count depends on its inputs is made, as Vitis HLS makes it (#1699): a state machine that runs until its condition is false, its latency unknown (a warning; #pragma HLS LOOP_TRIPCOUNT max= gives the report a bound).
  4. Unambiguous: a pointer only to an argument, an array or a variable, no function pointers, no goto. Pointer arithmetic (#1599) as Vitis HLS takes it: *(p + e) is p[e]; a local pointer is set to an array, &x, &a[i] or a + i (p = sel ? a : b in an if), read as *p or p[i] and moved with p += n or p++: Silinx makes it the target it points to (a multiplexer of their elements when it has several; written only when it has one) and an offset. Vitis HLS's other forms (#1895): a local pointer passed to a function (its target passed; one target, not moved); a pointer cast to a narrower native integer type (char *p = (char *)&a[i], read only: the bytes of a's elements from their least significant, as on x86); a pointer to a pointer parameter of a function the top calls, resolved at compile time (each call passes &q, q a pointer; read through only, **pp); a pointer argument moved by arithmetic (p += n, p++, p = p + n), then indexed from its new base. A pointer compared, or one that does not resolve so, is refused, with the rule.
  5. No undefined behaviour Silinx can see.

Each refused construct has its own message, at its line and column, saying what is not possible and what to write instead.

The module made

Names and behaviour as Vitis HLS makes them (UG1399, "Interface synthesis"):

SourcePorts
(clock and reset)ap_clk, ap_rst (active high, synchronous) — none for a combinational module (#1900); ap_rst_n (active low) when the top has an axis port (#1894)
the block protocol ap_ctrl_hs (default)ap_start in; ap_done, ap_idle, ap_ready out
#pragma HLS INTERFACE ap_ctrl_chain port=returnap_ctrl_hs's and ap_continue in (#1965): ap_done and ap_return held after a call until ap_continue is 1, no new call meanwhile; ap_ready one cycle; ap_idle also 0 while ap_start is 1; ap_clk and ap_rst even when combinational (its latency 0), as Vitis HLS 2025.2
#pragma HLS INTERFACE ap_ctrl_none port=returnno block protocol ports (a sequential module: ap_clk and ap_rst only, running by itself, #1900)
the returned valueap_return (its type's width)
a scalar argument int ainput a (ap_none)
a pointer argument only readinput p (ap_none)
a pointer argument only writtenoutput p and p_ap_vld (ap_vld)
a pointer argument read and writteninput p_i, output p_o and p_o_ap_vld (ap_ovld)
a struct argument (#1628)one port of its members (above): read, input s; written, s_i, s_o, s_o_ap_vld; returned, ap_return
an array argumentap_memory: a_address0, a_ce0, a_we0, a_d0, a_q0; one of two or more dimensions (a[N][M], #1786) one memory of N*M words, a[i][j] at i*M + j; an array of structs one memory of its words (#1668)
an array argument with #pragma HLS INTERFACE bram (#1668)a BRAM's port: a_Addr_A (32 bits, an address in bytes), a_EN_A, a_WEN_A (a write enable a byte), a_Din_A, a_Dout_A (its words a power of 2 of bytes), a_Clk_A, a_Rst_A
a pointer argument indexed (p[i], *(p + i), #1599), or passed to a function that indexes it (#1684)ap_memory, its depth the INTERFACE pragma's depth= (else 1024, a warning); a pointer to structs one memory of their words (#1668), a pragma naming the struct applying to it
a pointer or an array argument with #pragma HLS INTERFACE ap_fifo (#1901)ap_fifo, as a stream's: each *p, p[i] a read, each *p = v, p[i] = v a write, in the order of the code (constant positions out of order, or read and written: an error)
a pointer argument with #pragma HLS INTERFACE ap_hs (#1901)the two-way handshake: read, p, p_ap_vld, p_ap_ack; written, p, p_ap_vld, p_ap_ack; each access a state that waits for it
an array argument with BIND_STORAGE or storage_type= ram_2p / ram_t2p, in a loop with UNROLL, or of a DATAFLOW top (#1901)two ports: ram_2p reads on a_address0, a_ce0, a_q0 and writes on a_address1, a_ce1, a_we1, a_d1; ram_t2p (UNROLL's) has both ports, as far as it is read and written; a DATAFLOW top's has all their signals, those no process uses driven 0. Two reads of a statement share a state, two writes too when their addresses cannot be the same; unrolled copies do not share one yet, port 1 then idle
a stream argument, hls::stream<T>ap_fifo: s_dout, s_empty_n, s_read; s_din, s_full_n, s_write; a stream of structs one of their words (#1668)
a stream with #pragma HLS INTERFACE axis, or of ap_axis / ap_axiu / hls::axis_user with no pragma (#1894)AXI4-Stream: s_TVALID, s_TREADY, s_TDATA (a struct's word, or an element of an array of streams s_0_TDATA…); those of ap_axi_sdata.h their side channels, s_TKEEP, s_TSTRB, s_TUSER, s_TLAST, s_TID, s_TDEST, those of width 0 none. Not with an hls::FIR (a warning, its ap_fifo kept)
an array argument with #pragma HLS INTERFACE axis (#1894)AXI4-Stream as above, when the array is read or written once in one loop for (i = 0; i < N; i++) of its size; else a warning, its ap_memory kept

Ports are std_logic_vector(W-1 downto 0) (VHDL) or [W-1:0] (Verilog), a 1-bit type a std_logic / plain wire. The block protocol: ap_start starts a call; ap_ready says the inputs are read and the next call may start; ap_done (one cycle) says the outputs and ap_return are valid; ap_idle is 1 while no call runs.

An argument named as a reserved word of VHDL or Verilog (in, out, signal…), or as one of the names Vitis HLS reserves (pos, read, write, value, length, rst, the block protocol's ap_start, ap_return…; #1902, #1926), in any letter case, has its ports named <name>_r (in_r_dout, pos_r), with a warning, as Vitis HLS 2025.2 names them (test/hls-corpus/vitis-names.json, from scripts/hls-vitis-names.mjs). neg and SystemC's other names (sensitive, sc_module, clk) are kept. Vitis keeps a few words of the languages: VHDL-2008's PSL words (vunit…) and SystemVerilog-2009's (soft, nettype…) are kept too; units, uwire, include, incdir and rtranif1, which Silinx's VHDL or Verilog would not compile with, are renamed, and their warning says Vitis does not.

A function with no static variable whose loops all have constant bounds (fully unrolled) is combinational: with ap_ctrl_hs, ap_done and ap_ready follow ap_start and ap_idle is 1; with ap_ctrl_none, only the data ports. Any other function (a loop whose count depends on its inputs, a static or global variable) is a sequential module: a finite state machine with a datapath. Its code is cut into basic blocks (what runs with no jump, its ifs and switches with no loop in them included), one state each, run in one clock cycle; its variables are registers (a static or a global keeps its value between calls, its initial value set at the reset); its loops, break, continue and return choose the next state. The arguments are read when ap_start is 1 in the idle state; the call's last state has ap_done and ap_ready at 1 for one cycle, ap_return valid; a pointer output's _ap_vld is 1 for one cycle after each write, its value then valid. With ap_ctrl_none (#1900) a sequential function with a stream argument has only ap_clk and ap_rst: it runs by itself, starting its next call when one is done (Vitis HLS's free-running kernel), and the co-simulation feeds its streams and waits for each call's values; one with no stream keeps ap_ctrl_hs, with a warning (its calls could not be told apart: Vitis HLS's co-simulation refuses it too). A function with a loop called by the top, or given an array, is inlined into it (#1632): its loops are the top's (each call its own), its array parameters the arguments (a memory too), its pointer and reference parameters the variables passed, its by-value parameters local variables, its static variables one register per function shared by every call; an early return ends it through a flag. Such a call in an expression is made before it; in a loop's condition, or after &&, || or ?:, it is refused. A division or remainder (#1656) by a constant power of 2 is shifts, by another constant a multiplication by its reciprocal and a shift, by a variable a restoring divider (one compare-and-subtract per bit, combinational: in one cycle); all written with + - * and comparisons, as XST takes them. A division by zero gives every quotient bit 1 and the dividend as the remainder (the C simulation stops on it). The machine shown as an ASM chart: #1575.

A function with #pragma HLS INLINE off is a sub-module (#1960): a module of its own with its block protocol (ap_start, ap_done, ap_idle, ap_ready), an instance of it a call, as Vitis HLS makes them (<function>_U0, _U1, …, #2244); one shared by all its calls when it, or what it calls, holds a static variable (one variable, as the C's). Each call is a state of the caller's machine holding ap_start at 1 and the arguments until ap_done; a loop calling it is not pipelined (said, if asked). Its value and a pointer's are taken when they come (ap_return at ap_done, a pointer's at its _ap_vld, so one it does not write keeps the caller's); an array or a stream argument's port is the callee's during the call (the array a memory, whatever its size); its static variables are the module's. A global variable it shares with its caller is a port of it, as Vitis HLS makes it (#2244): an integer one a pointer's (g_i, g_o, g_o_ap_vld; g alone when it only reads it), an array a memory's, the caller's variable passed at each call. The report lists each function's calls, latency (from ap_start to ap_done; at most, when its branches differ) and resources (states, register bits, memories), a sub-module's own below it. The same modules serve DATAFLOW's processes. Five cases stay inlined, with a warning: a function of latency 0 called by a top of latency 0 (no clock to start it with: its ports are Vitis HLS's), one sharing a global variable with its caller that a function it calls uses too, or that is not an integer nor an array of them (not yet), one with a struct argument, an hls::vector too (not yet), one with ap_ctrl_chain, and one called by a module that waits for an AXI master (ap_ce) (not yet). A function is one module per size of its arrays; FUNCTION_INSTANTIATE variable=v (#2244) makes one per constant v its calls give, v a constant inside it (its port gone), a call whose v is not a constant the module with the port; ALLOCATION instances=f limit=N function (below) gives its calls N instances at most, in turn. With no pragma a function is inlined, where Vitis HLS keeps a large one: cToHdl(…, { large: true }) (and cosimulate's) keeps a function that holds a loop of its own (not unrolled whole) and is called outside any loop and any pipelined function a sub-module; it is not the default until Vitis HLS's modules of the corpus are recorded (scripts/hls-vitis.mjs reads them from csynth.xml's RTL hierarchy into vitis.json, #2244) and say which of its functions it keeps.

Arrays and memories (#1527). A local array of up to 64 elements is registers (one per element; an index that is not a constant a multiplexer). An array argument is a memory outside the module, ap_memory: one port, its address (_address0, enough bits for its size) and enable (_ce0), its write enable and data (_we0, _d0, when it is written) and the value read (_q0, the cycle after its address, as a block RAM gives it); the module is sequential. A local, static or global array of more than 64 elements, and a constant one in a sequential module, is a memory inside it with the same port, written so that ISE and Yosys make it a block RAM: its initial values its contents (a const array, or one never written, is a ROM); a static or global one keeps its values between calls; one initialized with { … } and written must be static (or initialized with a loop). Each access takes a state: a statement reading a memory has a state per read (its address driven), then its own (the values read in registers); a write is a statement of its own (a[i] = v;, a[i] += v;, a[i]++;), with no other side effect in it; the index of a memory has no side effect; a memory is accessed in the top function only (not passed to a function, not in a switch). A combinational function's constant arrays are LUT ROMs.

The library's types (#1891)

DATAFLOW (#1707)

#pragma HLS DATAFLOW in the top function, whose body is calls of functions and declarations of streams and arrays, makes each call a process running at the same time as the others, as Vitis HLS does (UG1399, Task-level parallelism): each callee is a module of its own, made as the top would be (its own machine and ap_ctrl_hs; a callee called twice, two instances; a pointer argument the size of the array it is given). The channels between them:

The top's ap_ctrl_hs starts every process once a call and is done when every one is. With ap_ctrl_none (and a stream argument), or when every process is an hls::task (a data-driven top), the top has only ap_clk and ap_rst, as Vitis HLS's (#1900): its processes start again once all are done. The C simulation runs the calls in order; the co-simulation drives the top's ports as for any module, and when a call does not end it names the streams that may be too shallow (a stream to a process that waits for its writer to be done, through a buffer, must hold all a call writes). A loop among the calls of a region of streams is a process of its own (Loop_<k>_proc, as Vitis HLS's Loop_…_proc), and a process may give a value back through an output of the top (inner(b, s, &out), out and out_ap_vld) (#1706). A region's process that is itself a region (a function template's instances, Vitis HLS's unique task regions) has its processes and channels in its caller's region; a region the top calls among other statements is a module of its own, called each time (its tasks' state kept). The report gives each process's latency, and the region's latency and interval (their streams' waits are the co-simulation's). Not yet: a process's result (return) or an output to another process, an argument of the top shared by two processes, a channel with two writers or readers.

hls::stream_of_blocks (hls_streamofblocks.h, #1891): hls::stream_of_blocks<B> s; with typedef T B[N];, hls::write_lock<B> l(s); and hls::read_lock<B> l(s);, l[j]. A block is a word of a FIFO (a stream per element, its depth the blocks', hls::stream_of_blocks<B, D>), not Vitis HLS's ping-pong memory: the same values, more registers. A write lock's block is written at the end of its scope; a return, break or continue within that scope is refused.

hls::split and hls::merge (hls_np_channel.h, #1743): hls::split::round_robin<T, N, D> s; (its processes writing s.in, reading s.out[i]) and hls::merge::round_robin<T, N, D> m; (writing m.in[i], reading m.out) are FIFOs and a task of their own moving each value, a split's to its outputs in turn, a merge's from its inputs in turn. load_balance (Vitis HLS's a free output, an input with data, in the schedule's order) is made as round_robin, with a warning.

hls::task (hls_task.h, #1721): hls_thread_local hls::task t(f, a…); starts, once, a task running f again and again while its inputs have values (hls_thread_local streams and tasks live across calls). The C simulation runs the tasks whenever the test bench or the top would wait (a read of an empty stream, the end of a call of the top), as Vitis HLS's threads would: an invocation of f that would read an empty stream is undone and run again later; an f of the form init; while (1) body keeps its init's variables across its iterations. In hardware (#1719) each task is a process running by itself (its ap_start 1: its machine starts again when done, its state kept across calls), its hls_thread_local streams FIFOs; the top's ap_done does not wait for the tasks, and the co-simulation waits for the values a call reads and writes (an input stream's values kept across calls: a task may read ahead of the C's).

The FIR filter: hls::FIR (hls_fir.h, #1942)

Vitis HLS's FIR filter (the FIR Compiler, PG149), with Silinx's own C model and hardware:

struct config1 : hls::ip_fir::params_t {
  static const unsigned num_coeffs = 7;
  static const unsigned coeff_sets = 3;
  static const unsigned input_length = 20;
  static const unsigned output_length = 10;
  static const unsigned filter_type = hls::ip_fir::decimation;
  static const unsigned decim_rate = 2;
  static constexpr double coeff_vec[21] = { … };   // (or declared here, defined after: const double config1::coeff_vec[21] = { … };)
};
void top(data_t in[20], out_t out[10], ap_uint<8> *config) {
  static hls::FIR<config1> fir1;   // (static, or at file scope: its delay line lives across calls)
  fir1.run(in, out, config);       // (run(in, out) with one set; arrays or hls::streams; a config stream)
}

An RTL blackbox: syn.blackbox (#1903)

A function written in VHDL or Verilog, as Vitis HLS's RTL blackbox (UG1399): a JSON file describes it, and Silinx HLS uses its C model in the C simulation and its module in the synthesis, one instance for each call.

The FFT: hls::fft (hls_fft.h, #1943)

Vitis HLS's FFT (the FFT LogiCORE, PG109), with Silinx's own C model and hardware:

typedef std::complex<ap_fixed<16, 1> > cx;
struct config1 : hls::ip_fft::params_t {
  static const unsigned max_nfft = 10;
  static const unsigned output_ordering = hls::ip_fft::natural_order;
};
void top(ap_uint<1> dir, ap_uint<15> scaling, cx xn[1024], cx xk[1024], bool *status) {
#pragma HLS interface ap_fifo depth=1 port=status
#pragma HLS interface ap_fifo depth=1024 port=xn,xk
#pragma HLS stream variable=xn
#pragma HLS stream variable=xk
#pragma HLS dataflow
  hls::fft<config1>(xn, xk, dir, scaling, -1, status);   // (xn, xk arrays or hls::streams)
}

Pragmas (#pragma HLS …)

PragmaIn Silinx
TOP name=the top function
INTERFACE ap_ctrl_none / ap_ctrl_hs / ap_ctrl_chain port=returnthe block protocol
INTERFACE ap_none / ap_vld / ap_ovld / ap_memory / bram port=the argument's interface
INTERFACE s_axilite port= [bundle=] [offset=] (#1893)an AXI4-Lite slave s_axi_<bundle>_* (control by default): a scalar or a pointer to one a register, port=return the block protocol's (interrupt, the control register at 0x00; the interrupts' at 0x04, 0x08, 0x0c; the arguments from 0x10); the module's reset ap_rst_n
INTERFACE m_axi port= [bundle=] [depth=] [offset=] [max_widen_bitwidth=] (#1893)an AXI4 master m_axi_<bundle>_* (gmem by default): an array, or a pointer indexed or read and written as *p, a memory read and written over the bus, a word on its byte lanes, in bursts (#2276): a read that misses fetches a burst from its element on (ARLEN + 1 beats: up to max_read_burst_length=, 16 by default, within its array and its 4 KB page) into a buffer of its port, whose next reads are served at once; writes go into a buffer of their port, consecutive ones gathered into a burst (up to max_write_burst_length=), written out when it is full, when a write does not follow, when a read misses and before ap_done; a write updates the read buffers that hold its beat; the module waits (ap_ce) only for an access not served; its address a register of 64 bits of the slave (offset=slave, the default: control if no s_axilite names it), a port (offset=direct) or 0 (offset=off); the bus 32 bits at least, or a word's, or max_widen_bitwidth=. A config's syn.directive.interface=<top> mode=m_axi … is the same pragma; hls_burst_maxi.h's hls::burst_maxi<T> argument a master's pointer, its read_request(o, n) / write_request(o, n) queued (up to 4) and its read() / write(v) at the requests' elements in turn, one a statement; memcpy(a, b, n) a loop of the elements
AGGREGATE variable= compact= / DISAGGREGATE variable= (the top's, #1668)a struct argument, a stream or an array of structs one port, stream or memory of its words, packed compact=bit (an array's or a stream's default), byte, none (a scalar struct's default) / a port, a stream or a memory per member
INLINE / INLINE recursive / INLINE offthe function dissolved in its callers / the functions it calls too / a sub-module of its own, an instance a call (#2244), whatever its caller's recursive (#1960, below)
FUNCTION_INSTANTIATE variable=v (in an INLINE off function's body, #2244)a module of the function for each constant v its calls give, v a constant in it (no port); an argument that is no value (a pointer, an array, a stream, a struct) or no argument: a warning
LOOP_TRIPCOUNT min= max=the report's bound of a loop whose count depends on the inputs (its latency, else unknown)
PIPELINE [II=] / PIPELINE off (in a loop's or the top function's body)a sequential module's loop: its iterations overlapping, a new one every II cycles, its inner loops of constant count unrolled in it (below); the top function's: its calls overlapping; a warning saying the II made, and why, when it is more than asked. off: not pipelined, not even automatically
UNROLL / UNROLL factor=N (in a loop's body)whole: a loop of constant count run in the state it is in (no state of its own); factor=N: N iterations a state. A combinational module's loops are all unrolled
ARRAY_PARTITION variable= type=completethe array's elements registers, whatever its size (not a memory); dim=N of an array of more dimensions: a memory per value of that index
`ARRAY_PARTITION variable= type=block\cyclic factor=N [dim=D]` (#1920)several memories, as Vitis HLS's: cyclic element k in memory k % N, block consecutive blocks of ceil(L / N); an argument's each with its own port (d_0_address0, d_1_address0, …), a local's A_0, A_1, … A local array of 64 elements or fewer stays registers. Accesses of different memories share a state only when the memory is known at synthesis (A[i * N + 3] cyclic factor=N)
DATAFLOW (the top function's, #1707)its calls processes running at once (below); a region of other statements: a warning, made sequential
STREAM variable= depth=a DATAFLOW region's stream: its FIFO's depth (else hls::stream<T, D>'s D, else 2)
BIND_STORAGE variable= type= (#1901)a local array a memory (a small one too) of ram_1p, ram_2p, ram_s2p, ram_t2p, rom_1p or rom_2p's ports; another type: a warning. impl= (#1961): lutram and bram told to the tools (ram_style, rom_style), register its elements registers, no memory; uram, srl, latency= and an argument's: a warning
ARRAY_RESHAPE variable= type= [factor=] [dim=] (#1961)type=cyclic factor=N: element k in word k / N at slice k % N; type=block: word k % S at slice k / S, as Vitis HLS packs them (core/c-reshape.js, #2424). The top's argument of one dimension (integers, factor 2 or more) is one ap_memory of the words, the co-simulation packing the C's elements; a local memory is one memory of the words, its initial values packed; a small local array is registers, as a partition's. Otherwise made as ARRAY_PARTITION (a local) or its port's words kept (an argument), with a warning
`DEPENDENCE [variable=] [class=array] inter\intra [RAW\WAR\WAW] false` (#1961)a pipelined loop's or function's memory, in the loop the pragma is in and those in it: inter a read need not come after another iteration's write, so the II is no longer bound by it (the C's results then only if the dependence really is false, as in Vitis HLS); intra a read and a write of one iteration in the same stage. true or no false: no effect. A variable's dependence is kept: a warning
LOOP_FLATTEN [off] (in a loop's body, #1961)the loop made one with the loop around it (and on up, each with its own pragma), of the product of their counts, when the one around holds nothing else, both counts are constants and no break, continue, return or goto is in it; else a warning, its loops kept. off: left alone
LOOP_MERGE [force] (in a body, #1961)its consecutive for loops made one, of the largest count (each body while its own lasts), or of their common bound; not when a value crosses them in another order than the C's (only an array at each one's own variable is safe), a warning; force merges them all the same, on the designer's word
ARRAY_STENCIL variable= (in a pipelined loop's body, #2503)the loop and the loop over the rows around it (both of constant counts, the outer holding nothing else) made one over the 2-D array's elements, an element read an iteration, kept in line buffers (a memory of a row for each row of the window but the last) and a window of registers, the taps a[y + i][x + j] of the body (i, j constants or its inner loops' counters, directly or through variables): II=1 with one read of the array an iteration. The outputs come in the C's order, later; the body runs every iteration, its writes only on an output's. A local array the body reads at constant indices (its inner loops unrolled), the filter's coefficients, is made registers. A body that writes the array, reads another argument, or has a break, continue, return, goto or call: a warning, its reads one at a time
`BIND_OP variable= op=mul impl=fabric\dsp\auto` (#1961)fabric: the multiplications assigned to the variable made of LUTs (a shift and an addition a bit), no multiplier block; dsp, auto: a block, as with no pragma. latency=, another operation on dsp, a floating-point operation: a warning
ALLOCATION instances=mul limit=N operation (#1961)a cycle takes at most N multiplier blocks (a wide multiplication counts its 18 x 18 blocks), the others waiting for a later cycle and sharing them; a pipeline's II is kept, with a warning if it takes more. instances=f limit=N function of an INLINE off function: its calls on N instances at most, in turn (#2244; else one a call). instances=dmul limit=1 operation (and dadd, dsub, ddiv, dsqrt, fadd, fsub, fmul, fdiv, fsqrt, #2273): the operations of that kind in the pragma's scope (its function, or its loop's body) one shared unit, a sub-module of the soft-float's operation scheduled over the clock, each operation a call of it (its alignment, normalization and rounding made once: much less area, a few cycles more each, and a loop calling it not pipelined); without the pragma each operation is inlined where it is; one in a loop's header, after && / `\\ or in a branch of ?:` stays inlined. Other operations and an inlined function: a warning
LATENCY [min=] [max=] (of the top function, #1961)min=: wait states at its start, a combinational top made sequential; max=: a warning if a path takes more. Of a loop or a region, or of a pipelined function: a warning
EXPRESSION_BALANCE off (in the top's body, #2613)by default a sum of four terms or more of one width is balanced into a tree (core/c-balance.js), before the states and a pipeline's stages are made: the same value, log2 of its terms deep; off keeps the chains as written. Elsewhere, or not off: a warning
STREAM outside a DATAFLOW region; type=shared / unsync, or depth= of an array, in one (#1961)a warning saying why: a stream is a FIFO, a local array a buffer (PIPO)
Vitis HLS's other pragmas, and AXI4-Stream (axis) on what is not a stream or an arrayaccepted and ignored, with a warning; an unknown pragma: a warning

A loop's pragma is its body's first statements; one elsewhere is ignored with a warning.

PIPELINE, as Vitis HLS makes it (#1962, core/c-pipe-sched.js): the iterations of a loop that accesses a memory or holds a continue or a break overlap, a new one every II cycles, and its cycles are Vitis's count, (N - 1) x II + the stages of an iteration (the report's depth). Each memory's port takes one access a cycle (a read's value the cycle after), the operations are chained while they fit the clock, its inner loops of constant count are unrolled, those with accesses too, and an element read twice is one read. The II is the one the ports and the dependences allow; the operations are then cut into stages by the clock, an iteration over several cycles at that II (#2182: the report's depth, and View C Synthesis Report's "an iteration N cycles"), a sum's variable that the next iteration reads added last (s += a + b + c: one addition in the recurrence). When the clock's stages need a larger II (a recurrence through a long operation, as a float sum), the II is raised until they fit, and a warning says so (a dependence at this clock: …), as Vitis HLS raises it. A local array of registers that the body reads and writes only at the loop's counter (b[i] = b[i] + 100, the counter stepped by a constant and written nowhere else) is no dependence: each iteration writes its own element. A loop with no memory, one state an iteration when it fits the clock, is made so too when it does not; so is a loop that reads or writes streams (below, a state an access) when its states do not fit the clock and each stream is read or written once an iteration (a statement of its own, empty() / full() not read): its access in its stage, the value read there and carried on, every stage held while one waits (its FIFO empty or full). An exit known only after the next iteration has started squashes that iteration, if none has written anything by then but the loop's own variables. A warning says the II made only when the II asked cannot be met, and why: a memory's one port, or a dependence (a variable or a memory another iteration reads, the exit). A loop with a stream, a memory of structs, a return or a goto is made as below, its accesses a state each (a path longer than the clock said in View C Synthesis Report, #2080, when it cannot be made in stages). The top function's PIPELINE makes the whole function so, its machine one pipeline: a new call whenever ap_start finds the first stage free (ap_ready, ahead of ap_done), its loops unrolled, the report's pipeline its II and depth; one with a stream, or that cannot be made so, runs its calls one after the other, with a warning saying why. A function the top calls is inlined: its pragma has no effect (a warning). A top that fits the clock with no state is combinational, whatever its pragma. BIND_STORAGE is not made, so a memory has one port even where Vitis's ram_2p has two.

Loops pipelined automatically (#1919), as Vitis HLS's default (UG1399): with no PIPELINE pragma, an innermost loop of more than 64 iterations is pipelined (II=1 aimed at); one of 64 or fewer has its parent pipelined instead, the inner loop unrolled in it, when Silinx can make the parent so (else the inner loop is pipelined); an innermost loop with no parent is pipelined whatever its count. The threshold is Vitis HLS's syn.compile.pipeline_loops: cToHdl(…, { pipelineLoops: N }) (and cosimulate's), 0 for none; #pragma HLS PIPELINE off in a loop leaves it as it is. A pipelined loop that accesses a stream (or that the pipeline above cannot make) keeps a state per access (a memory's read is in its register a cycle later), its condition and step in its last state, consecutive states merged when they use no port of the same memory or stream; its first state's work is done in its last for the next iteration when they share no port: s += a[i] takes a cycle an iteration, a[i] = a[i] + 1 two (one port). A state that waits for a stream writes nothing while it waits. Where the II of 1 is not met, a warning gives the II made and why: a memory's accesses a state each, or a loop that cannot be made so (a branch or a break around an access, a do-while, an inner loop that cannot be unrolled), then made as before. The generation's report (cToHdl(…).report) gives a sequential module's states, register bits, memories and, for each loop, what its pragmas made: its II (states an iteration) and its cycles. Only one state runs in a cycle, so the multiplications of different states share their units (#2125), as Vitis HLS binds its operations: a state's multiplications take the first free units of their kind (one multiplier block, 18 x 18 at the operands' own widths, or the same widths), the units' operands multiplexed by the state; a multiplication by a power of 2, or with an operand under 6 bits, keeps its own; so does one after another multiplication in its state, and the uses of a kind whose unit's path (the latest operands of its uses, the multiplexers, the longest path after any of them) has no room in the period: the latency is the schedule's, never longer. The soft-float's operations share their multiplications so. With the device's multiplier blocks known (the IDE gives them: a Spartan-3E's MULT18X18s, a Spartan-6's DSP48A1s; cToHdl(…, { mults: N })), a cycle takes no more than that many, every multiplication made of 18 x 18 ones: the others wait for a later cycle (pow in double on a Basys2-100's 4). The report's units give each unit's widths, its blocks, its uses and its inputs, blocks their sum and unitsNs the longest path with their multiplexers; the View C Synthesis Report lists them, and, when that path is over the clock, the machine is scheduled again with each multiplication's operands held in registers written the cycle before (core/c-schedule.js, #2273); the report warns if it is still over. A sub-module (#1960) has its own units and its own limit: the module's blocks do not count its sub-modules'.

HDL to C (the other way)

Any module of the project (VHDL, Verilog, or a drawing's generated HDL: a schematic, an ASM chart, a state diagram, a truth table) has a C model (Processes ▸ View C Model, #1530): C99 computing what Silinx's simulator computes, two-state (an unknown bit is 0): a struct of its signals (each of at most 64 bits, an array as an array of words) and

void top_init(top_t *s);   /* the signals at their initial values */
void top_eval(top_t *s);   /* the combinational logic settled, the inputs set first */
void top_step(top_t *s);   /* a sequential design: a rising edge of its clock, then top_eval */

The processes are C functions run in delta cycles (a VHDL signal or a Verilog nonblocking assignment takes its value in the next one), the clocked ones once per top_step; the HDL functions are C functions. One clock and its rising edges only; a wait with a time, file I/O, real values, more than 64 bits are said, not modelled. A C test bench sets the inputs, calls top_step (or top_eval) and reads the outputs, as Silinx's tests do against the simulator.

Checking it

The phases

  1. This specification (#1523).
  2. The C parser and its checks (#1524), and Check Syntax of a .c file.
  3. Combinational C to HDL (#1525).
  4. Sequential C, ap_ctrl_hs (#1526); its machine shown as an ASM chart (#1575).
  5. Arrays and memories (#1527).
  6. C simulation and co-simulation (#1528).
  7. The pragmas (#1529).
  8. HDL and state machines to C (#1530).
  9. The interface: New Source, the C editor, the processes, an example (#1531).