Adding RTL Blackbox Functions - 2023.1 English

Vitis High-Level Synthesis User Guide (UG1399)

Document ID
UG1399
Release Date
2023-07-17
Version
2023.1 English

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.

Tip: Adding an RTL blackbox to your design will restrict the tool from outputting VHDL code, Because the RTL blackbox must be Verilog, the output will be Verilog only.

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 a New Vitis HLS Project, 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.
  • Must use the ap_ctrl_chain protocol 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 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.
Tip: All other Vitis HLS design restrictions also apply when using RTL blackbox in your project.