7. Constraints Manual

LegUp accepts user-provided constraints that impact the automatically generated hardware. These constraints can be specified using the LegUp GUI and are stored in the Tcl configuration file config.tcl in your project directory. This reference section explains all of the constraints available for LegUp HLS.

The most commonly used constraints are available from the LegUp GUI:

A few debugging constraints are available from the LegUp GUI:

Note

Advanced users can read the defaults for each Tcl constraint in examples/legup.tcl. These defaults are read before being overridden by the project config.tcl file.


7.1. Commonly Used Constraints

7.1.1. CLOCK_PERIOD

This is a widely used constraint that allows the user to set the target clock period for a design. The clock period is specified in nanoseconds.

It has a significant impact on scheduling: the scheduler will schedule operators into clock cycles using delay estimates for each operator, such that the specified clock period is honored. In other words, operators will be chained together combinationally to the extent allowed by the value of the CLOCK_PERIOD parameter.

LegUp has a default CLOCK_PERIOD value for each device family that is supported. That default value was chosen to minimize the wall-clock time for a basket of benchmark programs (mainly the CHStone benchmark circuits).

If the parameter SDC_NO_CHAINING is 1, then the CLOCK_PERIOD parameter has no effect.

7.1.1.1. Category

HLS Constraints

7.1.1.2. Value Type

Integer represent a value in nanoseconds

7.1.1.3. Valid Values

Integer

7.1.1.4. Default Value

Depends on the target device

7.1.1.5. Location Where Default is Specified

boards/CycloneII/CycloneII.tcl

boards/StratixIV/StratixIV.tcl

and so on...

7.1.1.6. Dependencies

SDC_NO_CHAINING: If this parameter is set to 1, then CLOCK_PERIOD does nothing.

7.1.1.7. Applicable Flows

All devices and flows

7.1.1.8. Test Status

Actively in-use

7.1.1.9. Examples

set_parameter CLOCK_PERIOD 15

7.1.2. ENABLE_OPENMP

This parameter enables the synthesis of OpenMP pragmas and APIs. To compile OpenMP pragmas and API functions to hardware, this parameter must be set to 1.

7.1.2.1. Category

HLS Constraints

7.1.2.2. Value Type

Integer

7.1.2.3. Valid Values

0, 1

7.1.2.4. Default Value

0

7.1.2.5. Dependencies

None

7.1.2.6. Applicable Flows

All devices and flows

7.1.2.7. Test Status

Actively in-use

7.1.2.8. Examples

set_parameter ENABLE_OPENMP 1

7.1.3. loop_pipeline

This parameter enables pipelining for a given loop in the code. Loop pipelining allows a new iteration of the loop to begin before the current one has completed, achieving higher throughput. In a loop nest, only the innermost loop can be pipelined. Optional arguments:

Parameter Description
-ii Specify a pipeline initiation interval (default = 1)
-ignore-mem-deps Ignore loop carried dependencies for all memory accesses in the loop

7.1.3.1. Category

HLS Constraints

7.1.3.2. Value Type

Parameter Value Type
loop_pipeline String
-ii Integer
-ignore-mem-deps None

7.1.3.3. Valid Values

See Examples

7.1.3.4. Default Value

N/A

7.1.3.5. Location Where Default is Specified

examples/legup.tcl

7.1.3.6. Dependencies

None

7.1.3.7. Applicable Flows

All devices and flows

7.1.3.8. Test Status

Actively in-use

7.1.3.9. Examples

loop_pipeline "loop1"

loop_pipeline "loop2" -ii 1

loop_pipeline "loop3" -ignore-mem-deps


7.1.4. function_pipeline

This parameter enables pipelining for a given function in the code. Function pipelining allows a new invocation of a function to begin before the current one has completed, achieving higher throughput. Optional arguments:

Parameter Description
-ii Specify a pipeline initiation interval (default = 1)

7.1.4.1. Category

HLS Constraints

7.1.4.2. Value Type

Parameter Value Type
loop_pipeline String
-ii Integer

7.1.4.3. Valid Values

See Examples

7.1.4.4. Default Value

N/A

7.1.4.5. Dependencies

None

7.1.4.6. Applicable Flows

All devices and flows

7.1.4.7. Test Status

Actively in-use

7.1.4.8. Examples

function_pipeline "add"

function_pipeline "add" -ii 1


7.1.5. set_custom_top_level_module

This TCL command specifies the top-level C function that will be compiled to hardware by LegUp. All descendant functions called by the top-level C function will be compiled by LegUp. By default the top-level is the “main” function.

