RTL Kernels

To satisfy the Vitis core development kit execution model, an RTL kernel must adhere to the requirements described in Kernel Properties. The RTL kernel must have at least one clock interface port to supply a clock to the kernel logic. The various interface requirements are summarized in the following table.

RTL kernels can optionally have an interrupt port containing a single interrupt. The port name must be called interrupt and be active-High. It is enabled when both the global interrupt enable (GIE) and interrupt enable register (IER) bits are asserted.

By default, the IER uses the internal ap_done signal to trigger an interrupt. Further, the interrupt is cleared only when writing a one to bit-0 of the IP Interrupt Status Register.

If adding an interrupt port to the RTL kernel, the kernel.xml file needs to include this information. The kernel.xml, located in the kernel.xo file, is generated automatically when using the package_xo command, or RTL Kernel Wizard. By default, the kernel uses a single interrupt port, interrupt, along with the interrupt logic in the Control Register block. This is reflected in the generated Verilog code for the RTL kernel, and the associated component.xml and kernel.xml files.

The final step is to package the RTL IP into a Xilinx object file (.xo), so the kernel can be used in the Vitis core development kit. This is done using the package_xo Tcl command in the Vivado Design Suite.

The package_xo command uses the component.xml file from the IP to create the necessary kernel.xml if possible. The Vivado tool runs design rule checks as a pre-processor for package_xo to determine that everything is available and either processes the IP to create the .xo file, or returns errors indicating any problems that might exist.

The following example packages an RTL kernel IP named test_sincos into an object file named test.xo. After packaging the IP, the package_xo command is run from within the Vivado tool.

package_xo -xo_path ./test.xo -kernel_name test_sincos -ip_directory ./ip/

The output of the package_xo command is the test.xo file, that can be added as a source file to the v++ --link command as discussed in Building and Running the Application, or added to an application project as discussed in Using the Vitis IDE.

In some cases, you might find it necessary to provide a kernel.xml file for your IP, as specified in the requirements described in Creating the Kernel Description XML File. You can use the -kernel_xml option to specify the file for the package_xo command. In this case, the package_xo command uses the kernel.xml as specified. The following example shows this command.

package_xo -xo_path ./export/test.xo -kernel_name test_sincos \
-kernel_xml ./src/kernel.xml -ip_directory ./ip/

An XML kernel description file, called kernel.xml, must be created for each RTL kernel, so that it can be used in the Vitis application acceleration development flow. The kernel.xml file specifies kernel attributes like the register map and ports needed by the runtime and Vitis tool flows. The following code shows is an example of a kernel.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<root versionMajor="1" versionMinor="6">
  <kernel name="vitis_kernel_wizard_0" language="ip_c" 
      vlnv="mycompany.com:kernel:vitis_kernel_wizard_0:1.0" 
      attributes="" preferredWorkGroupSizeMultiple="0" workGroupSize="1" interrupt="true">
    <ports>
      <port name="s_axi_control" mode="slave" range="0x1000" dataWidth="32" portType="addressable" base="0x0"/>
      <port name="m00_axi" mode="master" range="0xFFFFFFFFFFFFFFFF" dataWidth="512" portType="addressable" 
         base="0x0"/>
    </ports>
    <args>
      <arg name="axi00_ptr0" addressQualifier="1" id="0" port="m00_axi" size="0x8" offset="0x010" type="int*" 
         hostOffset="0x0" hostSize="0x8"/> 
    </args>
  </kernel>
</root>

The following table describes the format of the kernel.xml in detail:

The RTL Kernel wizard is organized into multiple pages that break down the process of defining an RTL kernel. The pages of the wizard include:

1. General Settings
2. Scalars
3. Global Memory
4. Streaming Interfaces
5. Summary

To navigate between pages, click Next and Back as needed.

To finalize the kernel and build a project based on the kernel specification, click OK on the Summary page.

