XSCT Interface Examples

HSI Tcl Examples

This chapter demonstrates how to load a .xsa file, access the hardware information, and generate BSPs, applications, and the Device Tree.

Accessing Hardware Design Data

# Opening the hardware design

hsi::open_hw_design base_zynq_design_wrapper.xsa
base_zynq_design_imp

# List loaded hardware designs

hsi::get_hw_designs
base_zynq_design_imp

# Switch to current hardware design

hsi::current_hw_design
base_zynq_design_imp

# Report properties of the current hardware design

common::report_property [hsi::current_hw_design]
Property Type Read Only Visible Value
ADDRESS_TAG string* true true
  • base_zynq_design_i/
  • ps7_cortexa9_0:base_zynq_design_ibase_zynq_design_i/
  • ps7_cortexa9_1:base_zynq_design_i
BOARD string true true xilinx.com:zc702:part0:1.1
CLASS string true true hw_design
DEVICE string true true 7x020
FAMILY string true true zynq
NAME string true true base_zynq_design_imp
PACKAGE string true true clg484
PATH string true true /scratch/demo//base_zynq_design.hwh
SPEEDGRADE string true true ???1
SW_REPOSITORIES string* true true
TIMESTAMP string true true <current date and time>
VIVADO_VERSION string true true 2014.3

# List the .xsa files in the container

hsi::get_hw_files
base_zynq_design.hwh ps7_init.c ps7_init.h ps7_init_gpl.c
ps7_init_gpl.h ps7_init.tcl ps7_init.html
base_zynq_design_wrapper.mmi base_zynq_design_bd.tcl

# Filter the .bit files

hsi::get_hw_files -filter {TYPE==bit}
base_zynq_design_wrapper.bit

# List of external ports in the design

hsi::get_ports
DDR_cas_n DDR_cke DDR_ck_n DDR_ck_p DDR_cs_n DDR_reset_n
DDR_odt DDR_ras_n
DDR_we_n DDR_ba DDR_addr DDR_dm DDR_dq DDR_dqs_n DDR_dqs_p
FIXED_IO_mio
FIXED_IO_ddr_vrn FIXED_IO_ddr_vrp FIXED_IO_ps_srstb
FIXED_IO_ps_clk
FIXED_IO_ps_porb leds_4bits_tri_o

# Reports properties of an external port

