Vivado_build_system_fpga-vbs_Vivado_build_system_fpga-vbs.zip

<!-- # SPDX-License-Identifier: Apache-2.0 # ################################################################################ ## ## Copyright 2017-2023 Missing Link Electronics, Inc. ## ## Licensed under the Apache License, Version 2.0 (the "License"); ## you may not use this file except in compliance with the License. ## You may obtain a copy of the License at ## ## http://www.apache.org/licenses/LICENSE-2.0 ## ## Unless required by applicable law or agreed to in writing, software ## distributed under the License is distributed on an "AS IS" BASIS, ## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. ## See the License for the specific language governing permissions and ## limitations under the License. ## ################################################################################ ## ## File Name : README.md ## Initial Author : Andreas Braun <[email protected]> ## ################################################################################ --> # MLE FPGA Buildsystem for AMD Vivado TM To facilitate an FPGA Build Environment which can be automated, for example for Continuous Integration (CI), and which ensures fully reproducible results later in the development and product lifecycle, the Team at Missing Link Electronics has put together a collection of scripts. Currently focused on the AMD Vivado TM toolchain (Version 2016.4 or newer) and tested under Ubuntu Linux 16.04 LTS and 18.04 LTS, this scripted FPGA Build Environment has been made available here at GitHub under open source Apache 2.0 license. The following is a description of the FPGA project structure and build scripts to run Vivado builds in batch mode. The build scripts run under Linux and require the `bash` and common software such as `sed`, `grep`, etc. ## Before you start Place the files alongside this README file in a folder (e.g. named *scripts*) inside your project folder. Add the scripts-repository as GIT submodule to your repository or add the scripts folder to your project's *.gitignore* file. In addition, add the default build output folder *build* to your *.gitignore* file. ## add_flavor.sh `add_flavor.sh` will add a FPGA project/sub-project stub to the project's base directory. Sub-projects will be called **flavors** in the following. add_flavor.sh [flavor_name] [options] flavor_name : Sub-project to be added with name <flavor_name> -p [prj_config] : Project configuration file relative to base directory -h, -? : Print usage Before using the script, set the variables in *project.cfg* if a project wide configuration file with settings is used. Variables such as VIVADO_VERSION and PART will overwrite placeholder strings in the template/stub files that will be copied. The source template files that will be copied are located in the *templates* folder. To initialize a new FPGA project run `add_flavor.sh`. The template files will be copied to the project's base directory. You can start with the default flavor (not using the -f option) which will not create a flavor subfolder. When you need to add flavors afterwards, use the *-f* option to generate the subfolder and move the existing folders from the base directory to the flavor subfolder. See script [examples](#add_flavorsh-examples) at the end of this file. ## Project structure and build scripts The build system consists of the folders *scripts*, *constr*, *filelists*, *hdl*, *ip*, *sim* and the files *config.dict* and *project.cfg*. The *scripts* folder is shared among all flavors and contains TCL and Shell scripts to issue a Vivado build process; all other files/folders are generated for each flavor separately. * *scripts* : Contains TCL/Shell script files to run a Vivado batch-mode build * *constr* : Contains constraints files * *hdl* : Contains Verilog/VHDL source files * *ip* : Contains Verilog/VHDL source files for IP cores * *sim* : Contains test bench and waveform files for simulation * *filelists* : Contains filelists which refer to files in folders named above * *config.dict* : Main configuration file of the build process * *project.cfg* : Optional project configuration file used by the build scripts Running `build.sh` in a Vivado environment (e.g. for Vivado 2019.1 under Ubuntu run */opt/xilinx/vivado/v2019.1/Vivado/2019.1/settings64.sh*) will execute Vivado in non-project batch mode and pass over *build.tcl* with additional arguments. Vivado will execute *build.tcl* where the main build configuration file *config.dict* will be read to obtain all settings for the build. ### project.cfg Optional configuration file for the build scripts to be placed in the project's base directory. Sets variables to replace placeholder strings in copied template files and stores project name and flavors of the project. If *project.cfg* is not located in the project's base folder or has a different name, you may use the *-p* argument of `add_flavor.sh` and `build.sh` to target the configuration file. A template configuration file may be copied from *scripts/templates/project.cfg*. ### config.dict *config.dict* is a TCL dictionary with build settings as white space separated key-value tupels. Unused dictionary entries may be removed unless otherwise noted. There may exist multiple *<config>.dict* files that define different build settings/filesets and a specific one may be used for the build by using the *-c* option of `build.sh`. *** It defines mandatory parameters (MDT_PARAMS) such as Vivado version or FPGA part number which will be set initially by `add_flavor.sh`. Example: MDT_PARAMS { req_vivado_vers "2019.1" target_language "Verilog" default_lib "xil_defaultlib" part "xc7z045ffg900-2" } *** Also the fileset to be used for the build will be set by keys. Each 'filelist'-'directory' tupel adds a filelist (f-file) and a directory path relative to the flavor sub-directory where the source files are located to the *SET*. When a *SET* is unused, it may be removed. * Files added to CONSTR_SET will be added to Vivado's constraints-fileset * Files added to SRC_SET will be added to Vivado's source-fileset * Files added to SIM_SET will be added to Vivado's simulation-fileset * Files added to INCL_SET will be set as include directories for source- and simulation-fileset * Files added to SIM_INCL_SET will be set as include directories for simulation-fileset * Files added to TCL_SET will be sourced Example: SRC_SET { filelists/hdl.f hdl filelists/ip.f ip } *** Include/Merge dictionary file using the */include/* key. The file path is relative to the including dictionary file. Behavior: * Add keys to hierarchy if not existent * Overwrite values of existing keys at leaf level Example: /include/ "base-config.dict" *** Delete dictionary key by hierarchical statement using the ':' character to step into the next key-value level. Example: /delete/ {SRC_SET:filelists/ip.f} /delete/ {SIM_SET} *** Top level HDL generics may be set using the GENERICS key. Example: GENERICS { SIMULATION "FALSE" NUM_LANES 4 } *** Verilog options such as defines may be set using the VERILOG_OPTIONS key. Example: VERILOG_OPTIONS { # Verilog defines DEFINES { SIMULATION "FALSE" NUM_LANES 4 } SIM_DEFINES { } } *** Set miscellaneous/optional parameters using the OPT_PARAMS key. * fpga_top: FPGA design top level module name * debug_target: Constraints file to be marked as 'target' by Vivado. If the file does not exist, it will be created local to the project (with name 'debug.xdc' for an empty string) * board: FPGA board part * xpr_name: Vivado project name * ipxact_dir: IP-XACT repositories relative to flavor * use_ip_cache_dir: IP Cache directory relative to flavor. The default folder (empty string) is the build container directory e.g. *build/ip_cache