RTL Kernels

To satisfy the SDAccel execution model, an RTL kernel must adhere to the following interface requirements:

• One and only one AXI4-Lite interface is used to access control signals and pass arguments.
• At least one of the following interfaces (can have both):
  • AXI4 master interface to communicate with memory.
  • AXI4-Stream interface to communicate between the kernels and/or with the host.
    Note: With the ap_ctrl_none kernel control interface option, AXI4 master interfaces cannot be used.
• At least one clock interface port.

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. Further, the interrupt is cleared only when writing a one to asserted bits of the IP Interrupt Status Register.

If adding an interrupt port to the kernel, the kernel.xml file needs be updated with this information. The kernel.xml is generated automatically when using the RTL Kernel Wizard. For details on updating the file, see Create Kernel Description XML File.

The wizard is organized into pages that break down the process of creating a kernel into smaller steps. To navigate between pages, click Next and select Back. To finalize the kernel and build a project based on the inputs of the wizard, click OK. Each of the following sections describes each page and its input options.

The RTL Kernel Wizard configuration dialog box customizes the specification of an RTL kernel by specifying its I/O, control registers, and AXI4 interfaces. The next step in the process customizes the contents of the kernel and then packages those contents into a Xilinx Object (xo) file. After the RTL Kernel Wizard configuration GUI has completed, a Vivado kernel project is generated and populated with the files necessary to create an RTL Kernel.

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 when combined with the rest of the RTL/block design becomes the acceleration kernel. The AXI4 interfaces defined at the top-level file contain a minimum subset of AXI4 signals required to generate an efficient, high throughput interface. Signals omitted 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 starting with existing code that contains AXI signals not listed in the port list, it is possible to add these signals to the top-level ports and the IP packager will adapt to them appropriately.

Depending on the selected Kernel Type, the contents of the top-level file is populated either with a Verilog example and control registers or an instantiated IP integrator block design.

RTL kernels must be packaged as a Vivado IP suitable for use in the IP integrator. See the Vivado Design Suite User Guide: Creating and Packaging Custom IP (UG1118) for details on IP packaging in Vivado.

The following interface packaging is required for the RTL Kernel:

• The AXI4-Lite interface name must be packaged as S_AXI_CONTROL, but the underlying AXI ports can be named differently.
• The AXI4 interfaces must be packaged as AXI4 master endpoints with 64-bit address support.
  Note: Xilinx strongly recommends that AXI4 interfaces be packaged with AXI meta data HAS_BURST=0 and SUPPORTS_NARROW_BURST=0. These properties can be set in an IP level bd.tcl file. This indicates wrap and fixed burst type is not used and narrow (sub-size burst) is not used.
• ap_clk and ap_clk_2 must be packaged as clock interfaces.
• ap_rst_n and ap_rst_n_2 must be packaged as active-Low reset interfaces.
• ap_clk must be packaged to be associated with all AXI4-Lite, AXI4, and AXI4-Stream interfaces.

To test if the RTL kernel is packaged correctly for the IP integrator, try to instantiate the packaged kernel in the IP integrator. In the GUI, it should show up as having interfaces for clock, reset, AXI4-Lite slave, AXI4 master, and AXI4 slave only. No other ports should be present in the canvas view. The properties of the AXI interface can be viewed by selecting the interface on the canvas. Then in the Block Interface Properties window, select the Properties tab and expand the CONFIG table entry. If an interface is to be read-only or write-only, the unused AXI channels can be removed and the READ_WRITE_MODE is set to read-only or write-only.

A kernel description XML file needs to be created for each RTL kernel such that it can be used in the SDAccel environment. The file must be called kernel.xml. The XML file specifies kernel attributes like the register map and ports which are needed by the runtime and SDAccel flows. The following is an example of a kernel.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<root versionMajor="1" versionMinor="6">
  <kernel name="sdx_kernel_wizard_0" language="ip_c" vlnv="mycompany.com:kernel:sdx_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 final step is to package the RTL IP and the associated kernel XML file together into a Xilinx object file (.xo) so it can be used by the SDAccel compiler. The following example command line packages test_sincos RTL IP and kernel.xml into object file named test.xo.

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

For additional information on the package_xo, see the "package_xo Command" section in SDx Command and Utility Reference Guide (UG1279). Also, for examples on using the package_xo command, see the Xilinx GitHub repository.

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.

Thus 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 the clock resource placement DRCs in Vivado placement to stop a Vivado DRC error from occurring. An example of the Tcl command follows:

   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 shell clock structure of your platform.
4. Use the xocc --xp option to specify the above Tcl script for use by Vivado implementation, after optimization. For example:

   --xp vivado_prop:run.impl_1.STEPS.OPT_DESIGN.TCL.POST={<PATH>/<TCL Script>}

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

   xocc --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.

   xocc --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 (FFs).
• 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 Stack Silicon Interconnect (SSI) Technology. These devices have multiple die and any logic that must cross between them should be FF to FF 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.