A newer version of this document is available. Customers should click here to go to the newest version.
Visible to Intel only — GUID: GUID-FBD2FC3B-E756-4BBB-A65F-77421C14D5C9
Visible to Intel only — GUID: GUID-FBD2FC3B-E756-4BBB-A65F-77421C14D5C9
Object Manifest File Syntax of an RTL Library
This section provides the syntax of a simple object manifest file for an RTL library that implements double-precision square root function. The RTL library is implemented in VHDL with a Verilog wrapper.
The following object manifest file is for an RTL library named my_fp_sqrt_double (line 2) that implements a SYCL helper function named my_sqrtfd (line 2):
<RTL_SPEC> <FUNCTION name="my_sqrtfd" module="my_fp_sqrt_double"> <ATTRIBUTES> <IS_STALL_FREE value="yes"/> <IS_FIXED_LATENCY value="yes"/> <EXPECTED_LATENCY value="31"/> <CAPACITY value="1"/> <HAS_SIDE_EFFECTS value="no"/> <ALLOW_MERGING value="yes"/> </ATTRIBUTES> <INTERFACE> <AVALON port="clock" type="clock"/> <AVALON port="resetn" type="resetn"/> <AVALON port="ivalid" type="ivalid"/> <AVALON port="iready" type="iready"/> <AVALON port="ovalid" type="ovalid"/> <AVALON port="oready" type="oready"/> <INPUT port="datain" width="64"/> <OUTPUT port="dataout" width="64"/> </INTERFACE> <C_MODEL> <FILE name="c_model.cl" /> </C_MODEL> <REQUIREMENTS> <FILE name="my_fp_sqrt_double_s5.v" /> <FILE name="fp_sqrt_double_s5.vhd" /> </REQUIREMENTS> <RESOURCES> <ALUTS value="2057"/> <FFS value="3098"/> <RAMS value="15"/> <MLABS value="43"/> <DSPS value="1.5"/> </RESOURCES> </FUNCTION> </RTL_SPEC>
XML Element |
Description |
|---|---|
RTL_SPEC |
Top-level element in the object manifest file. There can only be one such top-level element in the file. In the above example, the name RTL_SPEC is historic and carries no file-specific meaning. |
FUNCTION |
Element that defines the SYCL function that the RTL library implements. The name attribute within the FUNCTION element specifies the function’s name. You can have multiple FUNCTION elements, each declaring a different function that you can call from the SYCL kernel. The same RTL library can implement multiple functions by specifying different parameters. |
ATTRIBUTES |
Element containing other XML elements that describe various characteristics (for example, latency) of the RTL library. The example RTL library takes one PARAMETER setting named WIDTH, which has a value of 32. Refer to XML Elements for ATTRIBUTES section below for more details about other ATTRIBUTES-specific elements.
NOTE:
If you create multiple SYCL helper functions for different libraries, or use the same RTL library with different PARAMETER settings, you must create a separate FUNCTION element for each function.
|
INTERFACE |
Element containing other XML elements that describe the RTL library’s interface. The example object manifest file shows the Avalon® streaming interface signals that every RTL library must provide (that is, clock, resetn, ivalid, iready, ovalid, and oready). The resetn signal is active low. Its synchronicity depends on the target device:
NOTE:
The signal names must match the ones specified in the .xml file. An error occurs during library creation if a signal name is inconsistent.
|
C_MODEL |
Element specifying one or more files that implement SYCL model for the function. The model is used only during emulation. However, the C_MODEL element and the associated file(s) must be present when you create the library file. |
REQUIREMENTS |
Element specifying one or more RTL resource files (that is, .v, .sv, .vhd, .hex, and .mif). The specified paths to these files are relative to the location of the object manifest file. Each RTL resource file becomes part of the associated Platform Designer component that corresponds to the entire SYCL system.
NOTE:
The SYCL library feature does not support .qip files. The Intel® oneAPI DPC++/C++ Compiler error occurs if you compile a SYCL kernel while using a library that includes an unsupported resource file type.
|
RESOURCES |
Optional element specifying the FPGA resources that the RTL library uses. If you do not specify this element, the FPGA resources that the RTL library uses defaults to zero. |
XML Elements for ATTRIBUTES
In the object manifest file of the RTL library, there are XML elements under ATTRIBUTES that you can specify to set the library’s characteristics.
XML Element |
Description |
|---|---|
IS_STALL_FREE |
Instructs the compiler properly handle all stall and valid signals. In this case, the compiler can save some area by not generating stall logic around your RTL libarary. Set IS_STALL_FREE to "yes" to indicate that the library neither generates stalls internally nor can it properly handle incoming stalls. The library simply ignores its stall input. If you set IS_STALL_FREE to "no", the library must properly handle all stall and valid signals.
NOTE:
If you set IS_STALL_FREE to "yes", you must also set IS_FIXED_LATENCY to "yes". Also, if the RTL library has an internal state, it must properly handle ivalid=0 inputs. An incorrect IS_STALL_FREE setting leads to incorrect results in hardware.
|
IS_FIXED_LATENCY |
Indicates whether the RTL library has a fixed latency. Set IS_FIXED_LATENCY to "yes" if the RTL library always takes a known number of clock cycles to compute its output. The value you assign to the EXPECTED_LATENCY element specifies the number of clock cycles. The safe value for IS_FIXED_LATENCY is "no". When you set IS_FIXED_LATENCY="no", the EXPECTED_LATENCY value must be at least 1.
NOTE:
For a given library, you may set IS_FIXED_LATENCY to "yes" and IS_STALL_FREE to "no". Such a library produces its output in a fixed number of clock cycles and handles stall signals properly.
|
EXPECTED_LATENCY |
Specifies the expected latency of the RTL library. If you set IS_FIXED_LATENCY to "yes", the EXPECTED_LATENCY value indicates the number of pipeline stages inside the library. In this case, you must set this value to be the exact latency of the library. Otherwise, the compiler generates incorrect hardware. For a library with variable latency, the compiler balances the pipeline around this library to the EXPECTED_LATENCY value that you specify. For libraries that can stall and require use of signals such as iready, set the EXPECTED_LATENCY value to at least 1. The specified value and the actual latency might differ, which might affect the number of stalls inside the pipeline. However, the resulting hardware is correct. |
CAPACITY |
Specifies the number of multiple inputs that the library can process simultaneously. You must specify a value for CAPACITY if you also set IS_STALL_FREE="no" and IS_FIXED_LATENCY="no". Otherwise, you do not need to specify a value for CAPACITY. If CAPACITY is strictly less than EXPECTED_LATENCY, the compiler automatically inserts capacity-balancing FIFO buffers after this library when necessary. The safe value for CAPACITY is 1. |
HAS_SIDE_EFFECTS |
Indicates whether the RTL library has side effects. Libraries that have internal states or communicate with external memories are examples of libraries with side effects. Set HAS_SIDE_EFFECTS to "yes" to indicate that the library has side effects. Specifying HAS_SIDE_EFFECTS to "yes" ensures that optimization efforts do not remove calls to libraries with side effects. Stall-free libraries with side effects (that is, IS_STALL_FREE="yes" and HAS_SIDE_EFFECTS="yes") must properly handle ivalid=0 input cases because the library might receive invalid data occasionally. The safe value for HAS_SIDE_EFFECTS is "yes". |
ALLOW_MERGING |
Instructs the compiler to merge multiple instances of the RTL library. Set ALLOW_MERGING to "yes" to allow merging of multiple instances of the library. Intel® recommends setting ALLOW_MERGING to "yes". The safe value for ALLOW_MERGING is "no".
NOTE:
Marking the library with HAS_SIDE_EFFECTS="yes" does not prevent merging.
|
PARAMETER |
Specifies the value of an RTL library parameter. PARAMETER attributes:
NOTE:
You can specify the value for an RTL library parameter using either a value or a type attribute.
|
XML Elements for INTERFACE
In the object manifest file of the RTL library within a SYCL library, there are XML elements under INTERFACE that you can define to specify aspects of the RTL library’s interface (for example, Avalon® streaming interface).
XML Element |
Description |
|---|---|
INPUT |
Specifies the RTL library input parameter. INPUT attributes:
The input parameters are concatenated to form the input stream.
NOTE:
Aggregate data structures, such as structs and arrays, are not supported as input parameters.
|
OUTPUT |
Specifies the RTL library output parameter. OUTPUT attributes:
The return value from the input stream is sent out via the output parameter on the output stream.
NOTE:
Aggregate data structures, such as structs and arrays, are not supported as input parameters.
|
XML Elements for RESOURCES
In the object manifest file of the RTL library within a SYCL library, there are optional elements under RESOURCES that you can define to specify the FPGA resource utilization of the library. If you do not specify a particular element, it has a default value of zero.
XML Element |
Description |
|---|---|
ALUTS |
Specifies the number of combinational adaptive look-up tables (ALUTs) that the library uses. |
FFS |
Specifies the number of dedicated logic registers that the library uses. |
RAMS |
Specifies the number of block RAMs that the library uses. |
DSPS |
Specifies the number of digital signal processing (DSP) blocks that the library uses. |
MLABS |
Specifies the number of memory logic arrays (MLABs) that the library uses. This value is equal to the number of adaptive logic modules (ALMs) that is used for memory divided by 10 because each MLAB consumes 10 ALMs. |