SDSoC Tcl Commands in Vivado

Introduction

After you complete the hardware platform design project in the Vivado Design Suite, you must create a Tcl script that the SDSoC Platform Utility uses to generate the hardware platform metadata file from the Vivado project. The Tcl script uses the SDSoC Vivado Tcl commands as described in the following section.

SDSoC Vivado Tcl Commands

The Vivado Design Suite provides SDSoC specific Tcl commands that specify the hardware interface of an SDSoC platform, which includes clock, reset, interrupt, AXI, and AXI4-Stream type interfaces. You must use the SDSoC Tcl commands in the Vivado Design Suite to create a script with the following steps:

  1. Declare the hardware platform: (sdsoc::create_pfm)
  2. Define the hardware platform name: (sdsoc::pfm_name)
  3. Define a brief description of the platform: (sdsoc::pfm_description)
  4. Declare the platform clock ports: (sdsoc::pfm_clock)
  5. Declare the platform AXI bus interfaces: (sdsoc::pfm_axi_port)
  6. Declare the platform AXI4-Stream bus interfaces: (sdsoc::pfm_axis_port)
  7. Declare the available platform interrupts: (sdsoc::pfm_irq)
  8. Write the hardware platform description metadata file: (sdsoc::generate_hw_pfm)

Each of these commands is detailed as follows. You may also refer to theComplete Exampleof this process provided below.

Defining the Hardware Platform Name and Description

The following describes the TCL API to be used within a block diagram in the Vivado IP Integrator feature.

  • To create a new hardware platform file, set the name and description, use:

    sdsoc::create_pfm .hpfm

    Arguments:

     - platform name

    Returns:

    new platform handle

  • To set the platform name and description:

    sdsoc::pfm_name      sdsoc::pfm_description  ""
    Example: 
    set pfm [sdsoc::create_pfm zc702.hpfm] sdsoc::pfm_name $pfm "xilinx.com" "xd" "zc702" "1.0" sdsoc::pfm_description $pfm "Zynq ZC702 Board"
Important:Your Tcl script must write the hardware platform metadata file with the .hpfmextension local to the Vivado project, and not in a separate directory. To conform to this requirement your Tcl script should use the command: 
set pfm [sdsoc::create_pfm .hpfm]

Declaring Clocks

You can export any clock source with the platform, but for each clock you must also export synchronized reset signals using a Processor System Reset IP block in the platform. To declare clocks, use: 
sdsoc::pfm_clock
Arguments:
Argument Description
pfm_handle pfmhandle
port Clock port name
instance Instance name of the block that contains the port
id Clock id (user-defined, must be a unique non-negative integer)
is_default True if this is the default clock, false otherwise
proc_sys_reset Correspondingproc_sys_resetblock instance for synchronized reset signals
Every platform must declare one default clock for the SDSoC environment to use when no explicit clock has been specified. A clock is the default clock when the “is_default” argument is set to true.
Examples: 
sdsoc::pfm_clock $pfm FCLK_CLK0 ps7 0 false proc_sys_reset_0 sdsoc::pfm_clock $pfm FCLK_CLK1 ps7 1 false proc_sys_reset_1 sdsoc::pfm_clock $pfm FCLK_CLK2 ps7 2 true proc_sys_reset_2 sdsoc::pfm_clock $pfm FCLK_CLK3 ps7 3 false proc_sys_reset_3

Declaring AXI Ports

To declare AXI ports, use: 
sdsoc::pfm_axi_port
Arguments:
Argument Description
pfm pfmhandle
port AXI port name
instance Instance name of the block that contains the port
memport Corresponding memory interface port type. Values:
  • M_AXI_GP– A general-purpose AXI master port
  • S_AXI_HP– A high-performance AXI slave port
  • S_AXI_ACP– An accelerator coherent slave port
  • MIG– An AXI slave connected to a MIG memory controller
Examples: 
sdsoc::pfm_axi_port $pfm M_AXI_GP0 ps7 M_AXI_GP sdsoc::pfm_axi_port $pfm M_AXI_GP1 ps7 M_AXI_GP sdsoc::pfm_axi_port $pfm S_AXI_ACP ps7 S_AXI_ACP sdsoc::pfm_axi_port $pfm S_AXI_HP0 ps7 S_AXI_HP sdsoc::pfm_axi_port $pfm S_AXI_HP1 ps7 S_AXI_HP sdsoc::pfm_axi_port $pfm S_AXI_HP2 ps7 S_AXI_HP sdsoc::pfm_axi_port $pfm S_AXI_HP3 ps7 S_AXI_HP
Example for an AXI interconnect: 
sdsoc::pfm_axi_port $pfm S01_AXI axi_interconnect_0 MIG