If you launched the RTL Kernel wizard from the Vitis IDE, after clicking OK on the Summary page, the Vivado Design Suite open with an example IP project to let you complete your RTL kernel code.

If you launched the RTL Kernel wizard from within the Vivado IP catalog, after clicking OK on the Summary page, an RTL Kernel Wizard IP is instantiated into your current project. From there you must take the following steps:

1. When the Generate Output Products dialog box appears, click Skip to close it.
2. Right-click the <kernel_name>.xci file that is added to the Sources view, and select Open IP Example Design.
3. In the Open Example Design dialog box, specify the Example project directory, or accept the default value, and click OK.
   TIP: An example project is created for the RTL kernel IP. This example IP project is the same as the example project created if you launch the RTL Kernel wizard from the Vitis IDE, and is where you will complete the development work for your kernel.
4. You can now close the original Vivado project from which you launched the RTL Kernel wizard.

Depending on the Kernel Type you selected for the kernel options, the example IP project is populated with a top-level RTL kernel file that contains either a Verilog example and control registers as described in RTL Type Kernel Project, or an instantiated IP integrator block design as described in Block Design Type Kernel Project. The top-level Verilog file contains the expected input/output signals and parameters. These top-level ports are matched to the kernel specification file (kernel.xml) and can be combined with your RTL code, or /block design, to complete the RTL kernel.

The AXI4 interfaces defined in the top-level file contain a minimum subset of AXI4 signals required to generate an efficient, high throughput interface. Signals that are not present inherit optimized defaults when connected to the rest of the AXI system. These optimized defaults allow the system to omit AXI features that are not required, saving area and reducing complexity. If your RTL code or block design contains AXI signals that were omitted, you can add these signals to the ports in the top-level RTL kernel file, and the IP packager will adapt to them appropriately.

The next step in the process customizes the contents of the kernel and then packages those contents into a Xilinx Object (xo) file.

The AXI4 interfaces typically connects to DDR memory controllers in the platform.

For best performance from the memory controller, the following is the recommended AXI interface behavior:

• Use an AXI data width that matches the native memory controller AXI data width, typically 512-bits.
• Do not use WRAP, FIXED, or sub-sized bursts.
• Use burst transfer as large as possible (up to 4k byte AXI4 protocol limit).
• Avoid use of deasserted write strobes. Deasserted write strobes can cause error-correction code (ECC) logic in the DDR memory controller to perform read-modify-write operations.
• Use pipelined AXI transactions.
• Avoid using threads if an AXI interface is only connected to one DDR controller.
• Avoid generating write address commands if the kernel does not have the ability to deliver the full write transaction (non-blocking write requests).
• Avoid generating read address commands if the kernel does not have the capacity to accept all the read data without back pressure (non-blocking read requests).
• If a read-only or write-only interfaces are desired, the ports of the unused channels can be commented out in the top level RTL file before the project is packaged into a kernel.
• Using multiple threads can cause larger resource requirements in the infrastructure IP between the kernel and the memory controllers.

An RTL kernel can have up to two external clock interfaces; a primary clock, ap_clk, and an optional secondary clock, ap_clk_2. Both clocks can be used for clocking internal logic. However, all external RTL kernel interfaces must be clocked on the primary clock. Both primary and secondary clocks support independent automatic frequency scaling.

If you require additional clocks within the RTL kernel, a frequency synthesizer such as the Clocking Wizard IP or MMCM/PLL primitive can be instantiated within the RTL kernel. Therefore, your RTL kernel can use just the primary clock, both primary and secondary clock, or primary and secondary clock along with an internal frequency synthesizer. The following shows the advantages and disadvantages of using these three RTL kernel clocking methods:

• Single input clock: ap_clk
  • External interfaces and internal kernel logic run at the same frequency.
  • No clock-domain-crossing (CDC) issues.
  • Frequency of ap_clk can automatically be scaled to allow kernel to meet timing.
