Page History

...

...

Table of contents

Quick Start

The most Trenz Electronic FPGA Reference Designs are TCL-script based project.

...

Online version of this manual and other related documents can be found at https://wiki.trenz-electronic.de/display/PD/Project+Delivery+-+Xilinx+devices

...

If you use our prepared batch files for project creation do the following steps:

1. open "design_basic_settings.cmd" with text editor and set correct vivado path and board part number
2. run "vivado_create_project_guimode.cmd"

See  Reference Design: Getting Started for more details.

If you need our Board Part files only, see Board Part Installation.

Zip Project Delivery

Zip Name Description

...

Last supported Release

...

1.9

...

Directory structure

...

...

...

Windows Command Files

...

Settings for the other *.cmd files. Following Settings are avaliable:

• General Settings:
  • (optional) DO_NOT_CLOSE_SHELL: Shell do not closed after processing
  • (optional) ZIP_PATH: Set Path to installed Zip-Program. Currently 7-Zip are supported. IUsed for predefined TCL-function to Backup project.
  • (optional) ENABLE_SDSOC: Enable SDSOC Setting. Currently only for some reference project as beta version!
• Xilinx Setting:
  
  • XILDIR: Set Xilinx installation path (Default: c:\Xilinx).
  • VIVADO_VERSION: Current Vivado/LabTool/SDK Version (Example:2015.4). Don't change Vivado Version.
    • Xilinx Software will be searched in:

    • VIVADO (optional for project creation and programming): %XILDIR%\Vivado\%VIVADO_VERSION%\

    • SDK (optional for software projects and programming): %XILDIR%\SDK\%VIVADO_VERSION%\

    • LabTools (optional for programming only): %XILDIR%\Vivado_Lab\%VIVADO_VERSION%\

    • SDSOC (optional): %XILDIR%\SDSOC\%VIVADO_VERSION%\
• Board Setting:
  • PARTNUMBER: Set Board part number of the project which should be created
    • Available Numbers: (you can use ID,PRODID,BOARDNAME or SHORTNAME from TExxxx_board_file.csv list)
    • Used for project creation and programming
    • To create empty project without board part, used PARTNUMBER=-1 (use GUI to create your project. No block design tcl-file should be in /block_design)
    • Example TE0726 Module :
    • USE ID                 |USE PRODID                      |Use Boardname                                                |Use Shortname
      PARTNUMBER=1|PARTNUMBER=te0726-01 |PARTNUMBER=trenz.biz:te0726-01:part0:1.0 |PARTNUMBER=TE0726-01