When a custom top-level module is specified, a custom testbench will be needed for running RTL simulation. Please see set_custom_test_bench_module and set_custom_test_bench_file.

7.1.5.1. Category

HLS Constraints

7.1.5.2. Value Type

string

7.1.5.3. Dependencies

NONE

7.1.5.4. Applicable Flows

All devices and flows

7.1.5.5. Test Status

Actively in-use

7.1.5.6. Examples

set_custom_top_level_module "accelerator_function"

7.1.6. set_custom_test_bench_module

This TCL command is to overwrite the name of testbench module to be elaborated in simulation.

7.1.6.1. Category

Simulation

7.1.6.2. Value Type

String

7.1.6.3. Dependencies

None

7.1.6.4. Applicable Flows

All devices and flows

7.1.6.5. Test Status

Actively in-use

7.1.6.6. Examples

set_custom_test_bench_module "custom_tb"

7.1.7. set_custom_test_bench_file

This TCL command is to specify the file that defines the custom testbench module, which is set via set_custom_test_bench_module. The testbench file will be compiled during RTL simulation.

7.1.7.1. Category

Simulation

7.1.7.2. Value Type

String

7.1.7.3. Dependencies

None

7.1.7.4. Applicable Flows

All devices and flows

7.1.7.5. Test Status

Actively in-use

7.1.7.6. Examples

set_custom_test_bench_file custom_tb.v

7.1.8. set_resource_constraint

This parameter constrains the number of times a given operation can occur in a cycle.

Note: A constraint on “signed_add” will apply to:
  • signed_add_8
  • signed_add_16
  • signed_add_32
  • signed_add_64
  • unsigned_add_8
  • unsigned_add_16
  • unsigned_add_32
  • unsigned_add_64

7.1.8.1. Category

HLS Constraints

7.1.8.2. Value Type

<operation> integer

7.1.8.3. Valid Values

See Default and Examples Note: operator name should match the device family operation database file: boards/StratixIV/StratixIV.tcl or boards/CycloneII/CycloneII.tcl

7.1.8.4. Default Values

memory_port 2
divide 1
modulus 1
multiply 2
altfp_add 1
altfp_subtract 1
altfp_multiply 1
altfp_divide 1
altfp 1

7.1.8.5. Location Where Default is Specified

examples/legup.tcl

7.1.8.6. Dependencies

None

7.1.8.7. Applicable Flows

All devices and flows

7.1.8.8. Test Status

Actively in-use

7.1.8.9. Examples

set_resource_constraint signed_divide_16 3

set_resource_constraint signed_divide 2

set_resource_constraint divide 1


7.1.9. set_operation_latency

This parameter sets the latency of a given operation when compiled in LegUp. Latency refers to the number of clock cycles required to complete the computation; an operation with latency one requires one cycle, while zero-latency operations are completely combinational, meaning multiple such operations can be chained together in a single clock cycle.

7.1.9.1. Category

HLS Constraints

7.1.9.2. Value Type

<operation> integer

7.1.9.3. Valid Values

See Default and Examples Note: operator name should match the device family operation database file: boards/StratixIV/StratixIV.tcl or boards/CycloneII/CycloneII.tcl

7.1.9.4. Default Values

altfp_add 14
altfp_subtract 14
altfp_multiply 11
altfp_divide_32 33
altfp_divide_64 61
altfp_truncate_64 3
altfp_extend_32 2
altfp_fptosi 6
altfp_sitofp 6
signed_comp_o 1
signed_comp_u 1
reg 2
memory_port 2
local_memory_port 1
multiply 1

7.1.9.5. Location Where Default is Specified

examples/legup.tcl

7.1.9.6. Dependencies

None

7.1.9.7. Applicable Flows

All devices and flows

7.1.9.8. Test Status

Actively in-use

7.1.9.9. Examples

set_operation_latency altfp_add_32 18

set_operation_latency multiply 0


7.1.10. inline_function

This parameter forces a given function to be inlined.

7.1.10.1. Category

HLS Constraints

7.1.10.2. Value Type

Parameter Value Type
inline_function String

7.1.10.3. Valid Values

See Examples

7.1.10.4. Default Value

N/A

7.1.10.5. Dependencies

None

7.1.10.6. Applicable Flows

All devices and flows

7.1.10.7. Test Status

Actively in-use

7.1.10.8. Examples

inline_function "add"


7.1.11. noinline_function