• Two input clocks: ap_clk and ap_clk_2
  • Kernel logic can run at either clock frequency.
  • Need proper CDC technique to move from one frequency to another.
  • Both ap_clk and ap_clk_2 can automatically scale their frequencies independently to allow the kernel to meet timing.
• Using a frequency synthesizer inside the kernel:
  • Additional device resources required to generate clocks.
  • Must have ap_clk and optionally ap_clk_2 interfaces.
  • Generated clocks can have different frequencies for different CUs.
  • Kernel logic can run at any available clock frequency.
  • Need proper CDC technique to move from one frequency to another.

When using a frequency synthesizer in the RTL kernel there are some constraints you should be aware of:

1. RTL external interfaces are clocked at ap_clk.
2. The frequency synthesizer can have multiple output clocks that are used as internal clocks to the RTL kernel.
3. You must provide a Tcl script to downgrade DRCs related to clock resource placement in Vivado placement to prevent a DRC error from occurring. Refer to CLOCK_DEDICATED_ROUTE in the Vivado Design Suite Properties Reference Guide (UG912) for more information. The following is an example of the needed Tcl command that you will add to your Tcl script:

   set_property CLOCK_DEDICATED_ROUTE ANY_CMT_COLUMN 
   [get_nets pfm_top_i/static_region/base_clocking/clkwiz_kernel/inst/CLK_CORE_DRP_I/clk_inst/clk_out1

   Note: This constraint should be edited to reflect the clock structure of your target platform.
4. Specify the Tcl script from step 3 for use by Vivado implementation, after optimization, by using the v++ --vivado.prop option as described in --vivado Options. The following option specifies a Tcl script for use by Vivado implementation, after completing the optimization step:

   --vivado.prop:run.impl_1.STEPS.OPT_DESIGN.TCL.POST={<PATH>/<Script_Name>.tcl}

5. Specify the two global clock input frequencies which can be used by the kernels (RTL or HLS-based). Use the v++ --kernel_frequency option to ensure the kernel input clock frequency is as expected. For example to specify one clock use:

   v++ --kernel_frequency 250

   For two clocks, you can specify multiple frequencies based on the clock ID. The primary clock has clock ID 0 and the secondary has clock ID 1.

   v++ --kernel_frequency 0:250|1:500

   TIP: Ensure that the PLL or MMCM output clock is locked before RTL kernel operations. Use the locked signal in the RTL kernel to ensure the clock is operating correctly.

ERROR: [VPL-1] design did not meet timing - Design did not meet timing. One 
or more unscalable system clocks did not meet their required target 
frequency. Please try specifying a clock frequency lower than 300 MHz using 
the '--kernel_frequency' switch for the next compilation. For all system 
clocks, this design is using 0 nanoseconds as the threshold worst negative 
slack (WNS) value. List of system clocks with timing failure.

In this case you will need to change the internal clock frequency, or optimize the kernel logic to meet timing.

The following recommendations help improve results for timing and area:

• Pipeline all reset inputs and internally distribute resets avoiding high fanout nets.
• Reset only essential control logic flip-flops.
• Consider registering input and output signals to the extent possible.
• Understand the size of the kernel relative to the capacity of the target platforms to ensure fit, especially if multiple kernels will be instantiated.
• Recognize platforms that use stacked silicon interconnect (SSI) technology. These devices have multiple die and any logic that must cross between them should be flip-flop to flip-flop timing paths.

• RTL kernels should be verified in their own test bench using advanced verification techniques including verification components, randomization, and protocol checkers. The AXI Verification IP (VIP) is available in the Vivado IP catalog and can help with the verification of AXI interfaces. The RTL kernel example designs contain an AXI VIP-based test bench with sample stimulus files.
• The hardware emulation flow should not be used for functional verification because it does not accurately represent the range of possible protocol signaling conditions that real AXI traffic in hardware can incur. Hardware emulation should be used to test the host code software integration or to view the interaction between multiple kernels.