This version is outdated by a newer approved version.DiffThis version (10 Jan 2022 14:30) was approved by Stefan-Robert Raus.The Previously approved version (16 Nov 2021 13:20) is available.Diff

This is an old revision of the document!

Building HDL

Please note that ADI only provides the source files necessary to create and build the designs. That means the burden of modifying and building these projects is on you. The build process, obviously, depends on certain software and tools. There are many ways you could use this software and tools. In other words, how you want to build these projects is entirely up to you. The only catch is that if you run into problems, you must use basic diligence in resolving it yourself.

Here we are giving you a quick rundown on how we build things. That is, the steps below are NOT a recommendation, but a suggestion. We use exclusively command line and mostly Linux systems. On Windows, we use Cygwin. Please do not ask any installation and/or setup instructions on these.

Setup and check your environment

This section contains a guide about how to setup your environment in order to build any HDL project from the repository.

First, you need to install the required FPGA Design Suite. You can find information about the proper version in the release notes. Make sure that you're always using the latest release.

If you are using a non-released branch, the easiest way to find out the required version is to look in the adi_project_xilinx.tcl and adi_project_intel.tcl scripts.

You can download the tools from the following links:

Xilinx tools

Intel tools

We are using git for version control and GNU Make to build the projects.



Clone the HDL repository

If you completed the above steps, next thing to do is clone the repository. This is the best method to get the sources. Here, I am cloning the repository inside a directory called adi. Please refer to the Git Repository section for more details.

mkdir adi
cd adi
git clone

Select your desired branch

The above command clones the 'default' branch, which is the 'master' for HDL (an alternative is to use 'git clone -b <branch>'). The 'master' branch always points to the latest stable release branch. If you want to switch to any other branch you need to checkout that branch.

cd hdl/
git status ## check for everything, including branch name
git checkout hdl_2019_r2 ## change to the hdl_2019_r2 branch

Screen shots:

Make sure everything is up to date

If this is your first time cloning, you have all the latest source files. If it has been a while, you can simply pull the latest sources using git pull or git rebase if you have local changes.

git fetch
git rebase origin/hdl_2019_r2

Screen shots:

It is good to know that the branch is up to date.

Intel: build your desired project

An Intel project build is relatively easy. There is no need to build any library components. However, the flow is the same, run 'make' to build your project of interest. In this example, I am only interested in the 'ADRV9371X' project on the 'A10SOC' carrier.

cd projects/adrv9371x/a10soc

Screen shots:

This assumes that you have the tools and licenses setup correctly. If you don't get to the last line, the make failed to build the project. There is nothing you can gather from the 'make' output (other than the build failed or not), the actual failure is in a log file. So let's see how to analyze the build log files and results.

If you want to use a NIOS-II based project with no-OS software, you have to turn off the MMU feature of the NIOS_II processor. In that case, the make will get an additional attribute:
make NIOS2_MMU=0

Intel: checking build and analyzing results

If you look closely at the 'rule' for this target, you see it is just calling 'quartus_sh' with the project TCL file and redirecting the output to a log file. In this case 'adrv9371_a10soc_quartus.log' and is inside the 'projects/adrv9371x/a10soc' directory.

make: Entering directory '/home/RKutty/gitadi/hdl/projects/adrv9371x/a10soc'
rm -rf *.log *_INFO.txt *_dump.txt db *.asm.rpt *.done *.eda.rpt *.fit.* *.map.* *.sta.* *.qsf *.qpf           *.qws *.sof *.cdf *.sld *.qdf hc_output system_bd hps_isw_handoff hps_sdram_*.csv *ddr3_*.csv increme          ntal_db reconfig_mif *.sopcinfo *.jdi *.pin *_summary.csv *.dpf
quartus_sh --64bit -t  system_project.tcl  >> adrv9371x_a10soc_quartus.log 2>&1
make: Leaving directory '/home/RKutty/gitadi/hdl/projects/adrv9371x/a10soc'

Quick (or detailed) check on files. If you are seeking support from us, this is the most relevant information you can provide (do NOT copy-paste 'make' command line text).