common::report_property [hsi::get_ports leds_4bits_tri_o]
Property Type Readonly Visible Value
CLASS string true true port
CLK_FREQ string true true
DIRECTION string true true 0
INTERFACE bool true true 0
IS_CONNECTED bool true true 0
LEFT string true true 3
NAME string true true leds_4bits_tri_o
RIGHT string true true 0
SENSITIVITY enum true true
TYPE enum true true undef
# List of IP instances in the design
hsi::get_cells
axi_bram_ctrl_0 axi_gpio_0 blk_mem_gen_0
processing_system7_0_axi_periph_m00_couplers_auto_pc
processing_system7_0_axi_periph_s00_couplers_auto_pc
processing_system7_0_axi_periph_xbar
rst_processing_system7_0_50M ps7_clockc_0 ps7_uart_1
ps7_pl310_0 ps7_pmu_0 ps7_qspi_0
ps7_qspi_linear_0 ps7_axi_interconnect_0 ps7_cortexa9_0
ps7_cortexa9_1 ps7_ddr_0
ps7_ethernet_0 ps7_usb_0 ps7_sd_0 ps7_i2c_0 ps7_can_0
ps7_ttc_0 ps7_gpio_0
ps7_ddrc_0 ps7_dev_cfg_0 ps7_xadc_0 ps7_ocmc_0
ps7_coresight_comp_0 ps7_gpv_0 ps7_scuc_0
ps7_globaltimer_0 ps7_intc_dist_0 ps7_l2cachec_0 ps7_dma_s
ps7_iop_bus_config_0 ps7_ram_0
ps7_ram_1 ps7_scugic_0 ps7_scutimer_0 ps7_scuwdt_0
ps7_slcr_0 ps7_dma_ns ps7_afi_0 ps7_afi_1
ps7_afi_2 ps7_afi_3 ps7_m_axi_gp0
#List of processors in the design
hsi::get_cells -filter {IP_TYPE==PROCESSOR}
ps7_cortexa9_0 ps7_cortexa9_1
# Properties of IP instance
common::report_property [hsi::get_cells axi_gpio_0]
Property Type Readonly Visible Value
CLASS string true true cell
CONFIG.C_ALL_INPUTS string true true 0
CONFIG.C_ALL_INPUTS_2 string true true 0
CONFIG.C_ALL_OUTPUTS string true true 1
CONFIG.C_ALL_OUTPUTS_2 string true true 0
CONFIG.C_BASEADDR string true true 0x41200000
CONFIG.C_DOUT_DEFAULT string true true 0x00000000
CONFIG.C_DOUT_DEFAULT_2 string true true 0x00000000
CONFIG.C_FAMILY string true true zynq
CONFIG.C_GPIO2_WIDTH string true true 32
CONFIG.C_GPIO_WIDTH string true true 4
CONFIG.C_HIGHADDR string true true 0x4120FFFF
CONFIG.C_INTERRUPT_PRESENT string true true 0
CONFIG.C_IS_DUAL string true true 0
CONFIG.C_S_AXI_ADDR_WIDTH string true true 9
CONFIG.C_S_AXI_DATA_WIDTH string true true 32
CONFIG.C_TRI_DEFAULT string true true 0xFFFFFFFF
CONFIG.C_TRI_DEFAULT_2 string true true 0xFFFFFFFF
CONFIG.Component_Name string true true base_zynq_design_axi_gpio_0_0
CONFIG.EDK_IPTYPE string true true PERIPHERAL
CONFIG.GPIO2_BOARD_INTERFACE string true true Custom
CONFIG.GPIO_BOARD_INTERFACE string true true leds_4bits
CONFIG.USE_BOARD_FLOW string true true true
CONFIGURABLE bool true true 0
IP_NAME string true true axi_gpio
IP_TYPE enum true true PERIPHERAL
NAME string* true true axi_gpio_0
PRODUCT_GUIDE string true true AXI GPIO LogiCORE IP Product Guide (PG144)
SLAVES string true true
VLNV string true true xilinx.com:ip:axi_gpio:2.0
# Memory range of the Slave IPs
common::report_property [lindex [hsi::get_mem_ranges -of_objects
[hsi::get_cells -filter {IP_TYPE==PROCESSOR}]] 39]
Table 1.
Property Type Read-only Visible Value
BASE_NAME string true true C_BASEADDR
BASE_VALUE string true true 0x41200000
CLASS string true true mem_range
HIGH_NAME string true true C_HIGHADDR
HIGH_VALUE string true true 0x4120FFFF
INSTANCE cell true true axi_gpio_0
IS_DATA bool true true 1
IS_INSTRUCTION bool true true 0
MEM_TYPE enum true true REGISTER
NAME string true true axi_gpio_0

Creating Standalone Software Design and Accessing Software Information

# List of the drivers in the software repository

hsi::get_sw_cores *uart*
uartlite_v2_01_a uartlite_v3_0 uartns550_v2_01_a
uartns550_v2_02_a uartns550_v3_0
uartns550_v3_1 uartps_v1_04_a uartps_v1_05_a uartps_v2_0
uartps_v2_1 uartps_v2_2

# Creates software design

hsi::create_sw_design swdesign -proc ps7_cortexa9_0 -os standalone
swdesign

# To switch to active software design

hsi::current_sw_design
swdesign

# Properties of the current software design

common::report_property [hsi::current_sw_design ]
Table 2. Example table
Property Type Read-only Visible Value
APP_COMPILER string FALSE TRUE arm-xilinx-eabi-gcc
APP_COMPILER_FLAGS string FALSE TRUE
APP_LINKER_FLAGS string FALSE TRUE
BSS_MEMORY string FALSE TRUE
CLASS string TRUE TRUE sw_design
CODE_MEMORY string FALSE TRUE
DATA_MEMORY string FALSE TRUE
NAME string TRUE TRUE swdesign

# The drivers associated to current hardware design

