Adding RTL Blackbox Functions - 2024.2 English - UG1399

The RTL blackbox enables the use of existing Verilog RTL IP in an HLS project. This lets you add RTL code to your C/C++ code for synthesis of the project by Vitis HLS. The RTL IP can be used in a sequential, pipeline, or dataflow region. Refer to Vitis-HLS-Introductory-Examples/Misc/rtl_as_blackbox on GitHub for examples of this technique.

Integrating RTL IP into a Vitis HLS project requires the following files:

• C function signature for the RTL code. This can be placed into a header (.h) file.
• Blackbox JSON description file as discussed in JSON File for RTL Blackbox.
• RTL IP files.

To use the RTL blackbox in an HLS project, use the following steps.

1. Call the C function signature from within your top-level function, or a sub-function in the Vitis HLS project.
2. Add the blackbox JSON description file to your HLS project using the Add Files command from the Vitis HLS IDE as discussed in Creating an HLS Component, or using the add_files command:

   add_files –blackbox my_file.json

   Tip: As explained in the next section, the new RTL Blackbox wizard can help you generate the JSON file and add the RTL IP to your project.
3. Run the Vitis HLS design flow for simulation, synthesis, and co-simulation as usual.

Requirements and Limitations

RTL IP used in the RTL blackbox feature have the following requirements:

• Should be Verilog (.v) code.
• Must have a unique clock signal, and a unique active-High reset signal.
• Must have a CE signal that is used to enable or stall the RTL IP.
• Can use either the ap_ctrl_chain or ap_ctrl_none block level control protocols as described in Block-Level Control Protocols.

Within Vitis HLS, the RTL blackbox feature:

• Supports only C++.
• Cannot connect to top-level interface I/O signals.
• Cannot directly serve as the design-under-test (DUT).
• Does not support struct or class type interfaces.
• Supports the following interface protocols for ap_ctrl_none as described in JSON File for RTL Blackbox:

  Wire inputs and outputs

  For pipeline with II=1 (see rtl_ports attribute in the JSON File Format table in JSON File for RTL Blackbox)

  FIFO Inputs and Outputs

  For dataflow with streams

• Supports the following interface protocols for ap_ctrl_chain as described in JSON File for RTL Blackbox:

  hls::stream

  The RTL blackbox IP supports the hls::stream interface. When this data type is used in the C function, use a FIFO RTL port protocol for this argument in the RTL blackbox IP.

  Arrays

  The RTL blackbox IP supports RAM interface for arrays. For array arguments in the C function, use one of the following RTL port protocols for the corresponding argument in the RTL blackbox IP:

  • Single port RAM – RAM_1P
  • Dual port RAM – RAM_T2P

  Scalars and Input Pointers

  The RTL Blackbox IP supports C scalars and input pointers only in sequential and pipeline regions. They are not supported in a dataflow region. When these constructs are used in the C function, use wire port protocol in the RTL IP.

  Inout and Output Pointers

  The RTL blackbox IP supports inout and output pointers only in sequential and pipeline regions. They are not supported in a dataflow region. When these constructs are used in the C function, the RTL IP should use ap_vld for output pointers, and ap_ovld for inout pointers.