JSON File for RTL Blackbox - 2024.2 English - UG1399

Vitis High-Level Synthesis User Guide (UG1399)

Document ID
UG1399
Release Date
2024-11-13
Version
2024.2 English

JSON File Format

The following table describes the JSON file format:

Table 1. JSON File Format
Item JSON Attribute Description
c_function_name   The C++ function name for the blackbox. The c_function_name must be consistent with the C function simulation model.
rtl_top_module_name   The RTL function name for the blackbox. The rtl_top_module_name must be consistent with the c_function_name.
c_files c_file Specifies the C file used for the blackbox module.
cflag Provides any compile option necessary for the corresponding C file.
rtl_files Specifies the RTL files for the blackbox module.
c_parameters c_name

Specifies the name of the argument used for the black box C++ function.

Unused c_parameters should be deleted from the template.

c_port_direction The access direction for the corresponding C argument.
in
Read only by blackbox C++ function.
out
Write only by blackbox C++ function.
inout
Will both read and write by blackbox C++ function.
RAM_type Specifies the RAM type to use if the corresponding C argument uses the RTL RAM protocol. Two type of RAM are used:
RAM_1P
For 1 port RAM module
RAM_T2P
For 2 port RAM module
Omit this attribute when the corresponding C argument is not using RTL 'RAM' protocol.
rtl_ports Specifies the RTL port protocol signals for the corresponding C argument (c_name). Every c_parameter should be associated with an rtl_port.
Five type of RTL port protocols are used, and only wire and FIFO are supported for the ap_ctrl_none control protocol. Refer to the RTL Port Protocols table for additional details.
wire
An argument can be mapped to wire if it is a either a scalar with in or out direction, or a pointer with 'in' direction.
ap_vld
An argument can be mapped to ap_vld if it uses pointer with 'out' direction.
ap_ovld
An argument can be mapped to ap_ovld if it use a pointer with an inout direction.
FIFO
An argument can be mapped to FIFO if it uses the hls::stream data type.
RAM
An argument can be mapped to RAM if it uses an array type. The array type supports inout directions.
The specified RTL port protocols have associated control signals, which also need to be specified in the JSON file.
c_return c_port_direction It must be out.
rtl_ports Specifies the corresponding RTL port name used in the RTL blackbox IP.
rtl_common_signal module_clock The unique clock signal for RTL blackbox module.
module_reset Specifies the reset signal for RTL blackbox module. The reset signal must be active-High or positive valid.
module_clock_enable Specifies the clock enable signal for the RTL blackbox module. The enable signal must be active-High or positive valid.
ap_ctrl_chain_protocol_idle The ap_idle signal in the ap_ctrl_chain protocol for the RTL blackbox module. This signal must be an empty string for the ap_ctrl_none control protocol.
ap_ctrl_chain_protocol_start The ap_start signal in the ap_ctrl_chain protocol for the RTL blackbox module. This signal must be an empty string for the ap_ctrl_none control protocol.
ap_ctrl_chain_protocol_ready The ap_ready signal in the ap_ctrl_chain protocol for the RTL blackbox IP. This signal must be an empty string for the ap_ctrl_none control protocol.
ap_ctrl_chain_protocol_done The ap_done signal in the ap_ctrl_chain protocol for blackbox RTL module. This signal must be an empty string for the ap_ctrl_none control protocol.
ap_ctrl_chain_protocol_continue The ap_continue signal in the ap_ctrl_chain protocol for RTL blackbox module. This signal must be an empty string for the ap_ctrl_none control protocol.
rtl_performance latency Specifies the Latency of the RTL blackbox module. It must be a non-negative integer value. For Combinatorial RTL IP specify 0, otherwise specify the exact latency of the RTL module.
II Number of clock cycles before the function can accept new input data. It must be non-negative integer value. 0 means the blackbox can not be pipelined. Otherwise, it means the blackbox module is pipelined.
rtl_resource_usage FF Specifies the register utilization for the RTL blackbox module.
LUT Specifies the LUT utilization for the RTL blackbox module.
block RAM Specifies the block RAM utilization for the RTL blackbox module.
URAM Specifies the URAM utilization for the RTL blackbox module.
DSP Specifies the DSP utilization for the RTL blackbox module.
Table 2. RTL Port Protocols
RTL Port Protocol C Port Direction JSON Attribute RTL Port Direction User-Defined Name Notes
wire in data_read_in in Specifies a user defined name used in the RTL blackbox IP. As an example for wire, if the RTL port name is "flag" then the JSON FILE format is "data_read-in" : "flag".  
ap_vld out data_write_out out
data_write_valid out
ap_ovld inout data_read_in in
data_write_out out
data_write_valid out
FIFO in FIFO_empty_flag in Must be negative valid.
FIFO_read_enable out  
FIFO_data_read_in in
out FIFO_full_flag in Must be negative valid.
FIFO_write_enable out  
FIFO_data_write_out out
RAM (RAM_1P) in RAM_address out  
RAM_clock_enable out
RAM_data_read_in in
out RAM_address out
RAM_clock_enable out
RAM_write_enable out
RAM_data_write_out out
inout RAM_address in
RAM_clock_enable in
RAM_write_enable out
RAM_data_write_out out
RAM_data_read_in in
RAM (RAM_T2P) in RAM_address out Specifies a user defined name used in the RTL blackbox IP. As an example for wire, if the RTL port name is "flag" then the JSON FILE format is "data_read-in" : "flag". Signals with _snd belong to the second port of the RAM. Signals without _snd belong to the first port.
RAM_clock_enable out
RAM_data_read_in in
RAM_address_snd out
RAM_clock_enable_snd out
RAM_data_read_in_snd in
out RAM_address out
RAM_clock_enable out
RAM_write_enable out
RAM_data_write_out out
RAM_address_snd out
RAM_clock_enable_snd out
RAM_write_enable_snd out
RAM_data_write_out_snd out
inout RAM_address out
RAM_clock_enable out
RAM_write_enable out
RAM_data_write_out out
RAM_data_read_in in
RAM_address_snd out
RAM_clock_enable_snd out
RAM_write_enable_snd out
RAM_data_write_out_snd out
RAM_data_read_in_snd in
Note: The behavioral C-function model for the RTL blackbox must also adhere to the recommended HLS coding styles.