• Programming Settings(program*file.cmd):
  
  • SWAPP: Select Software App, which should be configured.
    • Use the folder name of the <design_name>/prebuilt/boot_image/<partname>/* subfolder. The *bin,*.mcs or *.bit from this folder will be used.
    • If you will configure the raw *.bit or *.mcs  *.bin  from the <design_name>/prebuilt/hardware/<partname>/ folder, use @set SWAPP=NA or @set SWAPP="".
    • Example: SWAPP=hello_world   → used the file from prebuilt/boot_image/<partname>/hello_world
                      SWAPP=NA                → used the file from <design_name>/prebuilt/boot_image/<partname>/
  • PROGRAM_ROOT_FOLDER_FILE: If you want to program design file from the rootfolder <design_name>, set to 1

    • Attention: it should be only one *.bit, *.msc or *.bin file in the root folder.

...

(optional)  Create Project with setting from "design_basic_settings.cmd" and source folders. Build all Vivado hardware and software files if the sources are available.

Delete  "<design_name>/vivado/", and "<design_name>/workspace/hsi/" directory with related documents before Projekt will created.

...

Hardware Design

...

Create Project with setting from "design_basic_settings.cmd" and source folders. Vivado GUI will be opened during the process.

Delete "<design_name>/vivado/", and "<design_name>/workspace/" directory with related documents before Projekt will created.

If old vivado project exists, type "y" into the command line input to start project creation again.

...

(optional)  Create Project with setting from "design_basic_settings.cmd" and source folders.

Delete  "<design_name>/vivado/", and "<design_name>/workspace/" directory with related documents before Projekt will created.

If old vivado project exists, type "y" into the command line input to start project creation again.

...

(optional)  Create or open an existing Vivado Lab Tools Project. (Additional TCL functions from Programming and Utilities Group are usable). Settings are done in "design_basic_settings.cmd".

TE-TCL-Extentsions

...

Create new Block-Design with initial Setting for PS, for predefined bd_names:
fsys→Fabric Only, msys→Microblaze, zsys→7Series Zynq, zusys→UltraScale+ Zynq

Typ TE::hw_blockdesign_create_bd -help for more information

...

Copies current Hardware files and reports from the vivado project to the prebuilt folder, if -prebuild_hdf <arg> isn't set.
Copy the Hardware Defintition file to the working directory:<design_name>/workspace/hsi
Run HSI in <design_name>/workspace/hsi for all Programes listed in <design_name>/sw_lib/apps_list.csv
If HSI is finished, BIF-GEN and BIN-Gen are running for these Apps in the prepuilt folders <design_name>/prebuilt/...
You can deactivate different steps with following args :

• -no_hsi  : *.elf filesgeneration is disabled
• -no_bif   : *.bif files generation is disabled
• -no_bin  : *.bin files generation is disabled
• -no_bitmcs: *.bit and *.mcs file (with software design) is disabled

...

Copies current Hardware files and reports from the vivado project to the prebuilt folder, if -prebuild_hdf <arg> isn't set.
Copy the Hardware Defintition file to the working directory:<design_name>/workspace/sdk
Start SDK GUI in this workspace

...

Copies current Hardware files and reports from the vivado project to the prebuilt folder, if -used_board <arg> isn't set (Vivado only).
Programming Bitfile from <design_name>/prebuilt/hardware/<board_file_shortname> to the fpga device.
If "-used_basefolder_bitfile" is set, the Bitfile (*.bit)  from the base folder (<design_name>) is used instead of the prebuilts. Attention: Take only one Bitfile in the basefolder!

(MicroBlaze only) If "-swapp" is set, the Bitfile with *.elf configuration is used from <design_name>/prebuilt/boot_images/<board_file_shortname>/<app_name>

...

Attention: For Zynq Systems only!
Program the Bootbin from <design_name>/prebuilt/boot_images/<board_file_shortname>/<app_name> to the fpga device.
Appname is selected with: -swapp <app_name>
After programming device reboot from memory will be done.
Default SDK Programmer is used, if not available LabTools Programmer is used.
If "-used_basefolder_binfile" is set, the Binfile (*.bin)  from the base folder (<design_name>) is used instead of the prebuilts. Attention: Take only one Binfile in the basefolder!

...

Copies current Hardware files and reports from the vivado project to the prebuilt folder, if -used_board <arg> isn't set (Vivado only).
Initialise flash memory with configuration from *_board_files.csv
Programming  MCSfile from <design_name>/prebuilt/hardware/<board_file_shortname> to the Flash Device.
After programming device reboot from memory will be done.
If "-used_basefolder_binfile" is set, the MCSfile (*.mcs)  from the base folder (<design_name>) is used instead of  the prebuilts. Attention: Take only one MCSfile in the basefolder!

(MicroBlaze only) If "-swapp" is set, the MCSfile with *.elf configuration is used from <design_name>/prebuilt/boot_images/<board_file_shortname>/<app_name>

...

Make a Backup from your Project in <design_name>/backup/

Zip-Program Variable must be set in start_settings.cmd. Currently only 7-Zip is supported.

...

Create SDSOC-Workspace. Currently only on some Reference-Designs available. Run [-check_only] option to check SDSOC ready state.

...

Design Environment: Usage

Reference-Design: Getting Started

...

...

...

Programming FPGA or Flash Memory with prebuilt Files:
7. Connect your Hardware-Modul with PC via JTAG.
With Batch-file:
8. (optional) Zynq-Devices Flash Programming (*.bin):
    Run “program_flash_binfile.cmd”
9. (optional) FPGA-Device Flash Programming (*.mcs):
    Run “program_flash_mcsfile.cmd”
10. (optional) FPGA-Device Programming (*.bit):
      Run “program_fpga_bitfile.cmd”
With Vivado/Labtools TCL-Console:
11. Run “vivado_open_existing_project_guimode.cmd” or “labtools_open_project_guimode.cmd” to open Vivado  or LabTools
12. (optional) Zynq-Devices Flash Programming (*.bin):
      Type “TE::pr_program_flash_binfile -swap <app_name>” on Vivado TCL-Console
      Used *.bin from <design_name>/prebuilt/boot_images/<board_file_shortname>/<app_name>
13. (optional) FPGA-Device Flash Programming (*.mcs):
      Type “TE:: pr_program_flash_mcsfile -swap <app_name>” on Vivado TCL-Console
      Used *.mcs from <design_name>/prebuilt/boot_images/<board_file_shortname>/<app_name>
14. (optional) FPGA-Device Programming (*.bit):
      Type “TE:: pr_program_jtag_bitfile -swap <app_name>” on Vivado TCL-Console
      Used *.bit from <design_name>/prebuilt/boot_images/<board_file_shortname>/<app_name>

Basic Design Settings

Project Configuration

1. Unzip project files
2. Rename basefolder (basefolder name is used as project name)
3. Edit design_basic_settings.cmd
   1. Select the correct Xilinx Program path (See: Windows Command Files → design_basic_settings.cmd)
   2. Select the correct board part number for your PCB  (See: Windows Command Files → design_basic_settings.cmd)
   3. Other settings are optional  (See: Windows Command Files → design_basic_settings.cmd)
4. Excecute vivado_create_project_guimode.cmd or vivado_create_project_batchmode.cmd to generate a vivado project with the predefined Block Design from the Block Design folder
5. Open Vivado with vivado_open_existing_project_guimode.cmd (if you use vivado_create_project_guimode.cmd on step 4, you didn't need this)
6. Open the Block Design and create your own design inside this Block Design.
7. Backup your Block Design as tcl-script: Type "TE::hw_blockdesign_export_tcl" on Vivado Tcl Console. The old one will be overwritten.
8. Build your Design...

Initialise TE-scripts on Vivado/LabTools

• Variant 1 (recommended):
  • Start the project with the predefined command file (vivado_open_existing_project_guimode.cmd) respectively LabTools with (labtools_open_project_guimode.cmd)
• Variant 2:
  • Create your own Initialisation Button on the Vivado GUI:
    • Tools → Customize Commands → Customize Commands...
    • Push
    • Type Name ex.: Init Scripts
    • Press Enter
    • Select Run command and insert:
      
      • for Vivado: cd [get_property DIRECTORY [current_project]]; source -notrace "../scripts/reinitialise_all.tcl"
      • for LabTool: cd [pwd]; source -notrace "../scripts/reinitialise_all.tcl"
        
    • Press Enter
    • A new Button is shown on the Vivado Gui: All Scripts are reinitialised, if you press this Button.
      
• Variant 3:
  • Reinitialise Script on Vivado TCL-Console:
    • Type: source ../scripts/reinitialise_all.tcl
      

Use predefined TE-Script functions

• Variant 1 (recommended):
  • Typ function on Vivado TCL Console, ex.: TE::help
  • TE::help
    
    • Show all predefined TE-Script functions.
  • TE:<functionname> -help 
    
    • Show short description of this function.
    • Attention: If -help argument is set, all other args will be ignored. 
• Variant 2:
  • Create your own function Button on the Vivado GUI:
    • Tools → Customize Commands → Customize Commands...
    • Push +
    • Type Name ex.: Run SDK
      
    • Press Enter
      
    • Select Run command and insert function:
      • Variante 1 (no Vivado request window for args):
        • insert function and used args, ex.: TE::sw_program_zynq -swapp hello_world
      • Variant 2 (Vivado request window for args):
        • insert function, ex.:TE::sw_program_zynq
        • Press Define Args...
        • For every arg:
          
          • Push
          • Typ Name, Comment, Default Value and set optional
          • Press Enter
            
          • Example for args:
          • • Push
            • Index, Key Name, -swapp,
            • Push
            • Appname, Arg, hello_world,
              
             
    • Press Enter
    • A new Button is shown on the Vivado Gui.

Hardware Design

Board Part Files

Structure Board Parts

Board Parts located on subfolder "board_files", with the name of the special board. Revisions are splitt in the subfolder of the board part <boardpart_name><version>

Every Version of a Board Parts consists of four files:

• board.xml
  
• part0_pins.xml
• preset.xml
• picture.jpg

Board Part Carrier Extension

Board Part Carrier Extension is a TCL-Script and is used with TE-Scripts only. It contains additional settings of PS-System for special carrier-board.

Use Reference Designs or Vivado TCL-Console(TE-Script extensions, see Initialise TE-scripts on Vivado/LabTools): TE::hw_blockdesign_create_bd -help to create PS with full settings. Or source the TCL file manually direct after "Run Block Automation" 

Board Part CSV Description

Board Part csv file is used for TE-Scripts only.

...

"<Flash Name from Vivado>|<SPI Interface>|<Flash Size in MB>" or "NA" , NA is not defined, ex. s25fl256s-3.3v-qspi-x4-single|SPIx4|32

Flash Name is used for programming, SPI Interface and Size in MB is used for *.mcs build.

Block Design Conventions

...

Recommended BD-Names (currently importend for some TE-Scripts):
 

...

<!--
Generate new entry:
1:add new row below first
2:Copy Page Information Macro(date+user) Preview, Page Information Macro Preview, Vivado Version(or update)to the empty row
3.Update Metadate =Page Information Macro Preview+1
  -->

...

XDC Conventions

...

Recommended XDC-Names (used for Vivado XDC-options):

...

Backup Block Design as TCL-File

• Backup your Block-Design with TCL-Command "TE::hw_blockdesign_export_tcl" in <design_name>/block_design/
  It will be saved as *_bd.tcl
  Attention: If subfolder <design_name>/block_design/<board_file_shortname> is defined, it will be saved there!
                  Only one *.tcl file shoud be in the backup folder respectively the subfolder <board_file_shortname>

Microblaze Firmeware

• Microblaze Firmware (*.elf) can be add to the source folder <design_name>/firmware/<Microblaze IP Instance>.

Software Design

HSI: Generate predefined software from libraries

• To generate predefinde software from libraries, run "TE::sw_run_hsi" on Vivado TCL-Console
• All programs in in <design_name>/sw_lib/apps_list.csv are generated automaticly
• Supported are local application libaries from <design_name>/sw_lib/sw_apps or the most Xilinx SDK Applications found in %XILDIR%/SDK/%VIVADO_VERSION%/data/embeddedsw/lib/sw_app

SDK: Create user software project

• To start SDK project, run "TE::sw_run_sdk" on Vivado TCL-Console
  Include Hardware-Definition-File, Bit-file and local Software-libraries from  <design_name>/sw_lib/sw_apps
• To use Hardware-Definition-File, Bit-file from prebuilt folder without building the vivado hardware project, run "sdk_create_prebuilt_project_guimode.cmd" or type  "TE::sw_run_sdk -prebuilt_hdf <board_number>" on Vivado-TCL-Console
  
•  To open an existing SDK-project without update HDF-Data, type  "TE::sw_run_sdk -open_only" on Vivado-TCL-Console

Advanced Usage

Attention not all features of the TE-Scripts are supported in the advanced usage!

User defined board part csv file

To modifiy current board part csv list, make a copy of the original csv and rename with suffix "_mod.csv", ex.TE0782_board_files.csv as TE0782_board_files_mod.csv. Scripts used modified csv instead of the original file.

See Chapter Board Part Files for more information.

User defined Settings

Vivado settings:

Vivado Project settings (corresponding TCL-Commands) can be saved as a user defined file "<design_name>/settings/project_settings.tcl". This file will be loaded automatically on project creation.

Script settings:

Additional script settings (only some predefined  variables) can be  saved as a user defined file "<design_name>/settings/development_settings.tcl". This file will be loaded automatically on script initialisation.

ZIP ignore list:

Files which should not be added in the backup file can be can be defined in this file: "<design_name>/settings/zip_ignore_list.tcl". This file will be loaded automaticaly on script initialisation.

SDSOC settings:

SDSOC settings will are deposited on the following folder: "<design_name>/settings/sdsoc"

SDSOC-Template

SDSOC description and files to generate SDSoC project are deposited on the following folder: "<design_name>/settings/sdsoc"

HDL-Design

HDL files can be saved in the subfolder "<design_name>/hdl/" or "<design_name>/hdl/<shortname>". They will be loaded automatically on project creation. Available formats are *.vhd, *.v and *.sv.  A own top-file must be specified with the name "<design_name>_top.v" or "<design_name>_top.vhd".

To set file attributes, the file name must include "_simonly_" for simulation only and "_synonly_" for synthese only.

RTL-IP-cores (*.xci). can be saved in the subfolder "<design_name>/hdl/xci" or "<design_name>/hdl/xci/<shortname>". They will be loaded automatically on project creation.

Checklist / Troubleshoot

1. Are you using exactly the same Vivado version? If not then the scripts will not work, no need to try.
2. Ary you using Vivado in Windows PC? Vivado works in Linux also, but the scripts are tested on Windows only.
3. Is you PC OS Installation English? Vivado may work on national versions also, but there have been known problems.
4. Are space character on the project path? Somtimes TCL-Scripts can't handle this correctly. Remove spaces from project path.
5. Did you have the newest reference design build version? Maybe it's only a bug from a older version.
6. Check <design_name>/v_log/vivado.log? If no logfile exist, wrong xilinx paths are set in design_basic_settings.cmd
7. On project creation process old files will be deleted. Sometimes the access will be denied by os (synchronisiation problem) and the scripts canceled. Please try again. 
   
8. If nothing helps, send a mail to Trenz Electronic Support (support[at]trenz-electronic.de) with subject line "[TE-Reference Designs] ",  the complete zip-name from your reference design and the last log file (<design_name>/v_log/vivado.log)

References

1. Vivado Design Suite User Guide - Getting Started  (UG910)
2. Vivado Design Suite User Guide - Using the Vivado IDE (UG893)
3. Vivado Design Suite User Guide - I/O and Clock Planning (UG899)
4. Vivado Design Suite User Guide - Programming and Debugging (UG908)
5. Zynq-7000 All Programmable SoC Software Developers Guide (UG821)
6. SDSoC Environment User Guide - Getting Started (UG1028)
7. SDSoC Environment -  User Guide (UG1027)
8. SDSoC Environment User Guide - Platforms and Libraries (UG1146)

Document Change History

To get content of older revision  got to "Change History"  of this page and select older revision number.

...

...

...

<style>
.wiki-content .columnLayout .cell.aside {
width: 0%;
}</style>

...