function in the C test bench. -clean Enables a clean build. Without this option, csim_design compiles incrementally. -ldflags < string> Specifies the options passed to the linker for C simulation. This option is typically used to pass on library information for the C test bench and design. -compiler ( *gcc* | clang ) This option selects the compiler used for C simulation. The default compiler is gcc (g++ for C++). The clang option enables more restrictive compiler checks. This option is only available on Linux systems. -clang_sanitizer This option enables clang sanitizers for out-of-range addresses and undefined behaviors. This option can only be enabled when the compiler options is used to specify clang as the compiler and is only available on Linux systems. This option increases the amount of memory required to compile the design. -mflags < string> Specifies the options passed to the compiler for C simulation. This option is typically used to speed up compilation. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 430 Chapter 4: High-Level Synthesis Reference Guide -setup Creates the C simulation binary in the csim directory of the active solution. Simulation is not executed. Pragma There is no pragma equivalent. Examples Compiles and runs C simulation. csim_design Compiles source design and test bench to generate the simulation binary. Does not execute the binary. To run the simulation, execute run.sh in the csim/build directory of the active solution. csim_design -O -setup csynth_design Description Synthesizes the Vivado HLS database for the active solution. The command can be executed only in the context of an active solution. The elaborated design in the database is scheduled and mapped onto RTL, based on any constraints that are set. Syntax csynth_design Options This command has no options. Pragma There is no pragma equivalent. Examples Runs Vivado HLS on the top-level design. csynth_design High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 431 Chapter 4: High-Level Synthesis Reference Guide delete_project Description Deletes the directory associated with the project. The delete_project command checks the corresponding project directory to ensure that it is a valid Vivado HLS project before deleting it. If no directory exists in the current work directory, the command has no effect. Syntax delete_project where • is the project name. Options This command has no options. Pragma There is no pragma equivalent. Examples Deletes Project_1 by removing the directory Project_1 and all its contents. delete_project Project_1 delete_solution Syntax delete_solution where • < solution> is the solution to be deleted. Description Removes a solution from an active project, and deletes the subdirectory from the project directory. If the solution does not exist in the project directory, the command has no effect. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 432 Chapter 4: High-Level Synthesis Reference Guide Pragma There is no pragma equivalent. Examples Deletes solution Solution_1 from the active project by removing the subdirectory Solution_1 from the active project directory. delete_solution Solution_1 export_design Description Exports and packages the synthesized design in RTL as an IP for downstream tools. Supported IP formats are: • Vivado IP catalog • DCP format • System Generator The packaged design is under the impl directory of the active solution in one of the following subdirectories: • ip • sysgen Syntax export_design [OPTIONS] Options -description Provides a description for the generated IP Catalog IP. -flow (syn|impl) Obtains more accurate timing and utilization data for the specified HDL using RTL synthesis. Option syn perform RTL synthesis and option impl performs both RTL synthesis and implementation (detailed place & route of the synthesized gates). -format (sysgen|ip_catalog|syn_dcp) Specifies the format to package the IP. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 433 Chapter 4: High-Level Synthesis Reference Guide The supported formats are: • sysgen In a format accepted by System Generator for DSP for Vivado Design Suite (Xilinx 7 series devices only) • ip_catalog In format suitable for adding to the Vivado IP Catalog (default for Xilinx 7 series devices) • syn_dcp Synthesized checkpoint file for the Vivado Design Suite. If this option is used, RTL synthesis is automatically executed. -library Specifies the library name for the generated IP catalog IP. -rtl (verilog|vhdl) Selects which HDL is used when the flow option is executed. If not specified, verilog is the default language. -vendor Specifies the vendor string for the generated IP catalog IP. -version Specifies the version string for the generated IP catalog. Pragma There is no pragma equivalent. Examples Exports RTL for System Generator. export_design -format sysgen Exports RTL in IP catalog. Evaluates the VHDL to obtain better timing and utilization data (using the Vivado tools). export_design -flow syn -rtl vhdl -format ip_catalog High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 434 Chapter 4: High-Level Synthesis Reference Guide help Description • When used without any < cmd> as an argument, lists all Vivado HLS Tcl commands. • When used with a Vivado HLS Tcl command as an argument, provides information on the specified command. For legal Vivado HLS commands, auto-completion using the tab key is active when typing the command argument. Syntax help [OPTIONS] where • < cmd> is the command to display help on. Options This command has no options. Pragma There is no pragma equivalent. Examples Displays help for all commands and directives. help Displays help for the add_files command. help add_files list_core Description Lists all the cores in the currently loaded library. Cores are the components used to implement operations in the output RTL (such as adders, multipliers, and memories). After elaboration, the operations in the RTL are represented as operators in the internal database. During scheduling, operators are mapped to cores from the library to implement the RTL design. Multiple operators can be mapped on the same instance of a core, sharing the same RTL resource. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 435 Chapter 4: High-Level Synthesis Reference Guide The list_core command allows the available operators and cores to be listed by using the relevant option: • Operation Shows which cores in the library can implement each operation. • Type Lists the available cores by type, for example those that implement functional operations, or those that implement memory or storage operations. If no options are specified, the command lists all cores in the library. TIP: Use the information provided by the list_core command with the set_directive_resource command to implement specific operations onto specific cores. Syntax list_core [OPTIONS] Options -operation (opers) Lists the cores in the library that can implement the specified operation. The operations are: • add - Addition • sub - Subtraction • mul - Multiplication • udiv - Unsigned Division • urem - Unsigned Remainder (Modulus operator) • srem - Signed Remainder (Modulus operator) • icmp - Integer Compare • shl - Shift-Left • lshr - Logical Shift-Right • ashr - Arithmetic Shift-Right • mux - Multiplexor • load - Memory Read • store - Memory Write • fiforead - FIFO Read High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 436 Chapter 4: High-Level Synthesis Reference Guide • fifowrite - FIFO Write • fifonbread - Non-Blocking FIFO Read • fifonbwrite - Non-Blocking FIFO Write -type (functional_unit|storage|connector|adapter|ip_block) Lists cores only of the specified type. • Function Units Cores that implement standard RTL operations (such as add, multiply, or compare) • Storage Cores that implement storage elements such as registers or memories. • Connectors Cores used to implement connectivity within the design, including direct connections and streaming storage elements. • Adapter Cores that implement interfaces used to connect the top-level design when IP is generated. These interfaces are implemented in the RTL wrapper used in the IP generation flow (Xilinx EDK). • IP Blocks Any IP cores that you added. Pragma There is no pragma equivalent. Examples Lists all cores in the currently loaded libraries that can implement an add operation. list_core -operation add Lists all available memory (storage) cores in the library. list_core -type storage TIP: Use the set_directive_resource command to implement an array using one of the available memories. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 437 Chapter 4: High-Level Synthesis Reference Guide list_part Description • If a family is specified, returns the supported device families or supported parts for that family. • If no family is specified, returns all supported families. TIP: To return parts of a family, specify one of the supported families that was listed when no family was specified when the command was run. Syntax list_part [OPTIONS] Pragma There is no pragma equivalent. Examples Returns all supported families. list_part Returns all supported Virtex®-6 parts. list_part virtex6 open_project Description Opens an existing project or creates a new one. There can only be one project active at any given time in a Vivado HLS session. A project can contain multiple solutions. To close a project: • Use the close_project command, or • Start another project with the open_project command. Use the delete_project command to completely delete the project directory (removing it from the disk) and any solutions associated it. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 438 Chapter 4: High-Level Synthesis Reference Guide Syntax open_project [OPTIONS] where • < project> is the project name. Options -reset • Resets the project by removing any project data that already exists. • Removes any previous project information on design source files, header file search paths, and the top level function. The associated solution directories and files are kept, but might now have invalid results. Note: The delete_project command accomplishes the same as the -reset option and removes all solution data). RECOMMENDED: Use this option when executing Vivado HLS with Tcl scripts. Otherwise, each new add_files command adds additional files to the existing data. Pragma There is no pragma equivalent. Examples Opens a new or existing project named Project_1. open_project Project_1 Opens a project and removes any existing data. open_project -reset Project_2 RECOMMENDED: Use this method with Tcl scripts to prevent adding source or library files to the existing project data. open_solution Description Opens an existing solution or creates a new one in the currently active project. CAUTION! Attempting to open or create a solution when there is no active project results in an error. There can only be one solution active at any given time in a Vivado HLS session. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 439 Chapter 4: High-Level Synthesis Reference Guide Each solution is managed in a subdirectory of the current project directory. A new solution is created if the solution does not yet exist in the current work directory. To close a solution: • Run the close_solution command, or • Open another solution with the open_solution command. Use the delete_solution command to remove them from the project and delete the corresponding subdirectory. Syntax open_solution [OPTIONS] where • < solution> is the solution name. Options -reset • Resets the solution data if the solution already exists. Any previous solution information on libraries, constraints, and directives is removed. • Removes synthesis, verification, and implementation. Pragma There is no pragma equivalent. Examples Opens a new or existing solution in the active project named Solution_1. open_solution Solution_1 Opens a solution in the active project. Removes any existing data. open_solution -reset Solution_2 RECOMMENDED: Use this method with Tcl scripts to prevent adding to the existing solution data. set_clock_uncertainty Description Sets a margin on the clock period defined by create_clock. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 440 Chapter 4: High-Level Synthesis Reference Guide The margin is subtracted from the clock period to create an effective clock period. If the clock uncertainty is not defined in ns or as a percentage, it defaults to 12.5% of the clock period. Vivado HLS optimizes the design based on the effective clock period, providing a margin for downstream tools to account for logic synthesis and routing. The command can be executed only in the context of an active solution. Vivado HLS still uses the specified clock period in all output files for verification and implementation. For SystemC designs in which multiple named clocks are specified by the create_clock command, you can specify a different clock uncertainty on each named clock by specifying the named clock. Syntax set_clock_uncertainty where • < uncertainty> is a value, specified in ns, representing how much of the clock period is used as a margin. • < clock_list> a list of clocks to which the uncertainty is applied. If none is provided, it is applied to all clocks. Pragma There is no pragma equivalent. Examples Specifies an uncertainty or margin of 0.5 ns on the clock. This effectively reduces the clock period that Vivado HLS can use by 0.5 ns. set_clock_uncertainty 0.5 In this SystemC example, creates two clock domains. A different clock uncertainty is specified on each domain. create_clock -period 15 fast_clk create_clock -period 60 slow_clk set_clock_uncertainty 0.5 fast_clock set_clock_uncertainty 1.5 slow_clock TIP: SystemC designs support multiple clocks. Use the set_directive_clock command to apply the clock to the appropriate function. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 441 Chapter 4: High-Level Synthesis Reference Guide set_directive_allocation Description Specifies instance restrictions for resource allocation. This defines, and can limit, the number of RTL instances used to implement specific functions or operations. For example, if the C source has four instances of a function foo_sub, the set_directive_allocation command can ensure that there is only one instance of foo_sub in the final RTL. All four instances are implemented using the same RTL block. Syntax set_directive_allocation [OPTIONS] where • < location> is the location string in the format function[/label] • < instances> is a function or operator. The function can be any function in the original C code that has not been: • Inlined by the set_directive_inline command, or • Inlined automatically by Vivado HLS. The list of operators is as follows (provided there is an instance of such an operation in the C source code): • add - Addition • sub - Subtraction • mul - Multiplication • icmp - Integer Compare • sdiv - Signed Division • udiv - Unsigned Division • srem - Signed Remainder • urem - Unsigned Remainder • lshr - Logical Shift-Right • ashr - Arithmetic Shift-Right • shl - Shift-Left High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 442 Chapter 4: High-Level Synthesis Reference Guide Options -limit < integer> Sets a maximum limit on the number of instances (of the type defined by the -type option) to be used in the RTL design. -type (function|operation) The instance type can be function (default) or operation. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS allocation \ instances= \ limit= \ Examples Given a design foo_top with multiple instances of function foo, limits the number of instances of foo in the RTL to 2. set_directive_allocation -limit 2 -type function foo_top foo #pragma HLS allocation instances=foo limit=2 function Limits the number of multipliers used in the implementation of My_func to 1.This limit does not apply to any multipliers that might reside in sub-functions of My_func. To limit the multipliers used in the implementation of any sub-functions, specify an allocation directive on the sub-functions or inline the sub-function into function My_func. set_directive_allocation -limit 1 -type operation My_func mul #pragma HLS allocation instances=mul limit=1 operation set_directive_array_map Description Maps a smaller array into a larger array. Designers typically use the set_directive_array_map command (with the same -instance target) to map multiple smaller arrays into a single larger array. This larger array can then be targeted to a single larger memory (RAM or FIFO) resource. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 443 Chapter 4: High-Level Synthesis Reference Guide Use the -mode option to determine whether the new target is a concatenation of: • Elements (horizontal mapping), or • Bit-widths (vertical mapping) The arrays are concatenated in the order the set_directive_array_map commands are issued starting at: • Target element zero in horizontal mapping • Bit zero in vertical mapping. Syntax set_directive_array_map [OPTIONS] where • < location> is the location (in the format function[/label]) which contains the array variable. • < variable> is the array variable to be mapped into the new target array instance. Options -instance Specifies the new array instance name where the current array variable is to be mapped. -mode (horizontal|vertical) • Horizontal mapping (the default) concatenates the arrays to form a target with more elements. • Vertical mapping concatenates the array to form a target with longer words. -offset < integer> IMPORTANT: For horizontal mapping only. Specifies an integer value indicating the absolute offset in the target instance for current mapping operation. For example: • Element 0 of the array variable maps to element < int> of the new target. • Other elements map to , < int+2>... of the new target. If the value is not specified, Vivado HLS calculates the required offset automatically to avoid any overlap. Example: concatenating the arrays starting at the next unused element in the target. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 444 Chapter 4: High-Level Synthesis Reference Guide Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS array_map \ variable= \ instance= \ \ offset= Examples These commands map arrays A[10] and B[15] in function foo into a single new array AB[25]. • Element AB[0] will be the same as A[0]. • Element AB[10] will be the same as B[0] (because no -offset option is used). • The bit-width of array AB[25] will be the maximum bit-width of A[10] or B[15]. set_directive_array_map -instance AB -mode horizontal foo A set_directive_array_map -instance AB -mode horizontal foo B #pragma HLS array_map variable=A instance=AB horizontal #pragma HLS array_map variable=B instance=AB horizontal Concatenates arrays C and D into a new array CD with same number of bits as C and D combined. The number of elements in CD is the maximum of C or D set_directive_array_map -instance CD -mode vertical foo C set_directive_array_map -instance CD -mode vertical foo D #pragma HLS array_map variable=C instance=CD vertical #pragma HLS array_map variable=D instance=CD vertical set_directive_array_partition Description Partitions an array into smaller arrays or individual elements. This partitioning: • Results in RTL with multiple small memories or multiple registers instead of one large memory. • Effectively increases the amount of read and write ports for the storage. • Potentially improves the throughput of the design. • Requires more memory instances or registers. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 445 Chapter 4: High-Level Synthesis Reference Guide Syntax set_directive_array_partition [OPTIONS] where • < location> is the location (in the format function[/label]) which contains the array variable. • < array> is the array variable to be partitioned. Options -dim < integer> Note: Relevant for multi-dimensional arrays only. Specifies which dimension of the array is to be partitioned. • If a value of 0 is used, all dimensions are partitioned with the specified options. • Any other value partitions only that dimension. For example, if a value 1 is used, only the first dimension is partitioned. -factor < integer> Note: Relevant for type block or cyclic partitioning only. Specifies the number of smaller arrays that are to be created. -type (block|cyclic|complete) • Block partitioning creates smaller arrays from consecutive blocks of the original array. This effectively splits the array into N equal blocks where N is the integer defined by the -factor option. • Cyclic partitioning creates smaller arrays by interleaving elements from the original array. For example, if -factor 3 is used: • ° Element 0 is assigned to the first new array ° Element 1 is assigned to the second new array. ° Element 2 is assigned to the third new array. ° Element 3 is assigned to the first new array again. Complete partitioning decomposes the array into individual elements. For a one-dimensional array, this corresponds to resolving a memory into individual registers. For multi-dimensional arrays, specify the partitioning of each dimension, or use -dim 0 to partition all dimensions. The default is complete. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 446 Chapter 4: High-Level Synthesis Reference Guide Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS array_partition \ variable= \ \ factor= \ dim= Examples Partitions array AB[13] in function foo into four arrays. Because four is not an integer multiple of 13: • Three arrays have three elements. • One array has four elements (AB[9:12]). set_directive_array_partition -type block -factor 4 foo AB #pragma HLS array_partition variable=AB block factor=4 Partitions array AB[6][4] in function foo into two arrays, each of dimension [6][2]. set_directive_array_partition -type block -factor 2 -dim 2 foo AB #pragma HLS array_partition variable=AB block factor=2 dim=2 Partitions all dimensions of AB[4][10][6] in function foo into individual elements. set_directive_array_partition -type complete -dim 0 foo AB #pragma HLS array_partition variable=AB complete dim=0 set_directive_array_reshape Description Combines array partitioning with vertical array mapping to create a single new array with fewer elements but wider words. The set_directive_array_reshape command: 1. Splits the array into multiple arrays (in an identical manner as set_directive_array_partition) 2. Automatically recombine the arrays vertically (as per set_directive_array_map -type vertical) to create a new array with wider words. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 447 Chapter 4: High-Level Synthesis Reference Guide Syntax set_directive_array_reshape [OPTIONS] where • < location> is the location (in the format function[/label]) that contains the array variable. • < array> is the array variable to be reshaped. Options -dim < integer> Note: Relevant for multi-dimensional arrays only. Specifies which dimension of the array is to be reshaped. • If value = 0, all dimensions are partitioned with the specified options. • Any other value partitions only that dimension. For example, if value =1, only the first dimension is partitioned. -factor < integer> Note: Relevant for type block or cyclic reshaping only. Specifies the number of temporary smaller arrays to be created. -type (block|cyclic|complete) • Block reshaping creates smaller arrays from consecutive blocks of the original array. This effectively splits the array into N equal blocks where N is the integer defined by the -factor option and then combines the N blocks into a single array with word-width*N. The default is complete. • Cyclic reshaping creates smaller arrays by interleaving elements from the original array. For example, if -factor 3 is used, element 0 is assigned to the first new array, element 1 to the second new array, element 2 is assigned to the third new array, and then element 3 is assigned to the first new array again. The final array is a vertical concatenation (word concatenation, to create longer words) of the new arrays into a single array. • Complete reshaping decomposes the array into temporary individual elements and then recombines them into an array with a wider word. For a one-dimension array this is equivalent to creating a very-wide register (if the original array was N elements of M bits, the result is a register with N*M bits). -object Note: Relevant for container arrays only. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 448 Chapter 4: High-Level Synthesis Reference Guide Applies reshape on the objects within the container. If the option is specified, all dimensions of the objects will be reshaped, but all dimensions of the container will be kept. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS array_reshape \ variable= \ \ factor= \ dim= Examples Reshapes 8-bit array AB[17] in function foo, into a new 32-bit array with five elements. Because four is not an integer multiple of 13: • AB[17] is in the lower eight bits of the fifth element. • The remainder of the fifth element is unused. set_directive_array_reshape -type block -factor 4 foo AB #pragma HLS array_reshape variable=AB block factor=4 Partitions array AB[6][4] in function foo, into a new array of dimension [6][2], in which dimension 2 is twice the width. set_directive_array_reshape -type block -factor 2 -dim 2 foo AB #pragma HLS array_reshape variable=AB block factor=2 dim=2 Reshapes 8-bit array AB[4][2][2] in function foo into a new single element array (a register), 4*2*2*8(=128)-bits wide. set_directive_array_reshape -type complete -dim 0 foo AB #pragma HLS array_reshape variable=AB complete dim=0 set_directive_clock Description Applies the named clock to the specified function. C and C++ designs support only a single clock. The clock period specified by create_clock is applied to all functions in the design. SystemC designs support multiple clocks. Multiple named clocks can be specified using the create_clock command and applied to individual SC_MODULEs using the set_directive_clock command. Each SC_MODULE is synthesized using a single clock. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 449 Chapter 4: High-Level Synthesis Reference Guide Syntax set_directive_clock where • < location> is the function where the named clock is to be applied. • < domain> is the clock name as specified by the -name option of the create_clock command. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS clock domain= Examples Assume a SystemC design in which: • Top-level foo_top has clocks ports fast_clock and slow_clock. • It uses only fast_clock within its function. • Sub-block foo uses only slow_clock. In that case, the commands shown below: • Create both clocks. • Apply fast_clock to foo_top. • Apply slow_clock to sub-block foo. create_clock -period 15 fast_clk create_clock -period 60 slow_clk set_directive_clock foo_top fast_clock set_directive_clock foo slow_clock #pragma HLS clock domain=fast_clock #pragma HLS clock domain=slow_clock Note: There is no pragma equivalent of create_clock. set_directive_dataflow Description Specifies that dataflow optimization be performed on the functions or loops, improving the concurrency of the RTL implementation. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 450 Chapter 4: High-Level Synthesis Reference Guide All operations are performed sequentially in a C description. In the absence of any directives that limit resources (such as set_directive_allocation), Vivado HLS seeks to minimize latency and improve concurrency. Data dependencies can limit this. For example, functions or loops that access arrays must finish all read/write accesses to the arrays before they complete. This prevents the next function or loop that consumes the data from starting operation. It is possible for the operations in a function or loop to start operation before the previous function or loop completes all its operations. When dataflow optimization is specified, Vivado HLS: • Analyzes the dataflow between sequential functions or loops. • Seeks to create channels (based on pingpong RAMs or FIFOs) that allow consumer functions or loops to start operation before the producer functions or loops have completed. This allows functions or loops to operate in parallel, which in turn: • Decreases the latency • Improves the throughput of the RTL design If no initiation interval (number of cycles between the start of one function or loop and the next) is specified, Vivado HLS attempts to minimize the initiation interval and start operation as soon as data is available. Syntax set_directive_dataflow where • < location> is the location (in the format function[/label]) at which dataflow optimization is to be performed. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS dataflow Examples Specifies dataflow optimization within function foo. set_directive_dataflow foo #pragma HLS dataflow High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 451 Chapter 4: High-Level Synthesis Reference Guide set_directive_data_pack Description Packs the data fields of a struct into a single scalar with a wider word width. Any arrays declared inside the struct are completely partitioned and reshaped into a wide scalar and packed with other scalar fields. The bit alignment of the resulting new wide-word can be inferred from the declaration order of the struct fields. The first field takes the least significant sector of the word and so forth until all fields are mapped. Syntax set_directive_data_pack [OPTIONS] where • < location> is the location (in the format function[/label]) which contains the variable which will be packed. • < variable> is the variable to be packed. Options -instance Specifies the name of resultant variable after packing. If none is provided, the input variable is used. -byte_pad (struct_level|field_level) Specify whether to pack data on 8-bit boundary: • struct_level: Pack the struct first, then pack it on 8-bits boundary. • field_level: Pack each individual field on 8-bits boundary first, then pack the struct. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS data_pack variable= instance= High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 452 Chapter 4: High-Level Synthesis Reference Guide Examples Packs struct array AB[17] with three 8-bit field fields (typedef struct {unsigned char R, G, B;} pixel) in function foo, into a new 17 element array of 24 bits. set_directive_data_pack foo AB #pragma HLS data_pack variable=AB Packs struct pointer AB with three 8-bit fields (typedef struct {unsigned char R, G, B;} pixel) in function foo, into a new 24-bit pointer. set_directive_data_pack foo AB #pragma HLS data_pack variable=AB set_directive_dependence Description Vivado HLS detects dependencies: • Within loops (loop-independent dependency), or • Between different iterations of a loop (loop-carry dependency). These dependencies impact when operations can be scheduled, especially during function and loop pipelining. • Loop-independent dependence The same element is accessed in the same loop iteration. for (i=0;i where • < location> is the location (in the format function[/label]) at which the dependence is to be specified. Options -class (array|pointer) Specifies a class of variables in which the dependence needs clarification. This is mutually exclusive with the option -variable. -dependent (true|false) Specifies whether a dependence needs to be enforced (true) or removed (false). The default is true. -direction (RAW|WAR|WAW) Note: Relevant for loop-carry dependencies only. Specifies the direction for a dependence: • RAW (Read-After-Write - true dependence) The write instruction uses a value used by the read instruction. • WAR (Write-After-Read - anti dependence) The read instruction gets a value that is overwritten by the write instruction. • WAW (Write-After-Write - output dependence) Two write instructions write to the same location, in a certain order. -distance Note: Relevant only for loop-carry dependencies where -dependent is set to true. Specifies the inter-iteration distance for array access. -type (intra|inter) Specifies whether the dependence is: • Within the same loop iteration (intra), or • Between different loop iterations (inter) (default). High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 454 Chapter 4: High-Level Synthesis Reference Guide -variable Specifies the specific variable to consider for the dependence directive. Mutually exclusive with the option -class. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS dependence \ variable= \ \ \ \ distance= \ Examples Removes the dependence between Var1 in the same iterations of loop_1 in function foo. set_directive_dependence -variable Var1 -type intra \ -dependent false foo/loop_1 #pragma HLS dependence variable=Var1 intra false The dependence on all arrays in loop_2 of function foo informs Vivado HLS that all reads must happen after writes in the same loop iteration. set_directive_dependence -class array -type intra \ -dependent true -direction RAW foo/loop_2 #pragma HLS dependence array inter RAW true set_directive_expression_balance Description Sometimes a C-based specification is written with a sequence of operations. This can result in a lengthy chain of operations in RTL. With a small clock period, this can increase the design latency. By default, Vivado HLS rearranges the operations through associative and commutative properties. This rearrangement creates a balanced tree that can shorten the chain, potentially reducing latency at the cost of extra hardware. The set_directive_expression_balance command allows this expression balancing to be turned off or on within with a specified scope. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 455 Chapter 4: High-Level Synthesis Reference Guide Syntax set_directive_expression_balance [OPTIONS] where • < location> is the location (in the format function[/label]) where the balancing should be enabled or disabled. Options -off Turns off expression balancing at this location. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS expression_balance Examples Disables expression balancing within function My_Func. set_directive_expression_balance -off My_Func #pragma HLS expression_balance off Explicitly enables expression balancing in function My_Func2. set_directive_expression_balance My_Func2 #pragma HLS expression_balance set_directive_function_instantiate Description By default: • Functions remain as separate hierarchy blocks in the RTL. • All instances of a function, at the same level of hierarchy, uses the same RTL implementation (block). The set_directive_function_instantiate command is used to create a unique RTL implementation for each instance of a function, allowing each instance to be optimized. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 456 Chapter 4: High-Level Synthesis Reference Guide By default, the following code results in a single RTL implementation of function foo_sub for all three instances. char foo_sub(char inval, char incr) { return inval + incr; } void foo(char inval1, char inval2, char inval3, char *outval1, char *outval2, char * outval3) { *outval1 = foo_sub(inval1, 1); *outval2 = foo_sub(inval2, 2); *outval3 = foo_sub(inval3, 3); } Using the directive as shown in the example section below results in three versions of function foo_sub, each independently optimized for variable incr. Syntax set_directive_function_instantiate where • < location> is the location (in the format function[/label]) where the instances of a function are to be made unique. • variable specifies which function argument < string> is to be specified as constant. Options This command has no options. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS function_instantiate variable= Examples For the example code shown above, the following Tcl (or pragma placed in function foo_sub) allows each instance of function foo_sub to be independently optimized with respect to input incr. set_directive_function_instantiate foo_sub incr #pragma HLS function_instantiate variable=incr High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 457 Chapter 4: High-Level Synthesis Reference Guide set_directive_inline Description Removes a function as a separate entity in the hierarchy. After inlining, the function is dissolved and no longer appears as a separate level of hierarchy. In some cases, inlining a function allows operations within the function to be shared and optimized more effectively with surrounding operations. An inlined function cannot be shared. This can increase area. By default, inlining is only performed on the next level of function hierarchy. Syntax set_directive_inline [OPTIONS] where • < location> is the location (in the format function[/label]) where inlining is to be performed. Options -off Disables function inlining to prevent particular functions from being inlined. For example, if the -recursive option is used in a caller function, this option can prevent a particular called function from being inlined when all others are. -recursive By default, only one level of function inlining is performed. The functions within the specified function are not inlined. The -recursive option inlines all functions recursively down the hierarchy. -region All functions in the specified region are to be inlined. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS inline High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 458 Chapter 4: High-Level Synthesis Reference Guide Examples Inlines all functions in foo_top (but not any lower level functions). set_directive_inline -region foo_top #pragma HLS inline region Inlines only function foo_sub1. set_directive_inline foo_sub1 #pragma HLS inline Inline all functions in foo_top, recursively down the hierarchy, except function foo_sub2. The first pragma is placed in function foo_top. The second pragma is placed in function foo_sub2. set_directive_inline -region -recursive foo_top set_directive_inline -off foo_sub2 #pragma HLS inline region recursive #pragma HLS inline off set_directive_interface Description Specifies how RTL ports are created from the function description during interface synthesis. The ports in the RTL implementation are derived from: • Any function-level protocol that is specified. • Function arguments • Global variables (accessed by the top-level function and defined outside its scope) Function-level handshakes: • Control when the function starts operation. • Indicate when function operation: ° Ends ° Is idle ° Is ready for new inputs High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 459 Chapter 4: High-Level Synthesis Reference Guide The implementation of a function-level protocol: • Is controlled by modes ap_ctrl_none, ap_ctrl_hs or ap_ctrl_chain. • Requires only the top-level function name. Note: Specify the function return for the pragma. Each function argument can be specified to have its own I/O protocol (such as valid handshake or acknowledge handshake). If a global variable is accessed, but all read and write operations are local to the design, the resource is created in the design. There is no need for an I/O port in the RTL. If however, the global variable is expected to be an external source or destination, specify its interface in a similar manner as standard function arguments. See the examples below. When set_directive_interface is used on sub-functions, only the -register option can be used. The -mode option is not supported on sub-functions. Syntax set_directive_interface [OPTIONS] where • < location> is the location (in the format function[/label]) where the function interface or registered output is to be specified. • < port> is the parameter (function argument or global variable) for which the interface has to be synthesized. This is not required when modes ap_ctrl_none or ap_ctrl_hs are used. Options -bundle : Groups function arguments into AXI ports. By default, Vivado HLS groups all function arguments specified as an AXI4-Lite interface into a single AXI4-Lite port. Similarly, Vivado HLS groups all function arguments specified as an AXI4 interface into a single AXI4 port. The -bundle option explicitly groups all function arguments with the same into the same interface port and names the RTL port . -mode (ap_none|ap_stable|ap_vld|ap_ack|ap_hs|ap_ovld|ap_fifo| ap_bus|ap_memory|bram|axis|s_axilite|m_axi|ap_ctrl_none|ap_ctrl_hs |ap_ctrl_chain) Following is a summary of how Vivado HLS implements the -mode options. For detailed descriptions, see Interface Synthesis Reference. • ap_none: No protocol. The interface is a data port. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 460 Chapter 4: High-Level Synthesis Reference Guide • ap_stable: No protocol. The interface is a data port. Vivado HLS assumes the data port is always stable after reset, which allows internal optimizations to remove unnecessary registers. • ap_vld: Implements the data port with an associated valid port to indicate when the data is valid for reading or writing. • ap_ack: Implements the data port with an associated acknowledge port to acknowledge that the data was read or written. • ap_hs: Implements the data port with associated valid and acknowledge ports to provide a two-way handshake to indicate when the data is valid for reading and writing and to acknowledge that the data was read or written. • ap_ovld: Implements the output data port with an associated valid port to indicate when the data is valid for reading or writing. Note: Vivado HLS implements the input argument or the input half of any read/write arguments with mode ap_none. • ap_fifo: Implements the port with a standard FIFO interface using data input and output ports with associated active-Low FIFO empty and full ports. Note: You can only use this interface on read arguments or write arguments. The ap_fifo mode does not support bidirectional read/write arguments. • ap_bus: Implements pointer and pass-by-reference ports as a bus interface. • ap_memory: Implements array arguments as a standard RAM interface. If you use the RTL design in Vivado IP integrator, the memory interface appears as discrete ports. • bram: Implements array arguments as a standard RAM interface. If you use the RTL design in Vivado IP integrator, the memory interface appears as a single port. • axis: Implements all ports as an AXI4-Stream interface. • s_axilite: Implements all ports as an AXI4-Lite interface. Vivado HLS produces an associated set of C driver files during the Export RTL process. • m_axi: Implements all ports as an AXI4 interface. You can use the config_interface command to specify either 32-bit (default) or 64-bit address ports and to control any address offset. • ap_ctrl_none: No block-level I/O protocol. Note: Using the ap_ctrl_none mode might prevent the design from being verified using the C/RTL co-simulation feature. • ap_ctrl_hs: Implements a set of block-level control ports to start the design operation and to indicate when the design is idle, done, and ready for new input data. Note: The ap_ctrl_hs mode is the default block-level I/O protocol. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 461 Chapter 4: High-Level Synthesis Reference Guide • ap_ctrl_chain: Implements a set of block-level control ports to start the design operation, continue operation, and indicate when the design is idle, done, and ready for new input data. -name : This option is used to rename the port based on your own specification. The generated RTL port will use this name -depth: Specifies the maximum number of samples for the test bench to process. This setting indicates the maximum size of the FIFO needed in the verification adapter that Vivado HLS creates for RTL co-simulation. This option is required for pointer interfaces using ap_fifo or ap_bus modes. -register: Registers the signal and any relevant protocol signals and instructs the signals to persist until at least the last cycle of the function execution. This option applies to the following scalar interfaces for the top-level function: • ap_none • ap_ack • ap_vld • ap_ovld • ap_hs • ap_fifo -register_mode (both|forward|reverse|off): This option specifies if registers are placed on the forward path (TDATA and TVALID), the reserve path (TREADY), on both paths (TDATA, TVALID, and TREADY), or if none of the ports signals are to be registered (off). The default is both. AXI-Stream side-channel signals are considered to be data signals and are registered whenever the TDATA is registered. -offset : Controls the address offset in AXI4-Lite and AXI4 interfaces. In an AXI4-Lite interface, specifies the address in the register map. In an AXI interface, specifies the following: • off: Do not generate an offset port. • direct: Generate a scalar input offset port. • slave: Generate an offset port and automatically map it to an AXI4-Lite slave interface. -clock : By default, the AXI-Lite interface clock is the same clock as the system clock. This option is used to set specify a separate clock for an AXI-Lite interface. If the -bundle option is used to group multiple top-level function arguments into a signal AXI-Lite interface, the clock option need only be specified on one of bundle members. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 462 Chapter 4: High-Level Synthesis Reference Guide Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS interface register port= Examples Turns off function-level handshakes for function foo. set_directive_interface -mode ap_ctrl_none foo #pragma HLS interface ap_ctrl_none port=return Argument InData in function foo is specified to have a ap_vld interface and the input should be registered. set_directive_interface -mode ap_vld -register foo InData #pragma HLS interface ap_vld register port=InData Exposes global variable lookup_table used in function foo as a port on the RTL design, with an ap_memory interface. set_directive_interface -mode ap_memory foo look_table set_directive_latency Description Specifies a maximum or minimum latency value, or both, on a function, loop, or region. Vivado HLS always aims for minimum latency. The behavior of Vivado HLS when minimum and maximum latency values are specified is as follows: • Latency is less than the minimum. If Vivado HLS can achieve less than the minimum specified latency, it extends the latency to the specified value, potentially increasing sharing. • Latency is greater than the minimum. The constraint is satisfied. No further optimizations are performed. • Latency is less than the maximum. The constraint is satisfied. No further optimizations are performed. • Latency is greater than the maximum. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 463 Chapter 4: High-Level Synthesis Reference Guide If Vivado HLS cannot schedule within the maximum limit, it increases effort to achieve the specified constraint. If it still fails to meet the maximum latency, it issues a warning. Vivado HLS then produces a design with the smallest achievable latency. Syntax set_directive_latency [OPTIONS] where • < location> is the location (function, loop or region) (in the format function[/label]) to be constrained. Options -max < integer Specifies the maximum latency. -min < integer> Specifies the minimum latency. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS latency \ min= \ max= Examples Function foo is specified to have a minimum latency of 4 and a maximum latency of 8. set_directive_latency -min=4 -max=8 foo #pragma HLS latency min=4 max=8 In function foo, loop loop_row is specified to have a maximum latency of 12. Place the pragma in the loop body. set_directive_latency -max=12 foo/loop_row #pragma HLS latency max=12 set_directive_loop_flatten Description Flattens nested loops into a single loop hierarchy. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 464 Chapter 4: High-Level Synthesis Reference Guide In the RTL implementation, it costs a clock cycle to move between loops in the loop hierarchy. Flattening nested loops allows them to be optimized as a single loop. This saves clock cycles, potentially allowing for greater optimization of the loop body logic. RECOMMENDED: Apply this directive to the inner-most loop in the loop hierarchy. Only perfect and semi-perfect loops can be flattened in this manner. • • • Perfect loop nests ° Only the innermost loop has loop body content. ° There is no logic specified between the loop statements. ° All loop bounds are constant. Semi-perfect loop nests ° Only the innermost loop has loop body content. ° There is no logic specified between the loop statements. ° The outermost loop bound can be a variable. Imperfect loop nests When the inner loop has variables bounds (or the loop body is not exclusively inside the inner loop), try to restructure the code, or unroll the loops in the loop body to create a perfect loop nest. Syntax set_directive_loop_flatten [OPTIONS] where • < location> is the location (inner-most loop), in the format function[/label]. Options -off Prevents flattening from taking place. Can prevent some loops from being flattened while all others in the specified location are flattened. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS loop_flatten off High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 465 Chapter 4: High-Level Synthesis Reference Guide Examples Flattens loop_1 in function foo and all (perfect or semi-perfect) loops above it in the loop hierarchy, into a single loop. Place the pragma in the body of loop_1. set_directive_loop_flatten foo/loop_1 #pragma HLS loop_flatten Prevents loop flattening in loop_2 of function foo. Place the pragma in the body of loop_2. set_directive_loop_flatten -off foo/loop_2 #pragma HLS loop_flatten off set_directive_loop_merge Description Merges all loops into a single loop. Merging loops: • Reduces the number of clock cycles required in the RTL to transition between the loop-body implementations. • Allows the loops be implemented in parallel (if possible). The rules for loop merging are: • If the loop bounds are variables, they must have the same value (number of iterations). • If loops bounds are constants, the maximum constant value is used as the bound of the merged loop. • Loops with both variable bound and constant bound cannot be merged. • The code between loops to be merged cannot have side effects. Multiple execution of this code should generate the same results. • - a=b is allowed - a=a+1 is not allowed. Loops cannot be merged when they contain FIFO reads. Merging changes the order of the reads. Reads from a FIFO or FIFO interface must always be in sequence. Syntax set_directive_loop_merge where • < location> is the location (in the format function[/label]) at which the loops reside. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 466 Chapter 4: High-Level Synthesis Reference Guide Options -force Forces loops to be merged even when Vivado HLS issues a warning. You must assure that the merged loop will function correctly. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS loop_merge force Examples Merges all consecutive loops in function foo into a single loop. set_directive_loop_merge foo #pragma HLS loop_merge All loops inside loop_2 of function foo (but not loop_2 itself) are merged by using the -force option. Place the pragma in the body of loop_2. set_directive_loop_merge -force foo/loop_2 #pragma HLS loop_merge force set_directive_loop_tripcount Description The loop tripcount is the total number of iterations performed by a loop. Vivado HLS reports the total latency of each loop (the number of cycles to execute all iterations of the loop). This loop latency is therefore a function of the tripcount (number of loop iterations). The tripcount can be a constant value. It may depend on the value of variables used in the loop expression (for example, x where • < location> is the location of the loop (in the format function[/label]) at which the tripcount is specified. Options -max < integer> Specifies the maximum interval. -min < integer> Specifies the minimum interval. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS loop_tripcount \ min= \ max= Examples loop_1 in function foo is specified to have: • A minimum tripcount of 12 • A maximum tripcount of 16 set_directive_loop_tripcount -min 12 -max 16 -avg 14 foo/loop_1 #pragma HLS loop_tripcount min=12 max=16 avg=14 set_directive_occurrence Description When pipelining functions or loops, specifies that the code in a location is executed at a lesser rate than the code in the enclosing function or loop. This allows the code that is executed at the lesser rate to be pipelined at a slower rate, and potentially shared within the top-level pipeline. For example: • A loop iterates N times. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 468 Chapter 4: High-Level Synthesis Reference Guide • Part of the loop is protected by a conditional statement and only executes M times, where N is an integer multiple of M. • The code protected by the conditional is said to have an occurrence of N/M. If N is pipelined with an initiation interval II, any function or loops protected by the conditional statement: • May be pipelined with a higher initiation interval than II. Note: At a slower rate. This code is not executed as often. • Can potentially be shared better within the enclosing higher rate pipeline. Identifying a region with an occurrence allows the functions and loops in this region to be pipelined with an initiation interval that is slower than the enclosing function or loop. Syntax set_directive_occurrence [OPTIONS] where • < location> specifies the location with a slower rate of execution. Options -cycle < int> Specifies the occurrence N/M where: • N is the number of times the enclosing function or loop is executed • M is the number of times the conditional region is executed. N must be an integer multiple of M. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS occurrence cycle= Examples Region Cond_Region in function foo has an occurrence of 4. It executes at a rate four times slower than the code that encompasses it. set_directive_occurrence -cycle 4 foo/Cond_Region #pragma HLS occurrence cycle=4 High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 469 Chapter 4: High-Level Synthesis Reference Guide set_directive_pipeline Description Specifies the details for: • Function pipelining • Loop pipelining A pipelined function or loop can process new inputs every N clock cycles, where N is the initiation interval (II). The default initiation interval is 1, which processes a new input every clock cycle, or it can be specified by the -II option. If Vivado HLS cannot create a design with the specified II, it: • Issues a warning. • Creates a design with the lowest possible II. You can then analyze this design with the warning message to determine what steps must be taken to create a design that satisfies the required initiation interval. Syntax set_directive_pipeline [OPTIONS] where • < location> is the location (in the format function[/label]) to be pipelined. Options -II Specifies the desired initiation interval for the pipeline. Vivado HLS tries to meet this request. Based on data dependencies, the actual result might have a larger II. -enable_flush Implements a pipeline which will flush and empty if the data valid at the input of the pipeline goes inactive. This feature is only supported for pipelined functions: it is not supported for pipelined loops. -rewind Note: Applicable only to a loop. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 470 Chapter 4: High-Level Synthesis Reference Guide Enables rewinding. Rewinding enables continuous loop pipelining, with no pause between one loop iteration ending and the next starting. Rewinding is effective only if there is one single loop (or a perfect loop nest) inside the top-level function. The code segment before the loop: • Is considered as initialization. • Is executed only once in the pipeline. • Cannot contain any conditional operations (if-else). Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS pipeline \ II= \ enable_flush \ Examples Function foo is pipelined with an initiation interval of 1. set_directive_pipeline foo #pragma HLS pipeline set_directive_protocol Description Specifies a region of the code (a protocol region) in which no clock operations is inserted by Vivado HLS unless explicitly specified in the code. A protocol region can manually specify an interface protocol. Vivado HLS does not insert any clocks between any operations, including those that read from or write to function arguments. The order of read and writes are therefore obeyed at the RTL. A clock operation may be specified: • In C by using an ap_wait() statement (include ap_utils.h). • In C++ and SystemC designs by using the wait() statement (include systemc.h). The ap_wait and wait statements have no effect on the simulation of C and C++ designs respectively. They are only interpreted by Vivado HLS. To create a region of C code: 1. Enclosing the region in braces {}. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 471 Chapter 4: High-Level Synthesis Reference Guide 2. Name it. For example, the following defines a region called io_section: io_section:{..lines of C code...} Syntax set_directive_protocol [OPTIONS] where • < location> is the location (in the format function[/label]) to be implemented in a cycle-accurate manner, corresponding to external protocol requirements. Options -mode (floating|fixed) The default floating mode allows the code corresponding to statements outside the protocol region to overlap with the statements in the protocol statements in the final RTL. The protocol region remains cycle accurate, but other operations can occur at the same time. The fixed mode ensures that there is no overlap. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS protocol \ Examples Defines region io_section in function foo as a fixed protocol region. Place the pragma inside region io_section. set_directive_protocol -mode fixed foo/io_section #pragma HLS protocol fixed set_directive_reset Description Adds or removes resets for specific state variables (global or static). Syntax set_directive_reset [OPTIONS] High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 472 Chapter 4: High-Level Synthesis Reference Guide Options The location (in the format function[/label]) at which the variable is defined. The variable to which the directive is applied. -off • If -off is specified, reset is not generated for the specified variable. • If -off is not specified, reset is generated for the specified variable. Pragma Place the pragma in the C source within the boundaries of the variable life cycle. #pragma HLS reset variable=a off Examples Adds reset to variable static int a in function foo even when the global reset setting is none or control. set_directive_reset foo a #pragma HLS reset variable=a Removes reset from variable static int a in function foo even when the global reset setting is state or all. set_directive_reset -off foo a #pragma HLS reset variable=a off set_directive_resource Description Specifies the resource (core) to implement a variable in the RTL. The variable can be any of the following: • array • arithmetic operation • function argument Vivado HLS implements the operations in the code using hardware cores. When multiple cores in the library can implement the operation, you can specify which core to use with the High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 473 Chapter 4: High-Level Synthesis Reference Guide set_directive_resource command. To generate a list of cores, use the list_core command. If no resource is specified, Vivado HLS determines the resource to use. To specify which memory element in the library to use to implement an array, use the set_directive_resource command. For example, this allows you to control whether the array is implemented as a single or a dual-port RAM. This usage is important for arrays on the top-level function interface, because the memory associated with the array determines the ports in the RTL. You can use the -latency option to specify the latency of the core. For block RAMs on the interface, the -latency option allows you to model off-chip, non-standard SRAMs at the interface, for example to support an SRAM with a latency of 2 or 3. For internal operations, the -latency option allows the operation to be implemented using more pipelined stages. These additional pipeline stages can help resolve timing issues during RTL synthesis. IMPORTANT: To use the -latency option, the operation must have an available multi-stage core. Vivado HLS provides a multi-stage core for all basic arithmetic operations (add, subtract, multiply and divide), all floating-point operations, and all block RAMs. RECOMMENDED: For best results, Xilinx recommends that you use -std=c99 for C and -fno-builtin for C and C++. To specify the C compile options, such as -std=c99, use the Tcl command add_files with the -cflags option. Alternatively, use the Edit CFLAGs button in the Project Settings dialog box. Syntax set_directive_resource -core where • < location> is the location (in the format function[/label]) at which the variable can be found. • < variable> is the variable. Options -core Specifies the core, as defined in the technology library. -memory_style (auto|distribute|block|uram) This option is only applicable to the XPM_MEMORY core and specifies the memory style. Valid styles are auto, distribute, block, and uram (only available for certain Ultrascale+ devices). -latency < string> High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 474 Chapter 4: High-Level Synthesis Reference Guide Specifies the latency of the core. -port_map Specifies port mappings when using the IP generation flow to map ports on the design with ports on the adapter. The variable < string> is a Tcl list of the design port and adapter ports. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS resource \ variable= \ core= Examples Variable coeffs[128] is an argument to top-level function foo_top. This directive specifies that coeffs be implemented with core RAM_1P from the library. The ports created in the RTL to access the values of coeffs are those defined in the core RAM_1P. set_directive_resource -core RAM_1P foo_top coeffs #pragma HLS resource variable=coeffs core=RAM_1P Given code Result=A*B in function foo, specifies the multiplication be implemented with two-stage pipelined multiplier core. set_directive_resource -latency 2 foo Result #pragma HLS RESOURCE variable=Result latency=2 set_directive_stream Description By default, array variables are implemented as RAM: • Top-level function array parameters are implemented as a RAM interface port. • General arrays are implemented as RAMs for read-write access. • In sub-functions involved in dataflow optimizations, the array arguments are implemented using a RAM pingpong buffer channel. • Arrays involved in loop-based dataflow optimizations are implemented as a RAM pingpong buffer channel High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 475 Chapter 4: High-Level Synthesis Reference Guide If the data stored in the array is consumed or produced in a sequential manner, a more efficient communication mechanism is to use streaming data, where FIFOs are used instead of RAMs. When an argument of the top-level function is specified as interface type ap_fifo, the array is automatically implemented as streaming. Syntax set_directive_stream [OPTIONS] where • < location> is the location (in the format function[/label]) which contains the array variable. • < variable> is the array variable to be implemented as a FIFO. Options -depth < integer> Note: Relevant only for array streaming in dataflow channels. By default, the depth of the FIFO implemented in the RTL is the same size as the array specified in the C code. This options allows you to modify the size of the FIFO. When the array is implemented in a DATAFLOW region, it is common to the use the -depth option to reduce the size of the FIFO. For example, in a DATAFLOW region when all loops and functions are processing data at a rate of II=1, there is no need for a large FIFO because data is produced and consumed in each clock cycle. In this case, the -depth option may be used to reduce the FIFO size to 1 to substantially reduce the area of the RTL design. This same functionality is provided for all arrays in a DATAFLOW region using the config_dataflow command with the -depth option. The -depth option used with set_directive_stream overrides the default specified using config_dataflow. -dim Specifies the dimension of the array to be streamed. Default is dimension 1. -off Note: Relevant only for array streaming in dataflow channels. The config_dataflow -default_channel fifo command globally implies a set_directive_stream on all arrays in the design. This option allows streaming to be turned off on a specific array (and default back to using a RAM pingpong buffer based channel). High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 476 Chapter 4: High-Level Synthesis Reference Guide Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS stream variable= \ off \ depth= Examples Specifies array A[10] in function foo to be streaming, and implemented as a FIFO. set_directive_stream foo A #pragma HLS STREAM variable=A Array B in named loop loop_1 of function foo is set to streaming with a FIFO depth of 12. In this case, place the pragma inside loop_1. set_directive_stream -depth 12 foo/loop_1 B #pragma HLS STREAM variable=B depth=12 Array C has streaming disabled. It is assumed enabled by config_dataflow in this example. set_directive_stream -off foo C #pragma HLS STREAM variable=C off set_directive_top Description Attaches a name to a function, which can then be used for the set_top command. This is typically used to synthesize member functions of a class in C++. RECOMMENDED: Specify the directive in an active solution. Use the set_top command with the new name. Syntax set_directive_top [OPTIONS] where • < location> is the function to be renamed. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 477 Chapter 4: High-Level Synthesis Reference Guide Options -name Specifies the name to be used by the set_top command. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS top \ name= Examples Function foo_long_name is renamed to DESIGN_TOP, which is then specified as the top-level. If the pragma is placed in the code, the set_top command must still be issued in the top-level specified in the GUI project settings. set_directive_top -name DESIGN_TOP foo_long_name #pragma HLS top name=DESIGN_TOP set_top DESIGN_TOP set_directive_unroll Description Transforms loops by creating multiples copies of the loop body. A loop is executed for the number of iterations specified by the loop induction variable. The number of iterations may also be impacted by logic inside the loop body (for example, break or modifications to any loop exit variable). The loop is implemented in the RTL by a block of logic representing the loop body, which is executed for the same number of iterations. The set_directive_unroll command allows the loop to be fully unrolled. Unrolling the loop creates as many copies of the loop body in the RTL as there are loop iterations, or partially unrolled by a factor N, creating N copies of the loop body and adjusting the loop iteration accordingly. If the factor N used for partial unrolling is not an integer multiple of the original loop iteration count, the original exit condition must be checked after each unrolled fragment of the loop body. To unroll a loop completely, the loop bounds must be known at compile time. This is not required for partial unrolling. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 478 Chapter 4: High-Level Synthesis Reference Guide Syntax set_directive_unroll [OPTIONS] where • < location> is the location of the loop (in the format function[/label]) to be unrolled. Options -factor < integer> Specifies a non-zero integer indicating that partial unrolling is requested. The loop body is repeated this number of times. The iteration information is adjusted accordingly. -region Unrolls all loops within a loop without unrolling the enclosing loop itself. Consider the following example: • Loop loop_1 contains multiple loops at the same level of loop hierarchy (loops loop_2 and loop_3). • A named loop (such as loop_1) is also a region or location in the code. • A section of code is enclosed by braces { }. • If the unroll directive is specified on location /loop_1, it unrolls loop_1. The -region option specifies that the directive be applied only to the loops enclosing the named region. This results in: • loop_1 is left rolled. • All loops inside loop_1 (loop_2 and loop_3) are unrolled. -skip_exit_check Effective only if a factor is specified (partial unrolling). • Fixed bounds No exit condition check is performed if the iteration count is a multiple of the factor. If the iteration count is not an integer multiple of the factor, the tool: ° Prevents unrolling. ° Issues a warning that the exit check must be performed to proceed. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 479 Chapter 4: High-Level Synthesis Reference Guide • Variable bounds The exit condition check is removed. You must ensure that: ° The variable bounds is an integer multiple of the factor. ° No exit check is in fact required. Pragma Place the pragma in the C source within the boundaries of the required location. #pragma HLS unroll \ skip_exit_check \ factor= \ region Examples Unrolls loop L1 in function foo. Place the pragma in the body of loop L1. set_directive_unroll foo/L1 #pragma HLS unroll Specifies an unroll factor of 4 on loop L2 of function foo. Removes the exit check. Place the pragma in the body of loop L2. set_directive_unroll -skip_exit_check -factor 4 foo/L2 #pragma HLS unroll skip_exit_check factor=4 Unrolls all loops inside loop L3 in function foo, but not loop L3 itself. The -region option specifies the location be considered an enclosing region and not a loop label. set_directive_unroll -region foo/L3 #pragma HLS unroll region set_part Description Sets a target device for the current solution. The command can be executed only in the context of an active solution. Syntax set_part where High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 480 Chapter 4: High-Level Synthesis Reference Guide • < device_specification> is a a device specification that sets the target device for Vivado HLS synthesis and implementation. • < device_family> is the device family name, which uses the default device in the family. • < device>< package>< speed_grade> is the target device name including device, package, and speed-grade information. Options This command has no options. Pragma There is no pragma equivalent. Examples The FPGA libraries provided with Vivado HLS can be added to the current solution by providing the device family name as shown below. In this case, the default device, package, and speed-grade specified in the Vivado HLS FPGA library for this device family are used. set_part virtex7 The FPGA libraries provided with Vivado HLS can optionally specify the specific device with package and speed-grade information. set_part xc6vlx240tff1156-1 set_top Description Defines the top-level function to be synthesized. Any functions called from this function will also be part of the design. Syntax set_top where • < top> is the function to be synthesized. Options This command has no options. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 481 Chapter 4: High-Level Synthesis Reference Guide Pragma There is no pragma equivalent. Examples Sets the top-level function as foo_top. set_top foo_top GUI Reference This reference section explains how to use, control and customize the Vivado HLS GUI. Monitoring Variables You can view the values of variables and expressions directly in the Debug perspective. The following figure shows how you can monitor the value of individual variables. X-Ref Target - Figure 4-1 Figure 4-1: High-Level Synthesis UG902 (v2017.1) April 5, 2017 Monitoring Variables www.xilinx.com Send Feedback 482 Chapter 4: High-Level Synthesis Reference Guide You can monitor the value of expressions using the Expressions tab. X-Ref Target - Figure 4-2 Figure 4-2: Monitoring Expressions Resolving Header File Information By default, the Vivado HLS GUI continually parses all header files to resolve coding references. The GUI highlights unresolved references, as shown in the following figure: X-Ref Target - Figure 4-3 • Left sidebar: Highlights undefined references in the current view. • Right sidebar: Highlights unresolved references throughout the file. 0 Figure 4-3: High-Level Synthesis UG902 (v2017.1) April 5, 2017 Index C Files www.xilinx.com Send Feedback 483 Chapter 4: High-Level Synthesis Reference Guide IMPORTANT: It is important to remove undefined references in the code before performing C simulation or synthesis. To check for undefined references, see the annotations in the code viewer that indicate a variable or value is unknown or cannot be defined. Undefined references do not appear in the directives window. Undefined references occur when code defined in a header file (.h or .hpp extension) cannot be resolved. The primary causes of undefined references are: • The code was recently added to the file. If the code is new, ensure the header file is saved. After saving the header file, Vivado HLS automatically indexes the header files and updates the coding references. • The header file is not in the search path. Ensure the header file is included in the C code using an include statement, the location to the header file is in the search path, and the header file is in the same directory as the C files added to the project. Note: To explicitly add the search path, select Solution > Solution Settings, click Synthesis or Simulation, and use the Edit CFLAGs button. For more information, see Creating a New Synthesis Project in Chapter 1. • Automatic indexing is disabled. Ensure that Vivado HLS is parsing all header files automatically. Select Project > Project Settings to open the Project Settings dialog box. Click General, and make sure Disable Parsing All Header Files is deselected, as shown in the following figure. This might result in a reduced GUI response time, because Vivado HLS uses CPU cycles to automatically check the header files. Note: To manually force Vivado HLS to index all C files, click the Index C files toolbar button . High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 484 Chapter 4: High-Level Synthesis Reference Guide X-Ref Target - Figure 4-4 Figure 4-4: Controlling Header File Parsing Resolving Comments in the Source Code In some localizations, non-English comments in the source file appears as strange characters. This can be corrected by: 1. Selecting the project in the Explorer Pane. 2. Right-click and select the appropriate language encoding using Properties > Resource. In the section titled Text File Encoding select Other and choose appropriate encoding from the drop-down menu. Customizing the GUI Behavior In some cases the default setting of the Vivado HLS GUI prevents certain information from being shown or the defaults that are not suitable for you. This sections explains how the following can be customized: • Console window buffer size. • Default key behaviors. Customizing the Console Window The console windows displays the messages issued during operations such as synthesize and verification. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 485 Chapter 4: High-Level Synthesis Reference Guide The default buffer size for this windows is 80,000 characters and can be changed, or the limit can be removed, to ensure all messages can be reviewed, by using menu Window > Preferences > Run/Debug > Console. Customizing the Key Behavior The behavior of the GUI can be customized using the menu Windows > Preferences and new user-defined tool settings saved. The default setting for the key combination Ctrl+Tab, is to make the active tab in the Information Pane toggle between the source code and the header file. This is changed to make the Ctrl+Tab combination make each tab in turn the active tab. • In the Preferences menu, sub-menu General > Keys allows the Command value Toggle Source/Header to be selected and the CTRL-TAB combination removed by using the Unbind Command key. • Selecting Next Tab in the Command column, placing the cursor in the Binding dialog box and pressing the Ctrl key and then the Tab key, that causes the operation Ctrl+Tab to be associated with making the next tab active. A find-next hot key can be implemented by using the Microsoft Visual Studio scheme. This can be performed using the menu Window > Preference > General > Keys and replace the Default scheme with the Microsoft Visual Studio scheme. Reviewing the sub-menus in the Preferences menu allows every aspect of the GUI environment to be customized to ensure the highest levels of productivity. Interface Synthesis Reference This reference section explains each of the Vivado HLS interface protocol modes. Block-Level I/O Protocols Vivado HLS uses the interface types ap_ctrl_none, ap_ctrl_hs, and ap_ctrl_chain to specify whether the RTL is implemented with block-level handshake signals. Block-level handshake signals specify the following: • When the design can start to perform the operation • When the operation ends • When the design is idle and ready for new inputs You can specify these block-level I/O protocols on the function or the function return. If the C code does not return a value, you can still specify the block-level I/O protocol on the High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 486 Chapter 4: High-Level Synthesis Reference Guide function return. If the C code uses a function return, Vivado HLS creates an output port ap_return for the return value. The ap_ctrl_hs block-level I/O protocol is the default. The following figure shows the resulting RTL ports and behavior when Vivado HLS implements ap_ctrl_hs on a function. In this example, the function returns a value using the return statement, and Vivado HLS creates the ap_return output port in the RTL design. If a function return statement is not included in the C code, this port is not created. X-Ref Target - Figure 4-5 #include “adders.h” int adders(int in1, int in2, int in3) { int sum; sum = in1 + in2 + in3; return sum; LQ DGGHUV ,Q 6\QWKHVLV ,Q } DSBVWDUW DSBUHWXUQ  DSBUHDG\ DSBGRQH DSBLGOH ; Figure 4-5: Example ap_ctrl_hs Interface The ap_ctrl_chain interface mode is similar to ap_ctrl_hs but provides an additional input signal ap_continue to apply back pressure. Xilinx recommends using the ap_ctrl_chain block-level I/O protocol when chaining Vivado HLS blocks together. ap_ctrl_none If you specify the ap_ctrl_none block-level I/O protocol, the handshake signal ports (ap_start, ap_idle, ap_ready, and ap_done) shown in Figure 4-5 are not created. If you do not specify block-level I/O protocols on the design, you must adhere to the conditions described in Interface Synthesis Requirements in Chapter 1 when using C/RTL cosimulation to verify the RTL design. ap_ctrl_hs The following figure shows the behavior of the block-level handshake signals created by the ap_ctrl_hs I/O protocol. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 487 Chapter 4: High-Level Synthesis Reference Guide X-Ref Target - Figure 4-6 Figure 4-6: Behavior of ap_ctrl_hs Interface After reset, the following occurs: 1. The block waits for ap_start to go High before it begins operation. 2. Output ap_idle goes Low immediately to indicate the design is no longer idle. 3. The ap_start signal must remain High until ap_ready goes High. Once ap_ready goes High: ° If ap_start remains High the design will start the next transaction. ° If ap_start is taken Low, the design will complete the current transaction and halt operation. 4. Data can be read on the input ports. Note: The input ports can use a port-level I/O protocol that is independent of this block-level I/O protocol. For details, see Port-Level I/O Protocols. 5. Data can be written to the output ports. Note: The output ports can use a port-level I/O protocol that is independent of this block-level I/O protocol. For details, see Port-Level I/O Protocols. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 488 Chapter 4: High-Level Synthesis Reference Guide 6. Output ap_done goes High when the block completes operation. Note: If there is an ap_return port, the data on this port is valid when ap_done is High. Therefore, the ap_done signal also indicates when the data on output ap_return is valid. 7. When the design is ready to accept new inputs, the ap_ready signal goes High. Following is additional information about the ap_ready signal: ° The ap_ready signal is inactive until the design starts operation. ° In non-pipelined designs, the ap_ready signal is asserted at the same time as ap_done. ° In pipelined designs, the ap_ready signal might go High at any cycle after ap_start is sampled High. This depends on how the design is pipelined. ° If the ap_start signal is Low when ap_ready is High, the design executes until ap_done is High and then stops operation. ° If the ap_start signal is High when ap_ready is High, the next transaction starts immediately, and the design continues to operate. 8. The ap_idle signal indicates when the design is idle and not operating. Following is additional information about the ap_idle signal: ° If the ap_start signal is Low when ap_ready is High, the design stops operation, and the ap_idle signal goes High one cycle after ap_done. ° If the ap_start signal is High when ap_ready is High, the design continues to operate, and the ap_idle signal remains Low. ap_ctrl_chain The ap_ctrl_chain block-level I/O protocol is similar to the ap_ctrl_hs protocol but provides an additional input port named ap_continue. An active High ap_continue signal indicates that the downstream block that consumes the output data is ready for new data inputs. If the downstream block is not able to consume new data inputs, the ap_continue signal is Low, which prevents upstream blocks from generating additional data. The ap_ready port of the downstream block can directly drive the ap_continue port. Following is additional information about the ap_continue port: • If the ap_continue signal is High when ap_done is High, the design continues operating. The behavior of the other block-level I/O signals is identical to those described in the ap_ctrl_hs block-level I/O protocol. • If the ap_continue signal is Low when ap_done is High, the design stops operating, the ap_done signal remains High, and data remains valid on the ap_return port if the ap_return port is present. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 489 Chapter 4: High-Level Synthesis Reference Guide In the following figure, the first transaction completes, and the second transaction starts immediately because ap_continue is High when ap_done is High. However, the design halts at the end of the second transaction until ap_continue is asserted High. X-Ref Target - Figure 4-7 Figure 4-7: Behavior of ap_ctrl_chain Interface Port-Level I/O Protocols ap_none The ap_none port-level I/O protocol is the simplest interface type and has no other signals associated with it. Neither the input nor output data signals have associated control ports that indicate when data is read or written. The only ports in the RTL design are those specified in the source code. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 490 Chapter 4: High-Level Synthesis Reference Guide An ap_none interface does not require additional hardware overhead. However, the ap_none interface does requires the following: • • Producer blocks to do one of the following: ° Provide data to the input port at the correct time ° Hold data for the length of a transaction until the design completes Consumer blocks to read output ports at the correct time Note: The ap_none interface cannot be used with array arguments. ap_stable Like ap_none, the ap_stable port-level I/O protocol does not add any interface control ports to the design. The ap_stable type is typically used for data that can change but remains stable during normal operation, such as ports that provide configuration data. The ap_stable type informs Vivado HLS of the following: • The data applied to the port remains stable during normal operation but is not a constant value that can be optimized. • The fanout from this port is not required to be registered. Note: The ap_stable type can only be applied to input ports. When applied to inout ports, only the input of the port is considered stable. ap_hs (ap_ack, ap_vld, and ap_ovld) The ap_hs port-level I/O protocol provides the greatest flexibility in the development process, allowing both bottom-up and top-down design flows. Two-way handshakes safely perform all intra-block communication, and manual intervention or assumptions are not required for correct operation. The ap_hs port-level I/O protocol provides the following signals: • Data port • Acknowledge signal to indicate when data is consumed • Valid signal to indicate when data is read The following figure shows how an ap_hs interface behaves for both an input and output port. In this example, the input port is named in, and the output port is named out. Note: The control signals names are based on the original port name. For example, the valid port for data input in is named in_vld. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 491 Chapter 4: High-Level Synthesis Reference Guide X-Ref Target - Figure 4-8 Figure 4-8: Behavior of ap_hs Interface For inputs, the following occurs: • After start is applied, the block begins normal operation. • If the design is ready for input data but the input valid is Low, the design stalls and waits for the input valid to be asserted to indicate a new input value is present. Note: The preceding figure shows this behavior. In this example, the design is ready to read data input in on clock cycle 4 and stalls waiting for the input valid before reading the data. • When the input valid is asserted High, an output acknowledge is asserted High to indicate the data was read. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 492 Chapter 4: High-Level Synthesis Reference Guide For outputs, the following occurs: • After start is applied, the block begins normal operation. • When an output port is written to, its associated output valid signal is simultaneously asserted to indicate valid data is present on the port. • If the associated input acknowledge is Low, the design stalls and waits for the input acknowledge to be asserted. • When the input acknowledge is asserted, the output valid is deasserted on the next clock edge. ap_ack The ap_ack port-level I/O protocol is a subset of the ap_hs interface type. The ap_ack port-level I/O protocol provides the following signals: • Data port • Acknowledge signal to indicate when data is consumed ° For input arguments, the design generates an output acknowledge that is active-High in the cycle the input is read. ° For output arguments, Vivado HLS implements an input acknowledge port to confirm the output was read. Note: After a write operation, the design stalls and waits until the input acknowledge is asserted High, which indicates the output was read by a consumer block. However, there is no associated output port to indicate when the data can be consumed. CAUTION! You cannot use C/RTL cosimulation to verify designs that use ap_ack on an output port. ap_vld The ap_vld is a subset of the ap_hs interface type. The ap_vld port-level I/O protocol provides the following signals: • Data port • Valid signal to indicate when data is read ° ° For input arguments, the design reads the data port as soon as the valid is active. Even if the design is not ready to read new data, the design samples the data port and holds the data internally until needed. For output arguments, Vivado HLS implements an output valid port to indicate when the data on the output port is valid. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 493 Chapter 4: High-Level Synthesis Reference Guide ap_ovld The ap_ovld is a subset of the ap_hs interface type. The ap_ovld port-level I/O protocol provides the following signals: • Data port • Valid signal to indicate when data is read ° For input arguments and the input half of inout arguments, the design defaults to type ap_none. ° For output arguments and the output half of inout arguments, the design implements type ap_vld. ap_memory, bram The ap_memory and bram interface port-level I/O protocols are used to implement array arguments. This type of port-level I/O protocol can communicate with memory elements (for example, RAMs and ROMs) when the implementation requires random accesses to the memory address locations. Note: If you only need sequential access to the memory element, use the ap_fifo interface instead. The ap_fifo interface reduces the hardware overhead, because address generation is not performed. For more information, see ap_fifo. The ap_memory and bram interface port-level I/O protocols are identical. The only difference is the way Vivado IP integrator shows the blocks: • The ap_memory interface appears as discrete ports. • The bram interface appears as a single, grouped port. In IP integrator, you can use a single connection to create connections to all ports. When using an ap_memory interface, specify the array targets using the RESOURCE directive. If no target is specified for the arrays, Vivado HLS determines whether to use a single or dual-port RAM interface. TIP: Before running synthesis, ensure array arguments are targeted to the correct memory type using the RESOURCE directive. Re-synthesizing with corrected memories can result in a different schedule and RTL. The following figure shows an array named d specified as a single-port block RAM. The port names are based on the C function argument. For example, if the C argument is d, the chip-enable is d_ce, and the input data is d_q0 based on the output/q port of the BRAM. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 494 Chapter 4: High-Level Synthesis Reference Guide X-Ref Target - Figure 4-9 Figure 4-9: Behavior of ap_memory Interface After reset, the following occurs: • After start is applied, the block begins normal operation. • Reads are performed by applying an address on the output address ports while asserting the output signal d_ce. Note: For a default block RAM, the design expects the input data d_q0 to be available in the next clock cycle. You can use the RESOURCE directive to indicate the RAM has a longer read latency. • Write operations are performed by asserting output ports d_ce and d_we while simultaneously applying the address and output data d_d0. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 495 Chapter 4: High-Level Synthesis Reference Guide ap_fifo An ap_fifo interface is the most hardware-efficient approach when the design requires access to a memory element and the access is always performed in a sequential manner, that is, no random access is required. The ap_fifo port-level I/O protocol supports the following: • Allows the port to be connected to a FIFO • Enables complete, two-way empty-full communication • Works for arrays, pointers, and pass-by-reference argument types Note: Functions that can use an ap_fifo interface often use pointers and might access the same variable multiple times. To understand the importance of the volatile qualifier when using this coding style, see Multi-Access Pointer Interfaces: Streaming Data in Chapter 3. In the following example, in1 is a pointer that accesses the current address, then two addresses above the current address, and finally one address below. void foo(int* in1, ...) { int data1, data2, data3; ... data1= *in1; data2= *(in1+2); data3= *(in1-1); ... } If in1 is specified as an ap_fifo interface, Vivado HLS checks the accesses, determines the accesses are not in sequential order, issues an error, and halts. To read from non-sequential address locations, use an ap_memory or bram interface. For more information, see ap_memory, bram. You cannot specify an ap_fifo interface on an argument that is both read from and written to. You can only specify an ap_fifo interface on an input or an output argument. A design with input argument in and output argument out specified as ap_fifo interfaces behaves as shown in the following figure. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 496 Chapter 4: High-Level Synthesis Reference Guide X-Ref Target - Figure 4-10 Figure 4-10: Behavior of ap_fifo Interface For inputs, the following occurs: • After start is applied, the block begins normal operation. • If the input port is ready to be read but the FIFO is empty as indicated by input port in_empty_n Low, the design stalls and waits for data to become available. • When the FIFO contains data as indicated by input port in_empty_n High, an output acknowledge in_read is asserted High to indicate the data was read in this cycle. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 497 Chapter 4: High-Level Synthesis Reference Guide For outputs, the following occurs: • After start is applied, the block begins normal operation. • If an output port is ready to be written to but the FIFO is full as indicated by out_full_n Low, the data is placed on the output port but the design stalls and waits for the space to become available in the FIFO. • When space becomes available in the FIFO as indicated by out_full_n High, the output acknowledge signal out_write is asserted to indicate the output data is valid. • If the top-level function or the top-level loop is pipelined using the -rewind option, Vivado HLS creates an additional output port with the suffix _lwr. When the last write to the FIFO interface completes, the _lwr port goes active-High. ap_bus An ap_bus interface can communicate with a bus bridge. Because the ap_bus interface does not follow specific bus standards, you can use this interface with a bus bridge that communicates with the system bus. The bus bridge must be able to cache all burst writes. Note: Functions that can use an ap_bus interface use pointers and might access the same variable multiple times. To understand the importance of the volatile qualifier when using this coding style, see Multi-Access Pointer Interfaces: Streaming Data in Chapter 3. You can use an ap_bus interface in the following ways: • Standard Mode: This mode performs individual read and write operations, specifying the address of each. • Burst Mode: This mode performs data transfers if the C function memcpy is used in the C source code. In burst mode, the interface indicates the base address and the size of the transfer. The data samples are then transferred in consecutive cycles. Note: Arrays accessed by the memcpy function cannot be partitioned into registers. Figure 4-11 and Figure 4-12 show the behavior for read and write operations in standard mode when an ap_bus interface is applied to argument d, as shown in the following example: void foo (int *d) { static int acc = 0; int i; for (i=0;i<4;i++) { acc += d[i+1]; d[i] = acc; } } High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 498 Chapter 4: High-Level Synthesis Reference Guide Figure 4-13 and Figure 4-14 show the behavior when the C memcpy function and burst mode are used, as shown in the following example: void bus (int *d) { int buf1[4], buf2[4]; int i; memcpy(buf1,d,4*sizeof(int)); for (i=0;i<4;i++) { buf2[i] = buf1[3-i]; } memcpy(d,buf2,4*sizeof(int)); } , X-Ref Target - Figure 4-11 Figure 4-11: High-Level Synthesis UG902 (v2017.1) April 5, 2017 Behavior of ap_bus Interface: Standard Read www.xilinx.com Send Feedback 499 Chapter 4: High-Level Synthesis Reference Guide After reset, the following occurs: • After start, the block begins normal operation. • If a read must be performed but there is no data in the bus bridge FIFO, indicated by d_rsp_empty_n Low, the following occurs: ° Output port d_req_write is asserted with port d_req_din deasserted to indicate a read operation. ° The address is output. ° The design stalls and waits for data to become available. • When data becomes available for reading the output signal, d_rsp_read is immediately asserted and data is read at the next clock edge. • If a read must be performed and data is available in the bus bridge FIFO, indicated by d_rsp_empty_n High, the following occurs: ° Output port d_req_write is asserted and port d_req_din is deasserted to indicate a read operation. ° The address is output. ° Output signal d_rsp_read is asserted in the next clock cycle and data is read at the next clock edge. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 500 Chapter 4: High-Level Synthesis Reference Guide X-Ref Target - Figure 4-12 Figure 4-12: Behavior of ap_bus Interface: Standard Write After reset, the following occurs: • After start, the block begins normal operation. • If a write must be performed but there is no space in the bus bridge FIFO, indicated by d_req_full_n Low, the following occurs: ° The address and data are output. ° The design stalls and waits for space to become available. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 501 Chapter 4: High-Level Synthesis Reference Guide • • When space becomes available for writing, the following occurs: ° Output ports d_req_write and d_req_din are asserted to indicate a write operation. ° The output signal d_req_din is immediately asserted to indicate the data is valid at the next clock edge. If a write must be performed and space is available in the bus bridge FIFO, indicated by d_req_full_n High, the following occurs: ° Output ports d_req_write and d_req_din are asserted to indicate a write operation. ° The address and data are output. ° The output signal d_req_din is asserted to indicate the data is valid at the next clock edge. X-Ref Target - Figure 4-13 Figure 4-13: High-Level Synthesis UG902 (v2017.1) April 5, 2017 Behavior of ap_bus Interface: Burst Read www.xilinx.com Send Feedback 502 Chapter 4: High-Level Synthesis Reference Guide After reset, the following occurs: • After start, the block begins normal operation. • If a read must be performed but there is no data in the bus bridge FIFO, indicated by d_rsp_empty_n Low, the following occurs: ° Output port d_req_write is asserted with port d_req_din deasserted to indicate a read operation. ° The base address for the transfer and the size are output. ° The design stalls and waits for data to become available. • When data becomes available for reading the output signal, d_rsp_read is immediately asserted and data is read at the next N clock edges, where N is the value on output port size. • If the bus bridge FIFO runs empty of values, the data transfers stop immediately and wait until data is available before continuing. X-Ref Target - Figure 4-14 Figure 4-14: High-Level Synthesis UG902 (v2017.1) April 5, 2017 Behavior of ap_bus Interface: Burst Write www.xilinx.com Send Feedback 503 Chapter 4: High-Level Synthesis Reference Guide After reset, the following occurs: • After start, the block begins normal operation. • If a write must be performed but there is no space in the bus bridge FIFO, indicated by d_req_full_n Low, the following occurs: • • ° The base address, transfer size, and data are output. ° The design stalls and waits for space to become available. When space becomes available for writing, the following occurs: ° Output ports d_req_write and d_req_din are asserted to indicate a write operation. ° The output signal d_req_din is immediately asserted to indicate the data is valid at the next clock edge. ° Output signal d_req_din is immediately deasserted if the FIFO becomes full and reasserted when space is available. ° The transfer stops after N data values are transferred, where N is the value on the size output port. If a write must be performed and space is available in the bus bridge FIFO, indicated by d_rsp_full_n High, transfer begins and the design stalls and waits until the FIFO is full. axis The axis mode specifies an AXI4-Stream I/O protocol. For a complete description of the AXI4-Stream interface, including timing and ports, see the Vivado Design Suite AXI Reference Guide (UG1037) [Ref 8]. For information on using the full capabilities of this I/O protocol, see Using AXI4 Interfaces in Chapter 1. s_axilite The s_axilite mode specifies an AXI4-Lite slave I/O protocol. For a complete description of the AXI4-Lite slave interface, including timing and ports, see the Vivado Design Suite AXI Reference Guide (UG1037) [Ref 8]. For information on using the full capabilities of this I/O protocol, see Using AXI4 Interfaces in Chapter 1. m_axi The m_axi mode specifies an AXI4 master I/O protocol. For a complete description of the AXI4 master interface including timing and ports, see the Vivado Design Suite AXI Reference Guide (UG1037) [Ref 8]. For information on using the full capabilities of this I/O protocol, see Using AXI4 Interfaces in Chapter 1. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 504 Chapter 4: High-Level Synthesis Reference Guide AXI4-Lite Slave C Driver Reference When an AXI4-Lite slave interface is added to the design, a set of C driver files are automatically created. These C driver files provide a set of APIs that can be integrated into any software running on a CPU and used to communicate with the device using the AXI4-Lite interface. The API functions derive their name from the top-level function for synthesis. This reference section assumes the top-level function is called DUT. The following table lists each of the API function provided in the C driver files. Table 4-1: C Driver API Functions API Function Description XDut_Initialize This API will write value to InstancePtr which then can be used in other APIs. Xilinx recommends calling this API to initialize a device except when an MMU is used in the system. XDut_CfgInitialize Initialize a device configuration. When a MMU is used in the system, replace the base address in the XDut_Config variable with virtual base address before calling this function. Not for use on Linux systems. XDut_LookupConfig Used to obtain the configuration information of the device by ID. The configuration information contain the physical base address. Not for use on Linux. XDut_Release Release the uio device in linux. Delete the mappings by munmap: the mapping will automatically be deleted if the process terminated. Only for use on Linux systems. XDut_Start Start the device. This function will assert the ap_start port on the device. Available only if there is ap_start port on the device. XDut_IsDone Check if the device has finished the previous execution: this function will return the value of the ap_done port on the device. Available only if there is an ap_done port on the device. XDut_IsIdle Check if the device is in idle state: this function will return the value of the ap_idle port. Available only if there is an ap_idle port on the device. XDut_IsReady Check if the device is ready for the next input: this function will return the value of the ap_ready port. Available only if there is an ap_ready port on the device. XDut_Continue Assert port ap_continue. Available only if there is an ap_continue port on the device. XDut_EnableAutoRestart Enables “auto restart” on device. When this is set the device will automatically start the next transaction when the current transaction completes. XDut_DisableAutoRestart Disable the “auto restart” function. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 505 Chapter 4: High-Level Synthesis Reference Guide Table 4-1: C Driver API Functions (Cont’d) API Function Description XDut_Set_ARG Write a value to port ARG (a scalar argument of the top function). Available only if ARG is input port. XDut_Set_ARG_vld Assert port ARG_vld. Available only if ARG is an input port and implemented with an ap_hs or ap_vld interface protocol. XDut_Set_ARG_ack Assert port ARG_ack. Available only if ARG is an output port and implemented with an ap_hs or ap_ack interface protocol. XDut_Get_ARG Read a value from ARG. Only available if port ARG is an output port on the device. XDut_Get_ARg_vld Read a value from ARG_vld. Only available if port ARG is an output port on the device and implemented with an ap_hs or ap_vld interface protocol. XDut_Get_ARg_ack Read a value from ARG_ack. Only available if port ARG is an input port on the device and implemented with an ap_hs or ap_ack interface protocol. XDut_Get_ARG_BaseAddress Return the base address of the array inside the interface. Only available when ARG is an array grouped into the AXI4-Lite interface. XDut_Get_ARG_HighAddress Return the address of the uppermost element of the array. Only available when ARG is an array grouped into the AXI4-Lite interface. XDut_Get_ARG_TotalBytes Return the total number of bytes used to store the array. Only available when ARG is an array grouped into the AXI4-Lite interface. Note: If the elements in the array are less than 16-bit, Vivado HLS groups multiple elements into the 32-bit data width of the AXI4-Lite interface. If the bit width of the elements exceeds 32-bit, Vivado HLS stores each element over multiple consecutive addresses. XDut_Get_ARG_BitWidth Return the bit width of each element in the array. Only available when ARG is an array grouped into the AXI4-Lite interface. Note: If the elements in the array are less than 16-bit, Vivado HLS groups multiple elements into the 32-bit data width of the AXI4-Lite interface. If the bit width of the elements exceeds 32-bit, Vivado HLS stores each element over multiple consecutive addresses. XDut_Get_ARG_Depth Return the total number of elements in the array. Only available when ARG is an array grouped into the AXI4-Lite interface. Note: If the elements in the array are less than 16-bit, Vivado HLS groups multiple elements into the 32-bit data width of the AXI4-Lite interface. If the bit width of the elements exceeds 32-bit, Vivado HLS stores each element over multiple consecutive addresses. XDut_Write_ARG_Words High-Level Synthesis UG902 (v2017.1) April 5, 2017 Write the length of a 32-bit word into the specified address of the AXI4-Lite interface. This API requires the offset address from BaseAddress and the length of the data to be stored. Only available when ARG is an array grouped into the AXI4-Lite interface. www.xilinx.com Send Feedback 506 Chapter 4: High-Level Synthesis Reference Guide Table 4-1: C Driver API Functions (Cont’d) API Function Description XDut_Read_ARG_Words Read the length of a 32-bit word from the array. This API requires the data target, the offset address from BaseAddress, and the length of the data to be stored. Only available when ARG is an array grouped into the AXI4-Lite interface. XDut_Write_ARG_Bytes Write the length of bytes into the specified address of the AXI4-Lite interface. This API requires the offset address from BaseAddress and the length of the data to be stored. Only available when ARG is an array grouped into the AXI4-Lite interface. XDut_Read_ARG_Bytes Read the length of bytes from the array. This API requires the data target, the offset address from BaseAddress, and the length of data to be loaded. Only available when ARG is an array grouped into the AXI4-Lite interface. XDut_InterruptGlobalEnable Enable the interrupt output. Interrupt functions are available only if there is ap_start. XDut_InterruptGlobalDisable Disable the interrupt output. XDut_InterruptEnable Enable the interrupt source. There may be at most 2 interrupt sources (source 0 for ap_done and source 1 for ap_ready) XDut_InterruptDisable Disable the interrupt source. XDut_InterruptClear Clear the interrupt status. XDut_InterruptGetEnabled Check which interrupt sources are enabled. XDut_InterruptGetStatus Check which interrupt sources are triggered. The details on the API functions are provided below. XDut_Initialize Synopsis int XDut_Initialize(XDut *InstancePtr, u16 DeviceId); int XDut_Initialize(XDut *InstancePtr, const char* InstanceName); Description int XDut_Initialize(XDut *InstancePtr, u16 DeviceId): For use on standalone systems, initialize a device. This API will write a proper value to InstancePtr which then can be used in other APIs. Xilinx recommends calling this API to initialize a device except when an MMU is used in the system, in which case refer to function XDut_CfgInitialize. int XDut_Initialize(XDut *InstancePtr, const char* InstanceName): For use on Linux systems, initialize a specifically named uio device. Create up to 5 memory mappings and assign the slave base addresses by mmap, utilizing the uio device information in sysfs. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 507 Chapter 4: High-Level Synthesis Reference Guide • InstancePtr: A pointer to the device instance. • DeviceId: Device ID as defined in xparameters.h. • InstanceName: The name of the uio device. • Return: XST_SUCCESS indicates success, otherwise fail. XDut_CfgInitialize Synopsis XDut_CfgInitializeint XDut_CfgInitialize(XDut *InstancePtr, XDut_Config *ConfigPtr); Description Initialize a device when an MMU is used in the system. In such a case the effective address of the AXI4-Lite slave is different from that defined in xparameters.h and API is required to initialize the device. • InstancePtr: A pointer to the device instance. • DeviceId: A pointer to a XDut_Config. • Return: XST_SUCCESS indicates success, otherwise fail. XDut_LookupConfig Synopsis XDut_Config* XDut_LookupConfig(u16 DeviceId); Description This function is used to obtain the configuration information of the device by ID. • DeviceId: Device ID as defined in xparameters.h. • Return: A pointer to a XDut_LookupConfig variable that holds the configuration information of the device whose ID is DeviceId. NULL if no matching Deviceid is found. XDut_Release Synopsis int XDut_Release(XDut *InstancePtr); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 508 Chapter 4: High-Level Synthesis Reference Guide Description Release the uio device. Delete the mappings by munmap. (The mapping will automatically be deleted if the process terminated) • InstanceName: The name of the uio device. • Return: XST_SUCCESS indicates success, otherwise fail. XDut_Start Synopsis void XDut_Start(XDut *InstancePtr); Description Start the device. This function will assert the ap_start port on the device. Available only if there is ap_start port on the device. • InstancePtr: A pointer to the device instance. XDut_IsDone Synopsis void XDut_IsDone(XDut *InstancePtr); Description Check if the device has finished the previous execution: this function will return the value of the ap_done port on the device. Available only if there is an ap_done port on the device. • InstancePtr: A pointer to the device instance. XDut_IsIdle Synopsis void XDut_IsIdle(XDut *InstancePtr); Description Check if the device is in idle state: this function will return the value of the ap_idle port. Available only if there is an ap_idle port on the device. • InstancePtr: A pointer to the device instance. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 509 Chapter 4: High-Level Synthesis Reference Guide XDut_IsReady Synopsis void XDut_IsReady(XDut *InstancePtr); Description Check if the device is ready for the next input: this function will return the value of the ap_ready port. Available only if there is an ap_ready port on the device. • InstancePtr: A pointer to the device instance. XDut_Continue Synopsis void XExample_Continue(XExample *InstancePtr); Description Assert port ap_continue. Available only if there is an ap_continue port on the device. • InstancePtr: A pointer to the device instance. XDut_EnableAutoRestart Synopsis void XDut_EnableAutoRestart(XDut *InstancePtr); Description Enables “auto restart” on device. When this is enabled, • Port ap_start will be asserted as soon as ap_done is asserted by the device and the device will auto-start the next transaction. • Alternatively, if the block-level I/O protocol ap_ctrl_chain is implemented on the device, the next transaction will auto-restart (ap_start will be asserted) when ap_ready is asserted by the device and if ap_continue is asserted when ap_done is asserted by the device. Available only if there is an ap_start port. • InstancePtr: A pointer to the device instance. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 510 Chapter 4: High-Level Synthesis Reference Guide XDut_DisableAutoRestart Synopsis void XDut_DisableAutoRestart(XDut *InstancePtr); Description Disable the “auto restart” function. Available only if there is an ap_start port. • InstancePtr: A pointer to the device instance. XDut_Set_ARG Synopsis void XDut_Set_ARG(XDut *InstancePtr, u32 Data); Description Write a value to port ARG (a scalar argument of the top-level function). Available only if ARG is an input port. • InstancePtr: A pointer to the device instance. • Data: Value to write. XDut_Set_ARG_vld Synopsis void XDut_Set_ARG_vld(XDut *InstancePtr); Description Assert port ARG_vld. Available only if ARG is an input port and implemented with an ap_hs or ap_vld interface protocol. • InstancePtr: A pointer to the device instance. XDut_Set_ARG_ack Synopsis void XDut_Set_ARG_ack(XDut *InstancePtr); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 511 Chapter 4: High-Level Synthesis Reference Guide Description Assert port ARG_ack. Available only if ARG is an output port and implemented with an ap_hs or ap_ack interface protocol. • InstancePtr: A pointer to the device instance. XDut_Get_ARG Synopsis u32 XDut_Get_ARG(XDut *InstancePtr); Description Read a value from ARG. Only available if port ARG is an output port on the device. • InstancePtr: A pointer to the device instance. Return: Value of ARG. XDut_Get_ARG_vld Synopsis u32 XDut_Get_ARG_vld(XDut *InstancePtr); Description Read a value from ARG_vld. Only available if port ARG is an output port on the device and implemented with an ap_hs or ap_vld interface protocol. • InstancePtr: A pointer to the device instance. Return: Value of ARG_vld. XDut_Get_ARG_ack Synopsis u32 XDut_Get_ARG_ack(XDut *InstancePtr); Description Read a value from ARG_ack Only available if port ARG is an input port on the device and implemented with an ap_hs or ap_ack interface protocol. • InstancePtr: A pointer to the device instance. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 512 Chapter 4: High-Level Synthesis Reference Guide Return: Value of ARG_ack. XDut_Get_ARG_BaseAddress Synopsis u32 XDut_Get_ARG_BaseAddress(XDut *InstancePtr); Description Return the base address of the array inside the interface. Only available when ARG is an array grouped into the AXI4-Lite interface. • InstancePtr: A pointer to the device instance. Return: Base address of the array. XDut_Get_ARG_HighAddress Synopsis u32 XDut_Get_ARG_HighAddress(XDut *InstancePtr); Description Return the address of the uppermost element of the array. Only available when ARG is an array grouped into the AXI4-Lite interface. • InstancePtr: A pointer to the device instance. Return: Address of the uppermost element of the array. XDut_Get_ARG_TotalBytes Synopsis u32 XDut_Get_ARG_TotalBytes(XDut *InstancePtr); Description Return the total number of bytes used to store the array. Only available when ARG is an array grouped into the AXI4-Lite interface. Note: If the elements in the array are less than 16-bit, Vivado HLS groups multiple elements into the 32-bit data width of the AXI4-Lite interface. If the bit width of the elements exceeds 32-bit, Vivado HLS stores each element over multiple consecutive addresses. • InstancePtr: A pointer to the device instance. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 513 Chapter 4: High-Level Synthesis Reference Guide Return: The total number of bytes used to store the array. XDut_Get_ARG_BitWidth Synopsis u32 XDut_Get_ARG_BitWidth(XDut *InstancePtr); Description Return the bit width of each element in the array. Only available when ARG is an array grouped into the AXI4-Lite interface. Note: If the elements in the array are less than 16-bit, Vivado HLS groups multiple elements into the 32-bit data width of the AXI4-Lite interface. If the bit width of the elements exceeds 32-bit, Vivado HLS stores each element over multiple consecutive addresses. • InstancePtr: A pointer to the device instance. Return: The bit-width of each element in the array. XDut_Get_ARG_Depth Synopsis u32 XDut_Get_ARG_Depth(XDut *InstancePtr); Description Return the total number of elements in the array. Only available when ARG is an array grouped into the AXI4-Lite interface. Note: If the elements in the array are less than 16-bit, Vivado HLS groups multiple elements into the 32-bit data width of the AXI4-Lite interface. If the bit width of the elements exceeds 32-bit, Vivado HLS stores each element over multiple consecutive addresses. • InstancePtr: A pointer to the device instance. Return: The total number of elements in the array. XDut_Write_ARG_Words Synopsis u32 XDut_Write_ARG_Words(XDut *InstancePtr, int offset, int *data, int length); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 514 Chapter 4: High-Level Synthesis Reference Guide Description Write the length of a 32-bit word into the specified address of the AXI4-Lite interface. This API requires the offset address from BaseAddress and the length of the data to be stored. Only available when ARG is an array grouped into the AXI4-Lite interface. • InstancePtr: A pointer to the device instance. • offset: The address in the AXI4-Lite interface. • data: A pointer to the data value to be stored. • length: The length of the data to be stored. Return: Write length of data from the specified address. XDut_Read_ARG_Words Synopsis u32 XDut_Read_ARG_Words(XDut *InstancePtr, int offset, int *data, int length); Description Read the length of a 32-bit word from the array. This API requires the data target, the offset address from BaseAddress, and the length of the data to be stored. Only available when ARG is an array grouped into the AXI4-Lite interface. • InstancePtr: A pointer to the device instance. • offset: The address in the ARG. • data: A pointer to the data buffer. • length: The length of the data to be stored. Return: Read length of data from the specified address. XDut_Write_ARG_Bytes Synopsis u32 XDut_Write_ARG_Bytes(XDut *InstancePtr, int offset, char *data, int length); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 515 Chapter 4: High-Level Synthesis Reference Guide Description Write the length of bytes into the specified address of the AXI4-Lite interface. This API requires the offset address from BaseAddress and the length of the data to be stored. Only available when ARG is an array grouped into the AXI4-Lite interface. • InstancePtr: A pointer to the device instance. • offset: The address in the ARG. • data: A pointer to the data value to be stored. • length: The length of data to be stored. Return: Write length of data from the specified address. XDut_Read_ARG_Bytes Synopsis u32 XDut_Read_ARG_Bytes(XDut *InstancePtr, int offset, char *data, int length); Description Read the length of bytes from the array. This API requires the data target, the offset address from BaseAddress, and the length of data to be loaded. Only available when ARG is an array grouped into the AXI4-Lite interface. • InstancePtr: A pointer to the device instance. • offset: The address in the ARG. • data: A pointer to the data buffer. • length: The length of data to be loaded. Return: Read length of data from the specified address. XDut_InterruptGlobalEnable Synopsis void XDut_InterruptGlobalEnable(XDut *InstancePtr); Description Enable the interrupt output. Interrupt functions are available only if there is ap_start. • InstancePtr: A pointer to the device instance. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 516 Chapter 4: High-Level Synthesis Reference Guide XDut_InterruptGlobalDisable Synopsis void XDut_InterruptGlobalDisable(XDut *InstancePtr); Description Disable the interrupt output. • InstancePtr: A pointer to the device instance. XDut_InterruptEnable Synopsis void XDut_InterruptEnable(XDut *InstancePtr, u32 Mask); Description Enable the interrupt source. There may be at most 2 interrupt sources (source 0 for ap_done and source 1 for ap_ready). • InstancePtr: A pointer to the device instance. • Mask: Bit mask. ° Bit n = 1: enable interrupt source n. ° Bit n = 0: no change. XDut_InterruptDisable Synopsis void XDut_InterruptDisable(XDut *InstancePtr, u32 Mask); Description Disable the interrupt source. • InstancePtr: A pointer to the device instance. • Mask: Bit mask. ° Bit n = 1: disable interrupt source n. ° Bit n = 0: no change. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 517 Chapter 4: High-Level Synthesis Reference Guide XDut_InterruptClear Synopsis void XDut_InterruptClear(XDut *InstancePtr, u32 Mask); Description Clear the interrupt status. • InstancePtr: A pointer to the device instance. • Mask: Bit mask. ° Bit n = 1: toggle interrupt status n. ° Bit n = 0: no change. XDut_InterruptGetEnabled Synopsis u32 XDut_InterruptGetEnabled(XDut *InstancePtr); Description Check which interrupt sources are enabled. • InstancePtr: A pointer to the device instance. • Return: Bit mask. ° Bit n = 1: enabled. ° Bit n = 0: disabled. XDut_InterruptGetStatus Synopsis u32 XDut_InterruptGetStatus(XDut *InstancePtr); Description Check which interrupt sources are triggered. • InstancePtr: A pointer to the device instance. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 518 Chapter 4: High-Level Synthesis Reference Guide • Return: Bit mask. ° Bit n = 1: triggered. ° Bit n = 0: not triggered. HLS Video Functions Library This section explains the following Vivado HLS video functions. • OpenCV Interface Functions Converts data to and from the standard OpenCV data types to AXI4 streaming protocol. • AXI4-Stream I/O Functions Allows the AXI4 streaming protocol to be converted into the hsl::Mat data types used by the video processing functions. • Video Processing Functions Compatible with standard OpenCV functions for manipulating and processing video images. For more information and a complete methodology for working with the video functions in the context of an existing OpenCV design, see Accelerating OpenCV Applications with Zynq-7000 All Programmable SoC Using Vivado HLS Video Libraries (XAPP1167) [Ref 9]. OpenCV Interface Functions IplImage2AXIvideo Synopsis template void IplImage2AXIvideo ( IplImage* img, hls::stream >& AXI_video_strm); Parameters Table 4-2: Parameters Parameter Description img Input image header in OpenCV IplImage format AXI_video_strm Output AXI4 video stream in hls::stream format, compatible with AXI4-Stream protocol High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 519 Chapter 4: High-Level Synthesis Reference Guide Description • Converts data from OpenCV IplImage format to AXI4 video stream (hls::stream) format. • Image data must be stored in img. • AXI_video_strm must be empty before invoking. • The data width (in bits) of a pixel in img must be no greater than W, the data width of TDATA in AXI4-Stream protocol. AXIvideo2IplImage Synopsis template void AXIvideo2IplImage ( hls::stream >& AXI_video_strm, IplImage* img); Parameters Table 4-3: Parameters Parameter Description AXI_video_strm Input AXI4 video stream in hls::stream format, compatible with AXI4-Stream protocol img Output image header in OpenCV IplImage format Description • Converts data from AXI4 video stream (hls::stream) format to OpenCV IplImage format. • Image data must be stored in AXI_video_strm. • Invoking this function consumes the data in AXI_video_strm. • The data width of a pixel in img must be no greater than W, the data width of TDATA in AXI4-Stream protocol. cvMat2AXIvideo Synopsis template void cvMat2AXIvideo ( cv::Mat& cv_mat, hls::stream >& AXI_video_strm); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 520 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-4: Parameters Parameter Description cv_mat Input image in OpenCV cv::Mat format AXI_video_strm Output AXI4 video stream in hls::stream format, compatible with AXI4-Stream protocol Description • Converts data from OpenCV cv::Mat format to AXI4 video stream (hls::stream) format. • Image data must be stored in cv_mat. • AXI_video_strm must be empty before invoking. • The data width (in bits) of a pixel in cv_mat must be no greater than W, the data width of TDATA in AXI4-Stream protocol. AXIvideo2cvMat Synopsis template void AXIvideo2cvMat ( hls::stream >& AXI_video_strm, cv::Mat& cv_mat); Parameters • Converts data from AXI4 video stream (hls::stream) format to OpenCV cv::Mat format. • Image data must be stored in AXI_video_strm. • Invoking this function consumes the data in AXI_video_strm. • The data width of a pixel in cv_mat must be no greater than W, the data width of TDATA in AXI4-Stream protocol. Description • Converts data from OpenCV cv::Mat format to AXI4 video stream (hls::stream) format. • Image data must be stored in cv_mat. • AXI_video_strm must be empty before invoking. • The data width (in bits) of a pixel in cv_mat must be no greater than W, the data width of TDATA in AXI4-Stream protocol. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 521 Chapter 4: High-Level Synthesis Reference Guide CvMat2AXIvideo Synopsis template void CvMat2AXIvideo ( CvMat* cvmat, hls::stream >& AXI_video_strm); Parameters Table 4-5: Parameters Parameter Description cvmat Input image pointer to OpenCV CvMat format AXI_video_strm Output AXI4 video stream in hls::stream format, compatible with AXI4-Stream protocol Description • Converts data from OpenCV CvMat format to AXI4 video stream (hls::stream) format. • Image data must be stored in cvmat. • AXI_video_strm must be empty before invoking. • The data width (in bits) of a pixel in cvmat must be no greater than W, the data width of TDATA in AXI4-Stream protocol. AXIvideo2CvMat Synopsis template void AXIvideo2CvMat ( hls::stream >& AXI_video_strm, CvMat* cvmat); Parameters Table 4-6: Parameters Parameter Description AXI_video_strm Input AXI4 video stream in hls::stream format, compatible with AXI4-Stream protocol cvmat Output image pointer to OpenCV CvMat format Description • Converts data from AXI4 video stream (hls::stream) format to OpenCV CvMat format. • Image data must be stored in AXI_video_strm. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 522 Chapter 4: High-Level Synthesis Reference Guide • Invoking this function consumes the data in AXI_video_strm. • The data width of a pixel in cvmat must be no greater than W, the data width of TDATA in AXI4-Stream protocol. IplImage2hlsMat Synopsis template void IplImage2hlsMat ( IplImage* img, hls::Mat& mat); Parameters Table 4-7: Parameters Parameter Description img Input image header in OpenCV IplImage format mat Output image in hls::Mat format Description • Converts data from OpenCV IplImage format to hls::Mat format. • Image data must be stored in img. • mat must be empty before invoking. • Arguments img and mat must have the same size and number of channels. hlsMat2IplImage Synopsis template void hlsMat2IplImage ( hls::Mat& mat, IplImage* img); Parameters Table 4-8: Parameters Parameter Description mat Input image in hls::Mat format img Output image header in OpenCV IplImage format Description • Converts data from hls::Mat format to OpenCV IplImage format. • Image data must be stored in mat. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 523 Chapter 4: High-Level Synthesis Reference Guide • Invoking this function consumes the data in mat. • Arguments mat and img must have the same size and number of channels. cvMat2hlsMat Synopsis template void cvMat2hlsMat ( cv::Mat* cv_mat, hls::Mat& mat); Parameters Table 4-9: Parameters Parameter Description cv_mat Input image in OpenCV cv::Mat format mat Output image in hls::Mat format Description • Converts data from OpenCV cv::Mat format to hls::Mat format. • Image data must be stored in cv_mat. • mat must be empty before invoking. • Arguments cv_mat and mat must have the same size and number of channels. hlsMat2cvMat Synopsis template void hlsMat2cvMat ( hls::Mat& mat, cv::Mat& cv_mat); Parameters Table 4-10: Parameters Parameter Description mat Input image in hls::Mat format cv_mat Output image in OpenCV cv::Mat format Description • Converts data from hls::Mat format to OpenCV cv::Mat format. • Image data must be stored in mat. • Invoking this function consumes the data in mat. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 524 Chapter 4: High-Level Synthesis Reference Guide • Arguments mat and cv_mat must have the same size and number of channels. CvMat2hlsMat Synopsis template void CvMat2hlsMat ( CvMat* cvmat, hls::Mat& mat); Parameters Table 4-11: Parameters Parameter Description cvmat Input image pointer to OpenCV CvMat format mat Output image in hls::Mat format Description • Converts data from OpenCV CvMat format to hls::Mat format. • Image data must be stored in cvmat. • mat must be empty before invoking. • Arguments cvmat and mat must have the same size and number of channels. hlsMat2CvMat Synopsis template void hlsMat2CvMat ( hls::Mat& mat, CvMat* cvmat); Parameters Table 4-12: Parameters Parameter Description mat Input image in hls::Mat format cvmat Output image pointer in OpenCV cv::Mat format Description • Converts data from hls::Mat format to OpenCV CvMat format. • Image data must be stored in mat. • Invoking this function consumes the data in mat. • Arguments mat and cvmat must have the same size and number of channels. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 525 Chapter 4: High-Level Synthesis Reference Guide CvMat2hlsWindow Synopsis template void CvMat2hlsWindow ( CvMat* cvmat, hls::Window& window); Parameters Table 4-13: Parameters Parameter Description cvmat Input 2D window pointer to OpenCV CvMat format window Output 2D window in hls::Window format Description • Converts data from OpenCV CvMat format to hls::Window format. • Image data must be stored in cvmat. • window must be empty before invoking. • Arguments cvmat and window must be single-channel, and have the same size. This function is mainly for converting image processing kernels. hlsWindow2CvMat Synopsis template void hlsWindow2hlsCvMat ( hls::Window& window, CvMat* cvmat); Parameters Table 4-14: Parameters Parameter Description window Input 2D window in hls::Window format cvmat Output 2D window pointer to OpenCV CvMat format Description • Converts data from hls::Window format to OpenCV CvMat format. • Image data must be stored in window. • Invoking this function consumes the data in window. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 526 Chapter 4: High-Level Synthesis Reference Guide • Arguments mat and window must be single-channel, and have the same size. This function is mainly for converting image processing kernels. AXI4-Interface I/O Functions hls::Array2Mat Synopsis template int Array2Mat( FB_T fb[ROWS*FB_COLS], int rowStride, Mat& img) template int Array2Mat( FB_T fb[ROWS*FB_COLS], Mat& img) Parameters Table 4-15: Parameters Parameter Description FB Input array of image data. Mat Output image in hls::Mat format rowStride Specifies the row increment for reading the data. • The first line of video is read from fb[0] through fb[COLS-1]. • The second line of video is read from rb[rowStride] through fb[rowStride+COLS-1] If the rowStribe argument is not used, every row is read. Description • Converts image data stored in an array hls::Mat format to an image of hls::Mat format. The array may be: ° An array mapped to a BlockRAM or UltraRAM (useful for small images) ° An array mapped to an AXI4 interface (useful for large images) ° An array mapped to a stream (useful when integrating with DMA or other cores that implement non-AXI video streams, such as the AXI DMA) • Image data must be stored in FB. • The data field of mat must be empty before invoking. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 527 Chapter 4: High-Level Synthesis Reference Guide hls::Mat2Array Synopsis template int Mat2Array( Mat& img, FB_T fb[ROWS*FB_COLS], int rowStride) template int Mat2Array( Mat& img, FB_T fb[ROWS*FB_COLS]) Parameters Table 4-16: Parameters Parameter Description mat Input image in hls::Mat format FB Output array of image data rowStride Specifies the row increment for writing the data. • The first line of video is written to fb[0] through fb[COLS-1]. • The second line of video is written to rb[rowStride] through fb[rowStride+COLS-1] If the rowStribe argument is not used, every row is written to. Description • • Converts image data stored in hls::Mat format to an array. The array may be: ° An array mapped to a BlockRAM or UltraRAM (useful for small images) ° An array mapped to an AXI4 interface (useful for large images) ° An array mapped to a stream (useful when integrating with DMA or other cores that implement non-AXI video streams, such as the AXI DMA) Image data must be stored in mat. hls::AXIvideo2Mat Synopsis template int hls::AXIvideo2Mat ( hls::stream >& AXI_video_strm, hls::Mat& mat); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 528 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-17: Parameters Parameter Description AXI_video_strm Input AXI4 video stream in hls::stream format, compatible with AXI4-Stream protocol mat Output image in hls::Mat format Description • Converts image data stored in hls::Mat format to an AXI4 video stream (hls::stream) format. • Image data must be stored in AXI_video_strm. • The data field of mat must be empty before invoking. • Invoking this function consumes the data in AXI_video_strm and fills the image data of mat. • The data width of a pixel in mat must be no greater than W, the data width of TDATA in AXI4-Stream protocol. • This function is able to perform frame sync for the input video stream, by detecting the TUSER bit to mark the top-left pixel of an input frame. It returns a bit error of ERROR_IO_EOL_EARLY or ERROR_IO_EOL_LATE to indicate an unexpected line length, by detecting the TLAST input. hls::Mat2AXIvideo Synopsis template int hls::AXIvideo2Mat ( hls::Mat& mat, hls::stream >& AXI_video_strm); Parameters Table 4-18: Parameters Parameter Description mat Input image in hls::Mat format AXI_video_strm Output AXI4 video stream in hls::stream format, compatible with AXI4-Stream protocol Description • Converts image data stored in AXI4 video stream (hls::stream) format to an image of hls::Mat format. • Image data must be stored in mat. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 529 Chapter 4: High-Level Synthesis Reference Guide • The data field of AXI_video_strm must be empty before invoking. • Invoking this function consumes the data in mat and fills the image data of AXI_video_strm. • The data width of a pixel in mat must be no greater than W, the data width of TDATA in AXI4-Stream protocol. • To fill image data to AXI4 video stream, this function also sets TUSER bit of stream element for indicating the top-left pixel, as well as setting TLAST bit in the last pixel of each line to indicate the end of line. Video Processing Functions hls::AbsDiff Synopsis template void hls::AbsDiff ( hls::Mat& src1, hls::Mat& src2, hls::Mat& dst); Parameters Table 4-19: Parameters Parameter Description src1 First input image src2 Second input image dst Output image Description • Computes the absolute difference between two input images src1 and src2 and saves the result in dst. • Image data must be stored in src1 and src2. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src1 and src2 and fills the image data of dst. • src1 and src2 must have the same size and number of channels. • dst must have the same size and number of channels as the inputs. OpenCV Reference • cvAbsDiff High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 530 Chapter 4: High-Level Synthesis Reference Guide • cv::absdiff hls::AddS Synopsis Without Mask: template void hls::AddS ( hls::Mat& src, hls::Scalar& scl, hls::Mat& dst); With Mask: template void hls::AddS ( hls::Mat& src, hls::Scalar& scl, hls::Mat& dst, hls::Mat& mask, hls::Mat& dst_ref); Parameters Table 4-20: Parameters Parameter Description src Input image scl Input scalar dst Output image mask Operation mask, an 8-bit single channel image that specifies elements of the dst image to be computed. dst_ref Reference image that stores the elements for output image when mask(I) = 0 Description • Computes the per-element sum of an image src and a scalar scl. • Saves the result in dst. • If computed with mask: • Image data must be stored in src (if computed with mask, mask and dst_ref must have data stored), and the image data of dst must be empty before invoking. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 531 Chapter 4: High-Level Synthesis Reference Guide • Invoking this function consumes the data in src (if computed with mask. The data of mask and dst_ref are also consumed) and fills the image data of dst. • src and scl must have the same number of channels. dst and dst_ref must have the same size and number of channels as src. mask must have the same size as the src. OpenCV Reference • cvAddS • cv::add hls::AddWeighted Synopsis template void hls::AddWeighted ( hls::Mat& src1, P_T alpha, hls::Mat& src2, P_T beta, P_T gamma, hls::Mat& dst); Parameters Table 4-21: Parameters Parameter Description src1 First input image alpha Weight for the first image elements src2 Second input image beta Weight for the second image elements gamma Scalar added to each sum dst Output image Description • Computes the weighted per-element sum of two image src1 and src2. • Saves the result in dst. • The weighted sum computes as follows: • Image data must be stored in src1 and src2. • The image data of dst must be empty before invoking. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 532 Chapter 4: High-Level Synthesis Reference Guide • Invoking this function consumes the data in src1 and src2 and fills the image data of dst. • The three parameters (alpha, beta and gamma) must have the same datatypes. • src1 and src2 must have the same size and number of channels. • dst must have the same size and number of channels as the inputs. OpenCV Reference • cvAddWeighted • cv::addWeighted hls::And Synopsis Without Mask: template void hls::And ( hls::Mat& src1, hls::Mat& src2, hls::Mat& dst); With Mask: template void hls::And ( hls::Mat& src1, hls::Mat& src2, hls::Mat& dst, hls::Mat& mask, hls::Mat& dst_ref); Parameters Table 4-22: Parameters Parameter Description src1 First input image src2 Second input scalar dst Output image mask Operation mask, an 8-bit single channel image that specifies elements of the dst image to be computed dst_ref Reference image that stores the elements for output image when mask(I) = 0 High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 533 Chapter 4: High-Level Synthesis Reference Guide Description • Calculates the per-element bitwise logical conjunction of two images src1 and src2 • Returns the result as image dst. • If computed with mask: • Image data must be stored in src1 and src2. • The image data of dst must be empty before invoking. • If computed with mask, mask and dst_ref must have data stored. • Invoking this function: ° Consumes the data in src1 and src2 Note: If computed with mask, the data of mask and dst_ref are also consumed. ° Fills the image data of dst. • src1 and src2 must have the same size and number of channels. • dst and dst_ref must have the same size and number of channels as the inputs. • mask must have the same size as the inputs. OpenCV Reference • cvAnd, • cv::bitwise_and hls::Avg Synopsis Without Mask: template hls::Scalar hls::Avg( hls::Mat& src); With Mask: template hls::Scalar hls::Avg( hls::Mat& src, hls::Mat& mask); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 534 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-23: Parameters Parameter Description src Input image mask Operation mask, an 8-bit single channel image that specifies elements of the src image to be computed Description • Calculates an average of elements in image src. • Returns the result in hls::Scalar format. • If computed with mask: • Image data must be stored in src. • If computed with mask, mask must have data stored. • Invoking this function consumes the data in src. • If computed with mask, the data of mask is also consumed). • src and mask must have the same size. • mask must have non-zero element. OpenCV Reference • cvAvg • cv::mean hls::AvgSdv Synopsis Without Mask: template void hls::AvgSdv( hls::Mat& src, hls::Scalar& avg, hls::Scalar& sdv); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 535 Chapter 4: High-Level Synthesis Reference Guide With Mask: template void hls::AvgSdv( hls::Mat& src, hls::Scalar& avg, hls::Scalar& sdv, hls::Mat& mask); Parameters Table 4-24: Parameters Parameter Description src Input image avg Output scalar of computed mean value sdv Output scalar of computed standard deviation mask Operation mask, an 8-bit single channel image that specifies elements of the src image to be computed Description • Calculates an average of elements in image src. • Returns the result in hls::Scalar format. • If computed with mask: • Image data must be stored in src. • If computed with mask, mask must have data stored. • Invoking this function consumes the data in src. • If computed with mask, the data of mask is also consumed. • Arguments src and mask must have the same size. • mask must have a non-zero element. OpenCV Reference • cvAvgSdv • cv::meanStdDev High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 536 Chapter 4: High-Level Synthesis Reference Guide hls::Cmp Synopsis template void hls::Cmp ( hls::Mat& src1, hls::Mat& src2, hls::Mat& dst, int cmp_op); Parameters Table 4-25: Parameters Parameter Description src1 Returns first input image src2 Returns second input image dst Returns the output 8returnsbit single channel image cmp_op Returns the flag specifying the relation between the elements to be checked HLS_CMP_EQ Equal to HLS_CMP_GT Greater than HLS_CMP_GE Greater or equal HLS_CMP_LT Less than HLS_CMP_LE Less or equal HLS_CMP_NE Not equal Description • Performs the per-element comparison of two input images src1 and src2. • Saves the result in dst. • If the comparison result is true, the corresponding element of dst is set to 255. Otherwise, it is set to 0. • Image data must be stored in src1 and src2. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src1 and src2 and fills the image data of dst. • src1 and src2 must have the same size and number of channels. • dst must have the same size and number of channels as the inputs. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 537 Chapter 4: High-Level Synthesis Reference Guide OpenCV Reference • cvCmp • cv::compare hls::CmpS Synopsis template void hls::CmpS ( hls::Mat& src, P_T value, hls::Mat& dst, int cmp_op); Parameters Table 4-26: Parameters Parameter Description src Input image value Input scalar value dst Output 8-bit single channel image cmp_op Flag that specifies the relation between the elements to be checked HLS_CMP_EQ Equal to HLS_CMP_GT Greater than HLS_CMP_GE Greater or equal HLS_CMP_LT Less than HLS_CMP_LE Less or equal HLS_CMP_NE Not equal Description • Performs the comparison between the elements of input images src and the input value and saves the result in dst. • If the comparison result is true, the corresponding element of dst is set to 255. Otherwise it is set to 0. • Image data must be stored in src. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src and fills the image data of dst. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 538 Chapter 4: High-Level Synthesis Reference Guide • src and dst must have the same size and number of channels. OpenCV Reference • cvCmpS • cv::compare hls::CornerHarris Synopsis template void CornerHarris( hls::Mat &_src, hls::Mat &_dst, KT k); Parameters Table 4-27: Parameters Parameter Description src Input image dst Output mask of detected corners k Harris detector parameter borderType How borders are handled Description • This function implements a Harris edge/corner detector. The horizontal and vertical derivatives are estimated using a Ksize*Ksize Sobel filter. The local covariance matrix M of the derivatives is smoothed over a blockSize*blockSize neighborhood of each pixel (x,y). This function outputs the function. • Only Ksize=3 or Ksize=5 is supported. OpenCV Reference • cvCornerHarris • cv::cornerHarris High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 539 Chapter 4: High-Level Synthesis Reference Guide hls::CvtColor Synopsis template void hls::CvtColor ( hls::Mat& src, hls::Mat& dst); Parameters Table 4-28: Parameters Parameter Description src Input image dst Output image code Template parameter of type of color conversion Description • Converts a color image from or to a grayscale image. The type of conversion is defined by the value of code: ° HLS_RGB2GRAY converts a RGB color image to a grayscale image. ° HLS_BGR2GRAY converts a BGR color image to a grayscale image. ° HLS_GRAY2RGB converts a grayscale image to a RGB image. ° HLS_GRAY2BGR converts a grayscale image to BRG color image. ° HLS_RGB2XYZ converts an RGB color image to XYZ color image. ° HLS_BGR2XYZ converts an BRG color image to XYZ color image. ° HLS_XYZ2RGB converts an XYZ color image to RGB color image. ° HLS_XYZ2BGR converts an XYZ color image to BGR color image. ° HLS_RGB2YCrCb converts an RGB color image to YCbCr color image. ° HLS_BGR2YCrCb converts an BRG color image to YCbCr color image. ° HLS_YCrCb2RGB converts an YCbCr color image to RGB color image. ° HLS_YCrCb2BGR converts an YCbCr color image to BGR color image. ° HLS_RGB2HSV converts an RGB color image to HSV color image. ° HLS_BGR2HSV converts an BRG color image to HSV color image. ° HLS_HSV2RGB converts an HSV color image to RGB color image. ° HLS_HSV2BGR converts an HSV color image to BGR color image. ° HLS_RGB2HLS converts an RGB color image to HLS color image. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 540 Chapter 4: High-Level Synthesis Reference Guide ° HLS_BGR2HLS converts an BRG color image to HLS color image. ° HLS_HLS2RGB converts an HLS color image to RGB color image. ° HLS_HLS2BGR converts an HLS color image to BGR color image. • Image data must be stored in src. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src and fills the image data of dst. • src and dst must have the same size and required number of channels. OpenCV Reference • cvCvtColor • cv::cvtColor hls::Dilate Synopsis Default: template void hls::Dilate ( hls::Mat& src, hls::Mat& dst); Custom: template void hls::Dilate ( hls::Mat& src, hls::Mat& dst, hls::Window & kernel); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 541 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-29: Parameters Parameter Description src Input image dst Output image kernel Rectangle of structuring element used for dilation, defined by hls::Window class. Position of the anchor within the element is at (K_ROWS/2, K_COLS/2). A 3x3 rectangular structuring element is used by default. Shape_type Shape of structuring element HLS_SHAPE_RECT Rectangular structuring element HLS_SHAPE_CROSS Cross-shaped structuring element, cross point is at anchor HLS_SHAPE_ELLIPSE Elliptic structuring element, a filled ellipse inscribed into the rectangular element ITERATIONS Number of times dilation is applied Description • Dilates the image src using the specified structuring element constructed within the kernel. • Saves the result in dst. • The dilation determines the shape of a pixel neighborhood over which the maximum is taken. • Each channel of image src is processed independently. • Image data must be stored in src. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src and fills the image data of dst. • src and dst must have the same size and number of channels. OpenCV Reference • cvDilate • cv::dilate High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 542 Chapter 4: High-Level Synthesis Reference Guide hls::Duplicate Synopsis template void hls::Duplicate ( hls::Mat& src, hls::Mat& dst1, hls::Mat& dst2); Parameters Table 4-30: Parameters Parameter Description src Input image dst1 First output image dst2 Second output image Description • Copies the input image src to two output images dst1 and dst2, for divergent point of two datapaths. • Image data must be stored in src. • The image data of dst1 and dst2 must be empty before invoking. • Invoking this function consumes the data in src and fills the image data of dst1 and dst2. • src, dst1, and dst2 must have the same size and number of channels. OpenCV Reference Not applicable. hls::EqualizeHist Synopsis template void EqualizeHist( Mat&_src, Mat&_dst); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 543 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-31: Parameters Parameter Description src Input image dst Output image Description • Computes a histogram of each frame and uses it to normalize the range of the following frame. • The delay avoids the use of a frame buffer in the implementation. • The histogram is stored as static data internal to this function, allowing only one call to EqualizeHist to be made. • The input is expected to have type HLS_8UC1. OpenCV Reference • cvEqualizeHist • cv::EqualizeHist hls::Erode Synopsis Default: template void hls::Erode ( hls::Mat& src, hls::Mat& dst); Custom: template void Erode( hls::Mat&_src, hls::Mat&_dst, hls::Window&_kernel) { High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 544 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-32: Parameters Parameter Description src Input image dst Output image kernel Rectangle of structuring element used for dilation, defined by hls::Window class. Position of the anchor within the element is at (K_ROWS/2, K_COLS/2). A 3x3 rectangular structuring element is used by default. Shape_type Shape of structuring element HLS_SHAPE_RECT Rectangular structuring element HLS_SHAPE_CROSS Cross-shaped structuring element, cross point is at anchor HLS_SHAPE_ELLIPSE Elliptic structuring element, a filled ellipse inscribed into the rectangle element ITERATIONS Number of times erosion is applied Description • Erodes the image src using the specified structuring element constructed within kernel. • Saves the result in dst. • The erosion determines the shape of a pixel neighborhood over which the maximum is taken, each channel of image src is processed independently: • Image data must be stored in src. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src and fills the image data of dst. • src and dst must have the same size and number of channels. OpenCV Reference • cvErode • cv::erode High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 545 Chapter 4: High-Level Synthesis Reference Guide hls::FASTX Synopsis template void FASTX( hls::Mat &_src, hls::Mat &_mask, int _threshold, bool _nomax_supression); template void FASTX( hls::Mat &_src, Point_ (&_keypoints)[N], int _threshold, bool _nomax_supression); Parameters Table 4-33: Parameters Parameter Description src Input image mask Output image with value 255 where corners are detected keypoints Array of the coordinates of detected corners threshold FAST detector threshold. If a pixel differs from the center pixel of the window by more than this threshold, then it is either a light or a dark pixel. nomax_supression If true, then enable suppression of non-maximal edges Description • Implements the FAST corner detector, generating either a mask of corners, or an array of coordinates. OpenCV Reference • cvFAST • cv::FASTX High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 546 Chapter 4: High-Level Synthesis Reference Guide hls::Filter2D Synopsis template void Filter2D( Mat&_src, Mat &_dst, Window&_kernel, Point_anchor) template void Filter2D( Mat&_src, Mat &_dst, Window&_kernel, Point_anchor); Parameters Table 4-34: Parameters Parameter Description src Input image dst Output image kernel Kernel of 2D filtering, defined by hls::Window class anchor Anchor of the kernel that indicates that the relative position of a filtered point within the kernel Description • Applies an arbitrary linear filter to the image src using the specified kernel. • Saves the result to image dst. • This function filters the image by computing correlation using kernel: • Image data must be stored in src. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src and fills the image data of dst. • src and dst must have the same size and number of channels. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 547 Chapter 4: High-Level Synthesis Reference Guide OpenCV Reference The function can be used with or without border modes. Usage: hls::Filter2D<3,3,BORDER_CONSTANT>(src,dst) hls::Filter2D<3,3>(src,dst) • cv::filter2D • cvFilter2D (see the note below in the discussion of border modes) If no border mode is selected, the default mode BORDER_DEFAULT is used. The selection for the border modes are: • BORDER_CONSTANT: The input is extended with zeros. • BORDER_REPLICATE: The input is extended at the boundary with the boundary value. Given the series of pixels “abcde” the boundary value at the border is completed as “abcdeeee”. • BORDER_REFLECT: The input is extended at the boundary with the edge pixel duplicated. Given the series of pixels “abcde” the boundary value at the border is completed as “abcdeedc”. • BORDER_REFLECT_101: The input is extended at the boundary with the edge pixel not duplicated. Given the series of pixels “abcde” the boundary value at the border is completed as “abcdedcb”. • BORDER_DEFAULT: Same as BORDER_REFLECT_101. Note: For compatibility with OpenCV function cvFilter2D use the BORDER_REPLICATE mode. hls::FindStereoCorrespondenceBM Synopsis template void FindStereoCorrespondenceBM( Mat& left, Mat& right, Mat& disp, StereoBMState& state) High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 548 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-35: Parameters Parameter Description Left 8-bit image. left right Right image of the same size and type as the left image disp Output disparity map. It has the same size as the input images. state Stereo BM state Description • Computes disparity using the Block Matching algorithm for a rectified stereo pair. OpenCV Reference • cvFindStereoCorrespondenceBM • cv::FindStereoCorrespondenceBM hls::GaussianBlur Synopsis template void GaussianBlur( Mat &_src, Mat &_dst, double sigmaX=0, double sigmaY=0); template void GaussianBlur( hls::Mat &_src, hls::Mat &_dst); double sigmaX=0, double sigmaY=0); Parameters Table 4-36: Parameters Parameter Description src Input image dst Output image Description • Applies a normalized 2D Gaussian Blur filter to the input. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 549 Chapter 4: High-Level Synthesis Reference Guide • The filter coefficients are determined by the KH and KW parameters, which must either be 3 or 5. • The 3x3 filter taps are given by: [1,2,1 2,4,2 1,2,1] * 1/16 • The 5x5 filter taps are given by: [1, 2, 3, 2, 1, 2, 5, 6, 5, 2, 3, 6, 8, 6, 3, 2, 5, 6, 5, 2, 1, 2, 3, 2, 1]* 1/84 OpenCV Reference Usage: hls::GaussianBlur<3,3,BORDER_CONSTANT>(src,dst) hls::GaussianBlur<3,3>(src,dst) • cv::GaussianBlur If no border mode is selected, the default mode BORDER_DEFAULT is used. The selection for the border modes are: • BORDER_CONSTANT: The input is extended with zeros. • BORDER_REPLICATE: The input is extended at the boundary with the boundary value. Given the series of pixels “abcde” the boundary value the border is completed as “abcdeeee”. • BORDER_REFLECT: The input is extended at the boundary with the edge pixel duplicated. Given the series of pixels “abcde” the boundary value the border is completed as “abcdeedc”. • BORDER_REFLECT_101: The input is extended at the boundary with the edge pixel not duplicated. Given the series of pixels “abcde” the boundary value the border is completed as “abcdedcb”. • BORDER_DEFAULT: Same as BORDER_REFLECT_101. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 550 Chapter 4: High-Level Synthesis Reference Guide hls::Harris Synopsis template void Harris( hls::Mat &_src, hls::Mat &_dst, KT k, int threshold); Parameters Table 4-37: Parameters Parameter Description src Input image dst Output mask of detected corners k Harris detector parameter threshold Threshold for maximum finding Description • This function implements a Harris edge or corner detector. • The horizontal and vertical derivatives are estimated using a Ksize*Ksize Sobel filter. • The local covariance matrix M of the derivatives is smoothed over a blockSize*blockSize neighborhood of each pixel (x,y). • Points where the function has a maximum, and is greater than the threshold are marked as corners/edges in the output image. • Only Ksize=3 is supported. OpenCV Reference • cvCornerHarris • cv::cornerHarris hls::HoughLines2 Synopsis template struct Polar_ High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 551 Chapter 4: High-Level Synthesis Reference Guide AT angle; RT rho; }; template void HoughLines2( hls::Mat &_src, Polar_ (&_lines)[linesMax], unsigned int threshold ); Parameters Table 4-38: Parameters Parameter Description src Input image lines Array of parameterized lines, given in polar coordinates threshold Number of pixels that must land on a line before it is returned Description • Implements the Hough line transform. OpenCV Reference • cvHoughLines2 • cv::HoughLines hls::Integral Synopsis template void Integral( Mat&_src, Mat&_sum); template void Integral( Mat&_src, Mat&_sum, Mat&_sqsum); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 552 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-39: Parameters Parameter Description src Input image sum Sum of pixels in the input image above and to the left of the pixel sqsum Sum of the squares of pixels in the input image above and to the left of the pixel Description • Implements the computation of an integral image. OpenCV Reference • cvIntegral • cv::integral hls::InitUndistortRectifyMap Synopsis template< typename CMT, typename RT, typename DT, int ROW, int COL, int MAP1_T, int MAP2_T, int N> void InitUndistortRectifyMap( Window<3,3, CMT> cameraMatrix, DT (&distCoeffs)[N], Window<3,3, RT> R, Window<3,3, CMT> newcameraMatrix, Mat &map1, Mat &map2); template< typename CMT, typename RT, typename DT, int ROW, int COL, int MAP1_T, int MAP2_T, int N> void InitUndistortRectifyMapInverse( Window<3,3, CMT> cameraMatrix, DT (&distCoeffs)[N], Window<3,3, ICMT> ir Mat &map1, Mat &map2); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 553 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-40: Parameters Parameter Description cameraMatrix Input matrix representing the camera in the old coordinate system DT Input distortion coefficients (Generally 4, 5, or 8 distortion coefficients are provided) R Input rotation matrix newCameraMatrix Input matrix representing the camera in the new coordinate system ir Input transformation matrix, equal to Invert(newcameraMatrix*R) map1, map2 Images representing the remapping Description • Generates map1 and map2, based on a set of parameters, where map1 and map2 are suitable inputs for hls::Remap(). • In general, InitUndistortRectifyMapInverse() is preferred for synthesis, because the per-frame processing to compute ir is performed outside of the synthesized logic. The various parameters may be floating point or fixed-point. If fixed-point inputs are used, then internal coordinate transformations are done with at least the precision given by ICMT. • As the coordinate transformations implemented in this function can be hardware resource intensive, it may be preferable to compute the results of this function offline and store map1 and map2 in external memory if the input parameters are fixed and sufficient external memory bandwidth is available. Limitations map1 and map2 are only supported as HLS_16SC2. cameraMatrix, and newCameraMatrix, are normalized in the sense that their form is: [f_x,0,c_x, 0,f_y,c_y, 0,0,1] High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 554 Chapter 4: High-Level Synthesis Reference Guide R and ir are also normalized with the form: [a,b,c, d,e,f, 0,0,1] OpenCV Reference • cv::initUndistortRectifyMap hls::Max Synopsis template void hls::Max ( hls::Mat& src1, hls::Mat& src2, hls::Mat& dst); Parameters Table 4-41: Parameters Parameter Description src1 First input image src2 Second input image dst Output image Description • Calculates per-element maximum of two input images src1 and src2 and saves the result in dst. • Image data must be stored in src1 and src2. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src1 and src2 and fills the image data of dst. • src1 and src2 must have the same size and number of channels. dst must have the same size and number of channels as the inputs. OpenCV Reference • cvMax • cv::max High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 555 Chapter 4: High-Level Synthesis Reference Guide hls::MaxS Synopsis template void hls::MaxS ( hls::Mat& src, P_T value, hls::Mat& dst); Parameters Table 4-42: Parameters Parameter Description src Input image value Input scalar value dst Output image Description • Calculates the maximum between the elements of input images src and the input value and saves the result in dst. • Image data must be stored in src. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src and fills the image data of dst. • src and dst must have the same size and number of channels. OpenCV Reference • cvMaxS • cv::max hls::Mean Synopsis Without Mask: template DST_T hls::Mean( hls::Mat& src); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 556 Chapter 4: High-Level Synthesis Reference Guide With Mask: template DST_T hls::Mean( hls::Mat& src, hls::Mat& mask); Parameters Table 4-43: Parameters Parameter Description src Input image mask Operation mask, an 8-bit single channel image that specifies elements of the src image to be computed Description • Calculates an average of elements in image src, and return the value of first channel of result scalar. • If computed with mask: • Image data must be stored in src (if computed with mask, mask must have data stored). • Invoking this function consumes the data in src (if computes with mask. The data of mask is also consumed). • src and mask must have the same size. mask must have non-zero element. OpenCV Reference • cvMean • cv::mean High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 557 Chapter 4: High-Level Synthesis Reference Guide hls::Merge Synopsis Input of two single-channel images: template void hls::Merge ( hls::Mat& src0, hls::Mat& src1, hls::Mat& dst); Input of three single-channel images: template void hls::Merge ( hls::Mat& src0, hls::Mat& src1, hls::Mat& src2, hls::Mat& dst); Input of four single-channel images: template void hls::Merge ( hls::Mat& src0, hls::Mat& src1, hls::Mat& src2, hls::Mat& src3, hls::Mat& dst); Parameters Table 4-44: Parameters Parameter Description src0 First single-channel input image src1 Second single channel input image src2 Third single channel input image src3 Fourth single channel input image dst Output multichannel image High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 558 Chapter 4: High-Level Synthesis Reference Guide Description • Composes a multichannel image dst from several single-channel images. • Image data must be stored in input images. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in inputs and fills the image data of dst. • Input images must have the same size and be single-channel. dst must have the same size as the inputs, the number of channels of dst must equal to the number of input images. OpenCV Reference • cvMerge • cv::merge hls::Min Synopsis template void hls::Min ( hls::Mat& src1, hls::Mat& src2, hls::Mat& dst); Parameters Table 4-45: Parameters Parameter Description src1 First input image src2 Second input image dst Output image Description • Calculates per-element minimum of two input images src1 and src2 and saves the result in dst. • Image data must be stored in src1 and src2. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src1 and src2 and fills the image data of dst. • src1 and src2 must have the same size and number of channels. • dst must have the same size and number of channels as the inputs. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 559 Chapter 4: High-Level Synthesis Reference Guide OpenCV Reference • cvMin • cv::min hls::MinMaxLoc Synopsis Without Mask: template void hls::MinMaxLoc ( hls::Mat& src, P_T* min_val, P_T* max_val, hls::Point& min_loc, hls::Point& max_loc); With Mask: template void hls::MinMaxLoc ( hls::Mat& src, P_T* min_val, P_T* max_val, hls::Point& min_loc, hls::Point& max_loc, hls::Mat& mask); Parameters Table 4-46: Parameters Parameter Description src Input image min_val Pointer to the output minimum value max_val Pointer to the output maximum value min_loc Output point of minimum location in input image max_loc Output point of maximum location in input image mask Operation mask, an 8-bit single channel image that specifies elements of the src image to be found Description • Finds the global minimum and maximum and their locations in input image src. • Image data must be stored in src (if computed with mask, mask must have data stored). High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 560 Chapter 4: High-Level Synthesis Reference Guide • Invoking this function consumes the data in src (if computed with mask. The data of mask is also consumed). • min_val and max_val must have the save data type. src and mask must have the same size. OpenCV Reference • cvMinMaxLoc • cv::minMaxLoc hls::MinS Synopsis template void hls::MinS ( hls::Mat& src, P_T value, hls::Mat& dst); Parameters Table 4-47: Parameters Parameter Description src Input image value Input scalar value dst Output image Description • Calculates the minimum between the elements of input images src and the input value and saves the result in dst. • Image data must be stored in src. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src and fills the image data of dst. • src and dst must have the same size and number of channels. OpenCV Reference • cvMinS • cv::min High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 561 Chapter 4: High-Level Synthesis Reference Guide hls::Mul Synopsis template void hls::Mul ( hls::Mat& src1, hls::Mat& src2, hls::Mat& dst, P_T scale=1); Parameters Table 4-48: Parameters Parameter Description src1 First input image src2 Second input image dst Output image scale Optional scale factor Description • Calculates the per-element product of two input images src1 and src2. • Saves the result in image dst. An optional scaling factor scale can be used. • Image data must be stored in src1 and src2. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src1 and src2 and fills the image data of dst. • src1 and src2 must have the same size and number of channels. • dst must have the same size and number of channels as the inputs. OpenCV Reference • cvMul • cv::multiply High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 562 Chapter 4: High-Level Synthesis Reference Guide hls::Not Synopsis template void hls::Not ( hls::Mat& src, hls::Mat& dst); Parameters Table 4-49: Parameters Parameter Description src Input image dst Output image Description • Performs per-element bitwise inversion of image src. • Outputs the result as image dst. • Image data must be stored in src. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src and fills the image data of dst. • src and dst must have the same size and number of channels. OpenCV Reference • cvNot • cv::bitwise_not hls::PaintMask Synopsis template void PaintMask( hls::Mat &_src, hls::Mat &_mask, hls::Mat &_dst, hls::Scalar _color); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 563 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-50: Parameters Parameter Description src Input image mask Input mask dst Output image color Color for marking Description • Each pixel of the destination image is either set to color (if mask is not zero) or the corresponding pixel from the input image. • src, mask, and dst must all be the same size. hls::PyrDown Synopsis template void PyrDown( Mat &_src, Mat &_dst) Parameters Table 4-51: Parameters Parameter Description src Input image dst Output image Description • Blurs an image by performing the Gaussian pyramid construction and then downsizes the image by a factor of 2. • First, this function convolves the source image with the following kernel: [1, 4, 6, 4, 1, 4, 16, 24, 16, 2, 6, 24, 36, 24, 6, 4, 16, 24, 16, 2, 1, 4, 6, 4, 1]* 1/256 High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 564 Chapter 4: High-Level Synthesis Reference Guide • Then, this function downsamples the image by rejecting even rows and columns. OpenCV Reference • cvPyrDown • cv::pyrDown hls::PyrUp Synopsis template void PyrUp( Mat &_src, Mat &_dst) Parameters Table 4-52: Parameters Parameter Description src Input image dst Output image Description • Upsamples the image by a factor of 2 and then blurs it. • The function performs the upsampling step of the Gaussian pyramid construction, though it can actually be used to construct the Laplacian pyramid. • First, this function upsamples the source image by injecting even zero rows and columns. • Then, this function convolves the result with the following kernel (same as in pyrDown() but multiplied by 4). [1, 4, 6, 4, 1, 4, 16, 24, 16, 4, 6, 24, 36, 24, 6, 4, 16, 24, 16, 4, 1, 4, 6, 4, 1]* 1/64 High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 565 Chapter 4: High-Level Synthesis Reference Guide OpenCV Reference • cvPyrUp • cv::pyrup hls::Range Synopsis template void hls::Range ( hls::Mat& src, hls::Mat& dst, P_T start, P_T end); Parameters Table 4-53: Parameters Parameter Description src Input single-channel image dst Output single-channel image start Left boundary value of the range end Right boundary value of the range Description • Sets all value in image src by the following rule and return the result as image dst. • Image data must be stored in src. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src and fills the image data of dst. • src and dst must have the same size and be single-channel images. OpenCV Reference • cvRange High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 566 Chapter 4: High-Level Synthesis Reference Guide hls::Remap Synopsis template void Remap( hls::Mat &src, hls::Mat &dst, hls::Mat &map1, hls::Mat &map2); Parameters Table 4-54: Parameters Parameter Description src Input image dst Output image • map1 Remapping • map2 Description • Remaps the source image src to the destination image dst according to the given remapping. For each pixel in the output image, the coordinates of an input pixel are specified by map1 and map2. • This function is designed for streaming operation for cameras with small vertical disparity. It contains an internal linebuffer to enable the remapping that contains WIN_ROW rows of the input image. If the row r_i of an input pixel corresponding to an output pixel at row r_o is not in the range [r_o-(WIN_ROW/2-1], r_o+(WIN_ROW/2-1) then the output is black. • In addition, because of the architecture of the line buffer, the function uses fewer resources if WIN_ROW and COL are powers of 2. OpenCV Reference • cvRemap High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 567 Chapter 4: High-Level Synthesis Reference Guide hls::Reduce Synopsis template void hls::Reduce ( hls::Mat& src, hls::Mat& dst, int dim, int reduce_op=HLS_REDUCE_SUM); Parameters Table 4-55: Parameters Parameter Description src Input matrix dst Output vector dim Dimension index along which the matrix is reduced. 0 means that the matrix is reduced to a single row. 1 means that the matrix is reduced to a single column. reduce_op Reduction operation: • HLS_REDUCE_SUM: Output is the sum of all of the matrix rows/columns • HLS_REDUCE_AVG: Output is the mean vector of all of the matrix rows/columns • HLS_REDUCE_MAX: Output is the maximum (column/row-wise) of all of the matrix rows/columns • HLS_REDUCE_MIN: Output is the minimum (column/row-wise) of all of the matrix rows/columns Description • Reduces 2D image src along dimension dim to a vector dst. • Image data must be stored in src. • The data of dst must be empty before invoking. • Invoking this function consumes the data in src and fills the image data of dst. OpenCV Reference • cvReduce, • cv::reduce High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 568 Chapter 4: High-Level Synthesis Reference Guide hls::Resize Synopsis template void Resize ( Mat &_src, Mat &_dst); Parameters Table 4-56: Parameters Parameter Description src Input image dst Output image Description • Resizes the input image to the size of the output image using bilinear interpolation. OpenCV Reference • cvResize • cv::resize hls::Set Synopsis Sets src image: template void hls::Set ( hls::Mat& src, hls::Scalar scl, hls::Mat& dst); Generates dst image: template void hls::Set ( hls::Scalar scl, hls::Mat& dst); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 569 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-57: Parameters Parameter Description src Input image scl Scale value to be set dst Output image Description • Sets elements in image src to a given scalar value scl. • Saves the result as image dst. • Generates a dst image with all element has scalar value scl if no input image. • Image data must be stored in src. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src and fills the image data of dst. • src and scl must have the same number of channels. • dst must have the same size and number of channels as src. OpenCV Reference • cvSet hls::Scale Synopsis template void hls::Scale ( hls::Mat& src, hls::Mat& dst, P_T scale=1.0, P_T shift=0.0); Parameters Table 4-58: Parameters Parameter Description src Input image dst Output image scale Value of scale factor shift Value added to the scaled elements High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 570 Chapter 4: High-Level Synthesis Reference Guide Description • Converts an input image src with optional linear transformation. • Saves the result as image dst. • Image data must be stored in src. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src and fills the image data of dst. • src and dst must have the same size and number of channels. scale and shift must have the same data types. OpenCV Reference • cvScale • cvConvertScale hls::Sobel Synopsis template void Sobel ( Mat&_src, Mat&_dst) template void Sobel ( Mat&_src, Mat&_dst) Parameters Table 4-59: Parameters Parameter Description src Input image dst Output image High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 571 Chapter 4: High-Level Synthesis Reference Guide Description • Computes a horizontal or vertical Sobel filter, returning an estimate of the horizontal or vertical derivative, using a filter such as: [-1,0,1 -2,0,2, -1,0,1] • SIZE=3, 5, or 7 is supported. This is the same as the equivalent OpenCV function. • Only XORDER=1 and YORDER=0 (corresponding to horizontal derivative) or XORDER=0 and YORDER=1 (corresponding to a vertical derivative) are supported. OpenCV Reference The function can be used with or without border modes. Usage: hls::Sobel<1,0,3,BORDER_CONSTANT>(src,dst) hls::Sobel<1,0,3>(src,dst) • cv::Sobel • cvSobel (see the note below in the discussion of border modes). If no border mode is selected, the default mode BORDER_DEFAULT is used. The selection for the border modes are: • BORDER_CONSTANT: The input is extended with zeros. • BORDER_REPLICATE: The input is extended at the boundary with the boundary value. Given the series of pixels “abcde” the boundary value the border is completed as “abcdeeee”. • BORDER_REFLECT: The input is extended at the boundary with the edge pixel duplicated. Given the series of pixels “abcde” the boundary value the border is completed as “abcdeedc” • BORDER_REFLECT_101: The input is extended at the boundary with the edge pixel not duplicated. Given the series of pixels “abcde” the boundary value the border is completed as “abcdedcb”. • BORDER_DEFAULT: Same as BORDER_REFLECT_101. Note: For compatibility with OpenCV function cvSobel, use the BORDER_REPLICATE mode. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 572 Chapter 4: High-Level Synthesis Reference Guide hls::Split Synopsis Input image has 2 channels: template void hls::Split ( hls::Mat& src, hls::Mat& dst0, hls::Mat& dst1); Input image has 3 channels: template void hls::Split ( hls::Mat& src, hls::Mat& dst0, hls::Mat& dst1, hls::Mat& dst2); Input image has 4 channels: template void hls::Split ( hls::Mat& src, hls::Mat& dst0, hls::Mat& dst1, hls::Mat& dst2, hls::Mat& dst3); Parameters Table 4-60: Parameters Parameter Description src Input multichannel image dst0 First single channel output image dst1 Second single channel output image dst2 Third single channel output image dst3 Fourth single channel output image Description • Divides a multichannel image src from several single-channel images. • Image data must be stored in image src. • The image data of outputs must be empty before invoking. • Invoking this function consumes the data in src and fills the image data of outputs. • Output images must have the same size and be single-channel. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 573 Chapter 4: High-Level Synthesis Reference Guide • src must have the same size as the outputs. • The number of channels of src must equal to the number of output images. OpenCV Reference • cvSplit • cv::split hls::SubRS Synopsis Without Mask: template void hls::SubRS ( hls::Mat& src, hls::Scalar& scl, hls::Mat& dst); With Mask: template void hls::SubRS ( hls::Mat& src, hls::Scalar& scl, hls::Mat& dst, hls::Mat& mask, hls::Mat& dst_ref); Parameters Table 4-61: Parameters Parameter Description src Input image scl Input scalar dst Output image mask Operation mask, an 8-bit single channel image that specifies elements of the dst image to be computed dst_ref Reference image that stores the elements for output image when mask(I) = 0 Description • Computes the differences between scalar value scl and elements of image src. • Saves the result in dst. • If computed with mask: High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 574 Chapter 4: High-Level Synthesis Reference Guide • Image data must be stored in src. • If computed with mask, mask and dst_ref must have data stored. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src. • If computed with mask, the data of mask and dst_ref are also consumed and fills the image data of dst. • src and scl must have the same number of channels. dst and dst_ref must have the same size and number of channels as src. mask must have the same size as the src. OpenCV Reference • cvSubRS • cv::subtract hls::SubS Synopsis Without Mask: template void hls::SubRS ( hls::Mat& src, hls::Scalar& scl, hls::Mat& dst); With Mask: template void hls::SubRS ( hls::Mat& src, hls::Scalar& scl, hls::Mat& dst, hls::Mat& mask, hls::Mat& dst_ref); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 575 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-62: Parameters Parameter Description src Input image scl Input scalar dst Output image mask Operation mask, an 8-bit single channel image that specifies elements of the dst image to be computed dst_ref Reference image that stores the elements for output image when mask(I) = 0 Description • Computes the differences between elements of image src and scalar value scl. • Saves the result in dst. If computed with mask: • Image data must be stored in src. • If computed with mask, mask and dst_ref must have data stored. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src and fills the image data of dst. • If computed with mask, the data of mask and dst_ref are also consumed. • src and scl must have the same number of channels. • dst and dst_ref must have the same size and number of channels as src OpenCV Reference • cvSub • cv::subtract hls::Sum Synopsis template hls::Scalar hls::Sum( hls::Mat& src); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 576 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-63: Parameters Parameter Description src Input image Description • Sums the elements of an image src. • Returns the result as a scalar value. • Image data must be stored in src • Invoking this function consumes the data in src OpenCV Reference • cvSum • cv::sum hls::Threshold Synopsis template void hls::Threshold ( hls::Mat& src, hls::Mat& dst, P_T thresh, P_T maxval, int thresh_type); Parameters Table 4-64: Parameters Parameter Description src Input single-channel image dst Output single-channel image thresh Threshold value maxval Maximum value to use with some threshold types thresh_type Threshold type. See details in description. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 577 Chapter 4: High-Level Synthesis Reference Guide Description Performs a fixed-level threshold to each element in a single-channel image src and return the result as a single-channel image dst. The thresholding type supported by this function are determined by thresh_type: HLS_THRESH_BINARY HLS_THRESH_BINARY_INV HLS_THRESH_TRUNC HLS_THRESH_TOZERO HLS_THRESH_TOZERO_INV • Image data must be stored in (if computed with src). • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src and fills the image data of dst. • src and dst must have the same size and be single-channel images. thresh and maxval must have the same data types. OpenCV Reference • cvThreshold • cv::threshold High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 578 Chapter 4: High-Level Synthesis Reference Guide hls::Zero Synopsis Set (if computed with image): template void hls::Zero ( hls::Mat& src, hls::Mat& dst); Generate dst image: template void hls::Zero ( hls::Mat& dst); Parameters Table 4-65: Parameters Parameter Description src Input image dst Output image Description • Sets elements in image src to 0. • Saves the result as image dst. • Generates a dst image with all element 0 if no input image. • Image data must be stored in src. • The image data of dst must be empty before invoking. • Invoking this function consumes the data in src and fills the image data of dst. • dst must have the same size and number of channels as src. OpenCV Reference • cvSetZero • cvZero High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 579 Chapter 4: High-Level Synthesis Reference Guide HLS Linear Algebra Library Functions This section explains the Vivado HLS linear algebra processing functions. matrix_multiply Synopsis template< class TransposeFormA, class TransposeFormB, int RowsA, int ColsA, int RowsB, int ColsB, int RowsC, int ColsC, typename InputType, typename OutputType> void matrix_multiply( const InputType A[RowsA][ColsA], const InputType B[RowsB][ColsB], OutputType C[RowsC][ColsC]); Description C=AB • Computes the product of two matrices, returning a third matrix. • Optional transposition (and conjugate transposition for complex data types) of input matrices. • Alternative architecture provided for unrolled floating-point implementations. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 580 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-66: Parameters Parameter Description TransposeFormA Transpose requirement for matrix A; NoTranspose, Transpose, ConjugateTranspose. TransposeFormB Transpose requirement for matrix B; NoTranspose, Transpose, ConjugateTranspose. RowsA Number of rows in matrix A ColsA Number of columns in matrix A RowsB Number of rows in matrix B ColsB Number of columns in matrix B RowsC Number of rows in matrix C ColsC Number of columns in matrix C InputType Input data type OutputType Output data type The function will throw an assertion and fail to compile, or synthesize, if ColsA != RowsB. The transpose requirements for A and B are resolved before check is made. Arguments Table 4-67: Arguments Argument Description A First input matrix B Second input matrix C AB product output matrix Return Values • Not applicable (void function) Supported Data Types • ap_fixed • float • x_complex • x_complex High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 581 Chapter 4: High-Level Synthesis Reference Guide Input Data Assumptions • For floating point types, subnormal input values are not supported. If used, the synthesized hardware will flush these to zero, and behavior will differ versus software simulation. cholesky Synopsis template< bool LowerTriangularL, int RowsColsA, typename InputType, typename OutputType> int cholesky( const InputType A[RowsColsA][RowsColsA], OutputType L[RowsColsA][RowsColsA]) Description A=LL* • Computes the Cholesky decomposition of input matrix A, returning matrix L. • Output matrix L may be upper triangular or lower triangular based on parameter LowerTriangularL. • Elements in the unused portion of matrix L are set to zero. Parameters Table 4-68: Parameters Parameter Description RowsColsA Row and column dimension of input and output matrices LowerTriangularL Selects whether lower triangular or upper triangular output is desired InputType Input data type OutputType Output data type Arguments Table 4-69: Arguments Argument Description A Hermitian/symmetric positive definite input matrix L Lower or upper triangular output matrix High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 582 Chapter 4: High-Level Synthesis Reference Guide Return Values • 0 = success • 1 = failure. The function attempted to find the square root of a negative number, that is, the input matrix A was not Hermitian/symmetric positive definite. Supported Data Types • ap_fixed • float • x_complex • x_complex Input Data Assumptions • The function assumes that the input matrix is symmetric positive definite (Hermitian positive definite for complex-valued inputs). • For floating point types, subnormal input values are not supported. If used, the synthesized hardware will flush these to zero, and behavior will differ versus software simulation. qrf Synopsis template< bool TransposeQ, int RowsA, int ColsA, typename InputType, typename OutputType> void qrf( const InputType A[RowsA][ColsA], OutputType Q[RowsA][RowsA], OutputType R[RowsA][ColsA]) Description A=QR • Computes the full QR factorization (QR decomposition) of input matrix A, producing orthogonal output matrix Q and upper-triangular matrix R. • Output matrix Q may be optionally transposed based on parameter TransposeQ. • Lower triangular elements of output matrix R are not zeroed. • The thin (also known as economy) QR decomposition is not implemented. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 583 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-70: Parameters Parameter Description TransposeQ Selects whether Q matrix should be transposed or not. RowsA Number of rows in input matrix A ColsA Number of columns in input matrix A InputType Input data type OutputType Output data type • The function will fail to compile, or synthesize, if RowsA < ColsA. Arguments Table 4-71: Arguments Argument Description A Input matrix Q Orthogonal output matrix R Upper triangular output matrix Return Values • Not applicable (void function) Supported Data Types • float • x_complex Input Data Assumptions • For floating point types, subnormal input values are not supported. If used, the synthesized hardware will flush these to zero, and behavior will differ versus software simulation. cholesky_inverse Synopsis template < int RowsColsA, typename InputType, typename OutputType> void cholesky_inverse(const InputType A[RowsColsA][RowsColsA], OutputType InverseA[RowsColsA][RowsColsA], int& cholesky_success) High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 584 Chapter 4: High-Level Synthesis Reference Guide Description AA-1 = I • Computes the inverse of symmetric positive definite input matrix A by the Cholesky decomposition method, producing matrix InverseA. Parameters Table 4-72: Parameters Parameter Description RowsColsA Row and column dimension of input and output matrices InputType Input data type OutputType Output data type Arguments Table 4-73: Arguments Argument Description A Square Hermitian/symmetric positive definite input matrix InverseA Inverse of input matrix cholesky_success 0 = success 1 = failure. The Cholesky function attempted to find the square root of a negative number. The input matrix A was not symmetric positive definite. Return Values • Not applicable (void function) Supported Data Types • ap_fixed • float • x_complex • x_complex Input Data Assumptions • The function assumes that the input matrix is symmetric positive definite (Hermitian positive definite for complex-valued inputs). High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 585 Chapter 4: High-Level Synthesis Reference Guide • For floating point types, subnormal input values are not supported. If used, the synthesized hardware will flush these to zero, and behavior will differ versus software simulation. qr_inverse Synopsis template < int RowsColsA, typename InputType, typename OutputType> void qr_inverse(const InputType A[RowsColsA][RowsColsA], OutputType InverseA[RowsColsA][RowsColsA], int& A_singular) Description AA-1=I • Computes the inverse of input matrix A by the QR factorization method, producing matrix InverseA. Parameters Table 4-74: Parameters Parameter Description RowsColsA Row and column dimension of input and output matrices. InputType Input data type OutputType Output data type Arguments Table 4-75: Arguments Argument Description A Input matrix A InverseA Inverse of input matrix A_singular 0 = success 1 = matrix A is singular Return Values • Not applicable (void function) High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 586 Chapter 4: High-Level Synthesis Reference Guide Supported Data Types • float • x_complex Input Data Assumptions • For floating point types, subnormal input values are not supported. If used, the synthesized hardware will flush these to zero, and behavior will differ versus software simulation. svd Synopsis template< int RowsA, int ColsA, typename InputType, typename OutputType> void svd( const InputType A[RowsA][ColsA], OutputType S[RowsA][ColsA], OutputType U[RowsA][RowsA], OutputType V[ColsA][ColsA]) Description A=USV* • Computes the singular value decomposition of input matrix A, producing matrices U, S and V. • Supports only square matrix. • Implemented using the iterative two-sided Jacobi method. Parameters Table 4-76: Parameters Parameter • Description RowsA Row dimension ColsA Column dimension InputType Input data type OutputType Output data type The function will throw an assertion and fail to compile, or synthesize, if RowsA != ColsA. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 587 Chapter 4: High-Level Synthesis Reference Guide Arguments Table 4-77: Arguments Argument Description A Input matrix S Singular values of input matrix U Left singular vectors of input matrix V Right singular vectors of input matrix Return Values • Not applicable (void function) Supported Data Types • float • x_complex Input Data Assumptions • For floating point types, subnormal input values are not supported. If used, the synthesized hardware will flush these to zero, and behavior will differ versus software simulation. Examples The examples provide a basic test-bench and demonstrate how to parameterize and instantiate each Linear Algebra function. One or more examples for each function are available in the Vivado HLS examples directory: /examples/design/linear_algebra Each example contains the following files: • .cpp: Top-level synthesis wrapper instantiating the library function. • .h: Header file defining matrix size, data type and, where applicable, architecture selection. • _tb.cpp: Basic test-bench instantiating top-level synthesis wrapper. • run_hls.tcl: Tcl commands to set up the example Vivado HLS project: vivado_hls -f run_hls.tcl • directives.tcl: (Optional) Additional Tcl commands applying optimization/implementation directives. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 588 Chapter 4: High-Level Synthesis Reference Guide HLS DSP Library Functions The HLS DSP library contains building block functions for DSP system modeling in C++ with an emphasis on functions used in SDR applications. HLS DSP Functions This section explains the Vivado HLS DSP processing functions. awgn Synopsis template< int OutputWidth> class awgn { public: typedef ap_ufixed<8,4, AP_RND, AP_SAT> t_ input_scale; static const int LFSR_SECTION_WIDTH = 32; static const int NUM_NOISE_GENS = 4; static const int LFSR_WIDTH = LFSR_SECTION_WIDTH*NUM_NOISE_GENS; void awgn(ap_uint seed); void ~awgn(); void operator()(t_input_scale &snr, ap_int &noise); Description • Outputs Gaussian noise of a magnitude determined by input signal-to-noise ratio (SNR). 0 dB for a BPSK signal results in a bit error rate (BER) of approximately 7%. This is because for Eb/N0 = 0, Eb = 1, but N0 / 2 = noise power for a BPSK channel, resulting in noise variance half that of the signal variance. For more information, see the AWGN page (www.mathworks.com/help/comm/ug/awgn-channel.html) on the MathWorks website. • The SNR input represents signal-to-noise ratio in decibels in the range [0.0 to 16.0) in steps of 1/16 of a decibel. • If the noise value exceeds that which can be described by the configuration, it saturates at the maximum positive or negative value appropriately. • The function uses multiple individual noise generators that are summed, which takes advantage of the central limit theorem, to create the output value. By default, these multiple generators are pipelined and unrolled, because the expected target application is for high-rate BER testing where a high clock rate and therefore, an Initiation Interval of 1 is expected. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 589 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-78: Parameters Template Parameter OutputWidth Description The number of bits in the output value. The SNR specifies the magnitude of noise relative to a soft BPSK signal with values 01000… and 11000… Range 8 to 32 bits. Table 4-79: Constructor Argument Argument seed Description The seed value for the LFSRs within the noise generators. Note: Parameters are checked during C simulation to verify that the template parameter configuration is legal. Arguments Table 4-80: Arguments Argument Description snr Signal-to-noise ratio input noise Output noise Return Values • Not applicable (void function) Supported Base Data Types • Input ° ap_ufixed See definition of typedef t_ input_scale in header file hls_awgn.h for details. • Output ° ap_int Input Data Assumptions • None High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 590 Chapter 4: High-Level Synthesis Reference Guide qam_mod Synopsis template< class Constellation, int OutputWidth> class qam_mod { public: typedef ap_int t_outcomponent; typedef std::complex< t_outcomponent > t_iq; void qam_mod(); void ~qam_mod(); void operator()(const typename Constellation::t_symbol &symbol, t_iq &outputdata); Description • Converts an input symbol (one of four values for QPSK, one of sixteen for QAM16, or one of sixty-four for QAM64) into an output value in complex form with I and Q components each of OutputWidth bits. • Where OutputWidth is greater than the minimum required to describe the I and Q values, and zeros are concatenated to the least significant bits until the output word is OutputWidth wide, for example, symbol 0 of QPSK output to 8 bits is I = Q = 01100000. Parameters Table 4-81: Parameters Template Parameter Description Constellation The selection of QAM type. One of QPSK, QAM4 (same as QPSK), QAM16, or QAM64. Essentially this is the selection of bits per symbol. OutputWidth Describes the number of bits in each component of the output value, for example, a value of 8 gives an 8-bit real and 8-bit imaginary value. Note: Parameters are checked during C simulation to verify that the template parameter configuration is legal. Arguments Table 4-82: Arguments Argument Description symbol Input symbol data outputData Modulated output data Return Values • Not applicable (void function) High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 591 Chapter 4: High-Level Synthesis Reference Guide Supported Base Data Types • Input ° ap_uint See definition of classes QPSK, QAM4, QAM16 and QAM64 in utils/hls_dsp_common_utils.h for details. • Output ° std::complex< ap_int > Input Data Assumptions • None qam_demod Synopsis template< Class Constellation, int InputWidth> class qam_demod { public: typedef ap_int t_incomponent; typedef std::complex< t_incomponent > t_in; void qam_demod(); void ~qam_demod(); void operator()(const t_in &inputData, typename Constellation::t_symbol &symbol); Description • Accepts an input of complex type with I and Q components each of InputWidth, matches this to the nearest point in the QAM type selected, and outputs the corresponding symbol value of that point in the constellation. • The output is a hard-decision. Parameters Table 4-83: Parameters Template Parameter Description Constellation One of QPSK, QAM4 (same as QPSK), QAM16, or QAM64. InputWidth Describes the number of bits in each component of the input value, for example, a value of 8 gives an 8-bit real and 8-bit imaginary value. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 592 Chapter 4: High-Level Synthesis Reference Guide Note: Parameters are checked during C simulation to verify that the template parameter configuration is legal. Arguments Table 4-84: Arguments Argument Description inputData Modulated input data symbol Demodulated output symbol Return Values • Not applicable (void function) Supported Base Data Types • Input ° • std::complex< ap_int > Output ° ap_uint See definition of classes QPSK, QAM4, QAM16, and QAM64 in utils/hls_dsp_common_utils.h for details. Input Data Assumptions • None High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 593 Chapter 4: High-Level Synthesis Reference Guide nco Synopsis template< int AccumWidth, int PhaseAngleWidth, int SuperSampleRate, int OutputWidth, class DualOutputCmpyImpl, class SingleOutputCmpyImpl, class SingleOutputNegCmpyImpl> class nco { public: void nco(const ap_uint InitPinc, const ap_uint InitPoff); void ~nco(); void operator()( stream< ap_uint > &pinc, stream< ap_uint > &poff, stream< t_nco_output_data > &outputData ); Description • Performs a numerically controlled oscillator (NCO) function. • Supports super sample rate (SSR), where the sample rate exceeds the clock rate, so multiple parallel data samples must be output on each clock cycle. • When in SSR mode, a change to phase increment (pinc) prompts an internal interrupt. This does not cause a disturbance to the output samples unless two or more changes to pinc occur less than N cycles apart where N is SuperSampleRate/2 +1. Parameters Table 4-85: Parameters Template Parameter Description AccumWidth Number of bits in the phase accumulator. This determines the precision of the frequency that can be synthesized. Range 4 to 48. PhaseAngleWidth Number of bits used in the sin/cos lookup directly. Larger values give more accurate output at the expense of lookup table size. Range 4 to 16. SuperSampleRate Number of output samples per clock cycle. Range 1 to 16. OutputWidth Width of each output (sine and cosine). Range 4 to 32. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 594 Chapter 4: High-Level Synthesis Reference Guide Table 4-85: Parameters (Cont’d) Template Parameter Description DualOutputCmpyImpl Select whether to implement dual-output complex multipliers with 5-multiplier (5 DSP48) or 4-multiplier (6 DSP48) architecture using classes NcoDualOutputCmpyFiveMult or NcoDualOutputCmpyFourMult. See hls_nco.h for details. SingleOutputCmpyImpl Select whether to implement single-output complex multipliers with 3-multiplier (3 DSP48) or 4-multiplier (4 DSP48) architecture using classes NcoSingleOutputCmpyThreeMult or NcoSingleOutputCmpyFourMult. See hls_nco.h for details. SingleOutputNegCmpyImpl Select whether to implement single-output negated complex multipliers with 3-multiplier (3 DSP48) or 4-multiplier (4 DSP48) architecture using classes NcoSingleOutputCmpyThreeMult or NcoSingleOutputCmpyFourMult. See hls_nco.h for details. Note: Parameters are checked during C simulation to verify that the template parameter configuration is legal. Arguments Table 4-86: Arguments Argument Description pinc Pinc is Phase Increment. The phase of the output advances by pinc/2AccumWidth *2π each sample. poff Poff is Phase Offset. This is added to the accumulated phase. The phase of the output is offset by poff/2 AccumWidth *2π . outputData Sine and cosine output. The magnitude of the output components is approximately cos(ϕ )*2OutputWidth-1 and sin(ϕ)*2 OutputWidth-1, where ϕ is the phase described by the phase accumulator, appropriately offset by poff. Return Values • Not applicable (void function) High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 595 Chapter 4: High-Level Synthesis Reference Guide Supported Base Data Types • Input ° • ap_uint Output ° std::complex< ap_int > See definition of struct t_nco_output_data in hls_nco.h for details. Input Data Assumptions • None convolution_encoder Synopsis template< int OutputWidth, bool Punctured, bool DualOutput, int InputRate, int OutputRate, int ConstraintLength, int PunctureCode0, int PunctureCode1, int ConvolutionCode0, int ConvolutionCode1, int ConvolutionCode2, int ConvolutionCode3, int ConvolutionCode4, int ConvolutionCode5, int ConvolutionCode6> class convolution_encoder { public: convolution_encoder(); ~convolution_encoder(); void operator()(stream< ap_uint<1> > &inputData, stream< ap_uint > &outputData); Description • Performs convolutional encoding of an input data stream based on user-defined convolution codes and constraint length • Optional puncturing of data • Optional dual channel output High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 596 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-87: Parameters Template Parameter Description OutputWidth Defines number of bits in the output bus. 1 bit when Punctured=true and DualOutput=false, 2 bits when DualOutput=true, else OutputRate bits. Punctured When true, enables puncturing of data. DualOutput When true, enables dual outputs with punctured data. InputRate Defines numerator of code rate. OutputRate Defines denominator of code rate. ConstraintLength The constraint length, K, is the number of registers in the encoder plus one. PunctureCode0 When Punctured=true, puncture code for output 0. Length (in binary) must equal the puncture input rate. Total number of 1s in both PunctureCode parameters equals the output rate. PunctureCode1 When Punctured=true, puncture code for output 1. Length (in binary) must equal the puncture input rate. Total number of 1s in both PunctureCode parameters equals the output rate. ConvolutionCode0 Convolution code for rates 1/2 to 1/7. Length (in binary) for all convolution codes (if used) must equal the constraint length value. ConvolutionCode1 Convolution code for rates 1/2 to 1/7. ConvolutionCode2 Convolution code for rates 1/3 to 1/7. ConvolutionCode3 Convolution code for rates 1/4 to 1/7. ConvolutionCode4 Convolution code for rates 1/5 to 1/7. ConvolutionCode5 Convolution code for rates 1/6 to 1/7. ConvolutionCode6 Convolution code for rate 1/7. Note: Parameters are checked during C simulation to verify that the template parameter configuration is legal. Arguments Table 4-88: Arguments Argument Description inputData Single-bit data stream to be encoded. outputData Encoded data stream. OutputRate-bits wide unless Punctured=true (1-bit wide) or DualOutput=true (2-bits wide). High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 597 Chapter 4: High-Level Synthesis Reference Guide Return Values • Not applicable (void function) Supported Base Data Types • ap_uint Input Data Assumptions • None viterbi_decoder Synopsis template< int ConstraintLength, int TracebackLength, bool HasEraseInput, bool SoftData, int InputDataWidth, int SoftDataFormat, int OutputRate, int ConvolutionCode0, int ConvolutionCode1, int ConvolutionCode2, int ConvolutionCode3, int ConvolutionCode4, int ConvolutionCode5, int ConvolutionCode6> class viterbi_decoder { public: viterbi_decoder(); ~viterbi_decoder(); void operator()(stream< viterbi_decoder_input > &inputData, stream< ap_uint<1> > &outputData) Description • Performs Viterbi decoding of a convolutionally encoded data stream • Supports hard or soft data • Supports offset binary and signed magnitude soft data formats • Supports erasures (puncturing) High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 598 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-89: Parameters Template Parameter Description ConstraintLength The constraint length, K. Supported range is 3 to 9. TracebackLength Number of states to trace back through the trellis during decoding. Use at least 6x ConstraintLength, or at least 12x ConstraintLength for punctured codes. HasEraseInput When true, an Erase input is present on the core to flag erasures (null symbols) in a punctured code. SoftData When true, the function accepts soft (multi-bit) input data. InputDataWidth Specifies width of the input data. Set to 1 for hard data and 3-5 for soft data. SoftDataFormat Specifies soft data formatting. 0 -> Signed Magnitude, 1 -> Offset Binary. OutputRate Specifies output rate of the matching convolution encoder. Determines number of inputs buses for decoder. ConvolutionCode0 Convolution code for rates 1/2 to 1/7. Length (in binary) for all convolution codes (if used) must equal the constraint length value. ConvolutionCode1 Convolution code for rates 1/2 to 1/7. ConvolutionCode2 Convolution code for rates 1/3 to 1/7. ConvolutionCode3 Convolution code for rates 1/4 to 1/7. ConvolutionCode4 Convolution code for rates 1/5 to 1/7. ConvolutionCode5 Convolution code for rates 1/6 to 1/7. ConvolutionCode6 Convolution code for rate 1/7. Note: Parameters are checked during C simulation to verify that the template parameter configuration is legal. Arguments Table 4-90: Arguments Argument Description inputData Convolution-encoded data stream with accompanying Erase signals if a punctured code is used. Data bus is OutputRate*InputDataWidth-bits wide. Erase bus is OutputRate bits wide. outputData Decoded single-bit data stream. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 599 Chapter 4: High-Level Synthesis Reference Guide Return Values • Not applicable (void function) Supported Base Data Types • Input ° ap_uint See definition of struct viterbi_decoder_input in hls_viterbi_decoder.h for details. • Output ° ap_uint Input Data Assumptions • None atan2 Synopsis template < int PhaseFormat, int InputWidth, int OutputWidth, int RoundMode> void atan2(const typename atan2_input::cartesian &x, typename atan2_output::phase &atanX) Description • CORDIC-based fixed-point implementation of two-argument arctangent • Configurable input and output widths • Configurable phase format • Configurable rounding mode High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 600 Chapter 4: High-Level Synthesis Reference Guide Parameters Table 4-91: Parameters Template Parameter Description PhaseFormat Selects whether the phase is expressed in radians or scaled radians (π * 1 radian). InputWidth Defines overall input data width. OutputWidth Defines overall output data width. RoundMode Selects the rounding mode to apply to the output data: 0=Truncate 1=Round-to-positive-infinity 2=Round-to-positive-and-negative-infinity 3=Round-to-nearest-even Note: Parameters are checked during C simulation to verify that the template parameter configuration is legal. Arguments Table 4-92: Arguments Argument Description x Input data with two integer bits and InputWidth-2 fractional bits in the range [-1,1]. atanX Four quadrant arctangent of x with three integer bits and OutputWidth-3 fractional bits in the range [-1,1]. Return Values • Not applicable (void function) Supported Base Data Types • Input ° std::complex< ap_fixed > See definitions of struct cordic_inputs in hls_cordic_functions.h and struct atan2_input in hls_atan2_cordic.h for details. • Output ° ap_fixed See definitions of struct cordic_outputs in hls_cordic_functions.h and struct atan2_output in hls_atan2_cordic.h for details. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 601 Chapter 4: High-Level Synthesis Reference Guide Input Data Assumptions • None sqrt Synopsis template < int DataFormat, int InputWidth, int OutputWidth, int RoundMode> void sqrt(const typename sqrt_input::in &x, typename sqrt_output::out &sqrtX) Description • CORDIC-based fixed-point implementation of square root • Unsigned fractional or unsigned integer data formats supported • Configurable rounding mode Parameters Table 4-93: Parameters Template Parameter Description DataFormat Selects between unsigned fraction (with integer width of 1 bit) and unsigned integer formats. InputWidth Defines overall input data width. OutputWidth Defines overall output data width. RoundMode Selects the rounding mode to apply to the output data: 0=Truncate 1=Round-to-positive-infinity 2=round-to-positive-and-negative-infinity 3=Round-to-nearest-even Note: Parameters are checked during C simulation to verify that the template parameter configuration is legal. Arguments Table 4-94: Arguments Argument Description x Input data. sqrtX Square root of input data. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 602 Chapter 4: High-Level Synthesis Reference Guide Return Values • Not applicable (void function) Supported Base Data Types • Input ° ap_ufixed ° ap_uint See definitions of struct cordic_inputs in hls_cordic_functions.h and struct sqrt_input in hls_sqrt_cordic.h for details. • Output ° ap_ufixed ° ap_uint See definitions of struct cordic_inputs in hls_cordic_functions.h and struct sqrt_input in hls_sqrt_cordic.h for details. Input Data Assumptions • None cmpy Synopsis • Scalar Interface template < class Architecture, int W1, int I1, ap_q_mode Q1, ap_o_mode O1, int N1, int W2, int I2, ap_q_mode Q2, ap_o_mode O2, int N2> void cmpy (const ap_fixed &ar, const ap_fixed &ai, const ap_fixed &br, const ap_fixed &bi, ap_fixed &pr, ap_fixed &pi); • std::complex interface template < class Architecture, int W1, int I1, ap_q_mode Q1, ap_o_mode O1, int N1, int W2, int I2, ap_q_mode Q2, ap_o_mode O2, int N2> void cmpy (const std::complex< ap_fixed > &a, const std::complex< ap_fixed > &b, std::complex< ap_fixed > &p); High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 603 Chapter 4: High-Level Synthesis Reference Guide Description • Performs fixed-point complex multiplication • Implements either three-multiplier or four-multiplier structure • Supports scalar or std::complex interfaces Parameters Table 4-95: Parameters Template Parameter Description Architecture Selects between three-multiplier and four-multiplier architectures. Specify using structs CmpyThreeMult or CmpyFourMult. W1, I1, Q1, O1, N1 Fixed-point parameters for multiplicand and multiplier. W2, I2, Q2, O2, N2 Fixed-point parameters for product. Arguments Table 4-96: Scalar Interface Arguments Argument Description ar Multiplicand real component ai Multiplicand imaginary component br Multiplier real component bi Multiplier imaginary component pr Product real component pi Product imaginary component Table 4-97: std::complex Interface Arguments Argument Description a Multiplicand b Multiplier p Product Return Values • Not applicable (void function) Supported Base Data Types • ap_fixed • std::complex< ap_fixed> High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 604 Chapter 4: High-Level Synthesis Reference Guide Input Data Assumptions • None HLS DSP Design Examples The Vivado HLS DSP design examples provide a basic test bench and demonstrate how to parameterize and instantiate each function. The design examples provide one or more examples for each function. To open the Vivado HLS design examples from the Welcome Page, click Open Example Project. In the Examples wizard, select a design from the Design Examples > dsp folder. Note: The Welcome Page appears when you invoke the Vivado HLS GUI. You can access it at any time by selecting Help > Welcome. You can also open the design examples directly from the Vivado Design Suite installation area: Vivado_HLS\2017.x\examples\design\dsp. Each example contains the following files: • .cpp: Top-level synthesis wrapper that instantiates the library class. • .h: Header file that defines parameter values. • _tb.cpp: Basic test bench that exercises the top-level synthesis wrapper. • run_hls.tcl: Tcl commands to set up the example Vivado HLS project: vivado_hls -f run_hls.tcl Note: Some of the design examples also include a directives.tcl file, which provides additional Tcl commands for applying optimization and implementation directives. C Arbitrary Precision Types This section discusses: • The Arbitrary Precision (AP) types provided for C language designs by Vivado HLS. • The associated functions for C int#w types. Compiling [u]int#W Types To use the [u]int#W types, you must include the ap_cint.h header file in all source files that reference [u]int#W variables. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 605 Chapter 4: High-Level Synthesis Reference Guide When compiling software models that use these types, it may be necessary to specify the location of the Vivado HLS header files, for example, by adding the “-I//include” option for gcc compilation. Declaring/Defining [u]int#W Variables There are separate signed and unsigned C types, respectively: • int#W • uint#W where • #W specifies the total width of the variable being declared. User-defined types may be created with the C/C++ ‘typedef’ statement as shown in the following examples: include "ap_cint.h" // use [u]int#W types typedef uint128 uint128_t; int96 my_wide_var; // 128-bit user defined type // a global variable declaration The maximum width allowed is 1024 bits. Initialization and Assignment from Constants (Literals) A [u]int#W variable can be initialized with the same integer constants that are supported for the native integer data types. The constants are zero or sign extended to the full width of the [u]int#W variable. #include "ap_cint.h" uint15 uint52 uint52 uint96 a b c d = = = = 0; 1234567890U; 0o12345670UL; 0x123456789ABCDEFULL; For bit-widths greater than 64-bit, the following functions can be used. apint_string2bits() This section also discusses use of the related functions: • apint_string2bits_bin() • apint_string2bits_oct() • apint_string2bits_hex() High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 606 Chapter 4: High-Level Synthesis Reference Guide These functions convert a constant character string of digits, specified within the constraints of the radix (decimal, binary, octal, hexadecimal), into the corresponding value with the given bit-width N. For any radix, the number can be preceded with the minus sign to indicate a negative value. int#W apint_string2bits[_radix](const char*, int N) This is used to construct integer constants with values that are larger than those already permitted by the C language. While smaller values also work, they are easier to specify with existing C language constant value constructs. #include #include "ap_cint.h" int128 a; // Set a to the value hex 00000000000000000123456789ABCDF0 a = apint_string2bits_hex(“-123456789ABCDEF”,128); Values can also be assigned directly from a character string. apint_vstring2bits() This function converts a character string of digits, specified within the constraints of the hexadecimal radix, into the corresponding value with the given bit-width N. The number can be preceded with the minus sign to indicate a negative value. This is used to construct integer constants with values that are larger than those already permitted by the C language. The function is typically used in a test bench to read information from a file. Given file test.dat contains the following data: 123456789ABCDEF -123456789ABCDEF -5 High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 607 Chapter 4: High-Level Synthesis Reference Guide The function, used in the test bench, supplies the following values: #include #include "ap_cint.h" typedef data_t; int128 test ( int128 t a ) { return a+1; } int main () { FILE *fp; char vstring[33]; fp = fopen(test.dat,r); while (fscanf(fp,%s,vstring)==1) { // // // // Supply function “test” with the following values 00000000000000000123456789ABCDF0 FFFFFFFFFFFFFFFFFEDCBA9876543212 FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFC test(apint_vstring2bits_hex(vstring,128)); printf(\n); } fclose(fp); return 0; } High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 608 Chapter 4: High-Level Synthesis Reference Guide Support for console I/O (Printing) A [u]int#W variable can be printed with the same conversion specifiers that are supported for the native integer data types. Only the bits that fit according to the conversion specifier are printed: #include "ap_cint.h" uint164 c = 0x123456789ABCDEFULL; printf( d%40d\n,c); // d printf( hd%40hd\n,c); // hd printf( ld%40ld\n,c); // ld printf(lld%40lld\n,c); // lld // Signed integer in decimal format -1985229329 // Short integer -12817 // Long integer 81985529216486895 // Long long integer 81985529216486895 printf( u%40u\n,c); // u printf( hu%40hu\n,c); // hu printf( lu%40lu\n,c); // lu printf(llu%40llu\n,c); // llu // Unsigned integer in decimal format 2309737967 printf( o%40o\n,c); // o printf( ho%40ho\n,c); // ho printf( lo%40lo\n,c); // lo printf(llo%40llo\n,c); // llo // Unsigned integer in octal format 21152746757 printf( x%40x\n,c); // x printf( hx%40hx\n,c); // hx printf( lx%40lx\n,c); // lx printf(llx%40llx\n,c); // llx // Unsigned integer in hexadecimal format [0-9a-f] 89abcdef printf( // X } // Unsigned integer in hexadecimal format [0-9A-F] 89ABCDEF X%40X\n,c); 52719 81985529216486895 81985529216486895 146757 4432126361152746757 4432126361152746757 cdef 123456789abcdef 123456789abcdef As with initialization and assignment to [u]int#W variables, features support printing values that require more than 64 bits to represent. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 609 Chapter 4: High-Level Synthesis Reference Guide apint_print() This is used to print integers with values that are larger than those already permitted by the C language. This function prints a value to stdout, interpreted according to the radix (2, 8, 10, 16). void apint_print(int#N value, int radix) The following example shows the results when apint_printf() is used: #include #include "ap_cint.h" int65 Var1 = 44; apint_print(Var1,2); //00000000000000000000000000000000000000000000000000000000000101100 apint_print(Var1,8); // 0000000000000000000054 apint_print(Var1,10); // 44 apint_print(Var1,16); // 0000000000000002C apint_fprint() This is used to print integers with values that are bigger than those already permitted by the C language. This function prints a value to a file, interpreted according to the radix (2, 8, 10, 16). void apint_fprint(FILE* file, int#N value, int radix) Expressions Involving [u]int#W types Variables of [u]int#W types may generally be used freely in expressions involving any C operators. Some behaviors may seem unexpected and require detailed explanation. Zero- and Sign-Extension on Assignment from Narrower to Wider Variables When assigning the value of a narrower bit-width signed variable to a wider one, the value is sign-extended to the width of the destination variable, regardless of its signedness. Similarly, an unsigned source variable is zero-extended before assignment. Explicit casting of the source variable might be necessary to ensure expected behavior on assignment. Truncation on Assignment of Wider to Narrower Variables Assigning a wider source variables value to a narrower one leads to truncation of the value. All bits beyond the most significant bit (MSB) position of the destination variable are lost. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 610 Chapter 4: High-Level Synthesis Reference Guide There is no special handling of the sign information during truncation, which may lead to unexpected behavior. Explicit casting may help avoid this unexpected behavior. Binary Arithmetic Operators In general, any valid operation that may be done on a native C integer data type is supported for [u]int#w types. Standard binary integer arithmetic operators are overloaded to provide arbitrary precision arithmetic. All of the following operators take either two operands of [u]int#W or one [u]int#W type and one C/C++ fundamental integer data type, for example, char, short, int. The width and signedness of the resulting value is determined by the width and signedness of the operands, before sign-extension, zero-padding or truncation are applied based on the width of the destination variable (or expression). Details of the return value are described for each operator. When expressions contain a mix of ap_[u]int and C/C++ fundamental integer types, the C++ types assume the following widths: • char: 8-bits • short: 16-bits • int: 32-bits • long: 32-bits • long long: 64-bits Addition [u]int#W::RType [u]int#W::operator + ([u]int#W op) Produces the sum of two ap_[u]int or one ap_[u]int and a C/C++ integer type. The width of the sum value is: • One bit more than the wider of the two operands • Two bits if and only if the wider is unsigned and the narrower is signed The sum is treated as signed if either (or both) of the operands is of a signed type. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 611 Chapter 4: High-Level Synthesis Reference Guide Subtraction [u]int#W::RType [u]int#W::operator - ([u]int#W op) • Produces the difference of two integers. • The width of the difference value is: ° One bit more than the wider of the two operands ° Two bits if and only if the wider is unsigned and the narrower signed • This applies before assignment, at which point it is sign-extended, zero-padded, or truncated based on the width of the destination variable. • The difference is treated as signed regardless of the signedness of the operands. Multiplication [u]int#W::RType [u]int#W::operator * ([u]int#W op) • Returns the product of two integer values. • The width of the product is the sum of the widths of the operands. • The product is treated as a signed type if either of the operands is of a signed type. Division [u]int#W::RType [u]int#W::operator / ([u]int#W op) • Returns the quotient of two integer values. • The width of the quotient is the width of the dividend if the divisor is an unsigned type; otherwise it is the width of the dividend plus one. • The quotient is treated as a signed type if either of the operands is of a signed type. Modulus [u]int#W::RType [u]int#W::operator % ([u]int#W op) • Returns the modulus, or remainder of integer division, for two integer values. • The width of the modulus is the minimum of the widths of the operands, if they are both of the same signedness; if the divisor is an unsigned type and the dividend is signed then the width is that of the divisor plus one. • The quotient is treated as having the same signedness as the dividend. Note: Vivado HLS synthesis of the modulus (%) operator will lead to lead to instantiation of appropriately parameterized Xilinx LogiCORE divider cores in the generated RTL. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 612 Chapter 4: High-Level Synthesis Reference Guide Bitwise Logical Operators The bitwise logical operators all return a value with a width that is the maximum of the widths of the two operands. They are treated as unsigned if and only if both operands are unsigned. Otherwise it is of a signed type. Sign-extension (or zero-padding) may occur, based on the signedness of the expression, not the destination variable. Bitwise OR [u]int#W::RType [u]int#W::operator | ([u]int#W op) Returns the bitwise OR of the two operands. Bitwise AND [u]int#W::RType [u]int#W::operator & ([u]int#W op) Returns the bitwise AND of the two operands. Bitwise XOR [u]int#W::RType [u]int#W::operator ^ ([u]int#W op) Returns the bitwise XOR of the two operands. Shift Operators Each shift operator comes in two versions, one for unsigned right-hand side (RHS) operands and one for signed RHS. A negative value supplied to the signed RHS versions reverses the shift operations direction, that is, a shift by the absolute value of the RHS operand in the opposite direction occurs. The shift operators return a value with the same width as the left-hand side (LHS) operand. As with C/C++, if the LHS operand of a shift-right is a signed type, the sign bit is copied into the most significant bit positions, maintaining the sign of the LHS operand. Unsigned Integer Shift Right [u]int#W [u]int#W::operator >>(ap_uint op) Integer Shift Right [u]int#W [u]int#W::operator >>(ap_int op) Unsigned Integer Shift Left [u]int#W [u]int#W::operator <<(ap_uint op) High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 613 Chapter 4: High-Level Synthesis Reference Guide Integer Shift Left [u]int#W [u]int#W::operator <<(ap_int op) CAUTION! When assigning the result of a shift-left operator to a wider destination variable, some (or all) information may be lost. Xilinx recommends that you explicitly cast the shift expression to the destination type to avoid unexpected behavior. Compound Assignment Operators Vivado HLS supports compound assignment operators: • *= • /= • %= • += • -= • <<= • >>= • &= • ^= • = The RHS expression is first evaluated then supplied as the RHS operand to the base operator. The result is assigned back to the LHS variable. The expression sizing, signedness, and potential sign-extension or truncation rules apply as discussed above for the relevant operations. Relational Operators Vivado HLS supports all relational operators. They return a Boolean value based on the result of the comparison. Variables of ap_[u]int types may be compared to C/C++ fundamental integer types with these operators. Equality bool [u]int#W::operator == ([u]int#W op) Inequality bool [u]int#W::operator != ([u]int#W op) High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 614 Chapter 4: High-Level Synthesis Reference Guide Less than bool [u]int#W::operator < ([u]int#W op) Greater than bool [u]int#W::operator > ([u]int#W op) Less than or equal to bool [u]int#W::operator <= ([u]int#W op) Greater than or equal to bool [u]int#W::operator >= ([u]int#W op) Bit-Level Operation: Support Function The [u]int#W types allow variables to be expressed with bit-level accuracy. It is often desirable with hardware algorithms to perform bit-level operations. Vivado HLS provides the following functions to enable this. Bit Manipulation The following methods are included to facilitate common bit-level operations on the value stored in ap_[u]int type variables. Length apint_bitwidthof() int apint_bitwidthof(type_or_value) Returns an integer value that provides the number of bits in an arbitrary precision integer value. It can be used with a type or a value. int5 Var1, Res1; Var1= -1; Res1 = apint_bitwidthof(Var1); Res1 = apint_bitwidthof(int7); // Res1 is assigned 5 // Res1 is assigned 7 Concatenation apint_concatenate() int#(N+M) apint_concatenate(int#N first, int#M second) Concatenates two [u]int#W variables. The width of the returned value is the sum of the widths of the operands. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 615 Chapter 4: High-Level Synthesis Reference Guide The High and Low arguments are placed in the higher and lower order bits of the result respectively. RECOMMENDED: To avoid unexpected results, explicitly cast C native types (including integer literals) to an appropriate [u]int#W type before concatenating. Bit Selection apint_get_bit() int apint_get_bit(int#N source, int index) Selects one bit from an arbitrary precision integer value and returns it. The source must be an [u]int#W type. The index argument must be an int value. It specifies the index of the bit to select. The least significant bit has index 0. The highest permissible index is one less than the bit-width of this [u]int#W. Set Bit Value apint_set_bit() int#N • apint_set_bit(int#N source, int index, int value) Sets the specified bit, index, of the [u]int#W instance source to the value specified (zero or one). Range Selection apint_get_range() int#N apint_get_range(int#N source, int high, int low) • Returns the value represented by the range of bits specified by the arguments. • The High argument specifies the most significant bit (MSB) position of the range. • THE Low argument specifies the least significant bit (LSB) position of the range. • The LSB of the source variable is in position 0. If the High argument has a value less than Low, the bits are returned in reverse order. Set Range Value apint_set_range() int#N • apint_set_range(int#N source, int high, int low, int#M part) Sets the source specified bits between High and Low to the value of the part. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 616 Chapter 4: High-Level Synthesis Reference Guide Bit Reduction AND Reduce apint_and_reduce() int apint_and_reduce(int#N value) • Applies the AND operation on all bits in the value. • Returns the resulting single bit as an integer value (which can be cast onto a bool). int5 Var1, Res1; • Var1= -1; Res1 = apint_and_reduce(Var1); // Res1 is assigned 1 Var1= 1; Res1 = apint_and_reduce(Var1); // Res1 is assigned 0 Equivalent to comparing to -1. It returns a 1 if it matches. It returns a 0 if it does not match. Another interpretation is to check that all bits are one. OR Reduce apint_or_reduce() int apint_or_reduce(int#N value) • Applies the XOR operation on all bits in the value. • Returns the resulting single bit as an integer value (which can be cast onto a bool). • Equivalent to comparing to 0, and return a 0 if it matches, 1 otherwise. int5 Var1, Res1; Var1= 1; Res1 = apint_or_reduce(Var1); // Res1 is assigned 1 Var1= 0; Res1 = apint_or_reduce(Var1); // Res1 is assigned 0 XOR Reduce apint_xor_reduce() int apint_xor_reduce(int#N value) • Applies the OR operation on all bits in the value. • Returns the resulting single bit as an integer value (which can be cast onto a bool). • Equivalent to counting the ones in the word. This operation: ° Returns 0if there is an even number. ° Returns 1if there is an odd number (even parity). High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 617 Chapter 4: High-Level Synthesis Reference Guide int5 Var1, Res1; Var1= 0; Res1 = apint_xor_reduce(Var1); // Res1 is assigned 0 Var1= 1; Res1 = apint_xor_reduce(Var1); // Res1 is assigned 1 NAND Reduce apint_nand_reduce() int apint_nand_reduce(int#N value) • Applies the NAND operation on all bits in the value. • Returns the resulting single bit as an integer value (which can be cast onto a bool). • Equivalent to comparing this value against -1 (all ones) and returning false if it matches, true otherwise. int5 Var1, Res1; Var1= 1; Res1 = apint_nand_reduce(Var1); // Res1 is assigned 1 Var1= -1; Res1 = apint_nand_reduce(Var1); // Res1 is assigned 0 NOR Reduce apint_nor_reduce() int apint_nor_reduce(int#N value) • Applies the NOR operation on all bits in the value. • Returns the resulting single bit as an integer value (which can be cast onto a bool). • Equivalent to comparing this value against 0 (all zeros) and returning true if it matches, false otherwise. int5 Var1, Res1; Var1= 0; Res1 = apint_nor_reduce(Var1); // Res1 is assigned 1 Var1= 1; Res1 = apint_nor_reduce(Var1); // Res1 is assigned 0 High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 618 Chapter 4: High-Level Synthesis Reference Guide XNOR Reduce apint_xnor_reduce() int apint_xnor_reduce(int#N value) • Applies the XNOR operation on all bits in the value. • Returns the resulting single bit as an integer value (which can be cast onto a bool). • Equivalent to counting the ones in the word. • This operation: ° Returns 1 if there is an odd number. ° Returns 0 if there is an even number (odd parity). int5 Var1, Res1; Var1= 0; Res1 = apint_xnor_reduce(Var1); // Res1 is assigned 1 Var1= 1; Res1 = apint_xnor_reduce(Var1); // Res1 is assigned 0 C++ Arbitrary Precision Types Vivado HLS provides a C++ template class, ap_[u]int<>, that implements arbitrary precision (or bit-accurate) integer data types with consistent, bit-accurate behavior between software and hardware modeling. This class provides all arithmetic, bitwise, logical and relational operators allowed for native C integer types. In addition, this class provides methods to handle some useful hardware operations, such as allowing initialization and conversion of variables of widths greater than 64 bits. Details for all operators and class methods are discussed below. Compiling ap_[u]int<> Types To use the ap_[u]int<> classes, you must include the ap_int.h header file in all source files that reference ap_[u]int<> variables. When compiling software models that use these classes, it may be necessary to specify the location of the Vivado HLS header files, for example by adding the -I//include option for g++ compilation. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 619 Chapter 4: High-Level Synthesis Reference Guide Declaring/Defining ap_[u] Variables There are separate signed and unsigned classes: • ap_int (signed) • ap_uint (unsigned) The template parameter int_W specifies the total width of the variable being declared. User-defined types may be created with the C/C++ typedef statement as shown in the following examples: include "ap_int.h"// use ap_[u]fixed<> types typedef ap_uint<128> uint128_t; ap_int<96> my_wide_var; // 128-bit user defined type // a global variable declaration The default maximum width allowed is 1024 bits. This default may be overridden by defining the macro AP_INT_MAX_W with a positive integer value less than or equal to 32768 before inclusion of the ap_int.h header file. CAUTION! Setting the value of AP_INT_MAX_W too High may cause slow software compile and run times. Following is an example of overriding AP_INT_MAX_W: #define AP_INT_MAX_W 4096 #include "ap_int.h" // Must be defined before next line ap_int<4096> very_wide_var; Initialization and Assignment from Constants (Literals) The class constructor and assignment operator overloads, allows initialization of and assignment to ap_[u]fixed<> variables using standard C/C++ integer literals. This method of assigning values to ap_[u]fixed<> variables is subject to the limitations of C++ and the system upon which the software will run. This typically leads to a 64-bit limit on integer literals (for example, for those LL or ULL suffixes). To allow assignment of values wider than 64-bits, the ap_[u]fixed<> classes provide constructors that allow initialization from a string of arbitrary length (less than or equal to the width of the variable). By default, the string provided is interpreted as a hexadecimal value as long as it contains only valid hexadecimal digits (that is, 0-9 and a-f). To assign a value from such a string, an explicit C++ style cast of the string to the appropriate type must be made. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 620 Chapter 4: High-Level Synthesis Reference Guide Following are examples of initialization and assignments, including for values greater than 64-bit, are: ap_int<42> a_42b_var(-1424692392255LL); a_42b_var = 0x14BB648B13FLL; a_42b_var = -1; // long long decimal format // hexadecimal format // negative int literal sign-extended to full width ap_uint<96> wide_var(“76543210fedcba9876543210”, 16);// Greater than 64-bit wide_var = ap_int<96>(“0123456789abcdef01234567”, 16); The ap_[u]<> constructor may be explicitly instructed to interpret the string as representing the number in radix 2, 8, 10, or 16 formats. This is accomplished by adding the appropriate radix value as a second parameter to the constructor call. A compilation error occurs if the string literal contains any characters that are invalid as digits for the radix specified. The following examples use different radix formats: ap_int<6> a_6bit_var(“101010”, 2); a_6bit_var = ap_int<6>(“40”, 8); a_6bit_var = ap_int<6>(“55”, 10); a_6bit_var = ap_int<6>(“2A”, 16); a_6bit_var = ap_int<6>(“42”, 2); // // // // 42d in binary format 32d in octal format decimal format 42d in hexadecimal format // COMPILE-TIME ERROR! “42” is not binary The radix of the number encoded in the string can also be inferred by the constructor, when it is prefixed with a zero (0) followed by one of the following characters: “b”, “o” or “x”. The prefixes “0b”, “0o” and “0x” correspond to binary, octal and hexadecimal formats respectively. The following examples use alternate initializer string formats: ap_int<6> a_6bit_var(“0b101010”, 2); a_6bit_var = ap_int<6>(“0o40”, 8); a_6bit_var = ap_int<6>(“0x2A”, 16); // 42d in binary format // 32d in octal format // 42d in hexidecimal format a_6bit_var = ap_int<6>(“0b42”, 2); // COMPILE-TIME ERROR! “42” is not binary If the bit-width is greater than 53-bits, the ap_[u]fixed value must be initialized with a string, for example: ap_ufixed<72,10> Val(“2460508560057040035.375”); Support for Console I/O (Printing) As with initialization and assignment to ap_[u]fixed<> variables, Vivado HLS supports printing values that require more than 64-bits to represent. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 621 Chapter 4: High-Level Synthesis Reference Guide Using the C++ Standard Output Stream The easiest way to output any value stored in an ap_[u]int variable is to use the C++ standard output stream: • std::cout (#include or • ) The stream insertion operator (<<) is overloaded to correctly output the full range of values possible for any given ap_[u]fixed variable. The following stream manipulators are also supported: • dec (decimal) • hex (hexadecimal) • oct (octal) These allow formatting of the value as indicated. The following example uses cout to print values: #include // Alternative: #include ap_ufixed<72> Val(“10fedcba9876543210”); cout << Val << endl; // Yields: “313512663723845890576” cout << hex << val << endl; // Yields: “10fedcba9876543210” cout << oct << val << endl; // Yields: “41773345651416625031020” Using the Standard C Library You can also use the standard C library (#include ) to print out values larger than 64-bits: 1. Convert the value to a C++ std::string using the ap_[u]fixed classes method to_string(). 2. Convert the result to a null-terminated C character string using the std::string class method c_str(). High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 622 Chapter 4: High-Level Synthesis Reference Guide Optional Argument One (Specifying the Radix) You can pass the ap[u]int::to_string()method an optional argument specifying the radix of the numerical format desired. The valid radix argument values are: • 2 (binary) (default) • 8 (octal) • 10 (decimal) • 16 (hexadecimal) Optional Argument Two (Printing as Signed Values) A second optional argument to ap_[u]int::to_string() specifies whether to print the non-decimal formats as signed values. This argument is boolean. The default value is false, causing the non-decimal formats to be printed as unsigned values. The following examples use printf to print values: ap_int<72> Val(“80fedcba9876543210”); printf(“%s\n”, printf(“%s\n”, printf(“%s\n”, printf(“%s\n”, Val.to_string().c_str()); // Val.to_string(10).c_str()); // Val.to_string(8).c_str()); // Val.to_string(16, true).c_str()); => => => // “80FEDCBA9876543210” “-2342818482890329542128” “401773345651416625031020” => “-7F0123456789ABCDF0” Expressions Involving ap_[u]<> types Variables of ap_[u]<> types may generally be used freely in expressions involving C/C++ operators. Some behaviors may be unexpected. These are discussed in detail below. Zero- and Sign-Extension on Assignment From Narrower to Wider Variables When assigning the value of a narrower bit-width signed (ap_int<>) variable to a wider one, the value is sign-extended to the width of the destination variable, regardless of its signedness. Similarly, an unsigned source variable is zero-extended before assignment. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 623 Chapter 4: High-Level Synthesis Reference Guide Explicit casting of the source variable may be necessary to ensure expected behavior on assignment. See the following example: ap_uint<10> Result; ap_int<7> Val1 = 0x7f; ap_uint<6> Val2 = 0x3f; Result = Val1; Result = Val2; // Yields: 0x3ff (sign-extended) // Yields: 0x03f (zero-padded) Result = ap_uint<7>(Val1); Result = ap_int<6>(Val2); // Yields: 0x07f (zero-padded) // Yields: 0x3ff (sign-extended) Truncation on Assignment of Wider to Narrower Variables Assigning the value of a wider source variable to a narrower one leads to truncation of the value. All bits beyond the most significant bit (MSB) position of the destination variable are lost. There is no special handling of the sign information during truncation. This may lead to unexpected behavior. Explicit casting may help avoid this unexpected behavior. Class Methods and Operators The ap_[u]int types do not support implicit conversion from wide ap_[u]int (>64bits) to builtin C/C++ integer types. For example, the following code example return s1, because the implicit cast from ap_int[65] to bool in the if-statement returns a 0. bool nonzero(ap_uint<65> data) { return data; // This leads to implicit truncation to 64b int } int main() { if (nonzero((ap_uint<65>)1 << 64)) { return 0; } printf(FAIL\n); return 1; } To convert wide ap_[u]int types to built-in integers, use the explicit conversion functions included with the ap_[u]int types: • to_int() • to_long() • to_bool() In general, any valid operation that can be done on a native C/C++ integer data type is supported using operator overloading for ap_[u]int types. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 624 Chapter 4: High-Level Synthesis Reference Guide In addition to these overloaded operators, some class specific operators and methods are included to ease bit-level operations. Binary Arithmetic Operators Standard binary integer arithmetic operators are overloaded to provide arbitrary precision arithmetic. These operators take either: • Two operands of ap_[u]int, or • One ap_[u]int type and one C/C++ fundamental integer data type For example: • char • short • int The width and signedness of the resulting value is determined by the width and signedness of the operands, before sign-extension, zero-padding or truncation are applied based on the width of the destination variable (or expression). Details of the return value are described for each operator. When expressions contain a mix of ap_[u]int and C/C++ fundamental integer types, the C++ types assume the following widths: • char (8-bits) • short (16-bits) • int (32-bits) • long (32-bits) • long long (64-bits) Addition ap_(u)int::RType ap_(u)int::operator + (ap_(u)int op) Returns the sum of: • Two ap_[u]int, or • One ap_[u]int and a C/C++ integer type The width of the sum value is: • One bit more than the wider of the two operands, or • Two bits if and only if the wider is unsigned and the narrower is signed High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 625 Chapter 4: High-Level Synthesis Reference Guide The sum is treated as signed if either (or both) of the operands is of a signed type. Subtraction ap_(u)int::RType ap_(u)int::operator - (ap_(u)int op) Returns the difference of two integers. The width of the difference value is: • One bit more than the wider of the two operands, or • Two bits if and only if the wider is unsigned and the narrower signed This is true before assignment, at which point it is sign-extended, zero-padded, or truncated based on the width of the destination variable. The difference is treated as signed regardless of the signedness of the operands. Multiplication ap_(u)int::RType ap_(u)int::operator * (ap_(u)int op) Returns the product of two integer values. The width of the product is the sum of the widths of the operands. The product is treated as a signed type if either of the operands is of a signed type. Division ap_(u)int::RType ap_(u)int::operator / (ap_(u)int op) Returns the quotient of two integer values. The width of the quotient is the width of the dividend if the divisor is an unsigned type. Otherwise, it is the width of the dividend plus one. The quotient is treated as a signed type if either of the operands is of a signed type. Modulus ap_(u)int::RType ap_(u)int::operator % (ap_(u)int op) Returns the modulus, or remainder of integer division, for two integer values. The width of the modulus is the minimum of the widths of the operands, if they are both of the same signedness. If the divisor is an unsigned type and the dividend is signed, then the width is that of the divisor plus one. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 626 Chapter 4: High-Level Synthesis Reference Guide The quotient is treated as having the same signedness as the dividend. IMPORTANT: Vivado HLS synthesis of the modulus (%) operator will lead to lead to instantiation of appropriately parameterized Xilinx LogiCORE divider cores in the generated RTL. Following are examples of arithmetic operators: ap_uint<71> Rslt; ap_uint<42> Val1 = 5; ap_int<23> Val2 = -8; Rslt Rslt Rslt Rslt Rslt = = = = = Val1 Val1 Val1 50 / 50 % + Val2; - Val2; * Val2; Val2; Val2; // // // // // Yields: Yields: Yields: Yields: Yields: -3 (43 bits) sign-extended to 71 bits +3 sign extended to 71 bits -40 (65 bits) sign extended to 71 bits -6 (33 bits) sign extended to 71 bits +2 (23 bits) sign extended to 71 bits Bitwise Logical Operators The bitwise logical operators all return a value with a width that is the maximum of the widths of the two operand. It is treated as unsigned if and only if both operands are unsigned. Otherwise, it is of a signed type. Sign-extension (or zero-padding) may occur, based on the signedness of the expression, not the destination variable. Bitwise OR ap_(u)int::RType ap_(u)int::operator | (ap_(u)int op) Returns the bitwise OR of the two operands. Bitwise AND ap_(u)int::RType ap_(u)int::operator & (ap_(u)int op) Returns the bitwise AND of the two operands. Bitwise XOR ap_(u)int::RType ap_(u)int::operator ^ (ap_(u)int op) Returns the bitwise XOR of the two operands. Unary Operators Addition ap_(u)int ap_(u)int::operator + () High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 627 Chapter 4: High-Level Synthesis Reference Guide Returns the self copy of the ap_[u]int operand. Subtraction ap_(u)int::RType ap_(u)int::operator - () Returns the following: • The negated value of the operand with the same width if it is a signed type, or • Its width plus one if it is unsigned. The return value is always a signed type. Bitwise Inverse ap_(u)int::RType ap_(u)int::operator ~ () Returns the bitwise-NOT of the operand with the same width and signedness. Logical Invert bool ap_(u)int::operator ! () Returns a Boolean false value if and only if the operand is not equal to zero (0). Returns a Boolean true value if the operand is equal to zero (0). Ternary Operators When you use the ternary operator with the standard C int type, you must explicitly cast from one type to the other to ensure that both results have the same type. For example: // Integer type is cast to ap_int type ap_int<32> testc3(int a, ap_int<32> b, ap_int<32> c, bool d) { return d?ap_int<32>(a):b; } // ap_int type is cast to an integer type ap_int<32> testc4(int a, ap_int<32> b, ap_int<32> c, bool d) { return d?a+1:(int)b; } // Integer type is cast to ap_int type ap_int<32> testc5(int a, ap_int<32> b, ap_int<32> c, bool d) { return d?ap_int<33>(a):b+1; } Shift Operators Each shift operator comes in two versions: • One version for unsigned right-hand side (RHS) operands • One version for signed right-hand side (RHS) operands High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 628 Chapter 4: High-Level Synthesis Reference Guide A negative value supplied to the signed RHS versions reverses the shift operations direction. That is, a shift by the absolute value of the RHS operand in the opposite direction occurs. The shift operators return a value with the same width as the left-hand side (LHS) operand. As with C/C++, if the LHS operand of a shift-right is a signed type, the sign bit is copied into the most significant bit positions, maintaining the sign of the LHS operand. Unsigned Integer Shift Right ap_(u)int ap_(u)int::operator << (ap_uint op) Integer Shift Right ap_(u)int ap_(u)int::operator << (ap_int op) Unsigned Integer Shift Left ap_(u)int ap_(u)int::operator >> (ap_uint op) Integer Shift Left ap_(u)int ap_(u)int::operator >> (ap_int op) CAUTION! When assigning the result of a shift-left operator to a wider destination variable, some or all information may be lost. Xilinx recommends that you explicitly cast the shift expression to the destination type to avoid unexpected behavior. Following are examples of shift operations: ap_uint<13> Rslt; ap_uint<7> Val1 = 0x41; Rslt = Val1 << 6; Rslt = ap_uint<13>(Val1) << 6; // Yields: 0x0040, i.e. msb of Val1 is lost // Yields: 0x1040, no info lost ap_int<7> Val2 = -63; Rslt = Val2 >> 4; //Yields: 0x1ffc, sign is maintained and extended High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 629 Chapter 4: High-Level Synthesis Reference Guide Compound Assignment Operators Vivado HLS supports compound assignment operators: • *= • /= • %= • += • -= • <<= • >>= • &= • ^= • |= The RHS expression is first evaluated then supplied as the RHS operand to the base operator, the result of which is assigned back to the LHS variable. The expression sizing, signedness, and potential sign-extension or truncation rules apply as discussed above for the relevant operations. ap_uint<10> Val1 = 630; ap_int<3> Val2 = -3; ap_uint<5> Val3 = 27; Val1 += Val2 - Val3; // Yields: 600 and is equivalent to: // Val1 = ap_uint<10>(ap_int<11>(Val1) + // ap_int<11>((ap_int<6>(Val2) // ap_int<6>(Val3)))); Example 4-1: Compound Assignment Statement Increment and Decrement Operators The increment and decrement operators are provided. All return a value of the same width as the operand and which is unsigned if and only if both operands are of unsigned types and signed otherwise. Pre-Increment ap_(u)int& ap_(u)int::operator ++ () Returns the incremented value of the operand. Assigns the incremented value to the operand. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 630 Chapter 4: High-Level Synthesis Reference Guide Post-Increment const ap_(u)int ap_(u)int::operator ++ (int) Returns the value of the operand before assignment of the incremented value to the operand variable. Pre-Decrement ap_(u)int& ap_(u)int::operator -- () Returns the decremented value of, as well as assigning the decremented value to, the operand. Post-Decrement const ap_(u)int ap_(u)int::operator -- (int) Returns the value of the operand before assignment of the decremented value to the operand variable. Relational Operators Vivado HLS supports all relational operators. They return a Boolean value based on the result of the comparison. You can compare variables of ap_[u]int types to C/C++ fundamental integer types with these operators. Equality bool ap_(u)int::operator == (ap_(u)int op) Inequality bool ap_(u)int::operator != (ap_(u)int op) Less than bool ap_(u)int::operator < (ap_(u)int op) Greater than bool ap_(u)int::operator > (ap_(u)int op) Less than or equal to bool ap_(u)int::operator <= (ap_(u)int op) Greater than or equal to bool ap_(u)int::operator >= (ap_(u)int op) High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 631 Chapter 4: High-Level Synthesis Reference Guide Other Class Methods, Operators, and Data Members The following sections discuss other class methods, operators, and data members. Bit-Level Operations The following methods facilitate common bit-level operations on the value stored in ap_[u]int type variables. Length int ap_(u)int::length () Returns an integer value providing the total number of bits in the ap_[u]int variable. Concatenation ap_concat_ref ap_(u)int::concat (ap_(u)int low) ap_concat_ref ap_(u)int::operator , (ap_(u)int high, ap_(u)int low) Concatenates two ap_[u]int variables, the width of the returned value is the sum of the widths of the operands. The High and Low arguments are placed in the higher and lower order bits of the result respectively; the concat() method places the argument in the lower order bits. When using the overloaded comma operator, the parentheses are required. The comma operator version may also appear on the LHS of assignment. RECOMMENDED: To avoid unexpected results, explicitly cast C/C++ native types (including integer literals) to an appropriate ap_[u]int type before concatenating. ap_uint<10> Rslt; ap_int<3> Val1 = -3; ap_int<7> Val2 = 54; Rslt = (Val2, Val1); Rslt = Val1.concat(Val2); (Val1, Val2) = 0xAB; // Yields: 0x1B5 // Yields: 0x2B6 // Yields: Val1 == 1, Val2 == 43 Example 4-2: Concatenation Example Bit Selection ap_bit_ref ap_(u)int::operator [] (int bit) Selects one bit from an arbitrary precision integer value and returns it. The returned value is a reference value that can set or clear the corresponding bit in this ap_[u]int. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 632 Chapter 4: High-Level Synthesis Reference Guide The bit argument must be an int value. It specifies the index of the bit to select. The least significant bit has index 0. The highest permissible index is one less than the bit-width of this ap_[u]int. The result type ap_bit_ref represents the reference to one bit of this ap_[u]int instance specified by bit. Range Selection ap_range_ref ap_(u)int::range (unsigned Hi, unsigned Lo) ap_range_ref ap_(u)int::operator () (unsigned Hi, unsigned Lo) Returns the value represented by the range of bits specified by the arguments. The Hi argument specifies the most significant bit (MSB) position of the range, and Lo specifies the least significant bit (LSB). The LSB of the source variable is in position 0. If the Hi argument has a value less than Lo, the bits are returned in reverse order. ap_uint<4> Rslt; ap_uint<8> Val1 = 0x5f; ap_uint<8> Val2 = 0xaa; Rslt = Val1.range(3, 0); Val1(3,0) = Val2(3, 0); Val1(3,0) = Val2(4, 1); Rslt = Val1.range(4, 7); // // // // Yields: Yields: Yields: Yields: Example 4-3: 0xF 0x5A 0x55 0xA; bit-reversed! Range Selection Examples AND reduce bool ap_(u)int::and_reduce () • Applies the AND operation on all bits in this ap_(u)int. • Returns the resulting single bit. • Equivalent to comparing this value against -1 (all ones) and returning true if it matches, false otherwise. OR reduce bool ap_(u)int::or_reduce () • Applies the OR operation on all bits in this ap_(u)int. • Returns the resulting single bit. • Equivalent to comparing this value against 0 (all zeros) and returning false if it matches, true otherwise. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 633 Chapter 4: High-Level Synthesis Reference Guide XOR reduce bool ap_(u)int::xor_reduce () • Applies the XOR operation on all bits in this ap_int. • Returns the resulting single bit. • Equivalent to counting the number of 1 bits in this value and returning false if the count is even or true if the count is odd. NAND reduce bool ap_(u)int::nand_reduce () • Applies the NAND operation on all bits in this ap_int. • Returns the resulting single bit. • Equivalent to comparing this value against -1 (all ones) and returning false if it matches, true otherwise. NOR reduce bool ap_int::nor_reduce () • Applies the NOR operation on all bits in this ap_int. • Returns the resulting single bit. • Equivalent to comparing this value against 0 (all zeros) and returning true if it matches, false otherwise. XNOR reduce bool ap_(u)int::xnor_reduce () • Applies the XNOR operation on all bits in this ap_(u)int. • Returns the resulting single bit. • Equivalent to counting the number of 1 bits in this value and returning true if the count is even or false if the count is odd. Bit Reduction Method Examples ap_uint<8> Val = 0xaa; bool t = Val.and_reduce(); t = Val.or_reduce(); t = Val.xor_reduce(); t = Val.nand_reduce(); t = Val.nor_reduce(); t = Val.xnor_reduce(); // // // // // // Yields: Yields: Yields: Yields: Yields: Yields: Example 4-4: High-Level Synthesis UG902 (v2017.1) April 5, 2017 false true false true false true Bit Reduction Method Example www.xilinx.com Send Feedback 634 Chapter 4: High-Level Synthesis Reference Guide Bit Reverse void ap_(u)int::reverse () Reverses the contents of ap_[u]int instance: • The LSB becomes the MSB. • The MSB becomes the LSB. Reverse Method Example ap_uint<8> Val = 0x12; Val.reverse(); // Yields: 0x48 Test Bit Value bool ap_(u)int::test (unsigned i) Checks whether specified bit of ap_(u)int instance is 1. Returns true if Yes, false if No. Test Method Example ap_uint<8> Val = 0x12; bool t = Val.test(5); // Yields: true Set Bit Value void ap_(u)int::set (unsigned i, bool v) void ap_(u)int::set_bit (unsigned i, bool v) Sets the specified bit of the ap_(u)int instance to the value of integer V. Set Bit (to 1) void ap_(u)int::set (unsigned i) Sets the specified bit of the ap_(u)int instance to the value 1 (one). Clear Bit (to 0) void ap_(u)int:: clear(unsigned i) Sets the specified bit of the ap_(u)int instance to the value 0 (zero). Invert Bit void ap_(u)int:: invert(unsigned i) Inverts the bit specified in the function argument of the ap_(u)int instance. The specified bit becomes 0 if its original value is 1 and vice versa. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 635 Chapter 4: High-Level Synthesis Reference Guide Example of bit set, clear and invert bit methods: ap_uint<8> Val = 0x12; Val.set(0, 1); Val.set_bit(4, false); Val.set(7); Val.clear(1); Val.invert(4); // // // // // Yields: Yields: Yields: Yields: Yields: 0x13 0x03 0x83 0x81 0x91 Rotate Right void ap_(u)int:: rrotate(unsigned n) Rotates the ap_(u)int instance n places to right. Rotate Left void ap_(u)int:: lrotate(unsigned n) Rotates the ap_(u)int instance n places to left. ap_uint<8> Val = 0x12; Val.rrotate(3); Val.lrotate(6); // Yields: 0x42 // Yields: 0x90 Example 4-5: Rotate Methods Example Bitwise NOT void ap_(u)int:: b_not() • Complements every bit of the ap_(u)int instance. ap_uint<8> Val = 0x12; Val.b_not(); // Yields: 0xED Example 4-6: Bitwise NOT Example Test Sign bool ap_int:: sign() • Checks whether the ap_(u)int instance is negative. • Returns true if negative. • Returns false if positive. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 636 Chapter 4: High-Level Synthesis Reference Guide Explicit Conversion Methods To C/C++ “(u)int” int ap_(u)int::to_int () unsigned ap_(u)int::to_uint () • Returns native C/C++ (32-bit on most systems) integers with the value contained in the ap_[u]int. • Truncation occurs if the value is greater than can be represented by an [unsigned] int. To C/C++ 64-bit “(u)int” long long ap_(u)int::to_int64 () unsigned long long ap_(u)int::to_uint64 () • Returns native C/C++ 64-bit integers with the value contained in the ap_[u]int. • Truncation occurs if the value is greater than can be represented by an [unsigned] int. To C/C++ “double” double ap_(u)int::to_double () • Returns a native C/C++ double 64-bit floating point representation of the value contained in the ap_[u]int. • If the ap_[u]int is wider than 53 bits (the number of bits in the mantissa of a double), the resulting double may not have the exact value expected. Sizeof The standard C++ sizeof() function should not be used with ap_[u]int or other classes or instance of object. The ap_int<> data type is a class and sizeof returns the storage used by that class or instance object. sizeof(ap_int) always returns the number of bytes used. For example: sizeof(ap_int<127=>) // returns 16 sizeof(ap_int<128=>) // returns 16 sizeof(ap_int<129=16*8+1>) returns sizeof(ap_int<136=17*8+0>) returns since 127 is 15*8+7 since 128 is 15*8+7 24 // 127 is 15*8+7 24 // 127 is 15*8+7 Compile Time Access to Data Type Attributes The ap_[u]int<> types are provided with a static member that allows the size of the variables to be determined at compile time. The data type is provided with the static const member width, which is automatically assigned the width of the data type: static const int width = _AP_W; High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 637 Chapter 4: High-Level Synthesis Reference Guide You can use the width data member to extract the data width of an existing ap_[u]int<> data type to create another ap_[u]int<> data type at compile time. The following example shows how the size of variable Res is defined as 1-bit greater than variables Val1 and Val2: // Definition of basic data type #define INPUT_DATA_WIDTH 8 typedef ap_int data_t; // Definition of variables data_t Val1, Val2; // Res is automatically sized at run-time to be 1-bit greater than data type data_t ap_int Res = Val1 + Val2; This ensures that Vivado HLS correctly models the bit-growth caused by the addition even if you update the value of INPUT_DATA_WIDTH for data_t. C++ Arbitrary Precision Fixed-Point Types Vivado HLS supports fixed-point types that allow fractional arithmetic to be easily handled. The advantage of fixed-point arithmetic is shown in the following example. ap_fixed<11, 6> Var1 = 22.96875; ap_ufixed<12,11> Var2 = 512.5; ap_fixed<16,11> Res1; // 11-bit signed word, 5 fractional bits // 12-bit word, 1 fractional bit // 16-bit signed word, 5 fractional bits Res1 = Var1 + Var2; // Result is 535.46875 Even though Var1 and Var2 have different precisions, the fixed-point type ensures that the decimal point is correctly aligned before the operation (an addition in this case), is performed. You are not required to perform any operations in the C code to align the decimal point. The type used to store the result of any fixed-point arithmetic operation must be large enough (in both the integer and fractional bits) to store the full result. If this is not the case, the ap_fixed type performs: • overflow handling (when the result has more MSBs than the assigned type supports) • quantization (or rounding, when the result has fewer LSBs than the assigned type supports) The ap_[u]fixed type provides includes various options on how the overflow and quantization are performed. The options are discussed below. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 638 Chapter 4: High-Level Synthesis Reference Guide ap_[u]fixed Representation In ap[u]fixed types, a fixed-point value is represented as a sequence of bits with a specified position for the binary point. • Bits to the left of the binary point represent the integer part of the value. • Bits to the right of the binary point represent the fractional part of the value. ap_[u]fixed type is defined as follows: ap_[u]fixed; • The W attribute takes one parameter, the total number of bits for the word. Only a constant integer expression can be used as the parameter value. • The I attribute takes one parameter, the number of bits to represent the integer part. • • • ° The value of I must be less than or equal to W. ° The number of bits to represent the fractional part is W minus I. ° Only a constant integer expression can be used as the parameter value. The Q attribute takes one parameter, quantization mode. ° Only a predefined enumerated value can be used as the parameter value. ° The default value is AP_TRN. The O attribute takes one parameter, overflow mode. ° Only predefined enumerated value can be used as the parameter value. ° The default value is AP_WRAP. The N attribute takes one parameter, the number of saturation bits considered used in the overflow wrap modes. ° Only a constant integer expression can be used as the parameter value. ° The default value is zero. Note: If the quantization, overflow and saturation parameters are not specified, as in the first example above, the default settings are used. The quantization and overflow modes are explained below. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 639 Chapter 4: High-Level Synthesis Reference Guide Quantization Modes • Rounding to plus infinity AP_RND • Rounding to zero AP_RND_ZERO • Rounding to minus infinity AP_RND_MIN_INF • Rounding to infinity AP_RND_INF • Convergent rounding AP_RND_CONV • Truncation AP_TRN • Truncation to zero AP_TRN_ZERO AP_RND • Round the value to the nearest representable value for the specific ap_[u]fixed type. ap_fixed<3, 2, AP_RND, AP_SAT> UAPFixed4 = 1.25; ap_fixed<3, 2, AP_RND, AP_SAT> UAPFixed4 = -1.25; Example 4-7: // Yields: 1.5 // Yields: -1.0 AP_RND Example AP_RND_ZERO • Round the value to the nearest representable value. • Round towards zero. ° For positive values, delete the redundant bits. ° For negative values, add the least significant bits to get the nearest representable value. ap_fixed<3, 2, AP_RND_ZERO, AP_SAT> UAPFixed4 = 1.25; // Yields: 1.0 ap_fixed<3, 2, AP_RND_ZERO, AP_SAT> UAPFixed4 = -1.25; // Yields: -1.0 Example 4-8: AP_RND_ZERO Example AP_RND_MIN_INF • Round the value to the nearest representable value. • Round towards minus infinity. ° For positive values, delete the redundant bits. ° For negative values, add the least significant bits. ap_fixed<3, 2, AP_RND_MIN_INF, AP_SAT> UAPFixed4 = 1.25; ap_fixed<3, 2, AP_RND_MIN_INF, AP_SAT> UAPFixed4 = -1.25; Example 4-9: High-Level Synthesis UG902 (v2017.1) April 5, 2017 // Yields: 1.0 // Yields: -1.5 AP_RND_MIN_INF Example www.xilinx.com Send Feedback 640 Chapter 4: High-Level Synthesis Reference Guide AP_RND_INF • Round the value to the nearest representable value. • The rounding depends on the least significant bit. ° For positive values, if the least significant bit is set, round towards plus infinity. Otherwise, round towards minus infinity. ° For negative values, if the least significant bit is set, round towards minus infinity. Otherwise, round towards plus infinity. ap_fixed<3, 2, AP_RND_INF, AP_SAT> UAPFixed4 = 1.25; ap_fixed<3, 2, AP_RND_INF, AP_SAT> UAPFixed4 = -1.25; Example 4-10: // Yields: 1.5 // Yields: -1.5 AP_RND_INF Example AP_RND_CONV • Round the value to the nearest representable value. • The rounding depends on the least significant bit. ° If least significant bit is set, round towards plus infinity. ° Otherwise, round towards minus infinity. ap_fixed<3, 2, AP_RND_CONV, AP_SAT> UAPFixed4 = 0.75; ap_fixed<3, 2, AP_RND_CONV, AP_SAT> UAPFixed4 = -1.25; Example 4-11: // Yields: 1.0 // Yields: -1.0 AP_RND_CONV Examples AP_TRN • Round the value to the nearest representable value. • Always round the value towards minus infinity. ap_fixed<3, 2, AP_TRN, AP_SAT> UAPFixed4 = 1.25; ap_fixed<3, 2, AP_TRN, AP_SAT> UAPFixed4 = -1.25; Example 4-12: // Yields: 1.0 // Yields: -1.5 AP_TRN Examples AP_TRN_ZERO Round the value to the nearest representable value. * For positive values, the rounding is the same as mode AP_TRN. * For negative values, round towards zero. ap_fixed<3, 2, AP_TRN_ZERO, AP_SAT> UAPFixed4 = 1.25; ap_fixed<3, 2, AP_TRN_ZERO, AP_SAT> UAPFixed4 = -1.25; Example 4-13: High-Level Synthesis UG902 (v2017.1) April 5, 2017 // Yields: 1.0 // Yields: -1.0 AP_TRN_ZERO Examples www.xilinx.com Send Feedback 641 Chapter 4: High-Level Synthesis Reference Guide Overflow Modes • Saturation AP_SAT • Saturation to zero AP_SAT_ZERO • Symmetrical saturation AP_SAT_SYM • Wrap-around AP_WRAP • Sign magnitude wrap-around AP_WRAP_SM AP_SAT Saturate the value. • To the maximum value in case of overflow. • To the negative maximum value in case of negative overflow. ap_fixed<4, 4, AP_RND, AP_SAT> UAPFixed4 = 19.0; ap_fixed<4, 4, AP_RND, AP_SAT> UAPFixed4 = -19.0; ap_ufixed<4, 4, AP_RND, AP_SAT> UAPFixed4 = 19.0; ap_ufixed<4, 4, AP_RND, AP_SAT> UAPFixed4 = -19.0; Example 4-14: // // // // Yields: Yields: Yields: Yields: 7.0 -8.0 15.0 0.0 AP_SAT Examples AP_SAT_ZERO Force the value to zero in case of overflow, or negative overflow. ap_fixed<4, 4, AP_RND, AP_SAT_ZERO> UAPFixed4 = 19.0; ap_fixed<4, 4, AP_RND, AP_SAT_ZERO> UAPFixed4 = -19.0; ap_ufixed<4, 4, AP_RND, AP_SAT_ZERO> UAPFixed4 = 19.0; ap_ufixed<4, 4, AP_RND, AP_SAT_ZERO> UAPFixed4 = -19.0; Example 4-15: High-Level Synthesis UG902 (v2017.1) April 5, 2017 // // // // Yields: Yields: Yields: Yields: 0.0 0.0 0.0 0.0 AP_SAT_ZERO Examples www.xilinx.com Send Feedback 642 Chapter 4: High-Level Synthesis Reference Guide AP_SAT_SYM Saturate the value: • To the maximum value in case of overflow. • To the minimum value in case of negative overflow. ° Negative maximum for signed ap_fixed types ° Zero for unsigned ap_ufixed types ap_fixed<4, 4, AP_RND, AP_SAT_SYM> UAPFixed4 = 19.0; ap_fixed<4, 4, AP_RND, AP_SAT_SYM> UAPFixed4 = -19.0; ap_ufixed<4, 4, AP_RND, AP_SAT_SYM> UAPFixed4 = 19.0; ap_ufixed<4, 4, AP_RND, AP_SAT_SYM> UAPFixed4 = -19.0; Example 4-16: // // // // Yields: Yields: Yields: Yields: 7.0 -7.0 15.0 0.0 Yields: Yields: Yields: Yields: -1.0 -3.0 3.0 13.0 AP_SAT_SYM Examples AP_WRAP Wrap the value around in case of overflow. ap_fixed<4, 4, AP_RND, AP_WRAP> UAPFixed4 = 31.0; ap_fixed<4, 4, AP_RND, AP_WRAP> UAPFixed4 = -19.0; ap_ufixed<4, 4, AP_RND, AP_WRAP> UAPFixed4 = 19.0; ap_ufixed<4, 4, AP_RND, AP_WRAP> UAPFixed4 = -19.0; Example 4-17: // // // // AP_WRAP Examples If the value of N is set to zero (the default overflow mode): • All MSB bits outside the range are deleted. • For unsigned numbers. After the maximum it wraps around to zero. • For signed numbers. After the maximum, it wraps to the minimum values. If N>0: • When N > 0, N MSB bits are saturated or set to 1. • The sign bit is retained, so positive numbers remain positive and negative numbers remain negative. • The bits that are not saturated are copied starting from the LSB side. AP_WRAP_SM The value should be sign-magnitude wrapped around. ap_fixed<4, 4, AP_RND, AP_WRAP_SM> UAPFixed4 = 19.0; ap_fixed<4, 4, AP_RND, AP_WRAP_SM> UAPFixed4 = -19.0; Example 4-18: High-Level Synthesis UG902 (v2017.1) April 5, 2017 // Yields: -4.0 // Yields: 2.0 AP_WRAP_SM Examples www.xilinx.com Send Feedback 643 Chapter 4: High-Level Synthesis Reference Guide If the value of N is set to zero (the default overflow mode): • This mode uses sign magnitude wrapping. • Sign bit set to the value of the least significant deleted bit. • If the most significant remaining bit is different from the original MSB, all the remaining bits are inverted. • IF MSBs are same, the other bits are copied over. a. Delete redundant MSBs. b. The new sign bit is the least significant bit of the deleted bits. 0 in this case. c. Compare the new sign bit with the sign of the new value. • If different, invert all the numbers. They are different in this case. If N>0: • Uses sign magnitude saturation • N MSBs are saturated to 1. • Behaves similar to a case in which N = 0, except that positive numbers stay positive and negative numbers stay negative. Compiling ap_[u]fixed<> Types To use the ap_[u]fixed<> classes, you must include the ap_fixed.h header file in all source files that reference ap_[u]fixed<> variables. When compiling software models that use these classes, it may be necessary to specify the location of the Vivado HLS header files, for example by adding the “-I//include” option for g++ compilation. Declaring and Defining ap_[u]fixed<> Variables There are separate signed and unsigned classes: • ap_fixed (signed) • ap_ufixed (unsigned) You can create user-defined types with the C/C++ typedef statement: #include "ap_fixed.h" // use ap_[u]fixed<> types typedef ap_ufixed<128,32> uint128_t; // 128-bit user defined type, // 32 integer bits Example 4-19: High-Level Synthesis UG902 (v2017.1) April 5, 2017 User-Defined Types Examples www.xilinx.com Send Feedback 644 Chapter 4: High-Level Synthesis Reference Guide Initialization and Assignment from Constants (Literals) You can initialize ap_[u]fixed variable with normal floating point constants of the usual C/C++ width: • 32 bits for type float • 64 bits for type double That is, typically, a floating point value that is single precision type or in the form of double precision. Note that the value assigned to the fixed-point variable will be limited by the precision of the constant. Use string initialization as described in Initialization and Assignment from Constants (Literals) to ensure that all bits of the fixed-point variable are populated according to the precision described by the string. #include ap_ufixed<30, 15> my15BitInt = 3.1415; ap_fixed<42, 23> my42BitInt = -1158.987; ap_ufixed<99, 40> = 287432.0382911; ap_fixed<36,30> = -0x123.456p-1; The ap_[u]fixed types do not support initialization if they are used in an array of std::complex types. typedef ap_fixed coeff_t; // MUST have IW >= 1 std::complex twid_rom[REAL_SZ/2] = {{ 1, -0 },{ 0.9,-0.006 }, etc.} The initialization values must first be cast to std::complex: typedef ap_fixed coeff_t; // MUST have IW >= 1 std::complex twid_rom[REAL_SZ/2] = {std::complex( 1, -0 ), std::complex(0.9,-0.006 ),etc.} Support for Console I/O (Printing) As with initialization and assignment to ap_[u]fixed<> variables, Vivado HLS supports printing values that require more than 64 bits to represent. The easiest way to output any value stored in an ap_[u]fixed variable is to use the C++ standard output stream, std::cout (#include or ). The stream insertion operator, “<<“, is overloaded to correctly output the full range of values possible for any given ap_[u]fixed variable. The following stream manipulators are also supported, allowing formatting of the value as shown. • dec (decimal) • hex (hexadecimal) • oct (octal) High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 645 Chapter 4: High-Level Synthesis Reference Guide #include // Alternative: #include ap_fixed<6,3, AP_RND, AP_WRAP> Val = 3.25; cout << Val << endl; // Yields: 3.25 Example 4-20: Example Using cout to Print Values Using the Standard C Library You can also use the standard C library (#include ) to print out values larger than 64-bits: 1. Convert the value to a C++ std::string using the ap_[u]fixed classes method to_string(). 2. Convert the result to a null-terminated C character string using the std::string class method c_str(). Optional Argument One (Specifying the Radix) You can pass the ap[u]int::to_string()method an optional argument specifying the radix of the numerical format desired. The valid radix argument values are: • 2 (binary) • 8 (octal • 10 (decimal) • 16 (hexadecimal) (default) Optional Argument Two (Printing as Signed Values) A second optional argument to ap_[u]int::to_string() specifies whether to print the non-decimal formats as signed values. This argument is boolean. The default value is false, causing the non-decimal formats to be printed as unsigned values. ap_fixed<6,3, AP_RND, AP_WRAP> Val = 3.25; printf("%s \n", in2.to_string().c_str()); // Yields: 0b011.010 printf("%s \n", in2.to_string(10).c_str()); //Yields: 3.25 Example 4-21: Printing Binary and Base 10 The ap_[u]fixed types are supported by the following C++ manipulator functions: • setprecision • setw • setfill High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 646 Chapter 4: High-Level Synthesis Reference Guide The setprecision manipulator sets the decimal precision to be used. It takes one parameter f as the value of decimal precision, where n specifies the maximum number of meaningful digits to display in total (counting both those before and those after the decimal point). The default value of f is 6, which is consistent with native c float type. ap_fixed<64, 32> f =3.14159; cout << setprecision (5) << f << endl; cout << setprecision (9) << f << endl; f = 123456; cout << setprecision (5) << f << endl; The example above displays the following results where the printed results are rounded when the actual precision exceeds the specified precision: 3.1416 3.14159 1.2346e+05 The setw manipulator: • Sets the number of characters to be used for the field width. • Takes one parameter w as the value of the width where ° w determines the minimum number of characters to be written in some output representation. If the standard width of the representation is shorter than the field width, the representation is padded with fill characters. Fill characters are controlled by the setfill manipulator which takes one parameter f as the padding character. For example, given: ap_fixed<65,32> aa = 123456; int precision = 5; cout< types Arbitrary precision fixed-point values can participate in expressions that use any operators supported by C/C++. After an arbitrary precision fixed-point type or variable is defined, their usage is the same as for any floating point type or variable in the C/C++ languages. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 647 Chapter 4: High-Level Synthesis Reference Guide Observe the following caveats: • Zero and Sign Extensions All values of smaller bit-width are zero or sign-extended depending on the sign of the source value. You may need to insert casts to obtain alternative signs when assigning smaller bit-widths to larger. • Truncations Truncation occurs when you assign an arbitrary precision fixed-point of larger bit-width than the destination variable. Class Methods, Operators, and Data Members In general, any valid operation that can be done on a native C/C++ integer data type is supported (using operator overloading) for ap_[u]fixed types. In addition to these overloaded operators, some class specific operators and methods are included to ease bit-level operations. Binary Arithmetic Operators Addition ap_[u]fixed::RType ap_[u]fixed::operator + (ap_[u]fixed op) Adds an arbitrary precision fixed-point with a given operand op. The operands can be any of the following integer types: • ap_[u]fixed • ap_[u]int • C/C++ The result type ap_[u]fixed::RType depends on the type information of the two operands. ap_fixed<76, 63> Result; ap_fixed<5, 2> Val1 = 1.125; ap_fixed<75, 62> Val2 = 6721.35595703125; Result = Val1 + Val2; //Yields 6722.480957 Example 4-22: Binary Arithmetic Operator Addition Example Because Val2 has the larger bit-width on both integer part and fraction part, the result type has the same bit-width and plus one to be able to store all possible result values. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 648 Chapter 4: High-Level Synthesis Reference Guide Subtraction ap_[u]fixed::RType ap_[u]fixed::operator - (ap_[u]fixed op) Subtracts an arbitrary precision fixed-point with a given operand op. The result type ap_[u]fixed::RType depends on the type information of the two operands. ap_fixed<76, 63> Result; ap_fixed<5, 2> Val1 = 1625.153; ap_fixed<75, 62> Val2 = 6721.355992351; Result = Val2 - Val1; // Yields 6720.23057 Example 4-23: Binary Arithmetic Operator Subtraction Example Because Val2 has the larger bit-width on both integer part and fraction part, the result type has the same bit-width and plus one to be able to store all possible result values. Multiplication ap_[u]fixed::RType ap_[u]fixed::operator * (ap_[u]fixed op) Multiplies an arbitrary precision fixed-point with a given operand op. ap_fixed<80, 64> Result; ap_fixed<5, 2> Val1 = 1625.153; ap_fixed<75, 62> Val2 = 6721.355992351; Result = Val1 * Val2; // Yields 7561.525452 Example 4-24: Binary Arithmetic Operator Multiplication Example This shows the multiplication of Val1 and Val2. The result type is the sum of their integer part bit-width and their fraction part bit width. Division ap_[u]fixed::RType ap_[u]fixed::operator / (ap_[u]fixed op) Divides an arbitrary precision fixed-point by a given operand op. ap_fixed<84, 66> Result; ap_fixed<5, 2> Val1 = 1625.153; ap_fixed<75, 62> Val2 = 6721.355992351; Result = Val2 / Val1; Example 4-25: High-Level Synthesis UG902 (v2017.1) April 5, 2017 // Yields 5974.538628 Binary Arithmetic Operator Division Example www.xilinx.com Send Feedback 649 Chapter 4: High-Level Synthesis Reference Guide This shows the division of Val1 and Val2. To preserve enough precision: • The integer bit-width of the result type is sum of the integer = bit-width of Val1 and the fraction bit-width of Val2. • The fraction bit-width of the result type is sum of the fraction bit-width of Val1 and the whole bit-width of Val2. Bitwise Logical Operators Bitwise OR ap_[u]fixed::RType ap_[u]fixed::operator | (ap_[u]fixed op) Applies a bitwise operation on an arbitrary precision fixed-point and a given operand op. ap_fixed<75, 62> Result; ap_fixed<5, 2> Val1 = 1625.153; ap_fixed<75, 62> Val2 = 6721.355992351; Result = Val1 | Val2; Example 4-26: // Yields 6271.480957 Bitwise Logical Operator Bitwise OR Example Bitwise AND ap_[u]fixed::RType ap_[u]fixed::operator & (ap_[u]fixed op) Applies a bitwise operation on an arbitrary precision fixed-point and a given operand op. ap_fixed<75, 62> Result; ap_fixed<5, 2> Val1 = 1625.153; ap_fixed<75, 62> Val2 = 6721.355992351; Result = Val1 & Val2; Example 4-27: High-Level Synthesis UG902 (v2017.1) April 5, 2017 // Yields 1.00000 Bitwise Logical Operator Bitwise OR Example www.xilinx.com Send Feedback 650 Chapter 4: High-Level Synthesis Reference Guide Bitwise XOR ap_[u]fixed::RType ap_[u]fixed::operator ^ (ap_[u]fixed op) Applies an xor bitwise operation on an arbitrary precision fixed-point and a given operand op. ap_fixed<75, 62> Result; ap_fixed<5, 2> Val1 = 1625.153; ap_fixed<75, 62> Val2 = 6721.355992351; Result = Val1 ^ Val2; Example 4-28: // Yields 6720.480957 Bitwise Logical Operator Bitwise XOR Example Increment and Decrement Operators Pre-Increment ap_[u]fixed ap_[u]fixed::operator ++ () This operator function prefix increases an arbitrary precision fixed-point variable by 1. ap_fixed<25, 8> Result; ap_fixed<8, 5> Val1 = 5.125; Result = ++Val1; Example 4-29: // Yields 6.125000 Increment and Decrement Operators: Pre-Increment Example Post-Increment ap_[u]fixed ap_[u]fixed::operator ++ (int) This operator function postfix: • Increases an arbitrary precision fixed-point variable by 1. • Returns the original val of this arbitrary precision fixed-point. ap_fixed<25, 8> Result; ap_fixed<8, 5> Val1 = 5.125; Result = Val1++; Example 4-30: High-Level Synthesis UG902 (v2017.1) April 5, 2017 // Yields 5.125000 Increment and Decrement Operators: Post-Increment Example www.xilinx.com Send Feedback 651 Chapter 4: High-Level Synthesis Reference Guide Pre-Decrement ap_[u]fixed ap_[u]fixed::operator -- () This operator function prefix decreases this arbitrary precision fixed-point variable by 1. ap_fixed<25, 8> Result; ap_fixed<8, 5> Val1 = 5.125; Result = --Val1; // Yields 4.125000 Example 4-31: Increment and Decrement Operators: Pre-Decrement Example Post-Decrement ap_[u]fixed ap_[u]fixed::operator -- (int) This operator function postfix: • Decreases this arbitrary precision fixed-point variable by 1. • Returns the original val of this arbitrary precision fixed-point. ap_fixed<25, 8> Result; ap_fixed<8, 5> Val1 = 5.125; Result = Val1--; Example 4-32: // Yields 5.125000 Increment and Decrement Operators: Post-Decrement Example Unary Operators Addition ap_[u]fixed ap_[u]fixed::operator + () Returns a self copy of an arbitrary precision fixed-point variable. ap_fixed<25, 8> Result; ap_fixed<8, 5> Val1 = 5.125; Result = +Val1; // Yields 5.125000 Example 4-33: High-Level Synthesis UG902 (v2017.1) April 5, 2017 Unary Operators: Addition Example www.xilinx.com Send Feedback 652 Chapter 4: High-Level Synthesis Reference Guide Subtraction ap_[u]fixed::RType ap_[u]fixed::operator - () Returns a negative value of an arbitrary precision fixed-point variable. ap_fixed<25, 8> Result; ap_fixed<8, 5> Val1 = 5.125; Result = -Val1; // Yields -5.125000 Example 4-34: Unary Operators: Negation Example Equality Zero bool ap_[u]fixed::operator ! () This operator function: • Compares an arbitrary precision fixed-point variable with 0, • Returns the result. bool Result; ap_fixed<8, 5> Val1 = 5.125; Result = !Val1; Example 4-35: // Yields false Unary Operators: Equality Zero Example Bitwise Inverse ap_[u]fixed::RType ap_[u]fixed::operator ~ () Returns a bitwise complement of an arbitrary precision fixed-point variable. ap_fixed<25, 15> Result; ap_fixed<8, 5> Val1 = 5.125; Result = ~Val1; Example 4-36: // Yields -5.25 Unary Operators: Bitwise Inverse Example Shift Operators Unsigned Shift Left ap_[u]fixed ap_[u]fixed::operator << (ap_uint<_W2> op) This operator function: • Shifts left by a given integer operand. • Returns the result. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 653 Chapter 4: High-Level Synthesis Reference Guide The operand can be a C/C++ integer type: • char • short • int • long The return type of the shift left operation is the same width as the type being shifted. Note: Shift does not support overflow or quantization modes. ap_fixed<25, 15> Result; ap_fixed<8, 5> Val = 5.375; ap_uint<4> sh = 2; Result = Val << sh; Example 4-37: // Yields -10.5 Shift Operators: Unsigned Shift Left Example The bit-width of the result is (W = 25, I = 15). Because the shift left operation result type is same as the type of Val: • The high order two bits of Val are shifted out. • The result is -10.5. If a result of 21.5 is required, Val must be cast to ap_fixed<10, 7> first -- for example, ap_ufixed<10, 7>(Val). Signed Shift Left ap_[u]fixed ap_[u]fixed::operator << (ap_int<_W2> op) This operator: • Shifts left by a given integer operand. • Returns the result. The shift direction depends on whether the operand is positive or negative. • If the operand is positive, a shift right is performed. • If the operand is negative, a shift left (opposite direction) is performed. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 654 Chapter 4: High-Level Synthesis Reference Guide The operand can be a C/C++ integer type: • char • short • int • long The return type of the shift right operation is the same width as the type being shifted. ap_fixed<25, 15, false> Result; ap_uint<8, 5> Val = 5.375; ap_int<4> Sh = 2; Result = Val << sh; // Shift left, yields -10.25 Sh = -2; Result = Val << sh; // Shift right, yields 1.25 Example 4-38: Shift Operators: Signed Shift Left Example Unsigned Shift Right ap_[u]fixed ap_[u]fixed::operator >> (ap_uint<_W2> op) This operator function: • Shifts right by a given integer operand. • Returns the result. The operand can be a C/C++ integer type: • char • short • int • long The return type of the shift right operation is the same width as the type being shifted. ap_fixed<25, 15> Result; ap_fixed<8, 5> Val = 5.375; ap_uint<4> sh = 2; Result = Val >> sh; Example 4-39: High-Level Synthesis UG902 (v2017.1) April 5, 2017 // Yields 1.25 Shift Operators: Unsigned Shift Right Example www.xilinx.com Send Feedback 655 Chapter 4: High-Level Synthesis Reference Guide If it is necessary to preserve all significant bits, extend fraction part bit-width of the Val first, for example ap_fixed<10, 5>(Val). Signed Shift Right ap_[u]fixed ap_[u]fixed::operator >> (ap_int<_W2> op) This operator: • Shifts right by a given integer operand. • Returns the result. The shift direction depends on whether operand is positive or negative. • If the operand is positive, a shift right performed. • If operand is negative, a shift left (opposite direction) is performed. The operand can be a C/C++ integer type (char, short, int, or long). The return type of the shift right operation is the same width as type being shifted. For example: ap_fixed<25, 15, false> Result; ap_uint<8, 5> Val = 5.375; ap_int<4> Sh = 2; Result = Val >> sh; // Shift right, yields 1.25 Sh = -2; Result = Val >> sh; // Shift left, yields -10.5 1.25 Relational Operators Equality bool ap_[u]fixed::operator == (ap_[u]fixed op) This operator compares the arbitrary precision fixed-point variable with a given operand. Returns true if they are equal and false if they are not equal. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 656 Chapter 4: High-Level Synthesis Reference Guide The type of operand op can be ap_[u]fixed, ap_int or C/C++ integer types. For example: bool Result; ap_ufixed<8, 5> Val1 = 1.25; ap_fixed<9, 4> Val2 = 17.25; ap_fixed<10, 5> Val3 = 3.25; Result = Val1 == Val2; Result = Val1 == Val3; // Yields // Yields true false Inequality bool ap_[u]fixed::operator != (ap_[u]fixed op) This operator compares this arbitrary precision fixed-point variable with a given operand. Returns true if they are not equal and false if they are equal. The type of operand op can be: • ap_[u]fixed • ap_int • C or C++ integer types For example: bool Result; ap_ufixed<8, 5> Val1 = 1.25; ap_fixed<9, 4> Val2 = 17.25; ap_fixed<10, 5> Val3 = 3.25; Result = Val1 != Val2; Result = Val1 != Val3; // Yields false // Yields true Greater than or equal to bool ap_[u]fixed::operator >= (ap_[u]fixed op) This operator compares a variable with a given operand. Returns true if they are equal or if the variable is greater than the operator and false otherwise. The type of operand op can be ap_[u]fixed, ap_int or C/C++ integer types. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 657 Chapter 4: High-Level Synthesis Reference Guide For example: bool Result; ap_ufixed<8, 5> Val1 = 1.25; ap_fixed<9, 4> Val2 = 17.25; ap_fixed<10, 5> Val3 = 3.25; Result = Val1 >= Val2; Result = Val1 >= Val3; // Yields true // Yields false Less than or equal to bool ap_[u]fixed::operator <= (ap_[u]fixed op) This operator compares a variable with a given operand, and return true if it is equal to or less than the operand and false if not. The type of operand op can be ap_[u]fixed, ap_int or C/C++ integer types. For example: bool Result; ap_ufixed<8, 5> Val1 = 1.25; ap_fixed<9, 4> Val2 = 17.25; ap_fixed<10, 5> Val3 = 3.25; Result = Val1 <= Val2; Result = Val1 <= Val3; // Yields true // Yields true Greater than bool ap_[u]fixed::operator > (ap_[u]fixed op) This operator compares a variable with a given operand, and return true if it is greater than the operand and false if not. The type of operand op can be ap_[u]fixed, ap_int, or C/C++ integer types. For example: bool Result; ap_ufixed<8, 5> Val1 = 1.25; ap_fixed<9, 4> Val2 = 17.25; ap_fixed<10, 5> Val3 = 3.25; Result = Val1 > Val2; Result = Val1 > Val3; // Yields false // Yields false Less than bool ap_[u]fixed::operator < (ap_[u]fixed op) High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 658 Chapter 4: High-Level Synthesis Reference Guide This operator compares a variable with a given operand, and return true if it is less than the operand and false if not. The type of operand op can be ap_[u]fixed, ap_int, or C/C++ integer types. For example: bool Result; ap_ufixed<8, 5> Val1 = 1.25; ap_fixed<9, 4> Val2 = 17.25; ap_fixed<10, 5> Val3 = 3.25; Result = Val1 < Val2; Result = Val1 < Val3; // Yields false // Yields true Bit Operator Bit-Select and Set af_bit_ref ap_[u]fixed::operator [] (int bit) This operator selects one bit from an arbitrary precision fixed-point value and returns it. The returned value is a reference value that can set or clear the corresponding bit in the ap_[u]fixed variable. The bit argument must be an integer value and it specifies the index of the bit to select. The least significant bit has index 0. The highest permissible index is one less than the bit-width of this ap_[u]fixed variable. The result type is af_bit_ref with a value of either 0 or 1. For example: ap_int<8, 5> Value = 1.375; Value[3]; Value[4]; // Yields // Yields 1 0 Value[2] = 1; Value[3] = 0; // Yields 1.875 // Yields 0.875 Bit Range af_range_ref af_(u)fixed::range (unsigned Hi, unsigned Lo) af_range_ref af_(u)fixed::operator [] (unsigned Hi, unsigned Lo) This operation is similar to bit-select operator [] except that it operates on a range of bits instead of a single bit. It selects a group of bits from the arbitrary precision fixed-point variable. The Hi argument provides the upper range of bits to be selected. The Lo argument provides the lowest bit to be selected. If Lo is larger than Hi the bits selected are returned in the reverse order. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 659 Chapter 4: High-Level Synthesis Reference Guide The return type af_range_ref represents a reference in the range of the ap_[u]fixed variable specified by Hi and Lo. For example: ap_uint<4> Result = 0; ap_ufixed<4, 2> Value = 1.25; ap_uint<8> Repl = 0xAA; Result = Value.range(3, 0); Value(3, 0) = Repl(3, 0); // Yields: 0x5 // Yields: -1.5 // when Lo > Hi, return the reverse bits string Result = Value.range(0, 3); // Yields: 0xA Range Select af_range_ref af_(u)fixed::range () af_range_ref af_(u)fixed::operator [] This operation is the special case of the range select operator []. It selects all bits from this arbitrary precision fixed-point value in the normal order. The return type af_range_ref represents a reference to the range specified by Hi = W - 1 and Lo = 0. For example: ap_uint<4> Result = 0; ap_ufixed<4, 2> Value = 1.25; ap_uint<8> Repl = 0xAA; Result = Value.range(); Value() = Repl(3, 0); // Yields: 0x5 // Yields: -1.5 Length int ap_[u]fixed::length () This function returns an integer value that provides the number of bits in an arbitrary precision fixed-point value. It can be used with a type or a value. For example: ap_ufixed<128, 64> My128APFixed; int bitwidth = My128APFixed.length(); High-Level Synthesis UG902 (v2017.1) April 5, 2017 // Yields 128 www.xilinx.com Send Feedback 660 Chapter 4: High-Level Synthesis Reference Guide Explicit Conversion Methods Fixed-to-double double ap_[u]fixed::to_double () This member function returns this fixed-point value in form of IEEE double precision format. For example: ap_ufixed<256, 77> MyAPFixed = 333.789; double Result; Result = MyAPFixed.to_double(); // Yields 333.789 Fixed-to-ap_int ap_int ap_[u]fixed::to_ap_int () This member function explicitly converts this fixed-point value to ap_int that captures all integer bits (fraction bits are truncated). For example: ap_ufixed<256, 77> MyAPFixed = 333.789; ap_uint<77> Result; Result = MyAPFixed.to_ap_int(); //Yields 333 Fixed-to-integer int ap_[u]fixed::to_int () unsigned ap_[u]fixed::to_uint () ap_slong ap_[u]fixed::to_int64 () ap_ulong ap_[u]fixed::to_uint64 () This member function explicitly converts this fixed-point value to C built-in integer types. For example: ap_ufixed<256, 77> MyAPFixed = 333.789; unsigned int Result; Result = MyAPFixed.to_uint(); //Yields 333 unsigned long long Result; Result = MyAPFixed.to_uint64(); //Yields 333 High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 661 Chapter 4: High-Level Synthesis Reference Guide Compile Time Access to Data Type Attributes The ap_[u]fixed<> types are provided with several static members that allow the size and configuration of data types to be determined at compile time. The data type is provided with the static const members: width, iwidth, qmode and omode: static static static static const const const const int width = _AP_W; int iwidth = _AP_I; ap_q_mode qmode = _AP_Q; ap_o_mode omode = _AP_O; You can use these data members to extract the following information from any existing ap_[u]fixed<> data type: • width: The width of the data type. • iwidth: The width of the integer part of the data type. • qmode: The quantization mode of the data type. • omode: The overflow mode of the data type. For example, you can use these data members to extract the data width of an existing ap_[u]fixed<> data type to create another ap_[u]fixed<> data type at compile time. The following example shows how the size of variable Res is automatically defined as 1-bit greater than variables Val1 and Val2 with the same quantization modes: // Definition of basic data type #define INPUT_DATA_WIDTH 12 #define IN_INTG_WIDTH 6 #define IN_QMODE AP_RND_ZERO #define IN_OMODE AP_WRAP typedef ap_fixed data_t; // Definition of variables data_t Val1, Val2; // Res is automatically sized at run-time to be 1-bit greater than INPUT_DATA_WIDTH // The bit growth in Res will be in the integer bits ap_int Res = Val1 + Val2; This ensures that Vivado HLS correctly models the bit-growth caused by the addition even if you update the value of INPUT_DATA_WIDTH, IN_INTG_WIDTH, or the quantization modes for data_t. Comparison of SystemC and Vivado HLS Types The Vivado HLS types are similar and compatible the SystemC types in virtually all cases and code written using the Vivado HLS types can generally be migrated to a SystemC design and vice-versa. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 662 Chapter 4: High-Level Synthesis Reference Guide There are some differences in the behavior between Vivado HLS types and SystemC types. These differences are discussed in this section and cover the following topics. • Default constructor • Integer division • Integer modulus • Negative shifts • Over-left shift • Range operation • Fixed-point division • Fixed-point right-shift • Fixed-point left-shift Default Constructor In SystemC, the constructor for the following types initializes the values to zero before execution of the program: • sc_[u]int • sc_[u]bigint • sc_[u]fixed The following Vivado HLS types are not initialized by the constructor: • ap_[u]int • ap_[u]fixed Vivado HLS bit-accurate data types: • ap_[u]int No default initialization • ap_[u]fixed No default initialization High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 663 Chapter 4: High-Level Synthesis Reference Guide SystemC bit-accurate data types: • sc_[u]int Default initialization to 0 • sc_big[u]int Default initialization to 0 • sc_[u]fixed Default initialization to 0 CAUTION! When migrating SystemC types to Vivado HLS types, be sure that no variables are read or used in conditionals until they are written to. SystemC designs can be started showing all outputs with a default value of zero, whether or not the output has been written to. The same variables expressed as Vivado HLS types remain unknown until written to. Integer Division When using integer division, Vivado HLS types are consistent with sc_big[u]int types but behave differently than sc_[u]int types. The following figure shows an example. X-Ref Target - Figure 4-15 = ap_(u)int =/ sc_big(u)int sc_(u)int #include “ap_int.h” #include “systemc.h” #include “systemc.h” ap_uint<15>dividend = 32757; ap_int<15>divisor = -2; ap_int<21>ret = dividend/divisor; sc_biguint<15>dividend = 32757; sc_bigint<15>divisor = -2; sc_bigint<21>ret = dividend/divisor; sc_uint<15>dividend = 32757; sc_int<15>divisor = -2; sc_int<21>ret = dividend/divisor; dividend divisor / ret 1 F 32767 7 F F F 7 F F E -2 C 0 0 1 -16383 dividend divisor / ret 1 F 32767 7 F F F 7 F F E -2 C 0 0 1 -16383 dividend divisor / ret 0 0 7 F F F 32767 7 F F E -2 0 0 0 0 0 X14224 Figure 4-15: Integer Division Differences The SystemC sc_int type returns a zero value when an unsigned integer is divided by a negative signed integer. The Vivado HLS types, such as the SystemC sc_bigint type, represent the negative result. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 664 Chapter 4: High-Level Synthesis Reference Guide Integer Modulus When using the modulus operator, Vivado HLS types are consistent with sc_big[u]int types, but behave differently than sc_[u]int types. The following figure shows an example. X-Ref Target - Figure 4-16 = ap_(u)int =/ sc_big(u)int sc_(u)int #include “ap_int.h” #include “systemc.h” #include “systemc.h” ap_uint<15>dividend = 18; ap_int<15>divisor = -5; ap_int<21>ret = dividend%divisor; sc_biguint<15>dividend = 18; sc_bigint<15>divisor = -5; sc_bigint<21>ret = dividend%divisor; sc_uint<15>dividend = 18; sc_int<15>divisor = -5; sc_int<21>ret = dividend%divisor; dividend divisor % ret 0 0 0 0 1 2 18 7 F F B -5 0 0 0 3 3 dividend divisor % ret 0 0 0 0 1 2 18 7 F F B -5 0 0 0 3 3 dividend divisor % ret 0 0 0 0 1 2 18 7 F F B -5 0 0 1 2 18 X14225 Figure 4-16: Integer Modules Differences The SystemC sc_int type returns the value of the dividend of a modulus operation when: • The dividend is an unsigned integer, and • The divisor is a negative signed integer. The Vivado HLS types (such as the SystemC sc_bigint type) returns the positive result of the modulus operation. Negative Shifts When the value of a shift operation is a negative number, Vivado HLS ap_[u]int types shift the value in the opposite direction. For example, it returns a left-shift for a right-shift operation). The SystemC types sc_[u]int and sc_big[u]int behave differently in this case. The following figure shows an example of this operation for both Vivado HLS and SystemC types. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 665 Chapter 4: High-Level Synthesis Reference Guide X-Ref Target - Figure 4-17 =/ ap_(u)int =/ sc_big(u)int sc_(u)int #include “ap_int.h” #include “systemc.h” #include “systemc.h” ap_uint<15>op = 24; ap_int<15>shift = -2; ap_int<21>ret = op>>shift; sc_biguint<15>op = 24; sc_bigint<15>shift = -2; sc_bigint<21>ret = op>>shift; sc_uint<15>op = 24; sc_int<15>shift = -2; sc_int<21>ret = op>>shift; 8 24 7 F F E shift >> 0 0 0 0 6 0 ret 96 op 0 0 1 -2 op 8 24 op 7 F F E shift >> 0 0 0 0 1 8 ret -2 24 shift >> ret 0 0 1 0 0 0 0 1 8 24 7 F F E -2 0 0 0 0 0 X14226 Figure 4-17: Negative Shift Differences The following table summarizes the negative shift differences. Table 4-98: Negative Shift Differences Summary Type Action ap_[u]int Shifts in the opposite direction. sc_[u]int Returns a zero sc_big[u]int Does not shift Over-Shift Left When a shift operation is performed and the result overflows the input variable but not the output or assigned variable, Vivado HLS types and SystemC types behave differently. • Vivado HLS ap_[u]int shifts the value and then assigns meaning to the upper bits that are lost (or overflowed). • Both SystemC sc_big(u)int and sc_(u)int types assign the result and then shift, preserving the upper bits. • The following figure shows an example of this operation for both Vivado HLS and SystemC types. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 666 Chapter 4: High-Level Synthesis Reference Guide X-Ref Target - Figure 4-18 =/ ap_(u)int = sc_big(u)int sc_(u)int #include “ap_int.h” #include “systemc.h” #include “systemc.h” ap_uint<15>op = 0x7234; ap_int<15>shift = 4; ap_int<21>ret = op<op = 0x7234; sc_bigint<15>shift = 4; sc_bigint<21>ret = op<op = 0x7234; sc_int<15>shift = 4; sc_int<21>ret = op<repl = 0xABCDEFLL; sc_int<64>value = 0x12345678LL; value.range(43,8)=repl.range(23,8); sc_uint<64>repl = 0xABCDEFLL; sc_int<64>value = 0x12345678LL; value.range(43,8)=repl.range(23,8); sc_uint<64>repl = 0xABCDEFLL; sc_int<64>value = 0x12345678LL; value.range(43,8)=repl.range(23,8); repl 0000 0000 value 0000 0000 value 0000 0000 CDEF repl 0000 0000 1234 5678 value 0000 0000 00AB CD78 value 0000 0000 00AB CDEF repl 0000 0000 1234 5678 value 0000 0000 1234 5678 12AB CD78 value 0000 0000 00AB CD78 00AB 00AB CDEF Types ap_(u)int and sc_(u)int behave the same X14228 Figure 4-19: Range Operation Differences • Vivado HLS ap_[u]int types and SystemC sc_big[u]int types replace the specified range and extend to fill the target range with zeros. • SystemC sc_big[u]int types update only with the range of the source. Division and Fixed-Point Types When performing division with fixed-point type variables of different sizes, there is a difference in how the fractional values are assigned between Vivado HLS types and SystemC types. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 667 Chapter 4: High-Level Synthesis Reference Guide For ap_[u]fixed types, the fraction is no greater than that of the dividend. SystemC sc_[u]fixed types retain the fractional precision on divide. The fractional part can be retained when using the ap_[u]fixed type by casting to the new variable width before assignment. The following figure shows an example of this operation for both Vivado HLS and SystemC types. X-Ref Target - Figure 4-20 =/ ap_(u)fixed #include “ap_fixed.h” #include “systemc.h” #define SC_INCLUDE_FX ap_fixed<3,3> dividend=2; ap_fixed<4,4> divisor=4; ap_fixed<4,2> ret=dividend/divisor; //casting required to keep precision ap_fixed<4,2> ret2=ap_fixed<4,2>(dividend)/divisor; dividend sc_(u)fixed 0 sc_fixed<3,3> dividend=2; sc_fixed<4,4> divisor=4; sc_fixed<4,2> ret=dividend/divisor; 2.0 dividend 4.0 0 1 0 divisor 0 1 0 0 ret 0 0 0 0 0 0 0 ret2 0 0 0 0 1 0 0.5 Figure 4-20: 0 1 0 divisor 0 1 0 0 ret 0 0 0 0 2.0 0 4.0 1 0 0.5 X14229 Fixed-Point Division Differences Right Shift and Fixed-Point Types Vivado HLS and SystemC behave differently when a right-shift operation is performed • With Vivado HLS fixed-point types, the shift is performed and then the value is assigned. • With SystemC fixed-point types, the value is assigned and then the shift is performed. When the result is a fixed-point type with more fractional bits, the SystemC type preserves the additional accuracy. The following figure shows an example of this operation for both Vivado HLS and SystemC types. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 668 Chapter 4: High-Level Synthesis Reference Guide X-Ref Target - Figure 4-21 =/ ap_(u)fixed #include “ap_fixed.h” sc_(u)fixed #include “systemc.h” #define SC_INCLUDE_FX ap_fixed<5,3,AP_RND,AP_SAT> val=3.75 ap_fixed<5,3,AP_RND,AP_SAT> res=val>>2; ap_fixed<7,3,AP_RND,AP_SAT> res2=val>>2; sc_fixed<5,3 AP_RND,AP_SAT> val=3.75 sc_fixed<5,3,AP_RND,AP_SAT> res=val>>2; sc_fixed<7,3,AP_RND,AP_SAT> res2=val>>2; val 0 1 1 1 1 3.75 val 0 1 1 1 1 3.75 res 0 0 0 1 1 0.75 res 0 0 0 1 1 0.75 res2 0 0 0 1 1 0.75 res2 0 0 0 1 1 0 0 1 1 0.9375 X14230 Figure 4-21: Fixed-Point Differences with Right-Shift The type of quantization mode does not affect the result of the ap_[u]fixed right-shift. Xilinx recommends that you assign to the size of the result type before the shift operation. Left Shift and Fixed-Point Types When performing a left-shift operation with ap_[u]fixed types, the operand is sign-extended, then shifted and then assigned. The SystemC sc_[u]fixed types assign and then shift. In this case, the Vivado HLS types preserve any sign-intention. The following figure shows an example of this operation for both Vivado HLS and SystemC types. X-Ref Target - Figure 4-22 =/ ap_(u)fixed #include “ap_fixed.h” #include “systemc.h” #define SC_INCLUDE_FX ap_fixed<5,3,AP_RND,AP_SAT> val=3.75 ap_fixed<5,3,AP_RND,AP_SAT> res=val<<2; ap_fixed<7,5,AP_RND,AP_SAT> res2=val<<2; 0 val res res2 1 sc_(u)fixed 1 1 1 ap_fixed<5,3,AP_RND,AP_SAT> val=3.75 ap_fixed<5,3,AP_RND,AP_SAT> res=val<<2; ap_fixed<7,5,AP_RND,AP_SAT> res2=val<<2; 1 1 val 0 1 1 1 1 3.75 res 0 1 1 1 1 3.75 res2 1 1 1 0 0 15 3.75 1 1 1 0 0 -1 1 1 1 0 0 -1 0 1 X14231 Figure 4-22: High-Level Synthesis UG902 (v2017.1) April 5, 2017 Fixed-Point Differences with Left-Shift www.xilinx.com Send Feedback 669 Appendix A Additional Resources and Legal Notices Xilinx Resources For support resources such as Answers, Documentation, Downloads, and Forums, see Xilinx Support. Solution Centers See the Xilinx Solution Centers for support on devices, software tools, and intellectual property at all stages of the design cycle. Topics include design assistance, advisories, and troubleshooting tips. Documentation Navigator and Design Hubs Xilinx Documentation Navigator provides access to Xilinx documents, videos, and support resources, which you can filter and search to find information. To open the Xilinx Documentation Navigator (DocNav): • From the Vivado IDE, select Help > Documentation and Tutorials. • On Windows, select Start > All Programs > Xilinx Design Tools > DocNav. • At the Linux command prompt, enter docnav. Xilinx Design Hubs provide links to documentation organized by design tasks and other topics, which you can use to learn key concepts and address frequently asked questions. To access the Design Hubs: • In the Xilinx Documentation Navigator, click the Design Hubs View tab. • On the Xilinx website, see the Design Hubs page. Note: For more information on Documentation Navigator, see the Documentation Navigator page on the Xilinx website. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 670 Appendix A: Additional Resources and Legal Notices References 1. Introduction to FPGA Design with Vivado High-Level Synthesis (UG998) 2. Vivado® Design Suite Tutorial: High-Level Synthesis (UG871) 3. Vivado Design Suite User Guide: Release Notes, Installation, and Licensing (UG973) 4. Floating-Point Design with Vivado HLS (XAPP599) 5. LogiCORE IP Fast Fourier Transform Product Guide (PG109) 6. LogiCORE IP FIR Compiler Product Guide (PG149) 7. LogiCORE IP DDS Compiler Product Guide (PG141) 8. Vivado Design Suite AXI Reference Guide (UG1037) 9. Accelerating OpenCV Applications with Zynq-7000 All Programmable SoC Using Vivado HLS Video Libraries (XAPP1167) 10. UltraFast™ High-Level Productivity Design Methodology Guide (UG1197) 11. Option Summary page on the GCC website (gcc.gnu.org/onlinedocs/gcc/Option-Summary.html) 12. Accellera website (www.accellera.org) 13. AWGN page on the MathWorks website (www.mathworks.com/help/comm/ug/awgn-channel.html) 14. Vivado Design Suite Documentation Training Resources Xilinx provides a variety of training courses and QuickTake videos to help you learn more about the concepts presented in this document. Use these links to explore related training resources: 1. C-based Design: High-Level Synthesis with the Vivado HLS Tool Training Course 2. C-based HLS Coding for Hardware Designers Training Course 3. C-based HLS Coding for Software Designers Training Course 4. Vivado Design Suite QuickTake Video: Getting Started with Vivado High-Level Synthesis 5. Vivado Design Suite QuickTake Video Tutorials High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 671 Appendix A: Additional Resources and Legal Notices Please Read: Important Legal Notices The information disclosed to you hereunder (the “Materials”) is provided solely for the selection and use of Xilinx products. To the maximum extent permitted by applicable law: (1) Materials are made available "AS IS" and with all faults, Xilinx hereby DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS, IMPLIED, OR STATUTORY, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, OR FITNESS FOR ANY PARTICULAR PURPOSE; and (2) Xilinx shall not be liable (whether in contract or tort, including negligence, or under any other theory of liability) for any loss or damage of any kind or nature related to, arising under, or in connection with, the Materials (including your use of the Materials), including for any direct, indirect, special, incidental, or consequential loss or damage (including loss of data, profits, goodwill, or any type of loss or damage suffered as a result of any action brought by a third party) even if such damage or loss was reasonably foreseeable or Xilinx had been advised of the possibility of the same. Xilinx assumes no obligation to correct any errors contained in the Materials or to notify you of updates to the Materials or to product specifications. You may not reproduce, modify, distribute, or publicly display the Materials without prior written consent. Certain products are subject to the terms and conditions of Xilinx’s limited warranty, please refer to Xilinx’s Terms of Sale which can be viewed at https://www.xilinx.com/legal.htm#tos; IP cores may be subject to warranty and support terms contained in a license issued to you by Xilinx. Xilinx products are not designed or intended to be fail-safe or for use in any application requiring fail-safe performance; you assume sole risk and liability for use of Xilinx products in such critical applications, please refer to Xilinx’s Terms of Sale which can be viewed at https://www.xilinx.com/legal.htm#tos. AUTOMOTIVE APPLICATIONS DISCLAIMER AUTOMOTIVE PRODUCTS (IDENTIFIED AS “XA” IN THE PART NUMBER) ARE NOT WARRANTED FOR USE IN THE DEPLOYMENT OF AIRBAGS OR FOR USE IN APPLICATIONS THAT AFFECT CONTROL OF A VEHICLE (“SAFETY APPLICATION”) UNLESS THERE IS A SAFETY CONCEPT OR REDUNDANCY FEATURE CONSISTENT WITH THE ISO 26262 AUTOMOTIVE SAFETY STANDARD (“SAFETY DESIGN”). CUSTOMER SHALL, PRIOR TO USING OR DISTRIBUTING ANY SYSTEMS THAT INCORPORATE PRODUCTS, THOROUGHLY TEST SUCH SYSTEMS FOR SAFETY PURPOSES. USE OF PRODUCTS IN A SAFETY APPLICATION WITHOUT A SAFETY DESIGN IS FULLY AT THE RISK OF CUSTOMER, SUBJECT ONLY TO APPLICABLE LAWS AND REGULATIONS GOVERNING LIMITATIONS ON PRODUCT LIABILITY. © Copyright 2012-2017 Xilinx, Inc. Xilinx, the Xilinx logo, Artix, ISE, Kintex, Spartan, Virtex, Vivado, Zynq, and other designated brands included herein are trademarks of Xilinx in the United States and other countries. OpenCL and the OpenCL logo are trademarks of Apple Inc. used by permission by Khronos. All other trademarks are the property of their respective owners. High-Level Synthesis UG902 (v2017.1) April 5, 2017 www.xilinx.com Send Feedback 672