This parameter prevents a given function from being inlined.

7.1.11.1. Category

HLS Constraints

7.1.11.2. Value Type

Parameter Value Type
noinline_function String

7.1.11.3. Valid Values

See Examples

7.1.11.4. Default Value

N/A

7.1.11.5. Dependencies

None

7.1.11.6. Applicable Flows

All devices and flows

7.1.11.7. Test Status

Actively in-use

7.1.11.8. Examples

noinline_function "add"


7.1.12. flatten_function

This parameter unrolls all loops and inlines all subfunctions for a given function.

7.1.12.1. Category

HLS Constraints

7.1.12.2. Value Type

Parameter Value Type
flatten_function String

7.1.12.3. Valid Values

See Examples

7.1.12.4. Default Value

N/A

7.1.12.5. Dependencies

None

7.1.12.6. Applicable Flows

All devices and flows

7.1.12.7. Test Status

Actively in-use

7.1.12.8. Examples

flatten_function "add"


7.1.13. preserve_kernel

The LegUp HLS compiler optimizes away functions that are not used. This parameter prevents a given function from being optimized away.

7.1.13.1. Category

HLS Constraints

7.1.13.2. Value Type

Parameter Value Type
preserve_kernel String

7.1.13.3. Valid Values

See Examples

7.1.13.4. Default Value

N/A

7.1.13.5. Dependencies

None

7.1.13.6. Applicable Flows

All devices and flows

7.1.13.7. Test Status

Actively in-use

7.1.13.8. Examples

preserve_kernel "add"


7.1.14. MB_MINIMIZE_HW

This parameter toggles whether the reduced bitwidths analyzed by the bitwidth minimization pass will be used in generating the Verilog design.

7.1.14.1. Category

HLS Constraints

7.1.14.2. Value Type

Integer

7.1.14.3. Valid Values

0, 1

7.1.14.4. Default Value

0

7.1.14.5. Location Where Default is Specified

examples/legup.tcl

7.1.14.6. Dependencies

None

Related parameters: MB_RANGE_FILE, MB_MAX_BACK_PASSES, MB_PRINT_STATS

7.1.14.7. Applicable Flows

All devices and flows

7.1.14.8. Test Status

Prototype functionality

7.1.14.9. Examples

set_parameter MB_MINIMIZE_HW 1


7.1.15. REPLICATE_ROMS

This parameter replicates read-only memories (ROMs) to instantiate them in each of its accessing module. When the accessing modules execute concurrently, replicate the ROMs can reduce memory contention and increase performance, at the expense of more memory usage. It can also help to reduce LUTs, by reducing the arbitration/multiplexing logic that is required when the ROM is shared.

7.1.15.1. Category

HLS Constraints

7.1.15.2. Value Type

Integer

7.1.15.3. Valid Values

0, 1

7.1.15.4. Default Value

0

7.1.15.5. Location Where Default is Specified

examples/legup.tcl

7.1.15.6. Dependencies

None

7.1.15.7. Applicable Flows

All devices and flows

7.1.15.8. Examples

set_parameter REPLICATE_ROMS 1

7.1.16. set_synthesis_top_module

This TCL command specifies the name of the Verilog module that should be set as the top level when running FPGA vendors’ synthesis flows. By default the top level module for FPGA synthesis is “top”, which instantiates the RTL module of the top-level C function (“main” by default, or specified by set_custom_top_level_module).

This top level name is also used when creating a new Quartus project.

7.1.16.1. Category

Quartus

7.1.16.2. Value Type

string

7.1.16.3. Dependencies

NONE

7.1.16.4. Applicable Flows

All devices and flows

7.1.16.5. Test Status

Actively in-use

7.1.16.6. Examples

set_synthesis_top_module "accelerator_function"

7.2. Debugging Constraints

7.2.1. KEEP_SIGNALS_WITH_NO_FANOUT

If this parameter is enabled, all signals will be printed to the output Verilog file, even if they don’t drive any outputs.

7.2.1.1. Category

HLS Constraint

7.2.1.2. Value Type

Integer

7.2.1.3. Valid Values

0, 1

7.2.1.4. Default Value

unset (0)

7.2.1.5. Location Where Default is Specified

examples/legup.tcl

7.2.1.6. Dependencies

None

7.2.1.7. Applicable Flows

All devices and flows

7.2.1.8. Test Status

Actively in-use

7.2.1.9. Examples

set_parameter KEEP_SIGNALS_WITH_NO_FANOUT 1

