Vitis Unified Software Platform Documentation: Embedded Software Development (UG1400) - 2021.2 English - Describes the Vitis™ unified software platform, an integrated design environment (IDE) for development of embedded software applications targeted towards Xilinx® embedded processors. - UG1400
Document ID
UG1400
Release Date
2021-12-15
Version
2021.2 English
Getting Started with Vitis
Navigating Content by Design Process
Vitis Software Platform Release Notes
What's New
Supported Platforms
Embedded GNU Toolchain Details
Changed Behavior
Known Issues
Installation
Installation Requirements
Vitis Software Platform Installation
Installing the Vitis Software Platform
Installing Embedded Platforms
Setting Up the Environment to Run the Vitis Software Platform
Getting Started with the Vitis Software Platform
Vitis Unified Software Platform Overview
Vitis Software Development Workflow
Workspace Structure in the Vitis Software Platform
Migrating to the Vitis Software Platform from Xilinx SDK
Comparing Workflows in the Vitis Software Platform and SDK
Using the Vitis IDE
Develop
Vitis Command Options
Managing Platforms and Repositories
Target Platform
Creating a Hardware Design (XSA File)
Creating a Platform Project from XSA
Customizing a Pre-Built Platform
Adding a Domain to an Existing Platform
Adding a Standalone Domain
Adding a FreeRTOS Domain
Adding a Linux Domain
Configuring a Domain
Domain Overview Page
Board Support Package Settings Page
Switching FSBL Targeting Processor
Modifying Source Code for FSBL and PMU Firmware
Modifying the Domain Sources (Driver and Library Code)
Creating a Repository
Adding the Repository
Resetting BSP Sources for a Domain
Updating the Hardware Specification
Applications
Creating a Standalone Application Project
Creating a Linux Application Project
Managing Multiple Applications in a System Project
Building Projects
Build Configurations
Changing the Build Configuration
Adding Symbols or Definitions
Adding Libraries and Library Paths
Specifying the Linker Options
Specifying Debug and Optimization Compiler Flags
Specifying Miscellaneous Compiler Flags
Restoring Build Configuration
Makefiles
Linker Scripts
Generating a Linker Script for an Application
Basic Page
Advanced Page
Manually Adding the Linker Script
Modifying a Linker Script
Changing a Referenced Domain
Creating a Library Project
User Makefile Flow
Creating a User Application Template
Accessing User Application Templates
Using Custom Libraries in Application Projects
Version Control with Git
Using the Git Import Wizard
Importing Projects from a Local Git Repository
Solving Missing Projects
Team Actions
Git Ignore File Creation
Run, Debug, and Optimize
Run Application Project
Launch Configurations
Main Page
Application Page
Target Setup Page
Profiler
Creating or Editing a Launch Configuration
Customizing Launch Configurations
Target Connections
Creating a New Target Connection
Setting Custom JTAG Frequency
Establishing a Target Connection
Viewing Memory Contents
Dump/Restore Memory
Viewing Target Registers
Viewing IP Register Details
Debug Application Project
Using the Standalone Debug Flow
System Debugger Supported Design Flows
Standalone Application Debug Using Xilinx System Debugger
Linux Application Debugging with System Debugger
Troubleshooting
My application already exists in the Linux target. How can I tell System Debugger to use my existing application, instead of downloading the application?
Attach and Debug using Xilinx System Debugger
Standalone Application Debug Using System Debugger on QEMU
GDB (GNU Project Debugger)
Debugging on the Command Line
Debugging an Application on Hardware Using GDB
Debugging a Bare-Metal Application Using GDB
Debug an Application Already Running On a Target Device
Set Up Path Mapping
Debugging an Application on the Emulator (QEMU)
Running and Debugging Applications under a System Project Together
Using a Remote Host with System Debugger
Exporting Registers from the Vitis IDE
OS Aware Debugging
Enabling OS Aware Debug
Process/Thread Level Debugging
Debugging a Process from main()
Debugging a Loadable Kernel Module
Xen Aware Debugging
Enabling Xen Awareness
Debugging Hypervisor
Debugging a Dom-0/Dom-U Kernel
Debugging Dom-0/Dom-U User Space Processes
Debugging Self-Relocating Programs
Debugging an Application Project Using the Emulator (Command-Line Flow)
Cross-Triggering
Enable Cross-Triggering
Cross-Triggering in Zynq Devices
Cross-Triggering in Zynq UltraScale+ MPSoCs
Cross-Triggering in Versal Devices
Use Cases
FPGA to CPU Triggering
PTM to CPU Triggering
CPU to CPU Triggering
XSCT Cross-Triggering Commands
Profile/Analyze
TCF Profiling
gprof Profiling
Specifying Profiler Configuration
Setting Up the Hardware for Profiling
Setting Up the Software for Profiling
Setting Up the Domain
Setting Up the Software Application
Viewing the Profiling Results
Profiling Linux Applications with System Debugger
Non-Intrusive Profiling for MicroBlaze Processors
Specifying Non-Intrusive Profiler Configuration
Viewing the Non-Intrusive Profiling Results
FreeRTOS Analysis using STM
Optimize: Performance Analysis
Working with the Performance Analysis Perspective
Explorer View
Deleting Supplementary Files
Link with Editor
Exporting a Trace Package
Importing a Trace Package
Events Editor
Searching and Filtering Events
Searching an Event
Filtering an Event
Bookmarking an Event
Histogram View
Colors View
Filters View
Time Chart View
Analysis Views
Performance Session Manager
Configure Session
Modify ATG Configuration
System Performance Modeling
Predefined Design Flow
System Performance Modeling Using the Predefined Design
Creating the System Performance Modeling Project
Selecting an ATG Traffic Configuration
Configure FSBL Parameters
User-Defined Flow
System Performance Modeling Using a User-Defined Flow
Limitations
Creating a Boot Image
Program Flash
Create a Bootable Image and Program the Flash
Flash Programming
Multi-Cable and Multi-Device Support
Viewing Target Connections
Debugging an Application Using a Multi-Cable/Multi-Device Setup
Programming a Device Using a Multi-Device/Multi-Cable Setup
Programming the Flash Using a Multi-Device/Multi-Cable Setup
Vitis Utilities
Xilinx Software Command-Line Tool
Program Device
Dump/Restore Data File
Vitis Shell
Project Export and Import
Export a Vitis Project
Import a Vitis Project
Generating Device Tree
Embedded Software Development Use Cases in the Vitis Software Platform
Debugging an Application using the User-Modified/Custom FSBL
Creating a Hello World Application
Modifying the Source Code of the FSBL in Platform
Modifying the BSP Settings of the FSBL in Platform
Debugging the “Hello World” Application using the Modified FSBL
Bootgen Tool
Introduction
Navigating Content by Design Process
Installing Bootgen
Boot Time Security
Boot Image Layout
Zynq-7000 SoC Boot and Configuration
Zynq-7000 SoC Boot Image Layout
Zynq-7000 SoC Boot Header
Zynq-7000 SoC Register Initialization Table
Zynq-7000 SoC Image Header Table
Zynq-7000 SoC Image Header
Zynq-7000 SoC Partition Header
Zynq-7000 SoC Partition Attribute Bits
Zynq-7000 SoC Authentication Certificate
Zynq-7000 SoC Authentication Certificate Header
Zynq-7000 SoC Boot Image Block Diagram
Zynq UltraScale+ MPSoC Boot and Configuration
Zynq UltraScale+ MPSoC Boot Image
Zynq UltraScale+ MPSoC Boot Header
Zynq UltraScale+ MPSoC Boot Header Attribute Bits
Zynq UltraScale+ MPSoC Register Initialization Table
Zynq UltraScale+ MPSoC PUF Helper Data
Zynq UltraScale+ MPSoC Image Header Table
Zynq UltraScale+ MPSoC Image Header
Zynq UltraScale+ MPSoC Partition Header
Zynq UltraScale+ MPSoC Partition Attribute Bits
Zynq UltraScale+ MPSoC Authentication Certificates
Zynq UltraScale+ MPSoC Authentication Certification Header
Zynq UltraScale+ MPSoC Secure Header
Zynq UltraScale+ MPSoC Boot Image Block Diagram
Versal ACAP Boot Image Format
Versal ACAP Boot Header
Boot Header Attributes
Versal ACAP Image Header Table
Versal ACAP Image Header
Versal ACAP Partition Header
Versal ACAP Authentication Certificates
Versal ACAP Authentication Certification Header
Creating Boot Images
Boot Image Format (BIF)
BIF Syntax and Supported File Types
BIF Syntax for Versal ACAP
Attributes
Using Bootgen Interfaces
Bootgen IDE Options
Using Bootgen on the Command Line
Commands and Descriptions
Boot Time Security
Using Encryption
Encryption Process
Decryption Process
Encrypting Zynq-7000 Device Partitions
Encrypting Zynq MPSoC Device Partitions
Operational Key
Rolling Keys
Gray/Obfuscated Keys
Key Generation
Black/PUF Keys
Multiple Encryption Key Files
Encrypting Versal Device Partitions
Rolling Keys
Key Generation
Black/PUF Keys
Meta Header Encryption
Using Authentication
Signing
Verifying
Zynq UltraScale+ MPSoC Authentication Support
NIST SHA-3 Support
Bitstream Authentication Using External Memory
User eFUSE Support with Enhanced RSA Key Revocation
Key Generation
PPK Hash for eFUSE
Versal Authentication Support
Using HSM Mode
Creating a Boot Image Using HSM Mode: PSK is not Shared
Creating a Zynq-7000 SoC Device Boot Image using HSM Mode
Creating a Zynq UltraScale+ MPSoC Device Boot Image using HSM Mode
Creating a Versal Device Boot Image Using HSM
Generating the PDI
HSM Mode Steps
FPGA Support
Encryption and Authentication
HSM Mode
HSM Flow with Both Authentication and Encryption
Use Cases and Examples
Zynq MPSoC Use Cases
Simple Application Boot on Different Cores
PMU Firmware Load by BootROM
PMU Firmware Load by FSBL
Booting Linux
Encryption Flow: BBRAM Red Key
Encryption Flow: Red Key Stored in eFUSE
Encryption Flow: Black Key Stored in eFUSE
Encryption Flow: Black Key Stored in Boot Header
Encryption Flow: Gray Key Stored in eFUSE
Encryption Flow: Gray Key Stored in Boot Header
Operational Key
Using Op Key to Protect the Device Key in a Development Environment
Single Partition Image
Authentication Flow
BIF File with SHA-3 eFUSE RSA Authentication and PPK0
XIP
Split with "Offset" Attribute
Versal ACAP Use Cases
Bootloader, PMC_CDO
Bootloader, PMC_CDO with Load Address
Enable Checksum for Bootloader
Bootloader, PMC_CDO, PL CDO, NPI
Bootloader, PMC_CDO, PL CDO, NPI, PS CDO, and PS ELFs
AI Engine Configuration and AI Engine Partitions
Appending New Partitions to Existing PDI
RSA Authentication Example
ECDSA Authentication Example
AES Encryption Example
AES Encryption with Key Rolling Example
AES Encryption with Multiple Key Sources Example
AES Encryption and Authentication Example
Replacing PLM from an Existing PDI
BIF Attribute Reference
aarch32_mode
aeskeyfile
alignment
auth_params
authentication
big_endian
bbram_kek_iv
bh_kek_iv
bh_keyfile
bh_key_iv
bhsignature
blocks
boot_device
bootimage
bootloader
bootvectors
boot_config
checksum
copy
core
delay_handoff
delay_load
destination_cpu
destination_device
early_handoff
efuse_kek_iv
efuse_user_kek0_iv
efuse_user_kek1_iv
encryption
exception_level
familykey
file
fsbl_config
headersignature
hivec
id
image
init
keysrc
keysrc_encryption
load
metaheader
name
offset
parent_id
partition
partition_owner, owner
pid
pmufw_image
ppkfile
presign
pskfile
puf_file
reserve
split
spkfile
spksignature
spk_select
sskfile
startup
trustzone
type
udf_bh
udf_data
userkeys
xip_mode
Command Reference
arch
authenticatedjtag
bif_help
dual_ospi_mode
dual_qspi_mode
dump
dump_dir
efuseppkbits
encrypt
encryption_dump
fill
generate_hashes
generate_keys
h, help
image
log
nonbooting
o
p
padimageheader
process_bitstream
read
spksignature
split
verify
verify_kdf
w
zynqmpes1
Initialization Pairs and INT File Attribute
CDO Utility
Accessing
Usage
Command Line Options
Address Filter File
Examples
Converting Binary to Source without Annotations
Converting Binary to Source with Annotations
Editing Binary CDO File
Converting Source to Binary
Design Advisories for Bootgen
Xilinx Software Command-Line Tool
Xilinx Software Command-Line Tool
XSCT Commands
Target Connection Management
connect
disconnect
targets
gdbremote connect
gdbremote disconnect
Target Registers
rrd
rwr
Program Execution
state
stop
con
stp
nxt
stpi
nxti
stpout
dis
print
locals
backtrace
bt
profile
mbprofile
mbtrace
Target Memory
mrd
mwr
osa
memmap
Target Download FPGA/BINARY
dow
verify
fpga
Target Reset
rst
IPI commands to Versal PMC
plm
plm copy-debug-log
plm set-debug-log
plm set-log-level
plm log
Target Breakpoints/Watchpoints
bpadd
bpremove
bpenable
bpdisable
bplist
bpstatus
JTAG UART
jtagterminal
readjtaguart
Miscellaneous
loadhw
loadipxact
unloadhw
mdm_drwr
mb_drwr
mdm_drrd
mb_drrd
configparams
version
xsdbserver start
xsdbserver stop
xsdbserver disconnect
xsdbserver version
JTAG Access
jtag targets
jtag sequence
jtag device_properties
jtag lock
jtag unlock
jtag claim
jtag disclaim
jtag frequency
jtag skew
jtag servers
Target File System
tfile open
tfile close
tfile read
tfile write
tfile stat
tfile lstat
tfile fstat
tfile setstat
tfile fsetstat
tfile remove
tfile rmdir
tfile mkdir
tfile realpath
tfile rename
tfile readlink
tfile symlink
tfile opendir
tfile readdir
tfile copy
tfile user
tfile roots
tfile ls
SVF Operations
svf config
svf generate
svf mwr
svf dow
svf stop
svf con
svf delay
Device Configuration System
device program
device status
device authjtag
Vitis Projects
openhw
closehw
getaddrmap
getperipherals
getprocessors
repo
platform
platform active
platform clean
platform config
platform create
platform generate
platform list
platform report
platform read
platform remove
platform write
domain
domain active
domain config
domain create
domain list
domain remove
domain report
bsp
bsp config
bsp getdrivers
bsp getlibs
bsp getos
bsp listparams
bsp regenerate
bsp removelib
bsp setdriver
bsp setlib
bsp setosversion
library
library build
library clean
library create
library list
library remove
library report
checkvalidrmxsa
isstaticxsa
ishwexpandable
setws
getws
app
app build
app clean
app config
app create
app list
app remove
app report
app switch
sysproj
sysproj build
sysproj clean
sysproj list
sysproj remove
sysproj report
importprojects
importsources
toolchain
XSCT Use Cases
Common Use Cases
Changing Compiler Options of an Application Project
Creating an Application Project Using an Application Template (Zynq UltraScale+ MPSoC FSBL)
Creating an FSBL Application Project Using Manually Created Domain (Zynq UltraScale+ MPSoC FSBL)
Creating a Bootable Image and Program the Flash
Debugging a Program Already Running on the Target
Debugging Applications on Zynq UltraScale+ MPSoC
Selecting Target Based on Target Properties
Modifying BSP Settings
Performing Standalone Application Debug
Generating SVF Files
Running an Application in Non-Interactive Mode
Running Tcl Scripts
Switching Between XSCT and Vitis Integrated Design Environment
Using JTAG UART
Working with Libraries
Editing FSBL/PMUFW Source File
Editing FSBL/PMUFW Settings
Exchanging Files between Host Machine and Linux Running on QEMU
Hardware Software Interface (HSI) Commands
XSCT Interface Examples
HSI Tcl Examples
Accessing Hardware Design Data
Creating Standalone Software Design and Accessing Software Information
Generating and Compiling Applications with Customized Compiler Settings and Memory Sections
Generating and Compiling BSP with Advanced Driver/Library/OS/Processor Configuration
Generating and Compiling BSP for a Multi-Block Design
HSI Input and Output Files and Specifications
Input Files
XSA
Software Repository
Output Files
Generating Libraries and Drivers
MDD, MLD, and Tcl
MSS Parameters
Drivers
Libraries
OS Block
Microprocessor Software Specification (MSS)
MSS Overview
MSS Format
Global Parameters
Instance-Specific Parameters
OS, Driver, Library, and Processor Block Parameters
MLD/MDD Specific Parameters
OS-Specific Parameters
Processor-Specific Parameters
Microprocessor Library Definition (MLD)
Microprocessor Library Definition Overview
MLD Library Definition Files
MLD Format Specification
Tcl File Format Specification
MLD Parameter Descriptions
MLD Parameter Description Section
MLD Keywords
MLD Design Rule Check Section
MLD Tool Generation (Generate) Section
Microprocessor Driver Definition (MDD)
Microprocessor Driver Definition Overview
MDD Driver Definition Files
MDD Format Specification
MDD Format Examples
MDD Parameter Description
MDD Keywords
MDD Design Rule Check (DRC) Section
MDD Driver Generation (Generate) Section
Custom Driver
Microprocessor Application Definition (MAD)
Microprocessor Application Definition Overview
Microprocessor Application Definition Files
MAD Format Specification
MAD Format Example
HSI Commands
common::get_property
common::report_property
hsi::close_hw_design
hsi::create_dt_node
hsi::create_dt_tree
hsi::get_cells
hsi::get_dt_nodes
hsi::get_dt_trees
hsi::get_intf_nets
hsi::get_intf_pins
hsi::get_intf_ports
hsi::get_mem_ranges
hsi::get_nets
hsi::get_nodes
hsi::get_pins
hsi::get_ports
hsi::open_hw_design
GNU Compiler Tools
Overview
Compiler Framework
Common Compiler Usage and Options
Usage
Input Files
Output Files
File Types and Extensions
Libraries
Language Dialect
Commonly Used Compiler Options: Quick Reference
General Options
Library Search Options
Header File Search Option
Default Search Paths
Library Search Procedures
Header File Search Procedures
Initialization File Search Procedures
Linker Options
Memory Layout
Reserved Memory
I/O Memory
User and Program Memory
Object-File Sections
Linker Scripts
MicroBlaze Compiler Usage and Options
MicroBlaze Compiler
Processor Feature Selection Options
General Program Options
Application Execution Modes
Position Independent Code
MicroBlaze Application Binary Interface
MicroBlaze Assembler
MicroBlaze Linker Options
MicroBlaze Linker Script Sections
Tips for Writing or Customizing Linker Scripts
Startup Files
First Stage Initialization Files
Second Stage Initialization Files
Other Files
Modifying Startup Files
Reducing the Startup Code Size for C Programs
Compiler Libraries
Thread Safety
Command Line Arguments
Interrupt Handlers
Arm Cortex-A9 Compiler Usage and Options
Usage
Other Notes
C++ Code Size
C++ Standard Library
Position Independent Code (Relocatable Code)
Other Switches and Features
Embedded Design Tutorials
Drivers and Libraries
Additional Resources and Legal Notices
Xilinx Resources
Documentation Navigator and Design Hubs
Revision History
Please Read: Important Legal Notices