Differences

This shows you the differences between two versions of the page.

--- resources:fpga:docs:hdl:porting_project_quick_start_guide [02 Feb 2018 15:13] – Wording changes Adrian Costina
+++ resources:fpga:docs:hdl:porting_project_quick_start_guide [08 Apr 2024 14:32] (current) – Add documentation migration warning iulia Moldovan
@@ Line 1: / Line 1: @@
 ====== Porting ADI's HDL reference designs ======
+<note important>We are in the process of migrating our documentation to GitHubIO. This page is outdated. Please check out our latest guide at https://analogdevicesinc.github.io/hdl/user_guide/porting_project.html</note>
 In general, a given reference design for an FMC board is deployed to just a few carriers, although several [[https://github.com/analogdevicesinc/hdl/tree/master/projects/common|FPGA boards]] are supported in ADI's HDL repository. The simple reason behind this practice is that it would create a tremendous maintenance workload, that would require a lot of human resources, and would increase the required time for testing. The general rule of thumb is to support a given project with a fairly popular carrier (e.g. ZC706 or A10SoC), which is powerful enough to showcase the board features and maximum performance.
-All the HDL projects were designed to maximize source code reuse, minimize maintainability and simplify portability. The result of these design goals is that porting a given project to another carrier is fairly simple if the user respects a couple of guidelines. The main scope of this wiki page is to discuss these guidelines and provide simple indications for users who wants to port a project to a non-supported carrier.
+All the HDL projects were designed to maximize source code reuse, minimize maintainability and simplify portability. The result of these design goals is that porting a given project to another carrier is fairly simple if the user respects a couple of guidelines.
+The main scope of this wiki page is to discuss these guidelines and provide simple indications for users who wants to port a project to a non-supported carrier.
 ===== Quick Compatibility Check =====
@@ Line 8: / Line 13: @@
 <note>All ADI's FPGA Mezzanine Cards (FMC) are designed to respect all the specifications and requirements defined in the ANSI/VITA 57.1 FPGA Mezzanine Card Standard (if not otherwise stated on board's wiki page). If the new FPGA carrier is fully compliant with this standard, there will be no obstacles preventing the user to port the project to the required carrier card.</note>
-There are two types of FMC connector: LPC (Low Pin Count) and HPC (High Pin Count). In general, an FMC board is using the FMC connector type that has enough pins for the required interfaces between the IO devices and FPGA. A carrier with an FMC HPC connector can host FMC boards with an LPC or HPC connector, but a carrier with an FMC LPC can host a board just with an FMC LPC connector.
+There are two types of FMC connectors: LPC (Low Pin Count) and HPC (High Pin Count). In general, an FMC board is using the FMC connector type that has enough pins for the required interfaces between the I/O devices and FPGA. A carrier with an FMC HPC connector can host FMC boards with an LPC or HPC connector, but a carrier with an FMC LPC can host a board just with an FMC LPC connector.
-<note tip>First, always check out the already available [[https://github.com/analogdevicesinc/hdl/tree/dev/projects/common|base designs]]. If your board is present among our supported base designs, you do not need to verify the following things and can jump to the Project creation section</note>
+<note tip>First, always check out the already available [[https://github.com/analogdevicesinc/hdl/tree/master/projects/common|base designs]]. If your board is present among our supported base designs, you do not need to verify the following things and you can jump to the Project creation section</note>
 The most important things to check before porting are related to the ANSI/VITA 57.1 standard (the list is not necessarily exhaustive):
@@ Line 16: / Line 21: @@
   * Power and ground lines - 3P3V/3P3VAUX/12P0V/GND
   * VADJ - adjustable voltage level power from the carrier, each board has a specific requirement for VADJ
-  * Dedicated pins for clock signals - all the clock dedicated pins should be connected to a clock capable pin of the FPGA (IO pin which is capable to receive and/or transmit a clock signal)
+  * Dedicated pins for clock signals - all the clock dedicated pins should be connected to a clock capable pin of the FPGA (I/O pin which is capable to receive and/or transmit a clock signal)
   * Dedicated pins for transceiver lines (DPx_[M2C|C2M]_[P|N])
-<note important>To check all the requirements please refer to the ANSI/VITA 57.1 standard. The above few hints do not cover all the FMC standard and you may miss something that can prevent the port of the project.</note>
+<note important>To check all the requirements, please refer to the ANSI/VITA 57.1 standard. The above few hints do not cover all the FMC standards and you may miss something that can prevent the porting of the project.</note>
-<note tip>Make sure that you've reviewed all the documentation and design files in order to know the electrical specifications and/or requirements of the FMC board. If you're not sure, ask!</note>
+<note tip>Make sure that you have reviewed all the documentation and design files in order to know the electrical specifications and/or requirements of the FMC board. If you're not sure, ask!</note>
 ===== Base design files =====
-At [[https://wiki.analog.com/resources/fpga/docs/arch|HDL Architecture]] wiki describes a generic base design and possible components of it. The user should look at it as a suggestion only.
+At [[/resources/fpga/docs/arch|HDL Architecture]] wiki it is described a generic base design and possible components of it. The user should look at it as a suggestion only.
+<note tip>In [[repo>hdl/tree/master/projects/common|/projects/common/$carrier_name/]] you can find templates for the //system_top.v//, //Makefile//, etc. to help you when creating a new project. </note>
 ==== Example with a Xilinx board ====
-In this section we are presenting all the necessary steps to create a base design for the Xilinx ZCU102 development board.
+In this section, we are presenting all the necessary steps to create a base design for the Xilinx ZCU102 development board.
-First, you need to create a new directory in ~/projects/common with the name of the carrier.
+First, you need to create a new directory in //~/projects/common// with the name of the carrier.
 <code>[~/hdl]cd projects/common
@@ Line 38: / Line 45: @@
 The **zcu102** directory must contain the following files:
   * **zcu102_system_bd.tcl** - This script describes the base block design
-  * **zcu102_system_constr.xdc** - IO constraint file for the base design. Will contain IO definitions for GPIO, switches, LEDs or other peripherals of the board
+  * **zcu102_system_constr.xdc** - I/O constraint file for the base design. It will contain I/O definitions for GPIO, switches, LEDs or other peripherals of the board
   * MIG configuration file (if needed) - This file can be borrowed for the golden reference design of the board
   * other constraints files if needed
-You should define the board and its device in the project flow script, called ([[https://github.com/analogdevicesinc/hdl/blob/master/projects/scripts/adi_project.tcl|adi_project.tcl]]), by adding the following lines to the beginning of the **adi_project_create** process:
+You should define the board and its device in the project flow script, called ([[https://github.com/analogdevicesinc/hdl/blob/master/projects/scripts/adi_project_xilinx.tcl|adi_project_xilinx.tcl]]), by adding the following lines to the beginning of the **adi_project_create** process:
 <code tcl>if [regexp "_zcu102$" $project_name] {
@@ Line 59: / Line 66: @@
 ==== Example with an Intel board ====
-To create a new base design for a given Intel FPGA carrier board the following steps should be taken (the a10soc carrier was used as an example).
+To create a new base design for a given Intel FPGA carrier board, the following steps should be taken (the A10SoC carrier was used as an example).
 The following files should be created or copied into the directory:
-  * **a10soc_system_assign.tcl** - global and IO assignments of the base design
+  * **a10soc_system_assign.tcl** - global and I/O assignments of the base design
   * **a10soc_system_qsys.tcl** - the QSYS base design
-You should define the board and its device in the flow script ([[https://github.com/analogdevicesinc/hdl/blob/dev/projects/scripts/adi_project_alt.tcl|adi_project_alt.tcl]]), by adding the following lines to the beginning of the **adi_project_altera** process:
+You should define the board and its device in the flow script ([[https://github.com/analogdevicesinc/hdl/blob/master/projects/scripts/adi_project_intel.tcl|adi_project_intel.tcl]]), by adding the following lines to the beginning of the **adi_project_altera** process:
 <code tcl>if [regexp "_a10soc$" $project_name] {
@@ Line 73: / Line 80: @@
 }</code>
-===== Project files for Xilinx boards =====
+===== Project files =====
-To follow the project framework as much as possible the easiest way is to copy all the projects files from an already existing project and modifying those file to support the new carrier. A project for a Xilinx FPGA board should contain the following files:
+==== Project files for Xilinx boards ====
-  * **system_project.tcl** - This script is creating the actual Vivado project and runs the synthesis/implementation of the design. The name of the carrier must be updated.
+To follow the project framework as much as possible, the easiest way is to copy all the projects files from an already existing project and modifying those files to support the new carrier. A project for a Xilinx FPGA board should contain the following files:
-  * **system_bd.tcl** - In this file is sourced the base design's Tcl script and the board design's Tcl script. The name of the carrier must be updated.
+  * **system_project.tcl** - This script is creating the actual Vivado project and runs the synthesis/implementation of the design. The name of the carrier from inside the file, must be updated.
-  * **system_constr.xdc** - Constraint files of the board design. Here is defined the FMC IO's and board specific clock signals. All the IO definition must be updated, with the new pin names.
+  * **system_bd.tcl** - In this file is sourced the //base// design's Tcl script and the //board// design's Tcl script. Again, the name of the carrier must be updated.
-  * **system_top.v** - Top wrapper file, in which the system_wrapper.v module is instantiated, and a few I/O macros are defined. The IO port of this verilog module will be connected to actual IO pads of the FPGA. The simplest way to update the system_top is to let the synthesis fail and the tool will tell which ports are missing or which ports are redundant. The first thing to do after the failure is to verify the instantiation of the system_wrapper.v. This file is a tool generated file and can be found at <project_name>.srcs/sources_1/bd/system/hdl/system_wrapper.v. Fixing the instantiation of the wrapper module in most cases eliminates all the errors. If you get errors that you can not fix, ask for support.
+  * **system_constr.xdc** - Constraint file of the board design. Here are defined the FMC I/O pins and board specific clock signals. All the I/O definitions must be updated, with the new pin names.
+  * **system_top.v** - Top wrapper file, in which the system_wrapper.v module is instantiated, and a few I/O macros are defined. The I/O port of this Verilog module will be connected to actual I/O pads of the FPGA. The simplest way to update the //system_top// is to let the synthesis fail and the tool will tell you which ports are missing or which ports are redundant. The first thing to do after the failure is to verify the instantiation of the system_wrapper.v. This file is a tool generated file and can be found at //<project_name>.srcs/sources_1/bd/system/hdl/system_wrapper.v//. Fixing the instantiation of the wrapper module in most cases eliminates all the errors. If you get errors that you cannot fix, ask for support.
   * **Makefile** - This is an auto-generated file, but after updating the carrier name, should work with the new project without an issue.
-===== Project files for Intel boards =====
+==== Project files for Intel boards ====
 To follow the project framework as much as possible the easiest way is to copy all the projects file from an already existing project and modifying those files to support the new carrier. A project for an Intel FPGA board should contain the following files:
-  * **system_project.tcl** - This script is creating the actual Quartus project and run the synthesis/implementation of the design. It also contains the IO definitions for the interfaces between the FMC board and FPGA. The carrier name and all the IO pin names must be updated.
+  * **system_project.tcl** - This script is creating the actual Quartus project and runs the synthesis/implementation of the design. It also contains the I/O definitions for the interfaces between the FMC board and FPGA. The carrier name and all the I/O pin names inside the file, must be updated.
-  * **system_qsys.tcl** - In this file is sourced the base design's Tcl script and the board design's Tcl script. The name of the carrier must be updated.
+  * **system_qsys.tcl** - In this file is sourced the //base// design's Tcl script and the //board// design's Tcl script. Again, the name of the carrier must be updated.
   * **system_constr.sdc** - Contains clock definitions and other path constraints
-  * **system_top.v** - Top wrapper file of the project. The IO port of this verilog module will be actual IO pads of the FPGA. Need to make sure that the base design's IOs are updated. (Delete nonexistent IO or add new ones). The simplest way to update the system_top is to let the synthesis fail and the tool will tell which ports are missing or which ports are redundant.
+  * **system_top.v** - Top wrapper file of the project. The I/O ports of this Verilog module will be actual I/O pads of the FPGA. You must make sure that the base design's I/Os are updated (delete nonexistent I/Os or add new ones). The simplest way to update the //system_top// is to let the synthesis fail and the tool will you tell which ports are missing or which ports are redundant.
   * **Makefile** - This is an auto-generated file, but after updating the carrier name, it should work with the new project without an issue.
+===== Tips =====
+==== Generating the FMC I/O constraints ====
+The easiest way of writing the constraints for FMC I/O pins is making use of a script called [[repo>hdl/tree/master/projects/scripts/adi_fmc_constr_generator.tcl|adi_fmc_constr_generator.tcl]].
+Required setup:
+  * Carrier common FMC connections file ([[repo>hdl/tree/master/projects/common]]/<carrier>/<carrier>_<fmc_port>.txt)
+  * Project common FMC connections file ([[repo>hdl/tree/master/projects]]/<project>/common/<project>_fmc.txt)
+<note tip>In cases where these files don't already exist, you can make your own by following some existing ones as an example. For project common files, you can easily make them using our [[repo>hdl/tree/master/docs/FMC_eval_board_template.xlsx|template]] by following the instructions inside of it.</note>
+Calling the script:
+To use this script you can source it in any tcl shell or simply call the adi_fmc_constr_generator.tcl with argument(s) <fmc_port>. But before sourcing or calling it, your current directory needs to be [[repo>hdl/tree/master/projects]]/<project>/<carrier>
+For example:
+  * **tclsh ../../scripts/adi_fmc_constr_generator.tcl fmc0** (the project uses only one FMC port at a time)
+  * **tclsh ../../scripts/adi_fmc_constr_generator.tcl fmc0 fmc1** (the project uses two FMC ports at a time)
+If sourced without argument(s) then you can simply call gen_fmc_constr <fmc_port>.
+For example:
+  * **gen_fmc_constr fmc0** (the project uses only one FMC port at a time)
+  * **gen_fmc_constr fmc0 fmc1** (the project uses two FMC ports at a time)
+<note>The fmc port name can be deduced from the common carrier file name ([[repo>hdl/tree/master/projects/common]]/<carrier>/<carrier>_<fmc_port>.txt).</note>
+The generated file will appear in the current directory as **fmc_constr.xdc** (Xilinx board) or **fmc_constr.tcl** (Intel board). If ran from an open Vivado project, the generated file will be automatically added to the project.
 ===== Help and support =====
-You can ask questions at [[https://ez.analog.com/community/fpga|FPGA Reference Design]] EZ community.
+You can ask questions at [[ez>community/fpga|FPGA Reference Design]] EZ community.
 Threads that discuss this issue:

Wiki

Analog Devices Wiki

Differences

Analog Devices Wiki

Differences

Page Tools