package_xo Command

Syntax

package_xo  -kernel_name <arg> [-force] [-kernel_xml <arg>]
            [-output_kernel_xml <arg>] [-design_xml <arg>]
            [-ip_directory <arg>] [-parent_ip_directory <arg>]
            [-kernel_files <args>] [-kernel_xml_args <args>]
            [-kernel_xml_pipes <args>] [-kernel_xml_connections <args>]
            [-ctrl_protocol <arg>] -xo_path <arg> [-quiet] [-verbose]

Description

The package_xo command is a Tcl command within the Vivado Design Suite. Kernels written in RTL are compiled in the Vivado tool using the package_xo command line utility which generates a Xilinx object (XO) file which can subsequently used by the v++ command, during the linking stage.

Table 1. Arguments
Argument	Description
`-kernel_name <arg>`	(Required) Specify the name of the RTL kernel.
`-force`	(Optional) Overwrite an existing XO file if one exists.
`-kernel_xml <arg>`	(Optional) Specify the path to an existing kernel XML file. The Vivado tool will create a kernel.xml file for the XO file if one is not specified.
`-output_kernel_xml`	(Optional) Specify the path to write the kernel XML file. The Vivado tool will create a kernel.xml file to include in the XO file, and also write it to the specified output file. TIP: You can use this option to generate a kernel.xml file which you can edit and use as an input in the `package_xo` command.
`-design_xml <arg>`	(Optional) Specify the path to an existing design XML file
`-ip_directory <arg>`	(Optional) Specify the path to the packaged IP directory.
`-parent_ip_directory`	(Optional) If the kernel IP directory specified contains multiple IPs, specify a directory path to the parent IP where its component.xml is located directly below.
`-kernel_files`	(Optional) Kernel file name(s). Can be used to add a C-model to your kernel XO to enable software emulation for your kernel.
`-kernel_xml_args <args>`	(Optional) Generate the kernel.xml with the specified function arguments. Each argument value should use the following format: `{name:addressQualifier:id:port:size:offset:type:memSize}` Note: `memSize` is optional.
`-kernel_xml_pipes <args>`	(Optional) Generate the kernel.xml with the specified pipe(s). Each pipe value use the following format: `{name:width:depth}`
`-kernel_xml_connections <args>`	(Optional) Generate the kernel.xml file with the specified connections. Each connection value should use the following format: `{srcInst:srcPort:dstInst:dstPort}`
`-ctrl_protocol`	Kernel control protocol as described in Kernel Properties. Valid values: `ap_ctrl_hs`, `ap_ctrl_chain`, `ap_ctrl_none`, `user_managed`. TIP: The default `ap_ctrl_hs` is written to the kernel.xml file when `-ctrl_protocol` is not specified.
`-xo_path <arg>`	(Required) Specify the path and file name of the compiled object (XO) file.
`-quiet`	(Optional) Execute the command quietly, returning no messages from the command. The command also returns TCL_OK regardless of any errors encountered during execution. Note: Any errors encountered on the command-line, while launching the command, will be returned. Only errors occurring inside the command will be trapped.
`-verbose`	(Optional) Temporarily override any message limits and return all messages from this command. Note: Message limits can be defined with the `set_msg_config` command.

Examples

The following example creates the specified XO file containing an RTL kernel of the specified name using the ap_ctrl_chain control protocol, and creates the kernel.xml file because one has not been specified:

package_xo -xo_path Vadd_A_B.xo -kernel_name Vadd_A_B -ctrl_protocol ap_ctrl_chain -ip_directory ./ip

The following example creates the XO file using the specified kernel.xml file:

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

TIP: The control protocol will be defined in the specified kernel.xml file.

RTL Kernel XML File

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 2. Kernel XML File Content
Tag	Attribute	Description
`<root>`	`versionMajor`	For the current release of Vitis software platform, set to 1.
`<root>`	`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.