JSON File Example

This section provides details on manually writing the JSON file required for the RTL blackbox. The following is an example of a JSON file:

{
"c_function_name" : "foo",
"rtl_top_module_name" : "foo",
"c_files" :
      [
            {
              "c_file" : "../../a/top.cpp",
              "cflag" : ""
            },
            {
              "c_file" : "xx.cpp",
              "cflag" : "-D KF"
            }
           ],
"rtl_files" : [
                "../../foo.v",
                "xx.v"
              ],
"c_parameters" : [{
                   "c_name" : "a",
                   "c_port_direction" : "in",
                   "rtl_ports" : {
                                  "data_read_in" : "a"
                                 }
                  },
                  {
                   "c_name" : "b",
                   "c_port_direction" : "in",
                   "rtl_ports" : {
                                  "data_read_in" : "b"
                                 }
                  },
                  {
                   "c_name" : "c",
                   "c_port_direction" : "out",
                   "rtl_ports" : {
                                   "data_write_out" : "c",
                                   "data_write_valid" : "c_ap_vld"
                                 }
                  },
                  {
                   "c_name" : "d",
                   "c_port_direction" : "inout",
                   "rtl_ports" : {
                                   "data_read_in" : "d_i",
                                   "data_write_out" : "d_o",
                                   "data_write_valid" : "d_o_ap_vld"
                                 }
                  },
                  {
                   "c_name" : "e",
                   "c_port_direction" : "in",
                   "rtl_ports" : {
                                   "FIFO_empty_flag" : "e_empty_n",
                                   "FIFO_read_enable" : "e_read",
                                   "FIFO_data_read_in" : "e"
                                 }
                  },
                  {
                   "c_name" : "f",
                   "c_port_direction" : "out",
                   "rtl_ports" : {
                                   "FIFO_full_flag" : "f_full_n",
                                   "FIFO_write_enable" : "f_write",
                                   "FIFO_data_write_out" : "f"
                                 }
                  },
                  {
                   "c_name" : "g",
                   "c_port_direction" : "in",
                   "RAM_type" : "RAM_1P",
                   "rtl_ports" : {
                                   "RAM_address" : "g_address0",
                                   "RAM_clock_enable" : "g_ce0",
                                   "RAM_data_read_in" : "g_q0"
                                 }
                  },
                  {
                   "c_name" : "h",
                   "c_port_direction" : "out",
                   "RAM_type" : "RAM_1P",
                   "rtl_ports" : {
                                   "RAM_address" : "h_address0",
                                   "RAM_clock_enable" : "h_ce0",
                                   "RAM_write_enable" : "h_we0",
                                   "RAM_data_write_out" : "h_d0"
                                 }
                  },
                  {
                   "c_name" : "i",
                   "c_port_direction" : "inout",
                   "RAM_type" : "RAM_1P",
                   "rtl_ports" : {
                                   "RAM_address" : "i_address0",
                                   "RAM_clock_enable" : "i_ce0",
                                   "RAM_write_enable" : "i_we0",
                                   "RAM_data_write_out" : "i_d0",
                                   "RAM_data_read_in" : "i_q0"
                                 }
                  },
                  {
                   "c_name" : "j",
                   "c_port_direction" : "in",
                   "RAM_type" : "RAM_T2P",
                   "rtl_ports" : {
                                   "RAM_address" : "j_address0",
                                   "RAM_clock_enable" : "j_ce0",
                                   "RAM_data_read_in" : "j_q0",
                                   "RAM_address_snd" : "j_address1",
                                   "RAM_clock_enable_snd" : "j_ce1",
                                   "RAM_data_read_in_snd" : "j_q1"
                                 }
                  },
                  {
                   "c_name" : "k",
                   "c_port_direction" : "out",
                   "RAM_type" : "RAM_T2P",
                   "rtl_ports" : {
                                   "RAM_address" : "k_address0",
                                   "RAM_clock_enable" : "k_ce0",
                                   "RAM_write_enable" : "k_we0",
                                   "RAM_data_write_out" : "k_d0",
                                   "RAM_address_snd" : "k_address1",
                                   "RAM_clock_enable_snd" : "k_ce1",
                                   "RAM_write_enable_snd" : "k_we1",
                                   "RAM_data_write_out_snd" : "k_d1"
                                 }
                  },
                  {
                   "c_name" : "l",
                   "c_port_direction" : "inout",
                   "RAM_type" : "RAM_T2P",
                   "rtl_ports" : {
                                   "RAM_address" : "l_address0",
                                   "RAM_clock_enable" : "l_ce0",
                                   "RAM_write_enable" : "l_we0",
                                   "RAM_data_write_out" : "l_d0",
                                   "RAM_data_read_in" : "l_q0",
                                   "RAM_address_snd" : "l_address1",
                                   "RAM_clock_enable_snd" : "l_ce1",
                                   "RAM_write_enable_snd" : "l_we1",
                                   "RAM_data_write_out_snd" : "l_d1",
                                   "RAM_data_read_in_snd" : "l_q1"
                                 }
                  }],
"c_return" : {
               "c_port_direction" : "out",
               "rtl_ports" : {
                               "data_write_out" : "ap_return"
                             }
             },
"rtl_common_signal" : {
                        "module_clock" : "ap_clk",
                        "module_reset" : "ap_rst",
                        "module_clock_enable" : "ap_ce",
                        "ap_ctrl_chain_protocol_idle" : "ap_idle",
                        "ap_ctrl_chain_protocol_start" : "ap_start",
                        "ap_ctrl_chain_protocol_ready" : "ap_ready",
                        "ap_ctrl_chain_protocol_done" : "ap_done",
                        "ap_ctrl_chain_protocol_continue" : "ap_continue"
                       },
"rtl_performance" : {
                     "latency" : "6",
                     "II" : "2"
                    },
"rtl_resource_usage" : {
                        "FF" : "0",
                        "LUT" : "0",
                        "BRAM" : "0",
                        "URAM" : "0",
                        "DSP" : "0"
                       }
}