JSON File for RTL Blackbox - 2021.2 English

Vitis High-Level Synthesis User Guide (UG1399)
Document ID
UG1399
Release Date
2021-12-15
Version
2021.2 English

JSON File Format

The following table describes the JSON file format:

Table 1. JSON File Format
Item 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. Refer to the RTL Port Protocols table for additional details.
wire
An argument can be mapped to wire if it is a scalar or 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.
ap_ctrl_chain_protocol_start The ap_start signal in the ap_ctrl_chain protocol for the RTL blackbox module.
ap_ctrl_chain_protocol_ready The ap_ready signal in the ap_ctrl_chain protocol for the RTL blackbox IP.
ap_ctrl_chain_protocol_done The ap_done signal in the ap_ctrl_chain protocol for blackbox RTL module.
ap_ctrl_chain_protocol_continue The ap_continue signal in the ap_ctrl_chain protocol for RTL blackbox module.
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.
BRAM 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 RAM Type C Port Direction Attribute User-Defined Name Notes
wire in data_read_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
data_write_valid
ap_ovld inout data_read_in
data_write_out
data_write_valid
FIFO in FIFO_empty_flag Must be negative valid.
FIFO_read_enable
FIFO_data_read_in
out FIFO_full_flag Must be negative valid.
FIFO_write_enable
FIFO_data_write_out
RAM RAM_1P in RAM_address
RAM_clock_enable
RAM_data_read_in
out RAM_address
RAM_clock_enable
RAM_write_enable
RAM_data_write_out
inout RAM_address
RAM_clock_enable
RAM_write_enable
RAM_data_write_out
RAM_data_read_in
RAM RAM_T2P in RAM_address 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
RAM_data_read_in
RAM_address_snd
RAM_clock_enable_snd
RAM_data_read_in_snd
out RAM_address
RAM_clock_enable
RAM_write_enable
RAM_data_write_out
RAM_address_snd
RAM_clock_enable_snd
RAM_write_enable_snd
RAM_data_write_out_snd
inout RAM_address
RAM_clock_enable
RAM_write_enable
RAM_data_write_out
RAM_data_read_in
RAM_address_snd
RAM_clock_enable_snd
RAM_write_enable_snd
RAM_data_write_out_snd
RAM_data_read_in_snd
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"
                       }
}