RTL Kernel XML File - 2021.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)
Document ID
UG1393
Release Date
2022-03-29
Version
2021.2 English
Tip: The package_xo command will create a kernel.xml file from the component.xml of a packaged IP, so you do not need to manually provide one, or generate one using the RTL Kernel wizard.

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>
Note: The kernel.xml file can be created automatically using the RTL Kernel Wizard to specify the interface specification of your RTL kernel. For more information, refer to RTL Kernel Wizard.

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

Table 1. Kernel XML File Content
Tag Attribute Description
<root> versionMajor For the current release of Vitis software platform, set to 1.
versionMinor For the current release of Vitis software platform, set to 6.
<kernel> name Kernel name
language Always set to ip_c for RTL kernels.
vlnv Must match the vendor, library, name, and version attributes in the component.xml of an IP. For example, if component.xml has the following tags:

<spirit:vendor>xilinx.com</spirit:vendor>

<spirit:library>hls</spirit:library>

<spirit:name>test_sincos</spirit:name>

<spirit:version>1.0</spirit:version>

The vlnv attribute in kernel XML must be set to:xilinx.com:hls:test_sincos:1.0

attributes Reserved. Set it to empty string: ""
preferredWorkGroupSizeMultiple Reserved. Set it to 0.
workGroupSize Reserved. Set it to 1.
interrupt Set to "true" (interrupt="true") if the RTL kernel has an interrupt, otherwise omit.
hwControlProtocol Specifies the control protocol for the RTL kernel.
  • ap_ctrl_hs: Default control protocol for RTL kernels.
  • ap_ctrl_chain: Control protocol for chained kernels that support dataflow. Adds ap_continue to the control registers to enable ap_done/ap_continue completion acknowledgment.
  • ap_ctrl_none: Control protocol (none) applied for data driven kernels.
  • user_managed: Specifies a kernel that meets the interface requirements for Vitis compiler to link the kernel with other kernels and a target platform, but does not adhere to the requirements for execution management by XRT. Refer to Creating User-Managed RTL Kernels for more information.
<port> name Specifies the port name.
Important: The AXI4-Lite interface must be named S_AXI_CONTROL.
mode At least one AXI4 master port and one AXI4-Lite slave control port are required.

AXI4-Stream ports can be specified to stream data between kernels.

  • For AXI4 master port, set to "master."
  • For AXI4 slave port, set to "slave."
  • For AXI4-Stream master port, set to "write_only."
  • For AXI4-Stream slave port, set it "read_only."
range The range of the address space for the port.
dataWidth The width of the data that goes through the port, default is 32-bits.
portType Indicate whether or not the port is addressable or streaming.
  • For AXI4 master and slave ports, set it to "addressable."
  • For AXI4-Stream ports, set it to "stream."
base For AXI4 master and slave ports, set to 0x0. This tag is not applicable to AXI4-Stream ports.
<arg> name Specifies the kernel software argument name.
addressQualifier Valid values:
  • 0: Scalar kernel input argument
  • 1: global memory
  • 2: local memory
  • 3: constant memory
  • 4: pipe
id Only applicable for AXI4 master and slave ports. The ID needs to be sequential. It is used to determine the order of kernel arguments.

Not applicable for AXI4-Stream ports.
port Specifies the <port> name to which the arg is connected.
size Size of the argument in bytes. The default is 4 bytes.
offset Indicates the register memory address.
type The C data type of the argument. For example, uint*, int*, or float*.
hostOffset Reserved. Set to 0x0.
hostSize Size of the argument. The default is 4 bytes.
memSize For AXI4-Stream ports, memSize sets the depth of the created FIFO.
Tip: Not applicable to AXI4 ports.
The following tags specify additional tags for AXI4-Stream ports. They do not apply to AXI4 ports.
<connection> The connection tag describes the actual connection in hardware, either from the kernel to the FIFO inserted for the PIPE, or from the FIFO to the kernel.
srcInst Specifies the source instance of the connection.
srcPort Specifies the port on the source instance for the connection.
dstInst Specifies the destination instance of the connection.
dstPort Specifies the port on the destination instance of the connection.