Exporting AXI interconnect master and slave ports involves several requirements.

  1. All ports on the interconnect used within the platform must precede in index order any declared platform interfaces.
  2. There can be no gaps in the port indexing.
  3. The maximum number of master IDs for the S_AXI_ACP port is eight, so on an connected AXI interconnect, available ports to declare must be one of {S00_AXI, S01_AXI, ..., S07_AXI}. Do not declare any ports that are used within the platform itself. Declaring as many as possible will allow sds++ to avoid cascaded axi_interconnects in generated user systems.
  4. The maximum number of master IDs for an S_AXI_HP or MIG port is sixteen, so on an connected AXI interconnect, available ports to declare must be one of {S00_AXI, S01_AXI, ..., S15_AXI}. Do not declare any ports that are used within the platform itself. Declaring as many as possible will allow sds++ to avoid cascaded axi_interconnects in generated user systems.
  5. The maximum number of master ports declared on an interconnect connected to an M_AXI_GP port is sixty-four, so on an connected AXI interconnect, available ports to declare must be one of {M00_AXI, M01_AXI, ..., M63_AXI}. Do not declare any ports that are used within the platform itself. Declaring as many as possible will allow sds++ to avoid cascaded axi_interconnects in generated user systems.

As an example, the zc702_acp_pfm.tcl file includes the following declarations for interconnect ports connected to M_AXI_GP0 and S_AXI_ACP.

for {set i 1} {$i < 64} {incr i} { sdsoc::pfm_axi_port $pfm M[format %02d $i]_AXI axi_ic_gp0 M_AXI_GP } for {set i 1} {$i < 8} {incr i} { sdsoc::pfm_axi_port $pfm S[format %02d $i]_AXI axi_ic_acp S_AXI_ACP }

Declaring AXI4-Stream Ports

To declare AXI4-Stream ports, use: 
sdsoc::pfm_axis_port
Arguments:
Argument Description
pfm pfmhandle
port AXI4-Stream port name
instance Instance name of the block that contains the port
type Interface type (values: M_AXIS, S_AXIS)
Examples: 
sdsoc::pfm_axis_port $pfm S_AXIS axis2io S_AXIS sdsoc::pfm_axis_port $pfm M_AXIS io2axis M_AXIS

Declaring Interrupt Ports

Interrupts must be connected to the platform Processing System 7 IP block through an IP integrator Concat block (xlconcat). If any IP within the platform includes interrupts, these must occupy the least significant bits of the Concat block without gaps.

To declare interrupt ports, use: 
sdsoc::pfm_irq
Arguments:
Argument Description
pfm pfmhandle
port irqport name
instance Instance name of the concat block that contains the port
Example: 
for {set i 0} {$i < 16} {incr i} { sdsoc::pfm_irq $pfm In$i xlconcat }

Declaring IO Devices

If you use the Linux UIO framework, you must declare the devices. To declare an instance to be a Linux IO platform device, use: 
sdsoc::pfm_iodev
Arguments:
Argument Description
pfm pfmhandle
port I/O port name
instance Instance name of the block that contains the UIO
type I/O device type (e.g., UIO, KIO)
Example: 
sdsoc::pfm_iodev $pfm S_AXI axio_gpio_0 uio

Writing the Hardware Platform Description File

After using the above Tcl API commands to describe your platform, use the following to write the hardware platform description file: 
sdsoc::generate_hw_pfm
Example: 
sdsoc::generate_hw_pfm $pfm

This command will write the file specified in thesdsoc::create_pfmcommand.

Complete Example

All platforms included in the SDSoC release include the Tcl script used to generate the corresponding hardware description file. The Tcl script is located inside thehw/vivadodirectory and is called_pfm.tcl.

The following is a complete example of the usage of the Tcl API to generate a ZC702 platform 
# zc702_pfm.tcl -- # # This file uses the SDSoC Tcl Platform API to create the # zc702 hardware platform file # # Copyright (c) 2015 Xilinx, Inc. # # Uncomment and modify the line below to source the API script # source -notrace /scripts/vivado/sdsoc_pfm.tcl set pfm [sdsoc::create_pfm zc702_hw.pfm] sdsoc::pfm_name $pfm "xilinx.com" "xd" "zc702" "1.0" sdsoc::pfm_description $pfm "Zynq ZC702 Board" sdsoc::pfm_clock $pfm FCLK_CLK0 ps7 0 false proc_sys_reset_0 sdsoc::pfm_clock $pfm FCLK_CLK1 ps7 1 false proc_sys_reset_1 sdsoc::pfm_clock $pfm FCLK_CLK2 ps7 2 true proc_sys_reset_2 sdsoc::pfm_clock $pfm FCLK_CLK3 ps7 3 false proc_sys_reset_3 sdsoc::pfm_axi_port $pfm M_AXI_GP0 ps7 M_AXI_GP sdsoc::pfm_axi_port $pfm M_AXI_GP1 ps7 M_AXI_GP sdsoc::pfm_axi_port $pfm S_AXI_ACP ps7 S_AXI_ACP sdsoc::pfm_axi_port $pfm S_AXI_HP0 ps7 S_AXI_HP sdsoc::pfm_axi_port $pfm S_AXI_HP1 ps7 S_AXI_HP sdsoc::pfm_axi_port $pfm S_AXI_HP2 ps7 S_AXI_HP sdsoc::pfm_axi_port $pfm S_AXI_HP3 ps7 S_AXI_HP for {set i 0} {$i < 16} {incr i} { sdsoc::pfm_irq $pfm In$i xlconcat } sdsoc::generate_hw_pfm $pfm