hsi::get_drivers
axi_bram_ctrl_0 axi_gpio_0 ps7_afi_0 ps7_afi_1 ps7_afi_2
ps7_afi_3 ps7_can_0
ps7_coresight_comp_0 ps7_ddr_0 ps7_ddrc_0 ps7_dev_cfg_0
ps7_dma_ns ps7_dma_s
ps7_ethernet_0 ps7_globaltimer_0 ps7_gpio_0 ps7_gpv_0
ps7_i2c_0 ps7_intc_dist_0
ps7_iop_bus_config_0 ps7_l2cachec_0 ps7_ocmc_0 ps7_pl310_0
ps7_pmu_0 ps7_qspi_0
ps7_qspi_linear_0 ps7_ram_0 ps7_ram_1 ps7_scuc_0
ps7_scugic_0 ps7_scutimer_0
ps7_scuwdt_0 ps7_sd_0 ps7_slcr_0 ps7_ttc_0 ps7_uart_1
ps7_usb_0 ps7_xadc_0
hsi% get_osstandalone

# Properties of the OS object

common::report_property[hsi::get_os]
Table 3. Example Table
Property Type Read-only Visible Value
CLASS string TRUE TRUE sw_proc
CONFIG.archiver string FALSE TRUE arm-xilinx-eabi-ar
CONFIG.compiler string FALSE TRUE arm-xilinx-eabi-gcc
CONFIG.compiler_flags string FALSE TRUE -O2 -c
CONFIG.extra_compiler_flags string FALSE TRUE -g
HW_INSTANCE string TRUE TRUE ps7_cortexa9_0
NAME string FALSE TRUE cpu_cortexa9
VERSION string FALSE TRUE 2.1

# Generate BSP. BSP source code will be dumped to the output directory.

hsi::generate_bsp -dir bsp_out

# List of available apps in the repository

hsi::generate_app -lapp
peripheral_tests dhrystone empty_application hello_world
lwip_echo_server
memory_tests rsa_auth_app srec_bootloader
xilkernel_thread_demo zynq_dram_test
zynq_fsbl linux_empty_app linux_hello_world
opencv_hello_world

# Generate template application

hsi::generate_app -app hello_world -proc ps7_cortexa9_0 -
dir app_out

# Generate Device Tree. Clone device tree repo from GIT to /device_tree_repository/device-treegenerator-master directory.

# Load the hardware design

hsi::open_hw_design zynq_1_wrapper.xsa

# Cloned GIT repo path

hsi::set_repo_path ./device_tree_repository/device-tree-generator-master

# Create sw design

hsi::create_sw_design sw1 -proc ps7_cortexa9_0 -os device_tree

# Generate device tree

hsi::generate_target {dts} -dir dtg_out

Generating and Compiling Applications with Customized Compiler Settings and Memory Sections

#Create a software design for the template application with default compiler flags and memory section settings

set sw_system_1 [hsi::create_sw_design system_1 -proc microblaze_1 -os
xilkernel -app hello_world]

#Change compiler and its flags of the software design

common::set_property APP_COMPILER "mb-gcc" $sw_system_1
common::set_property -name APP_COMPILER_FLAGS -value "-DRSA_SUPPORT -
DFSBL_DEBUG_INFO"
-objects $sw_system_1
common::set_property -name APP_LINKER_FLAGS -value "-Wl,--start-group,-
lxil,-lgcc,-lc,--end-group"
-objects $sw_system_1

#Change memory sections

common::set_property CODE_MEMORY axi_bram_ctrl_1 $sw_system_1
common::set_property BSS_MEMORY axi_bram_ctrl_1 $sw_system_1
common::set_property DATA_MEMORY axi_bram_ctrl_2 $sw_system_1

#Genereate application for the above customized software design to Zynq_Fsbl directory

hsi::generate_app -dir hw_output -compile

Generating and Compiling BSP with Advanced Driver/Library/OS/Processor Configuration

#Create a software design for the template application with default compiler flags and memory section settings

set sw_system_1 [hsi::create_sw_design system_1 -proc microblaze_1 -os
xilkernel ]

#Get the old driver object

set old_driver [hsi::get_drivers myip1]

#Set repository path to find the custom drivers and libraries

hsi::set_repo_path ./my_local_sw_repository

#Set the new driver name and version to old driver object

common::set_property NAME myip1_custom_driver $old_driver
common::set_property VERSION 1.0 $old_driver

#Change default OS configuration to desired one