7.2.2. VSIM_ASSERT

When set to 1, this constraint causes assertions to be inserted in the Verilog produced by LegUp. This is useful for debugging the circuit to see where invalid values (X’s) are being assigned.

7.2.2.1. Category

Simulation

7.2.2.2. Value Type

Integer

7.2.2.3. Valid Values

0, 1

7.2.2.4. Default Value

0

7.2.2.5. Location Where Default is Specified

examples/legup.tcl

7.2.2.6. Dependencies

None

7.2.2.7. Applicable Flows

All devices and flows

7.2.2.8. Test Status

Actively in-use

7.2.2.9. Examples

set_parameter VSIM_ASSERT 1

7.3. Advanced Constraints

These are not available from the GUI.

7.3.1. CASE_FSM

This parameter controls whether the finite state machine (FSM) in the Verilog output by LegUp is implemented with a case statement or if-else statements. Although both options are functionally equivalent; some back-end RTL synthesis tools may be sensitive to the RTL coding style.

7.3.1.1. Category

HLS Constraints

7.3.1.2. Value Type

Integer

7.3.1.3. Valid Values

0, 1

7.3.1.4. Default Value

1

7.3.1.5. Location Where Default is Specified

examples/legup.tcl

7.3.1.6. Dependencies

None

7.3.1.7. Applicable Flows

All devices and flows

7.3.1.8. Test Status

Actively in-use

7.3.1.9. Examples

set_parameter CASE_FSM 1

7.3.2. GROUP_RAMS

This parameter group all arrays in the global memory controller into four RAMs (one for each bitwidth: 8, 16, 32, 64). This saves M9K blocks by avoiding having a small array taking up an entire M9K block.

7.3.2.1. Category

HLS Constraints

7.3.2.2. Value Type

Integer

7.3.2.3. Valid Values

0, 1

7.3.2.4. Default Value

0

7.3.2.5. Location Where Default is Specified

examples/legup.tcl

7.3.2.6. Dependencies

None

7.3.2.7. Applicable Flows

All devices and flows

7.3.2.8. Test Status

Actively in-use

7.3.2.9. Examples

set_parameter GROUP_RAMS 1

7.3.3. GROUP_RAMS_SIMPLE_OFFSET

When GROUP_RAMS is on, this option simplifies the address offset calculation. Calculate the offset for each array into the shared RAM to minimize addition. The offset must be a multiple of the size of the array in bytes (to allow an OR instead of an ADD):

before: addr = baseaddr + offset after: addr = baseaddr OR offset

the idea is that none of the lower bits of baseaddr should overlap with any bits of offset. This improves area and fmax (less adders) but at the cost of wasted empty memory inside the shared RAM

7.3.3.1. Category

HLS Constraints

7.3.3.2. Value Type

Integer

7.3.3.3. Valid Values

0, 1

7.3.3.4. Default Value

0

7.3.3.5. Location Where Default is Specified

examples/legup.tcl

7.3.3.6. Dependencies

None

7.3.3.7. Applicable Flows

All devices and flows

7.3.3.8. Test Status

Actively in-use

7.3.3.9. Examples

set_parameter GROUP_RAMS_SIMPLE_OFFSET 1

7.3.4. LOCAL_RAMS

This parameter turns on alias analysis to determine when an array is only used in one function. These arrays can be placed in a block ram inside that hardware module instead of in global memory. This increases performance because local rams can be accessed in parallel while global memory is limited to two ports.

7.3.4.1. Category

HLS Constraints

7.3.4.2. Value Type

Integer

7.3.4.3. Valid Values

0, 1

7.3.4.4. Default Value

0

7.3.4.5. Location Where Default is Specified

examples/legup.tcl

7.3.4.6. Dependencies

None

7.3.4.7. Applicable Flows

All devices and flows

7.3.4.8. Test Status

Actively in-use

7.3.4.9. Examples

set_parameter LOCAL_RAMS 1

7.3.5. NO_INLINE

This is a Makefile parameter that can disable the LLVM compiler from inlining functions. Note that all compiler optimizations will be turned off when NO_INLINE is enabled. This parameter can be set in examples/Makefile.config or in a local Makefile.

7.3.5.1. Category

LLVM

7.3.5.2. Value Type

Integer

7.3.5.3. Valid Values

0, 1

7.3.5.4. Default Value

unset (0)

7.3.5.5. Applicable Flows

All devices and flows

7.3.5.6. Test Status

Actively in-use