ls -ltr projects/adrv9371x/a10soc
tail projects/adrv9371x/a10soc/adrv9371x_a10soc_quartus.log

Screen shots:

Screen shots:

And finally, if the project build is successful, the sopcinfo and sof files should be in the same folder.

ls -ltr projects/adrv9371x/a10soc/*.sopcinfo
ls -ltr projects/adrv9371x/a10soc/*.sof

Screen shots:

You may now use this 'sopcinfo' file as the input to your no-OS and/or Linux build. The 'sof' file is used to program the device.

Xilinx: build your desired project

A Xilinx project is built the same way as an 'Intel' project. The only exception is that there are a few 'sub-make(s)' for the library components. In this example, I am building the 'DAQ2' project on the 'ZC706' carrier.

cd projects/daq2/zc706

Screen shots:

Screen shots:

The make builds all the libraries first and then builds the project. This assumes that you have the tools and licenses setup correctly. If you don't get to the last line, the make failed to build one or more targets: it could be a library component or the project itself. There is nothing you can gather from the 'make' output (other than which one failed). The actual failure is in a log file, so let's see how to analyze the build log files and results.

Enabling Out of Context synthesis

You can opt in for out of context synthesis during the build by defining the ADI_USE_OOC_SYNTHESIS system variable. By setting the ADI_MAX_OOC_JOBS system variable you can adjust the number of maximum parallel out-of-context synthesis jobs. If not set the default parallel job number is set to 4.

cd projects/daq2/zc706

This will synthesize each IP from the block design individually and will store it in a common cache for future re-use. The cache is located in the ipcache folder and is common for all the projects this way speeding up re-compile of the same project or compile time of common blocks used in base designs. Example a MicroBlaze base design for VCU118 once compiled it will be reused on other projects. Using the IP cache will speed up the re-compiles of every project in OOC mode since the cache is it not cleared as with normal compile flow.

Starting with Vivado 2020.2, Out of Context is the default mode. There is no need to set ADI_USE_OOC_SYNTHESIS variable.



only in case you want to use Project Mode.

Xilinx: checking build and analyzing results of library components

If you look closely, you see what it is actually doing. It enters a library component folder then calls 'Vivado' in batch mode. The IP commands are in the source 'Tcl' file and output is redirected to a log file. In the below example that is 'axi_ad9144_ip.log' inside the 'library/axi_ad9144' directory.

make[1]: Entering directory '/home/RKutty/gitadi/hdl/library/axi_ad9144'
rm -rf *.cache *.data *.xpr *.log component.xml *.jou xgui *.ip_user_files *.srcs *.hw *.sim .Xil
vivado -mode batch -source axi_ad9144_ip.tcl  >> axi_ad9144_ip.log 2>&1

If you see 'make' returns an error (and stops), you must first check the contents of this log file before going crazy on us. You may also do a sanity checking just to see what are the generated files and the log file contents.

ls -ltr library/axi_ad9144
tail library/axi_ad9144/axi_ad9144_ip.log

Screen shots:

Screen shots:

Xilinx: checking build and analyzing results of projects

The last thing make does in this above example is building the project. It is exactly the same 'rule' as the library component. The log file, in this example, is called 'daq2_zc706_vivado.log' and is inside the 'projects/daq2/zc706' directory.

rm -rf *.cache *.data *.xpr *.log *.jou xgui *.runs *.srcs *.sdk *.hw *.sim .Xil *.ip_user_files
vivado -mode batch -source system_project.tcl >> daq2_zc706_vivado.log 2>&1
make: Leaving directory '/home/RKutty/gitadi/hdl/projects/daq2/zc706'

Quick (or detailed) check on files.

ls -ltr projects/daq2/zc706
tail projects/daq2/zc706/daq2_zc706_vivado.log

Screen shots:

Screen shots:

And finally, if the project build is successful, the hdf file should be in the 'sdk' folder.

ls -ltr projects/daq2/zc706/daq2_zc706.sdk

Screen shots:

You may now use this 'hdf' file as the input to your no-OS and/or Linux build. Starting with Vivado 2019.3, output file extension got change from .hdf to .xsa.

Tools, Tool versions and Environment


ADI provides reference designs for both Intel and Xilinx. Please note that we have no preference over Intel or Xilinx, if possible we try to port the designs on both platforms. However, there are a few things you should be aware of when building the projects. This is NOT a comparison (generic or otherwise)- this is what you should expect and understand when using ADI HDL repository on these tools. A red text indicates that you must pay extra attention.

Notes Intel Xilinx
Main Tools Quartus Vivado
EDK Tools QSys IP Integrator
SDK Tools Eclipse-Nios, Eclipse-DS5 Eclipse
Building Library Do nothing. Quartus only need the _hw.tcl and QSys parses them whenever invoked. Need to build each and every library component. Vivado has its own way of identifying library components. This means you must build ALL the library components first before starting the project. You must re-run these scripts if there are any modifications.
Building the project Source the system_project.tcl file.
Timing Analysis The projects are usually tested and should be free of timing errors. There is no straightforward method to verify a timing pass (it usually involves writing a TCL proc by itself) on both the tools. The make build will fail and return with an error if the timing is not met (on both tools).
SDK (Microblaze/Nios) Use SOPCINFO and SOF files. Use XSA file.
SDK (ARM/FPGA combo) Not so well-thought procedure. Need to run different tools, manually edit build files etc. The steps involved are running bsp-editor, running make, modifying linker scripts, makefiles and sources, importing to SDK. Same procedure as Microblaze.
Upgrading/Version changes (non-ADI cores) Quartus automatically updates the cores. Almost hassle-free for most of the cores. Vivado does not automatically update the revisions in TCL flow (it does on GUI). It will stop at the first version mismatch (a rather slow and frustrating process).

Tool versions

Though the ADI libraries work across different versions of the tools, the projects we provide may not. The Xilinx and Intel IPs may or may not work across versions. We can only assure you that they are tested and works only for the versions we provide. The projects are usually upgraded to the latest tools after they are publicly released. The information about the version of the used tools can be found in the file of each branch. The script, which builds the project always double check the used tool version, and notifies the user, if he or she trying to use an unsupported version of tools.

There are several ways to find out which tool version you should use. The easiest way is to check the release notes. You may also check out or browse the desired branch, and verify the tool version in the base Tcl script (./hdl/projects/scripts/adi_project_xilinx.tcl) or (./hdl/projects/scripts/adi_project_intel.tcl), which build the projects.


As said above, our recommended build flow is to use make and the command line versions of the tools. This method highly facilitates our overall build and release process as it automatically builds the required libraries and dependencies.

Linux environment setup

All major distributions should have 'make' installed by default. If not if you try the command it should tell you how to install them with the package name. You may have to install 'git' (sudo apt-get install git)and the Intel and Xilinx tools. These tools come with certain 'settings*.sh' scripts that you may source in your '.bashrc' file to set up the environment. You may also do this manually (for better or worse), the following snippet is from a .bashrc file. Please note that unless you are an expert at manipulating these things, leave it to the tools to set up the environment.

export PATH=$PATH:/opt/Xilinx/Vivado/202X.X/bin:/opt/Xilinx/Vitis/202X.X/bin
export PATH=$PATH:/opt/intelFPGA_pro/2X.X/quartus/bin

Windows environment setup

The best option on Windows is to use Cygwin. When installing it, select the 'make' and 'git' packages. The manual changes to your '.bashrc' do a lot look like that of the Linux environment.

export PATH=$PATH:/cygdrive/d/Xilinx/Vivado/202x.x/bin:/cygdrive/d/Xilinx/Vitis/202x.x/bin
export PATH=$PATH:/cygdrive/d/intelFPGA_pro/2x.x/quartus/bin64

If you do not want to install Cygwin, there may still be some alternatives. There are 'make' alternatives for 'windows command prompt', minimalist GNU for Windows ('MinGW'), or the 'cygwin' variations installed by the tools itself. Some of these may not be fully functional with our scripts and/or projects. If you are an Intel user, the “Nios II Command Shell” do support make. If you are a Xilinx user, use the 'gnuwin' installed as part of the SDK, usually C:\Xilinx\Vitis\202x.x\gnuwin\bin.

Make: supported targets

Make is a build automation tool, which uses Makefile(s) to define a set of directives ('rules') about how to compile and/or link a program ('targets').

In general, always run 'make' within a project folder such as 'hdl/projects/fmcomms2/a10gx' or 'hdl/projects/fmcomms2/zc706'. There should not be a need for you to run 'make' inside the library or root folders. The 'make' framework passes the top level 'targets' to any sub-makes inside its sub-folders. What this means is that if you run 'make' inside 'hdl/projects/fmcomms2', it builds all the carriers ('ac701', 'a10gx' to 'zcu102') which is an overkill.

The following 'targets' are supported.

argument description
all This builds everything in the current folder and its sub-folders, see context examples below.
make -C library/axi_ad9122 all; ## build AD9122 library component (Xilinx only).
make -C library all; ## build ALL library components inside 'library' (Xilinx only).
make -C projects/fmcomms2/zc706 all; ## build FMCOMMS2_ZC706 (Xilinx) project.
make -C projects/fmcomms2/a10gx all; ## build FMCOMMS2_A10GX (Intel) project.
make -C projects/fmcomms2 all; ## build FMCOMMS2 ALL carrier (including Intel & Xilinx) projects.
make -C projects all; ## build ALL projects (something you really should NOT do).
clean This removes all tool and temporary files in the current folder and its sub-folders, same context as above.
clean-all This removes more things (?) same context as above.
lib This is same as 'all' in the library folder, ignored inside project folders.
project.platform This is a special target available only in the 'hdl' root folder and is ignored everywhere else, see syntax below.
make fmcomms2.a10gx ; ## build projects/fmcomms2/a10gx.
make fmcomms2.zc706 ; ## build projects/fmcomms2/zc706.

Xilinx auto Tcl build

We do not recommend using this flow (created mostly for Windows users that can't use GNU make). The benefit of this flow is that a user can build all desired libraries without manually building each library. The disadvantage comparing with make is that the script will rebuild an IP regardless if its sources were modified or not (timestamp comparison).

Open Vivado GUI, and in the Tcl console type:

cd c:/github/hdl/projects/daq2/zc706
source ../../scripts/adi_make.tcl

This will get you access to:

  1. adi_make::lib
  2. adi_make::boot_bin

Building the libraries (adi_make::lib)

This command allows you to build the desired libraries directly from the target project folder location. It accepts as arguments “all” or you can specify a specific library name.

  # How to use:
  adi_make::lib all # builds all libraries on which the project is depending on
  adi_make::lib axi_dmac # builds only the axi_dmac IP (and its dependencies)
  adi_make::lib jesd204/jesd204_rx

Building the project itself

After all required libraries are built, run source ./system_project.tcl in the Tcl console of Vivado, to build the project.

source ./system_project.tcl

Preparing the SD card

Firstly, you have to check this tutorial on how to put the Linux image on your SD card. Once you are done with that, you can go on with the following steps.

On the BOOT partition recently created, you will find folders for each carrier that we support, and each of these folders contain an archive called bootgen_sysfiles.tgz. These have all the files needed to generate the BOOT.BIN.

Copy the corresponding archive (checking for the name of your carrier and components) into the root folder of your project, unzip it twice, and there you will find the files that are needed to generate the BOOT.BIN. Copy them to be in the root directory.

  1. fsbl.elf
  2. zynq.bif
  3. u-boot.elf
  4. and if you're using ZCU102, then bl31.elf and pmu.elf

Next, what your project needs, is the uImage(for zynq based carriers), Image (for zynq ultrascale - ZCU102 and adrv9009-zu11eg carriers) or zImage (for Intel based carriers) file that you will find in the zynq-common / zynqmp-common / socfpga_arria10_common / socfpga_cyclone5_common on your BOOT partition. Copy this file also in the root directory of your project.

More info on how to generate this files you will find in the References section or on ReadMe.txt file from boot partition.

Make the BOOT.BIN (adi_make::boot_bin)

Not for Linux users. To build the BOOT.BIN in Linux see the References section.

As the name states, this procedure will build the “BOOT.BIN”. It does not require any arguments.


Building manually

We do not recommend using this flow, in general people are losing a lot of valuable time and nerve during this process.

Intel: Building manually on Quartus

There is no need to build any library for Quartus. However, you do need to specify the IP search path for QSYS. This is a global property, so only need to do it once. If you have multiple paths simply add to it. You get to this menu from the Tools→Options. The tool then parses these directories and picks up a _hw.tcl file (e.g. axi_ad9250_hw.tcl). The peripherals should show up on QSYS library.

Screen shots:

You may now run the project (generate the sof and software hand-off files) on Quartus. Open the GUI and select TCL console. At the prompt change the directory to where the project is, and source the system_project.tcl file.

cd c:/github/hdl/projects/fmcjesdadc1/a5gt
source ./system_project.tcl

You will see commands being executed, the script uses a board design in QSYS, generate all the IP targets, synthesize the netlist and implementation.

Screen shots:

Xilinx: Building manually on Vivado

In Vivado (Xilinx projects), you must build all the required libraries for your targeted project. Open the GUI and at the TCL console change the directory to where the libraries are, then source the '_ip.tcl' file.

cd c:/github/hdl/library/axi_ad9122
source ./axi_ad9122_ip.tcl

You will see commands being executed, and the GUI will change into a project window. There is nothing to do here, you could browse the source if you prefer to do synthesis as stand-alone and such things. After you're done, quit and change the directory to the next library and continue the process.

Screen shots:

After you built all the required libraries for your project, you can run the project (generate bitstream and export the design to SDK). This is the same procedure as above except for changes in path and Tcl file names:

cd c:/github/hdl/projects/fmcomms1/zc706
source ./system_project.tcl

Same behavior as above, the GUI will change into a project window. The script will create a board design in IPI, generate all the IP targets, synthesize the netlist and implementation.

Screen shots:


Errors, Warnings and Notes

Assuming the right to make an honest comment, the tools (both Quartus and Vivado) are not that useful or friendly when it comes to messages. In most cases, you may see 'hacked-in' debugging 'printf' sort of messages (Xilinx notoriously ranks high in this regard). So you are going to see a lot of 'warnings' and some 'critical-warnings' (critical to what could be hard to answer). Here are some of the commonly asked EngineerZone questions and its explanations.

Xilinx: Vivado

ERROR: [BD 5-216] VLNV <> is not supported for the current part. ERROR: [Common 17-39] 'create_bd_cell' failed due to earlier errors. while executing “create_bd_cell -type ip -vlnv axi_hdmi_clkgen” invoked from within “set axi_hdmi_clkgen [create_bd_cell -type ip -vlnv axi_hdmi_clkgen]” (file “../../../projects/common/zc706/zc706_system_bd.tcl” line 57)

You haven't generated the library component or have the wrong user IP repository setting. If you were using the GUI flow, now is a good time to evaluate the 'make' flow.

CRITICAL WARNING: [IP_Flow 19-459] IP file 'C:/Git/hdl/library/common/ad_pnmon.v' appears to be outside of the project area 'C:/Git/hdl/library/axi_ad9467'. You can use the ipx::package_project -import_files option to copy remote files into the IP directory.

These warnings appear because the libraries are using common modules which are located under the ./library/common/. These warnings can be ignored, they won't affect the functionality of the IP or the project. However, you may not be able to 'archive' these projects. The irony is that it does copy these files to the project area, but ignores them.

Navigation - HDL User Guide

resources/fpga/docs/build.1641821418.txt.gz · Last modified: 10 Jan 2022 14:30 by Stefan-Robert Raus