set OS [hsi::get_os]
common::set_property CONFIG.systmr_dev axi_timer_0 $OS
common::set_property CONFIG.stdin axi_uartlite_0 $OS
common::set_property CONFIG.stdout axi_uartlite_0 $OS

#Add custom library to software design

hsi::add_library xilflash

#Get all the properties of the library, only read_only = false properties can be changed

common::report_property [hsi::get_libs xilflash]

#Change the default configuration of the library

set lib [hsi::get_libs xilflash]
common::set_property CONFIG.enable_amd true $lib
common::set_property CONFIG.enable_intel false $lib

#Generate the BSP with the above configuration

hsi::generate_bsp -dir advanced_bsp -compile

#Delete the library added to software design

hsi::delete_objs $lib

Generating and Compiling BSP for a Multi-Block Design

Figure 1: Example Design with Multiple Block Design Instances in the Active Top Design
#Open hardware design with multiple block design instances
hsi% hsi::open_hw_design system_wrapper.xsa
design_1_wrapper
#Get the hardware cell instances
Note: Cell instances from all the block designs in the top are shown andtheir names are prefixed with their hierarchy
hsi% join [get_cells ] \n
ps_0_wrapper_i_ps_0_i_processing_system7_0
ps7_uart_1
ps7_qspi_0
ps7_cortexa9_0
ps7_cortexa9_1
ps7_ddr_0
ps7_ethernet_0
....
mb_2_wrapper_i_mb_2_i_axi_gpio_0
mb_2_wrapper_i_mb_2_i_mdm_1
mb_2_wrapper_i_mb_2_i_microblaze_0
mb_2_wrapper_i_mb_2_i_microblaze_0_axi_periph
mb_2_wrapper_i_mb_2_i_microblaze_0_local_memory_dlmb_bram_if_cntlr
mb_2_wrapper_i_mb_2_i_microblaze_0_local_memory_dlmb_v10
mb_2_wrapper_i_mb_2_i_microblaze_0_local_memory_ilmb_bram_if_cntlr
mb_2_wrapper_i_mb_2_i_microblaze_0_local_memory_ilmb_v10
mb_2_wrapper_i_mb_2_i_microblaze_0_local_memory_lmb_bram
mb_2_wrapper_i_mb_2_i_rst_clk_wiz_1_100M
mb_1_wrapper_i_mb_1_i_axi_gpio_0
mb_1_wrapper_i_mb_1_i_mdm_1
mb_1_wrapper_i_mb_1_i_microblaze_0
mb_1_wrapper_i_mb_1_i_microblaze_0_axi_periph
mb_1_wrapper_i_mb_1_i_microblaze_0_local_memory_dlmb_bram_if_cntlr
mb_1_wrapper_i_mb_1_i_microblaze_0_local_memory_dlmb_v10
mb_1_wrapper_i_mb_1_i_microblaze_0_local_memory_ilmb_bram_if_cntlr
mb_1_wrapper_i_mb_1_i_microblaze_0_local_memory_ilmb_v10
mb_1_wrapper_i_mb_1_i_microblaze_0_local_memory_lmb_bram
mb_1_wrapper_i_mb_1_i_rst_clk_wiz_1_100M
common_wrapper_i_common_i_axi_gpio_0
common_wrapper_i_common_i_axi_interconnect_0
common_wrapper_i_common_i_clk_wiz_1
common_wrapper_i_common_i_rst_clk_wiz_1_100M

#Generate BSP for a processor in bsp_out directory and compile the bsp sources

hsi::generate_bsp -proc mb_2_wrapper_i_mb_2_i_microblaze_0 -dir bsp_out -
compile
ls ./bsp_out/mb_2_wrapper_i_mb_2_i_microblaze_0
code
indent
lib
libsrc

HSI Input and Output Files and Specifications

Input Files

XSA

Xilinx® Support Archive (.xsa) is a Xilinx proprietary file format and only Xilinx software tools understand it. Third-party software tools can communicate to the XSCT Tcl interface to extract data from the .xsa file.

Note: Xilinx does not recommend manually editing the XSA file or altering its contents.