7.3.5.7. Examples

NO_INLINE=1

7.3.6. NO_OPT

This is a Makefile parameter that disables LLVM optimizations, which is equivalent to the -O0 flag. This parameter can be set in examples/Makefile.config or in a local Makefile.

7.3.6.1. Category

LLVM

7.3.6.2. Value Type

Integer

7.3.6.3. Valid Values

0, 1

7.3.6.4. Default Value

unset (0)

7.3.6.5. Applicable Flows

All devices and flows

7.3.6.6. Test Status

Actively in-use

7.3.6.7. Examples

NO_OPT=1

7.3.7. set_accelerator_function

This sets the C function to be accelerated to HW in the hybrid flow. It can be used on one or more functions.

7.3.7.1. Category

HLS Constraints

7.3.7.2. Value Type

String

7.3.7.3. Valid Values

Name of the function

7.3.7.4. Default Value

NULL

7.3.7.5. Location Where Default is Specified

N/A

7.3.7.6. Dependencies

None

7.3.7.7. Applicable Flows

Hybrid flow

7.3.7.8. Test Status

Actively in-use

7.3.7.9. Examples

set_accelerator_function "add"

set_accelerator_function "div"


7.3.8. UNROLL

This is a Makefile parameter that allows user to specify additional flags related to the unroll transformation in LLVM compiler. This parameter can be set in examples/Makefile.config or in a local Makefile. Please see example settings in examples/Makefile.config.

7.3.8.1. Category

LLVM

7.3.8.2. Value Type

string

7.3.8.3. Applicable Flows

All devices and flows

7.3.8.4. Test Status

Actively in-use

7.3.8.5. Examples

UNROLL = -unroll-allow-partial -unroll-threshold=1000

7.3.9. set_combine_basicblock

This parameter allows for basic block merging within the LLVM IR which potentially reduces the number of cycles of execution. There are two modes of operation: merge patterns throughout program, merge patterns only within loops. Currently, only 2 patterns are supported:

Pattern A:

_images/PatternA.PNG

A1, A2, A3 are basicblocks.

Pattern B:

_images/PatternB.PNG

B1, B2, B3, B4 are basicblocks.

7.3.9.1. Category

HLS Constraint

7.3.9.2. Value Type

Integer

7.3.9.3. Valid Values

0, 1, 2

7.3.9.4. Default Value

unset (off by default)

7.3.9.5. Location Where Default is Specified

examples/legup.tcl

7.3.9.6. Dependencies

None

Note: May require LOCAL_RAMS and GLOBAL_RAMS to be turned off.

7.3.9.7. Applicable Flows

All devices for pure hardware flow

7.3.9.8. Test Status

Prototype functionality

7.3.9.9. Examples

set_combine_basicblock 1


7.3.10. set_project

This parameter sets the default target project, or device, used. Changing the project also updates the associated family and board parameters.

7.3.10.1. Category

Board and Device Specification

7.3.10.2. Value Type

String

7.3.10.3. Valid Values

See Examples

7.3.10.4. Default Value

CycloneV DE1-SoC Tiger_SDRAM

7.3.10.5. Location Where Default is Specified

examples/legup.tcl

7.3.10.6. Dependencies

None

7.3.10.7. Applicable Flows

All devices and flows

7.3.10.8. Test Status

Actively in-use

7.3.10.9. Examples

set_project CycloneV DE1-SoC Tiger_SDRAM

set_project CycloneV DE1-SoC ARM_Simple_Hybrid_System

set_project CycloneV SoCKit ARM_Simple_Hybrid_System

set_project CycloneIV DE2-115 Tiger_SDRAM

set_project CycloneII DE2 Tiger_SDRAM

set_project CycloneII CycloneIIAuto Tiger_SDRAM

set_project StratixV DE5-Net Tiger_DDR3

set_project StratixIV DE4-230 Tiger_DDR2

set_project StratixIV DE4-530 Tiger_DDR2


7.3.11. USE_MEM_FILE

This parameter enables using .mem files for memory initialization.

7.3.11.1. Category

HLS Constraints

7.3.11.2. Value Type

Integer

7.3.11.3. Valid Values

0,1

7.3.11.4. Default Value

0

7.3.11.5. Location Where Default is Specified

examples/legup.tcl

7.3.11.6. Dependencies

None

7.3.11.7. Applicable Flows

All devices and flows

7.3.11.8. Test Status

Actively in-use

7.3.11.9. Examples

USE_MEM_FILE 1