Package the RTL Code as a Vivado IP - 2020.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)
Document ID
UG1393
Release Date
2021-03-22
Version
2020.2 English

RTL kernels must be packaged as a Vivado IP that can be used with the IP integrator. For details on IP packaging in the Vivado tool, see the Vivado Design Suite User Guide: Creating and Packaging Custom IP (UG1118).

The following required interfaces for the RTL kernel must be packaged:

  • The AXI4-Lite interface name must be packaged as S_AXI_CONTROL, but the underlying AXI ports can be named differently.
  • Any memory-mapped AXI4 interfaces must be packaged as AXI4 master endpoints with 64-bit address support.
    Recommended: 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.
  • You can also implement the AXI4-Stream interface.
  • ap_clk and ap_clk_2 must be packaged as clock interfaces (ap_clk_2 is only required when the RTL kernel has two clocks).
  • ap_rst_n and ap_rst_n_2 must be packaged as active-Low reset interfaces (when the RTL kernel has a reset).
  • ap_clk must be associated with all AXI4-Lite, AXI4, AXI4-Stream interfaces, and also any reset signals, ap_rst_n, on the kernel.

To package the IP, use the following steps:

  1. Create and package a new IP.
    1. From a Vivado project, with your RTL source files added, select Tools > Create and Package New IP.
    2. Select Package your current project, and click Next.

      You can select the default location for your IP, or choose a different location.

    3. To open the Package IP window, select Finish.
  2. Associate the clock to the AXI interfaces.

    In the Ports and Interfaces section of the Package IP window, you can associate the ap_clk with the AXI4 interfaces, and reset signal if needed.

    1. Right-click an interface, and select Associate Clocks.

      This opens the Associate Clocks dialog box which lists the ap_clk, and perhaps ap_clk_2.

    2. Select the ap_clk and click OK to associate it with the interface.
    3. Make sure to repeat this step to associate ap_clk with each of the AXI interfaces, and the reset.
  3. Add the control registers and offsets.

    The kernel requires control registers as discussed in Kernel Controls. The following table shows a list of the required registers.

    Table 1. Address Map
    Register Name Description Address Offset Size
    CTRL Control Signals.
    Important: The CTRL register and <kernel_args> are required on all kernels. The interrupt related registers are only required for designs with interrupts.
    		 0x000 32
    GIER Global Interrupt Enable Register. Used to enable interrupt to the host. 0x004 32
    IP_IER IP Interrupt Enable Register. Used to control which IP generated signal are used to generate an interrupt. 0x008 32
    IP_ISR IP Interrupt Status Register. Provides interrupt status. 0x00C 32
    <kernel_args> This includes a separate entry for each kernel argument as needed on the software function interface. All user-defined registers must begin at location 0x10; locations below this are reserved. 0x010 32/64

    Scalar arguments are 32-bits wide.m_axi and axis interfaces are 64 bits wide.
    1. To create the address map described in the table, select the Addressing and Memory section of the Package IP window. Right-click in the Address Blocks and select the Add Register command.

      This opens the Add Register dialog box in which you can enter one of the register names from the table above.

    2. Repeat as needed to add all required registers.
      This creates a Registers table in the Addressing and Memory section. You can edit the table to add the Description, Address Offset, and Size to each register. The Registers table should look similar to the following example.

    3. Finally, select the register for each of the pointer arguments from your table, right-click and select the Add Register Parameter command. Enter the name ASSOCIATED_BUSIF into the dialog box that opens, and click OK.

      This lets you define an association between the register and the AXI4 Interface. In the value field of the added parameter, enter the name of the m_axi interface assigned to the specific argument you are defining. In the example above, the argument A uses the m00_axi interface, and the argument B uses the m01_axi interface.

  4. Add required properties to the IP:
    The IP requires a few standard properties that you can add to your core. The easiest way to do this is by using the following commands from the Vivado Tcl Console.
    
set_property sdx_kernel true [ipx::current_core]
set_property sdx_kernel_type rtl [ipx::current_core]
  5. At this point you should be ready to package your IP.
    1. Select the Review and Package section of the Package IP window, review the Summary and After Packaging sections, and make whatever changes are needed.
      Important: You must enable the generation of an IP archive file. If the After Packaging section indicates An archive will not be generated., you must select the Edit packaging settings link and enable the Create archive of IP setting.
    2. When you are ready, click Package IP.

      The Vivado tool packages your kernel IP and opens a dialog box to inform you of success. You can go on to package the kernel using the package_xo command, as described in Creating the XO File from the RTL Kernel.

  6. To test if the RTL kernel is packaged correctly for the IP integrator, try to instantiate the packaged kernel IP into a block design in the IP integrator. For information on the tool, refer to Vivado Design Suite User Guide: Designing IP Subsystems Using IP Integrator (UG994).
  7. The kernel IP should show the various interfaces described above. Examine the IP 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.
  8. If the RTL kernel has constraints which refer to constraints in the static area such as clocks, then the RTL kernel constraint file needs to be marked as late processing order to ensure RTL kernel constraints are correctly applied.

    There are two methods to mark constraints as late processing order:

    1. If the constraints are given in a .ttcl file, add <: setFileProcessingOrder "late" :> to the .ttcl preamble section of the file as follows:
      <: set ComponentName [getComponentNameString] :>
<: setOutputDirectory "./" :>
<: setFileName $ComponentName :>
<: setFileExtension ".xdc" :>
<: setFileProcessingOrder "late" :>
    2. If constraints are defined in an .xdc file, then add the following four lines starting at <spirit:define> in the component.xml. The four lines in the component.xml need to be next to the area where the .xdc file is called. In the following example, my_ip_constraint.xdc file is being called with the subsequent late processing order defined.
      <spirit:file>
        <spirit:name>ttcl/my_ip_constraint.xdc</spirit:name>
        <spirit:userFileType>ttcl</spirit:userFileType>
        <spirit:userFileType>USED_IN_implementation</spirit:userFileType>
        <spirit:userFileType>USED_IN_synthesis</spirit:userFileType>
        <spirit:define>
             <spirit:name>processing_order</spirit:name>
             <spirit:value>late</spirit:value>
        </spirit:define>
</spirit:file>