XSA is a container and contains:

  • One or more .hwh files
    • Vivado® tool version, part, and board tag information
    • IP - instance, name, VLNV, and parameters
    • Memory Map information of the processors
    • Internal Connectivity information (including interrupts, clocks, etc.) and external ports information
  • BMM/MMI and BIT files
  • User and HLS driver files
  • Other meta-data files

Software Repository

Default Repositories

By default, the tool scans the following repositories for software components:

  • <install>/data/embeddedsw/lib/XilinxProcessorIPLib
  • <install>/data/embeddedsw/lib
  • <install>/data/embeddedsw/ThirdParty
GIT Repositories

The Device Tree repository can be cloned from Xilinx GIT. Use the set_repo_path Tcl command to specify the cloned GIT repository.

User Repositories

You can create drivers, BSPs, and Apps in an example directory structure format, as illustrated in the figure above. Use the set_repo_path Tcl command to specify the user repository.

Search Priority Mechanism

The tool uses a search priority mechanism to locate drivers and libraries, as follows:

  1. Search the repositories under the library path directory specified using the set_repo_path Tcl command.
  2. Search the default repositories described above.

Output Files

The tool generates directories, files, and the software design file (MSS) in the <your_project> directory. For every processor instance in the MSS file, the tool generates a directory with the name of the processor instance. Within each processor instance directory the tool generates the following directories and files.

The include Directory
The include directory contains C header files needed by drivers. The include file xparameters.h is also created using the tool in this directory. This file defines base addresses of the peripherals in the system, #defines needed by drivers, OSs, libraries, and user programs, as well as function prototypes.
  • The Microprocessor Driver Definition (MDD) file for each driver specifies the definitions that must be customized for each peripheral that uses the driver. See Microprocessor Driver Definition (MDD) Overview.
  • The Microprocessor Library Definition (MLD) file for each OS and library specifies the definitions that you must customize. See Microprocessor Library Definition (MLD) Overview.
The lib Directory
The lib directory contains libc.a, libm.a, and libxil.a libraries. The libxil library contains driver functions that the particular processor can access. For more information about the libraries, refer to the introductory section of the OS and Libraries Document Collection (UG643).
The libsrc Directory
The libsrc directory contains intermediate files and make files needed to compile the OSs, libraries, and drivers. The directory contains peripheral-specific driver files, BSP files for the OS, and library files that are copied from install, as well as your driver, OS, and library directories.
The code Directory
The code directory is a repository for tool executables. The tool creates an xmdstub.elf file (for the MicroBlaze™ processor on-board debug) in this directory.
Note: The tool removes these directories every time you run the it. You must put your sources, executables, and any other files in an area that you create.

Generating Libraries and Drivers

This section provides an overview of generating libraries and drivers. The hardware specification file and the MSS files define a system. For each processor in the system, the tool finds the list of addressable peripherals. For each processor, a unique list of drivers and libraries are built. The tool does the following for each processor:

  • Builds the directory structure, as defined in Output Files.
  • Copies the necessary source files for the drivers, OSs, and libraries into the processor instance specific area: OUTPUT_DIR/processor_instance_name/libsrc.
  • Calls the Design Rule Check (DRC) procedure, which is defined as an option in the MDD or MLD file, for each of the drivers, OSs, and libraries visible to the processor.
  • Calls the generate Tcl procedure (if defined in the Tcl file associated with an MDD or MLD file) for each of the drivers, OSs, and libraries visible to the processor. This generates the necessary configuration files for each of the drivers, OSs, and libraries in the include directory of the processor.
  • Calls the post_generate Tcl procedure (if defined in the Tcl file associated with an MDD or MLD file) for each of the drivers, OSs, and libraries visible to the processor.
  • Runs make (with targets include and libs) for the OSs, drivers, and libraries specific to the processor. On the Linux platform, the gmake utility is used, while on NT platforms, make is used for compilation.
  • Calls the execs_generate Tcl procedure (if defined in the Tcl file associated with an MDD or MLD file) for each of the drivers, OSs, and libraries visible to the processor.

MDD, MLD, and Tcl

A driver or library has two associated data files:

Data Definition File (MDD or MLD file)
This file defines the configurable parameters for the driver, OS, or library.
Data Generation File (Tcl)
This file uses the parameters configured in the MSS file for a driver, OS, or library to generate data. Data generated includes but is not limited to generation of header files, C files, running DRCs for the driver, OS, or library, and generating executables.

The Tcl file includes procedures that tool calls at various stages of its execution. Various procedures in a Tcl file include:

DRC
The name of DRC given in the MDD or MLD file.
generate
A tool-defined procedure that is called after files are copied.
post_generate
A tool-defined procedure that is called after generate has been called on all drivers, OSs, and libraries.
execs_generate
A tool-defined procedure that is called after the BSPs, libraries, and drivers have been generated.
Note: The data generation (Tcl) file is not necessary for a driver, OS, or library.

For more information about the Tcl procedures and MDD/MLD related parameters, refer to Microprocessor Driver Definition (MDD) and Microprocessor Library Definition (MLD).

MSS Parameters

For a complete description of the MSS format and all the parameters that MSS supports, refer to MSS Overview.

Drivers

Most peripherals require software drivers. The peripherals are shipped with associated drivers, libraries and BSPs. Refer to the Device Driver Programmer Guide for more information on driver functions. This guide can be found in the <install_directory>\vitis \<version> \data\embeddedsw\doc.

The MSS file includes a driver block for each peripheral instance. The block contains a reference to the driver by name (DRIVER_NAME parameter) and the driver version (DRIVER_VER). There is no default value for these parameters.

A driver has an associated MDD file and a Tcl file.

  • The driver MDD file is the data definition file and specifies all configurable parameters for the drivers.
  • Each MDD file has a corresponding Tcl file which generates data that includes generation of header files, generation of C files, running DRCs for the driver, and generating executables.

You can write your own drivers. These drivers must be in a specific directory under / or / drivers, as shown in the figure in Software Repository.

  • The DRIVER_NAME attribute allows you to specify any name for your drivers, which is also the name of the driver directory.
  • The source files and make file for the driver must be in the /src subdirectory under the / directory.
  • The make file must have the targets /include and /libs.
  • Each driver must also contain an MDD file and a Tcl file in the /data subdirectory.

Open the existing driver files to get an understanding of the required structure.

Refer to Microprocessor Driver Definition (MDD) for details on how to write an MDD and its corresponding Tcl file.

Libraries

The MSS file includes a library block for each library. The library block contains a reference to the library name (LIBRARY_NAME parameter) and the library version (LIBRARY_VER). There is no default value for these parameters. Each library is associated with a processor instance specified using the PROCESSOR_INSTANCE parameter. The library directory contains C source and header files and a make file for the library.

The MLD file for each library specifies all configurable options for the libraries and each MLD file has a corresponding Tcl file.

You can write your own libraries. These libraries must be in a specific directory under /sw_services as shown in the figure in Software Repository.

  • The LIBRARY_NAME attribute lets you specify any name for your libraries, which is also the name of the library directory.
  • The source files and make file for the library must be in the /src subdirectory under the / directory.
  • The make file must have the targets /include and /libs.
  • Each library must also contain an MLD file and a Tcl file in the /data subdirectory.

Refer to the existing libraries for more information about the structure of the libraries.

Refer to Microprocessor Library Definition (MLD) for details on how to write an MLD and its corresponding Tcl file.

OS Block

The MSS file includes an OS block for each processor instance. The OS block contains a reference to the OS name (OS_NAME parameter), and the OS version (OS_VER). There is no default value for these parameters. The bsp directory contains C source and header files and a make file for the OS.

The MLD file for each OS specifies all configurable options for the OS. Each MLD file has a corresponding Tcl file associated with it. Refer to Microprocessor Library Definition (MLD) and Microprocessor Software Specification (MSS).

You can write your own OSs. These OSs must be in a specific directory under /bsp or /bsp as shown in the figure in Software Repository.

  • The OS_NAME attribute allows you to specify any name for your OS, which is also the name of the OS directory.
  • The source files and make file for the OS must be in the src subdirectory under the / directory.
  • The make file should have the targets /include and /libs.
  • Each OS must contain an MLD file and a Tcl file in the /data subdirectory.

Look at the existing OSs to understand the structures. See Microprocessor Library Definition (MLD) Overview for details on how to write an MLD and its corresponding Tcl file, refer to the Device Driver Programmer Guide. This guide is located in your Vitis software platform installation in <install_directory>\vitis\<version> \data\embeddedsw\doc.