From 3cee92683af3d36bbfd93a764a9859e2915a507d Mon Sep 17 00:00:00 2001 From: Iulia Moldovan Date: Thu, 20 Jul 2023 16:04:46 +0300 Subject: [PATCH] docs/user_guide: Add user guide documentation * Created the first level of pages for the User guide, from Analog Wiki: * Architecture * Build HDL * Customize HDL * Docs guidelines (edited) * Git repository * HDL coding guideline (edited) * Introduction * IP cores * Porting projects (edited) * Releases * Third party * Moved hdl_coding_guideline under user_guide and changed extension to rst * Deleted hdl_pr_process.md * docs_guideline: Add reference to project doc template * porting_project: Signed-off-by: Iulia Moldovan --- docs/hdl_coding_guideline.md | 713 ----- docs/hdl_pr_process.md | 66 - docs/user_guide/architecture.rst | 526 ++++ docs/user_guide/build_hdl.rst | 842 ++++++ docs/user_guide/customize_hdl.rst | 17 + docs/user_guide/docs_guidelines.rst | 28 +- docs/user_guide/git_repository.rst | 189 ++ docs/user_guide/hdl_coding_guideline.rst | 868 ++++++ docs/user_guide/index.rst | 31 + docs/user_guide/introduction.rst | 34 + docs/user_guide/ip_cores.rst | 74 + docs/user_guide/porting_project.rst | 147 +- docs/user_guide/releases.rst | 157 ++ docs/user_guide/sources/base_platform.svg | 2913 +++++++++++++++++++++ docs/user_guide/third_party.rst | 31 + 15 files changed, 5787 insertions(+), 849 deletions(-) delete mode 100755 docs/hdl_coding_guideline.md delete mode 100644 docs/hdl_pr_process.md create mode 100644 docs/user_guide/architecture.rst create mode 100644 docs/user_guide/build_hdl.rst create mode 100644 docs/user_guide/customize_hdl.rst create mode 100644 docs/user_guide/git_repository.rst create mode 100755 docs/user_guide/hdl_coding_guideline.rst create mode 100644 docs/user_guide/introduction.rst create mode 100644 docs/user_guide/ip_cores.rst create mode 100644 docs/user_guide/releases.rst create mode 100755 docs/user_guide/sources/base_platform.svg create mode 100644 docs/user_guide/third_party.rst diff --git a/docs/hdl_coding_guideline.md b/docs/hdl_coding_guideline.md deleted file mode 100755 index d3f97b7ad..000000000 --- a/docs/hdl_coding_guideline.md +++ /dev/null @@ -1,713 +0,0 @@ -# HDL Coding Guidelines - - -## Introduction - -This document contains coding and documentation guidelines which must be -followed by all HDL projects. The purpose of this document is to establish -a set of rules that specify the layout, naming conventions and some general -coding practices for the HDL modules implementation. Specific HDL coding practices -meant to obtain maximum performance from a FPGA design are described by external -documents such as [1] and [2] and are not included in this document. - -There are two types of rules: *should* and *must* rules - * *Should* rules are advisory rules. They suggest the recommended way of doing -things. - * *Must* rules are mandatory requirements. - -The coding rules are intended to be applied to HDL modules written using VHDL -or Verilog. - -When an external IP is used, the naming conventions practiced by the IP *should* be kept, -even if they do not match the rules specified in this document. - -## Coding Style - -### A. Layout - -**A1**: For indentation, spaces **must** be used instead of tabs. This allows -the code to be properly visualized by any editor. **Do not** leave spaces at -the end of a line. The following editor settings **must** be used: -*Tab Size*: 2, *Indent Size*: 2 - - -**A2**: One white space **must** be inserted around operators, such as -=, ==, &&, ||, &, |, ^, etc. - -#### Example: - -##### Incorrect: -```verilog -if((my_signal1==1'b0)&&(my_bus[3:0]==4'd5)) -``` - -##### Correct: -```verilog -if ((my_signal == 1'b0) && (my_bus[3:0] == 4'd5)) -``` - - -**A3**: The _always_ block *should* have a space before **@** symbol. - -#### Example: - -##### Incorrect: -```verilog -always@(posedge clk) begin - ... -end -``` -##### Correct: -```verilog -always @(posedge clk) begin - ... -end -``` - - -**A4**: The Verilog ``begin``/``end`` block **must** always be used, even if there is -only one statement. This makes adding lines of code much easier and with fewer errors. - - -**A5**: Indentation levels **must** be used to show code nesting. Blank lines -may be used as desired to improve code readability, but _not_ in all cases. - -#### Example: - -##### Incorrect: -```verilog -if (my_signal == 1'b0) begin - if (my_bus[3:0]==4'd5) begin - statement1; - statement2; - end -statement3; -statement4; -end -else -statement5; -``` - -##### Correct: -```verilog -if (my_signal == 1'b0) begin - if (my_bus[3:0] == 4'd5) begin - statement1; - statement2; - end - statement3; - statement4; -end else begin - statement5; -end -``` - - -**A6**: In a ``case`` definition, indentation levels **must** be used to offset -the statements that are encapsulated, but the use of blank lines can be used or -omitted to best show the statement groupings (if really necessary). ``end`` should -be indented as in the correct example. - -#### Example: - -##### Incorrect: -```verilog -case ( my_bus[3:0] ) - 4'b0000 : my_signal1 = TRUE; - 4'b0001 : my_signal1 = FALSE; - 4'b0010 : - begin - my_signal1 = TRUE; - my_signal2 = FALSE; - end - 4'b0100 : my_signal2 = FALSE; - default : my_signal1 = TRUE; -endcase -``` - -##### Correct: -```verilog -case (my_bus[3:0]) - 4'b0000: begin - my_signal1 = TRUE; - end - 4'b0001: begin - my_signal1 = FALSE; - end - 4'b0010: begin - my_signal1 = TRUE; - my_signal2 = FALSE; - end - 4'b0100: begin - my_signal2 = FALSE; - end - default: begin - my_signal1 = TRUE; - end -endcase -``` - - -**A7**: Alignment **should** be used in declarations, assignments, multi-line -statements, and end of line comments. The code **must** be written in a tabular -format. - -#### Example: - -##### Incorrect: -```verilog - reg[3:0] my_signal1; //description -reg[31:0] my_decoded_signal1; //description -reg[4:0] my_signal2, my_signal3; //description -wire[2:0] my_select; //description -``` - -##### Correct: -```verilog -reg [ 3:0] my_signal1; //description -reg [31:0] my_decoded_signal1; //description -reg [ 4:0] my_signal2; //description -reg my_signal3; //description - -wire [ 2:0] my_select; //description -``` - - -**A8**: Parentheses **must** be used around all boolean statements and in -complex equations, in order to force the order of operations and avoid confusion. -Complex boolean expressions *should* be expressed as multi-line aligned statements. - -#### Example: - -##### Incorrect: -```verilog -if ((my_signal1 && your_signal1) || (my_signal2 && your_signal2) || (my_signal3 && your_signal3)) begin - my_signal1 = TRUE; - my_delayed_signal1 = !your_signal; -end -``` - -##### Correct: -```verilog -if ((my_signal1 && your_signal1) || - (my_signal2 && your_signal2) || - (my_signal3 && your_signal3)) begin - my_signal1 = TRUE; - my_delayed_signal1 = !your_signal; -end -``` - - -**A9**: A line **must** not contain more than one statement. **Do not** concatenate -multiple statements on the same line. - -#### Example: - -##### Incorrect: -```verilog -upper_en = (p5type && xadr1[0]); lower_en = (p5type && !xadr1[0]); -``` - -##### Correct: -```verilog -upper_en = (p5type && xadr1[0]); -lower_en = (p5type && !xadr1[0]); -``` - - -**A10**: In module instances: - -**A10.1**: **All** parameters and ports, **must** be written on a separate line, -even if there are few of them or their names are short. -#### Example: - -##### Incorrect: -```verilog -my_module #(.PARAMETER1 (PARAMETER1)) i_my_module (.clk (clk)); -``` - -##### Correct: -```verilog -my_module #( - .PARAMETER1 (PARAMETER1) -) i_my_module ( - .clk (clk)); -``` - - -**A10.2**: When instantiating a module, the label of the module instance **must** be -on a separate line, with the closing parenthesis of the parameters list (if that's -the case) and the opening parenthesis of the ports list. The closing parenthesis of -the ports list must be right next to the last parenthesis of the last port. - -#### Example: -```verilog -my_module #( - .PARAMETER1 (PARAMETER1), - .PARAMETER2 (PARAMETER2) -) i_my_module ( - .clk (clk), - .rst (rst), - .data_in (data_in), - .en (en), - .response_out (response_out)); -``` - -**A10.3**: Commented parts of code **must** not be added to the master branch (i.e if, -case, module instances, etc). - - - -**A11**: In module declarations: - -**A11.1**: Verilog modules **must** use Verilog-2001 style parameter -declarations. This increases legibility and consistency. - -#### Example: -```verilog -module my_module #( - parameter PARAMETER1 = 0 -) ( - input clk, - input rst, - input [7:0] data_0, - input [7:0] data_1, - input enable, - input valid, - - // interface 1 - input interf1_clk, - inout interf1_some_signal, - output [15:0] interf1_data_i, - output [15:0] interf1_data_q, - - // interface 2 - input interf2_some_signal, - output interf2_data_out -); -``` - - -**A11.2**: Comments are allowed inside a module declaration **only** for separating -the interfaces by specifying the name and giving supplementary explanations. - -**A11.3**: When declaring a module, the closing parenthesis of the parameters list -**must** be on the same line with the last parameter and with the opening parenthesis -of the ports list (as shown in the correct examples). - -**A11.4**: After ``endmodule`` there **must** be only one newline, and nothing else after. - - -**A12**: Ports **must** be indicated individually; that is, one port per line -must be declared, using the direction indication and data type with each port. - -**A13**: Signals and variables **must** be declared individually; that is, -one signal/variable per line **must** be declared. - -**A14**: All ports and signals **must** be grouped by interface. Group ports -declaration by direction starting with input, inout and output ports. - -**A15**: The clock and reset ports **must** be declared first. - -**A16**: Verilog wires and registers declarations **must** be grouped in -separate sections. **Firstly** register types and then wire types. - -**A17**: The source files *should* have the format shown in Annex 1 for -Verilog code and Annex 2 for VHDL code. - - - -### B. Naming Conventions - -**B1**: All the names in the source code **must** be written in English. - -**B2**: Names **must** start with a letter, be composed of alphanumeric -characters or underscores **[A-Z, a-z, 0-9,_]**. - -**B3**: All modules, signal and register names **must** be lower case, -delimited by underscores “_”. - -#### Example: -```verilog -module my_module ( - input ena_fft, - input ena_mdi, - input fft_in, - output mdi_out, - output [15:0] my_signal1 -); -``` - - -**B4**: A file **must** contain a single module. File name **must** be the same -as the module name. For sub-modules the name **must** be composed in the following -way: - -``` -_. -``` - - -**B5**: All parameter names **must** be upper case with underscore delimiters. - - -**B6**: Signals names *should* be composed in the following way: - -``` -[interface|clock domain]_[_ns][_l][_p][_n][_m1][_m2][_s] -``` - -The suffix component may be used as described below and, in the case of multiple -suffixes being used in the same signal name, must only be used in the order -specified in the signal name descriptions above. - -**_ns** - State machine next state. - -**_l** - Latch output. Optional for signals leaving top-level module or -sub-module, required for signals internal to a module - -**_p** - Positive side of differential signal. - -**_n** - Negative side of differential signal. - - Active low signal. Can also be used for negative side of differential -signal. - -**_m1/_m2** - Used to describe registers synchronizers (e.g. up_ack_m1, up_ack_m2) - -**_s** - Used to qualify wires/signals (e.g. up_ack_s) - -This rule is useful for complex modules where it is possible to incorrectly use -a signal if its name does not contain a suffix to specify its purpose. Generally -this rule can lead to an unnecessary naming complexity and thus can be -overlooked unless it is absolutely necessary. - - -**B7**: Ports names *should* be composed in the following way: - -``` -_[_clk][_rst][_p][_n] -``` - -**_clk** - Clock signal. Exception: Signals whose names obviously indicate -clocks (e.g. system_clock or clk32m), or when specifying a clock with a certain -frequency (in this case clk *should* be used as a prefix: e.g. clk_625mhz) - -**_rst / _rstn** - Reset signal (e.g. module_rst). Exception: Signals whose -names obviously indicate resets. - -**_p** - Positive side of differential signal. - -**_n** - Active low signal. Can also be used for negative side of differential -signal. - - -**B8**: Global text macros specified by the ``‘define`` directive **must** be -preceded with the top-level module name, as in: - -``` -_ -``` - - -**B9**: Consistent usage in the spelling and naming style of nets and -variables **must** be used throughout the design. - - -**B10**: Abbreviations used in a module **must** be documented and uncommon -abbreviations *should* be avoided. - -**B11**: Reset and clock names **must** remain the same across hierarchy. - - - -### C. Comments - -**C1**: Comments **must** be used to describe the functionality of the HDL -code. Liberal use of comments is strongly encouraged. Adding obvious comments -is discouraged. Basically, extensive comments that proceed blocks of code, -coupled with sparse back references, guide the reader through the code. - -**C2**: Each functional section of the code *should* be preceded by comments -describing the code's intent and function. - -**C3**: Unusual or non-obvious implementations **must** be explained and their -limitations documented with a comment. - -**C4**: Each port declaration *should* have a descriptive comment, **only** on the -preceding line. - -**C5**: Other declarations, such as regs, wires, local parameters, *should* have a -descriptive comment. Either on the same line (discouraged), or on the preceding line. -This rule is optional for auto-generated code. - -**C6**: All synthesis-specific directives **must** be documented where used, -identifying the reason they are used, the tool and the directive used. - -**C7**: The comments inserted in the code **must** comply with the format -shown in Annex 1 for Verilog code and Annex 2 for VHDL code. - - - -### D. General - -**D1**: A file **must** contain a single module. - -**D2**: A file **must** contain either: digital-only Verilog code (files with -.v extension); analog-only Verilog code (files with .va or .vams extension); or -mixed-signal Verilog code (files with .vams extension). - -**D3**: Symbolic constants (local parameter) *should* be used for register -field values rather than fixed numerical constants. The fields may be one or -more bits or the entire register. - -**D4**: Port connection width **must** match. In module instantiations, nets -connected to ports must have the same width as the respective port declaration. - -**D5**: The ranges in both the vector port declaration and the net/variable -declaration **must** be equal. - -**D6**: Operands sizes **must** match. No expression may have its size -implicitly extended or reduced. In a ``case`` statement, all the ``case`` item -expressions and the ``case`` expression must have the same size. - -**D7**: Combinational logic **must** be specified completely (i.e., a value -must be assigned to the logic outputs for all input combinations). In a construct -derived from either a ``case`` or an ``if`` statement, the outputs may be assigned -default values before the ``case`` or ``if`` statement, and then the logic is completely -specified. - -**D8**: The sensitivity list of Verilog ``always`` and VHDL ``process`` constructs -**must** be completely specified. - -**D9**: Modules **must** be instantiated with full I/O – all port names and -signal connections must be listed on all module instantiations. Do not leave any -input ports open (even if they are unused), always tie them to 0 or 1. Leave -unused outputs open **but do** list them. - -**D10**: A ``timescale`` directive that is best for simulation *should* be used -in Verilog modules. - -**D11**: Compile warnings **must** be treated as potential errors and *should* -always try to be resolved. In case a warning is not resolved its cause and -effects must be fully understood. - -**D12**: Critical warnings **must** be treated and fixed. - -**D13**: Each file **must** contain a license header, and when changes are made -to a file, when making a PR, the year _should_ be updated to the current year. - -## 3. Annexes - -### Annex 1 Verilog file format - -```verilog -// *************************************************************************** -// *************************************************************************** -// Copyright 2014 - 2017 (c) Analog Devices, Inc. All rights reserved. -// -// In this HDL repository, there are many different and unique modules, consisting -// of various HDL (Verilog or VHDL) components. The individual modules are -// developed independently, and may be accompanied by separate and unique license -// terms. -// -// The user should read each of these license terms, and understand the -// freedoms and responsibilities that he or she has by using this source/core. -// -// This core is distributed in the hope that it will be useful, but WITHOUT ANY -// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR -// A PARTICULAR PURPOSE. -// -// Redistribution and use of source or resulting binaries, with or without modification -// of this file, are permitted under one of the following two license terms: -// -// 1. The GNU General Public License version 2 as published by the -// Free Software Foundation, which can be found in the top level directory -// of this repository (LICENSE_GPL2), and also online at: -// -// -// OR -// -// 2. An ADI specific BSD license, which can be found in the top level directory -// of this repository (LICENSE_ADIBSD), and also on-line at: -// https://github.com/analogdevicesinc/hdl/blob/master/LICENSE_ADIBSD -// This will allow to generate bit files and not release the source code, -// as long as it attaches to an ADI device. -// -// *************************************************************************** -// *************************************************************************** -'timescale 1ns/100ps - -module prescaler #( - //Range = 1-16 - parameter FIRST_PARAMETER = 8, - //Range = N/A - parameter SECOND_PARAMETER = 12 -) ( - input core_32m_clk, // 32 MHz clock - input system_clk, // system clock - input scan_mode_test, // scan mode clock - input reset_n, // active low hard reset, synch w/ - // system_clk - output reg div16_clk, // input clock divided by 16 - output reg div16_clk_n // input clock divided by 16 and inverted -); - // Local Parameters - - // Registers Declarations - - reg [3:0] count; // 4-bit counter to make clock divider - reg [3:0] count1; // 4-bit counter to make clock divider - - // Wires Declarations - - wire [3:0] count1_ns; // clock divider next state input - - // Functions Definitions - - // This block updates the internal counter - always @(posedge core_32m_clk or negedge reset_n) begin - if (!reset_n) begin - count <= 4’b0000; - end else begin - // update counter - count <= count + 4’b0001; - end - end - - // This block updates the output clock signals - always @(scan_mode_test or system_clk or count) begin - if (!scan_mode_test) begin - // normal operation clock assign - div16_clk = count[3]; - div16_clk_n = ~count[3]; - end else begin - // scan mode clock assign - div16_clk = system_clk; - div16_clk_n = system_clk; - end - end - - // Modules Instantiations - -endmodule -``` - -### Annex 2 VHDL file format - -```vhdl --- *************************************************************************** --- *************************************************************************** --- Copyright 2014 - 2017 (c) Analog Devices, Inc. All rights reserved. --- --- In this HDL repository, there are many different and unique modules, consisting --- of various HDL (Verilog or VHDL) components. The individual modules are --- developed independently, and may be accompanied by separate and unique license --- terms. --- --- The user should read each of these license terms, and understand the --- freedoms and responsibilities that he or she has by using this source/core. --- --- This core is distributed in the hope that it will be useful, but WITHOUT ANY --- WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR --- A PARTICULAR PURPOSE. --- --- Redistribution and use of source or resulting binaries, with or without modification --- of this file, are permitted under one of the following two license terms: --- --- 1. The GNU General Public License version 2 as published by the --- Free Software Foundation, which can be found in the top level directory --- of this repository (LICENSE_GPL2), and also online at: --- --- --- OR --- --- 2. An ADI specific BSD license, which can be found in the top level directory --- of this repository (LICENSE_ADIBSD), and also on-line at: --- https://github.com/analogdevicesinc/hdl/blob/master/LICENSE_ADIBSD --- This will allow to generate bit files and not release the source code, --- as long as it attaches to an ADI device. --- --- *************************************************************************** --- *************************************************************************** - -entity prescaler is - Port ( - core_32m_clk : in std_logic, -- 32 MHz clock - system_clk : in std_logic, -- system clock - scan_mode_test : in std_logic, -- scan mode clock - reset_n : in std_logic, -- active low hard reset, synch - -- w/ system_clock - div16_clk : out std_logic, -- input clock divided by 16 - div16_clk_n : out std_logic -- input clock divided by 16 - -- and inverted - ); -end prescaler; - -architecture Behavioral of prescaler is - --- Components Declarations - --- Local Types Declarations - --- Constants Declarations - --- Signals Declarations - signal count : std_logic_vector(3 downto 0); -- 4-bit counter to - -- make clock divider - signal count_ns : std_logic_vector(3 downto 0); -- clock divider next - -- state input - --- Module Implementation -begin - - -- This process updates the internal counter - process(core_32m_clk) - begin - if (rising_edge(core_32m_clk)) then - if (reset_n = '0') then - -- reset counter - count <= "0000"; - else - -- update counter - count <= count + "0001"; - end if; - end if; - end process; - - -- This process updates the output clock signals - process(scan_mode_test, system_clk, count) - begin - if (scan_mode_test = '0') then - -- normal operation clock assign - div16_clk <= count(3); - div16_clk_n <= not count(3); - else - -- scan mode clock assign - div16_clk <= system_clk; - div16_clk_n <= system_clk; - end if; - end process; - -end Behavioral; -``` - -## 4. References - -[ 1] Philippe Garrault, Brian Philofsky, “HDL Coding Practices to Accelerate -Design Performance”, Xilinx, 2006, Online document available at: -http://www.xilinx.com/support/documentation/white_papers/wp231.pdf - -[ 2] Peter Chambers, “The Ten Commandments of Excellent Design”, VLSI Technology, -1997, Online document available at: -http://www.asic-world.com/code/verilog_tutorial/peter_chambers_10_commandments.pdf - -[ 3] “Verilog Coding Techniques, v3.2”, Freescale Semiconductor, 2005, Online -document available at: -http://courses.cit.cornell.edu/ece576/Verilog/FreescaleVerilog.pdf - -[ 4] Jane Smith, “Verilog Coding Guidelines, Rev. B”, Cisco Systems, 2000, Online -document available at: http://www.engr.sjsu.edu/cpham/VERILOG/VerilogCodingStyle.pdf - -[1]: http://www.xilinx.com/support/documentation/white_papers/wp231.pdf -[2]: http://www.asic-world.com/code/verilog_tutorial/peter_chambers_10_commandments.pdf - diff --git a/docs/hdl_pr_process.md b/docs/hdl_pr_process.md deleted file mode 100644 index fbde1abc7..000000000 --- a/docs/hdl_pr_process.md +++ /dev/null @@ -1,66 +0,0 @@ -# HDL PR process - -###### Copyright 2022 - 2023 (c) Analog Devices, Inc. All rights reserved. - -This page contains the pull-request process that the Analog Devices, Inc. HDL team follows. - -Check out: -* [How to write a good commit message](https://cbea.ms/git-commit/) and [another resource](https://gist.github.com/rsp/057481db4dbd999bb7077f211f53f212) -* [Write better commits, build better projects](https://github.blog/2022-06-30-write-better-commits-build-better-projects/) -* [Good commit example (but extreme one)](https://dhwthompson.com/2019/my-favourite-git-commit) -* [How should a PR look like](https://opensource.com/article/18/6/anatomy-perfect-pull-request) and [anatomy of a PR](https://github.blog/2015-01-21-how-to-write-the-perfect-pull-request/) -* [Submitting patches](https://github.com/analogdevicesinc/linux/blob/master/Documentation/process/submitting-patches.rst) -* [HDL coding guideline](https://github.com/analogdevicesinc/hdl/blob/master/docs/hdl_coding_guideline.md) - -## For first-timers - -- Make sure you are making a PR **from the proper account** (check [First-Time Git Setup](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup) if you haven't already done so) -- You will be asked by **CLAssistant** to "_sign our [Contributor License Agreement](https://cla-assistant.io/analogdevicesinc/hdl?pullRequest=959) before we can accept your contribution._" -- If you see this message on your PR page: "**username** _seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please [add the email address used for this commit to your account](https://help.github.com/articles/why-are-my-commits-linked-to-the-wrong-user/#commits-are-not-linked-to-any-user)._" then it means you didn't check properly the first step -- If you encounter conflicts with other files (that you didn't change, and that are already on **master**), **do not resolve the conflict using Git GUI!** This way, you will insert a **merge commit** into the commit history, and merge commits cannot be squashed with normal commits. **We do not want merge commits.** So, open a terminal and resolve it there (see [this discussion](https://stackoverflow.com/a/162056)) -- Add the FPGA group as reviewers (_analogdevicesinc/fpga_ group) - -## If you're the owner of the PR -Before opening a Pull Request: -1. **Rebase branch** onto latest master -2. Make sure the **new register map** is updated, if that's the case: - * Update the corresponding **docs/regmap text files** - * Update the [Register Map Wiki page](https://wiki.analog.com/resources/fpga/docs/hdl/regmap) with the *adi_regmap.wiki* code generated - * The IPs typically should follow [Semantic Versioning 2.0.0](https://semver.org/) -3. Check if in the meantime there were any **changes to the common IPs** that you used (e.g., *up_adc_common*, *up_adc_channel*, *up_delay_cntrl*, etc.). If there are changes in the I/O ports, update your instances accordingly -4. **Regenerate the Makefiles** that concern the projects you're editing/adding, to have them up-to-date -5. Run [check_guideline.py](https://github.com/analogdevicesinc/hdl/blob/master/.github/scripts/check_guideline.py) on your branch -6. Run **Verilator** -7. **Visually inspect the code** -8. Code must build OK on **at least one project**. **Warnings** are reviewed. **Critical Warnings** are not accepted -9. Test code in hardware on **at least one setup** -10. Check **README** links - -When opening the Pull Request: -1. Give a **detailed description** for the PR (add link to related PR if it depends on others, maybe link to software PR, etc.), everything that is relevant for the reviewer -2. In the description of the Pull Request, **identify all links for Wiki** where changes need to be reviewed, so that the Wiki approval and the HDL PR merge happen at the same time -3. Add some **labels** to be easier for others to review your changes -4. Check **GitHub actions** -5. If reviewers requested changes or you found mistakes, then: - - **No force-pushing**, even if there are tiny changes or typos - - **For every change**, a new commit at least - - Check the **GitHub actions** that are failing and fix the issues - - **Add a comment** explaining what you modified additionally (it's easier for the reviewer and for tracking) - - When the PR is approved by at least 2 people, you have 3 options - - Option 1: If all these commits must be pushed, then from the dropdown, select **Rebase and merge** - - Option 2: If all these commits must be in one commit in the end, then you can use the **Squash and merge** option from the dropdown. It will prompt you to give the name of the final commit - - Option 3: **Squash the commits locally**, force-push and if you don't make any changes to the code, then GitHub will recognize this force-push as being without changes, so you don't need approves again to merge it using **Rebase and merge** - - If you do make changes (**don't!!**), comment on what you did and ask those people that previously approved the PR, to approve it again – changed files will be seen with **Changes since last view** next to the name (in the PR > Files changed tab) - -## If you're a reviewer of a PR -1. **Visually inspect the code** and **mark the viewed ones** by ticking the box next to the name. In case the owner makes some other changes to the viewed files, you will see with **Changes since last view** next to the name (in the PR > Files changed tab) -2. If the design is new, **check the schematic and the pinout** -3. Check **README** links -4. **Build at least one of the affected projects** and **check warnings** -5. Make sure the **new register map** is updated, if that's the case. The IPs typically should follow [Semantic Versioning 2.0.0](https://semver.org/) -6. Check if in the meantime there were some **changes to the common IPs** that were used in the project from this PR (e.g., *up_adc_common*, *up_adc_channel*, *up_delay_cntrl*, etc.) -7. See if Makefiles are up-to-date by **regenerating** them (the ones that concern the edited projects) -8. Run [check_guideline.py](https://github.com/analogdevicesinc/hdl/blob/master/.github/scripts/check_guideline.py) -9. Run **Verilator** -10. Review the **wiki changes** -11. Check the **GitHub actions** if they fail diff --git a/docs/user_guide/architecture.rst b/docs/user_guide/architecture.rst new file mode 100644 index 000000000..c8f97bbd7 --- /dev/null +++ b/docs/user_guide/architecture.rst @@ -0,0 +1,526 @@ +.. _architecture: + +HDL Architecture +=============================================================================== + +Every HDL design of a reference project can be divided into two +subsystems: + +- **Base design** --- description of what the **carrier** contains: + + - an embedded processor - soft or hard + - all the peripheral IPs (that are necessary to run a Linux + distribution on the system) + - these designs are specific to each carrier, making them **carrier + dependent** + - it describes part of the ``system_wrapper`` module + - located in + :git-hdl:`projects/common `; + one for each carrier + +- **Board design** --- description of what the **board** attached to + the carrier contains: + + - all the necessary IPs needed to support the board + - these designs are common to all carriers, making them **carrier + independent** + - it describes part of the ``system_wrapper`` module + - located in ``hdl/projects/$project_name/common/*bd.tcl`` + +How they're instantiated +------------------------------------------------------------------------------- + +In case of a project, inside the ``system_bd.tcl`` file, we have to source +the *base design first*, then the *board design*. + +Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Take `AD-FMCOMMS2-EBZ`_ with ZedBoard; the ``system_bd.tcl`` will look like the +following: + +.. code-block:: bash + + source $ad_hdl_dir/projects/common/zed/zed_system_bd.tcl + source ../common/fmcomms2_bd.tcl + +Typical project diagram +------------------------------------------------------------------------------- + +|HDL overall system| + +Base Design +------------------------------------------------------------------------------- + +The base design contains all the I/O peripherals, memory interfaces +and processing components, which are necessary for a fully functional +Linux system. The majority of these components are Intel and AMD Xilinx IP +cores. + +Usually, they contain: + +- Microprocessor +- Memory interface controller +- Peripheral interfaces + +Microprocessor +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In our designs, we use only two types: + +.. list-table:: + :widths: 20 20 20 20 20 + :header-rows: 2 + + * - Intel + - + - AMD Xilinx + - + - + * - **SoC** + - **FPGA** + - **SoC** + - **FPGA** + - `ACAP`_ + * - `HPS`_ + - `NIOS II`_ + - `PS7`_ + `PS8`_ + - `MicroBlaze`_ + - `Versal`_ + +.. _ACAP: https://www.xilinx.com/an/adaptive-compute-acceleration-platforms.html +.. _HPS: https://www.intel.com/content/www/us/en/docs/programmable/683458/current/hard-processor-system-hps.html +.. _NIOS II: https://www.intel.com/content/www/us/en/products/programmable/processor/nios-ii.html +.. _PS7: https://www.xilinx.com/products/intellectual-property/processing_system7.html +.. _PS8: https://www.xilinx.com/products/intellectual-property/zynq-ultra-ps-e.html +.. _MicroBlaze: https://www.xilinx.com/products/design-tools/microblaze.html +.. _Versal: https://www.xilinx.com/products/silicon-devices/acap/versal.html + +Worth mentioning in case of SoCs, the **Hard Processor System** (HPS) +or **Processing System 7/8** (PS7/8) do not contain just the dual-core +ARM® Cortex® - A9 MPCore™ processor, they also have other integrated +peripherals and memory interfaces. For more information please visit +the manufacturer's website, listed in the table above. + +- ``PS7`` --- `Zynq-7000 SoC Processing + System `__ + (``processing_system7``) +- ``PS8`` --- `Zynq UltraScale+ MPSoC Processing + System `__ + (``zynq_ultra_ps_e``) +- ``Versal`` --- `Versal ACAP + CIPS `__ + (``versal_cips``) + +Memory Interface Controller +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In almost all cases, the carrier board is not made and designed by +Analog Devices, so the external memory solution of the system is given. +Meaning we can not support, modify or alter this important part of the +system, in several cases we even have system limitations because of it +(e.g. the memory interface is not fast enough to handle the required +data throughput). + +Under the two links below the user can find the landing page of the +available memory solutions for both Intel and AMD: + +- Intel's memory interfaces: + https://www.intel.com/content/www/us/en/programmable/support/support-resources/external-memory.html +- AMD's memory interfaces: + https://www.xilinx.com/products/intellectual-property/mig.html#documentation + +Peripheral interfaces +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These interfaces are used to control external peripherals located on +the prototyping board or the FMC IO board. + +In HDL, these ports are named slightly different than how they're in +the documentations. Thus, to make it easier for beginners, here you +have the naming of the ports depending on the microprocessor used. + +CPU/Memory interconnects addresses +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The memory addresses that will be used by software are based on the HDL +addresses of the IP register map, to which an offset is added, depending +on the architecture of the used FPGA (see also :git-hdl:`ad_cpu_interconnect +procedure `; architecture is +specified by ``sys_zynq`` variable, for AMD FPGAs). + +**Zynq-7000 and 7 Series** + +Because this was the original target, this is the reference +address used, the common one, to which depending on the architecture, +you add an offset to get to the address space for the peripherals (as they +differ from one to the other). + +**Zynq UltraScale+ MP** + +If the address is between 0x4000_0000 - 0x4FFF_FFFF then the +AXI peripherics will be placed in 0x8000_0000 - 0x8FFF_FFFF range +by adding 0x4000_0000 to the address. + +If the address is between 0x7000_0000 - 0x7FFF_FFFF then the +AXI peripherics will be placed in 0x9000_0000 - 0x9FFF_FFFF range +by adding 0x2000_0000 to the address. + +**Versal** + +If the address is between 0x4400_0000 - 0x4FFF_FFFF then the +AXI peripherics will be placed in 0xA400_0000 - 0xAFFF_FFFF range +by adding 0x6000_0000 to the address. + +If the address is between 0x7000_0000 - 0x7FFF_FFFF then the +AXI peripherics will be placed in 0xB000_0000 - 0xBFFF_FFFF range +by adding 0x4000_0000 to the address. + +SPI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In general, the base system has two Serial Peripheral Interfaces, which +are used as a control interface for FMC/HSMC devices. These SPI +interfaces are controlled by the integrated SPI controller of the **Hard +Processor System** (HPS) or **Processing System 7/8** (PS7/8) or an +Intel or AMD SPI controller core. + +I2C/I2S/SPDIF +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A couple of carrier boards require these standard interfaces for +different purposes, for example, a configuration interface for an audio +peripheral device. These peripherals do not necessarily have vital roles +in the reference design, it's more like a generic goal to support all +the provided peripherals of the carrier board. + +HDMI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +There is HDMI support for all the carriers which are using the ADV7511 +as HDMI transmitter. The HDMI transmitter core can be found +`here `__. + +GPIOs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The general rule of thumb is to define 64 GPIO pins for the base design: + +- bits [31: 0] always belong to the carrier board; +- bits [63:32] will be assigned to switches, buttons and/or LEDs, which + can be found on the FMC board. +- bits [95:64] will be used when the FPGA type is Zynq UltraScale+ + MPSoC + +When some of these GPIOs are not used, the input pins should have the +output pins driven to them, so that Vivado will not complain about +inputs not being assigned to. + +Depending on the processor type, add these values to the GPIO number +from the HDL project to obtain the final number used in software: + +- PS7 EMIO offset = 54 +- PS8 EMIO offset = 78 + +Connectivity +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Ethernet +- USB OTG + +These interfaces designs are borrowed from the golden reference design +of the board. + +Interrupts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When developing the Linux software parts for an HDL project, the +interrupts number to the PS have a different number in the software +side. + +Not a rule, but in our designs we preffer to use firstly the interrupts +from 15 and to go down to 0. Be careful when assigning one, because it +might be used in the base design of the carrier! + +Always check which are used (in +``/projects/common/$carrier/$carrier_system_bd.tcl``) + +Interrupts table +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +=== ========== =========== ============ ============= ====== =============== ================ +HDL Linux Zynq Actual Zynq Linux ZynqMP Actual ZynqMP S10SoC Linux Cyclone V Actual Cyclone V +=== ========== =========== ============ ============= ====== =============== ================ +15 59 91 111 143 32 55 87 +14 58 90 110 142 31 54 86 +13 57 89 109 141 30 53 85 +12 56 88 108 140 29 52 84 +11 55 87 107 139 28 51 83 +10 54 86 106 138 27 50 82 +9 53 85 105 137 26 49 81 +8 52 84 104 136 25 48 80 +7 36 68 96 128 24 47 79 +6 35 67 95 127 23 46 78 +5 34 66 94 126 22 45 77 +4 33 65 93 125 21 44 76 +3 32 64 92 124 20 43 75 +2 31 63 91 123 19 42 74 +1 30 62 90 122 18 41 73 +0 29 61 89 121 17 40 72 +=== ========== =========== ============ ============= ====== =============== ================ + +Board design and capabilities +------------------------------------------------------------------------------- + +AMD platforms +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :widths: 16 16 18 18 16 16 + :header-rows: 1 + + * - Board name + - Boots from + - FMC connector 1 + - FMC connector 2 + - VADJ FMC connector + - Family + * - `AC701 `__ + - JTAG + - HPC (2 GTP @ 6.6 Gbps) + - --- + - 3.3V/**\*2.5V**/1.8V + - Artix-7 + * - `Cora Z7-07S `__ + - SD card + - --- + - --- + - --- + - Zynq-7000 + * - `KC705 `__ + - JTAG + - HPC (4 GTX @ 10.3125 Gbps) + - LPC (1 GTX @ 10.3125 Gbps) + - 3.3V/**\*2.5V**/1.8V + - Kintex-7 + * - `KCU105 `__ + - JTAG + - HPC (8 GTH @ 16.3 Gbps) + - LPC (1 GTH @ 16.3 Gbps) + - **\*1.8V**/1.5V/1.2V + - Kintex UltraScale + * - `Microzed `__ + - JTAG + - --- + - --- + - --- + - Zynq-7000 + * - `VC707 `__ + - JTAG + - HPC (8 GTX @ 12.5 Gbps) + - HPC (8 GTX @ 12.5 Gbps) + - **\*1.8V**/1.5V/1.2V + - Virtex-7 + * - `VC709 `__ + - JTAG + - HPC (10 GTH @ 13.1 Gbps) + - --- + - **\*1.8V** + - Virtex-7 + * - `VCK190 `__ + - SD card + - FMC+ (12 GTY @ 28.21 Gbps) + - FMC+ (12 GTY @ 28.21 Gbps) + - **\*1.5V**/1.2V + - Versal AI Core + * - `VCU118 `__ + - JTAG + - FMC+ (24 GTY @ 28.21 Gbps) + - LPC + - **\*1.8V**/1.5V/1.2V + - Virtex UltraScale+ + * - `VCU128 `__ + - JTAG + - FMC+ (24 GTY @ 28.21 Gbps) + - --- + - **\*1.8V**/1.5V/1.2V + - Virtex UltraScale+ HBM + * - `VMK180 `__ + - SD card + - FMC+ (12 GTY @ 28.21 Gbps) + - FMC+ (12 GTY @ 28.21 Gbps) + - **\*1.5V**/1.2V + - Versal Prime Series + * - `ZC702 `__ + - SD card + - LPC + - LPC + - 3.3V/**\*2.5V**/1.8V + - Zynq-7000 + * - `ZC706 `__ + - SD card + - HPC (8 GTX @ 10.3125 Gbps) + - LPC (1 GTX @ 10.3125 Gbps) + - 3.3V/**\*2.5V**/1.8V + - Zynq-7000 + * - `ZCU102 `__ + - SD card + - HPC (8 GTH @ 16.3 Gbps) + - HPC (8 GTH @ 16.3 Gbps) + - **\*1.8V**/1.5V/1.2V + - Zynq UltraScale+ MP SoC + * - `ZedBoard `__ + - SD card + - LPC + - --- + - 3.3V/2.5V/**\*1.8V** + - Zynq-7000 + +.. note:: + + The column with the VADJ value applies to the FMC connectors when they + exist. If both of them exist, then it is the same for both of them. + If there is only one FMC connector, then it applies to only one. + If both are missing, then a --- (dash) will appear. + +.. note:: + + **(\* bold**) = default VADJ + FMC1 & FMC2 columns -> depending on the power supply of the device + connected to the FMC, the custom VADJ will have the value supported by + both the carrier and the device(s) + +Intel platforms +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :widths: 20 40 40 + :header-rows: 1 + + * - Board name + - FMC connector 1 + - FMC connector 2 + * - `A10GX `__ + - LPC () + - HPC (8 x 17.4 Gbps) + * - `A10SoC `__ + - HPC (8) + - LPC (8) + * - `S10SoC `__ + - FMC+ (24 @ 28.3 Gbps) + - FMC+ (24 @ 28.3 Gbps) + +VADJ values +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. list-table:: + :widths: 20 40 40 + :header-rows: 1 + + * - Board name + - FMC connector 1 + - FMC connector 2 + * - `A10GX `__ + - **\*1.8V**/1.5V/1.35V/1.2V + - **\*1.8V**/1.5V/1.35V/1.2V + * - `A10SoC `__ + - **\*1.8V**/1.5V/1.35V/1.25V/1.2V/1.1V + - **\*1.8V**/1.5V/1.35V/1.2V/1.1V + * - `S10SoC `__ + - **\*3.3V**/1.8V/1.2V + - **\*3.3V**/1.8V/1.2V + +(**\* bold**) = default VADJ +FMC1 & FMC2 columns -> depending on the power supply of the device +connected to the FMC, the custom VADJ will have the value supported by +both the carrier and the device(s) + + +File structure of a project +------------------------------------------------------------------------------- + +.. tip:: + + In ``/projects/common/$carrier_name/`` you can find templates for the + *system_top.v*, *Makefile*, etc. to help you when creating a new project. + +Project files for AMD boards +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A project for an AMD FPGA board should contain the following files: + +- ``Makefile`` --- auto-generated file; contains all the IP + dependencies needed for the project to be built + +- ``system_project.tcl`` --- script that creates the actual Vivado + project and runs the synthesis/implementation of the design + +- ``system_bd.tcl`` --- sources the *base design first*, then the + *board design*, and afterwards it contains all the IP instances and + connections that must be added on top of the sourced files, to + complete the design of the project (these are specific to the + combination of this carrier and board) + +- ``system_constr.xdc`` --- constraints file of the design; it’s the + connection between the physical pins of the FPGA that you want to use + and the HDL code that describes the behavior; here you define the FMC + I/O pins, board-specific clock signals, timing constraints, etc. The + constraints specific to the carrier are imported in the + *system_project.tcl* file + +- ``system_top.v`` --- contains everything about the HDL part of the + project; it instantiates the ``system_wrapper`` module, IO buffers, + I/ODDRs, modules that transform signals from LVDS to single-ended, + etc. The I/O ports of this Verilog module will be connected to actual + I/O pads of the FPGA. + + - ``system_wrapper`` --- is a tool generated file and can be found at + ``.srcs/sources_1/bd/system/hdl/system_wrapper.v`` + + - the I/O ports of this module are declared in either + *system_bd.tcl* or in the **board** design file + - this can be visualized in Vivado at the Block Design section + - the base design, board design and system_bd.tcl describe this + module, making the connections between the instantiated IPs + +Project files for Intel boards +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A project for an Intel FPGA board should contain the following files: + +- ``Makefile`` --- auto-generated file; contains all the IP + dependencies needed for the project to be built + +- ``system_project.tcl`` --- script that creates the actual Quartus + project and runs the synthesis/implementation of the design. It also + contains the I/O definitions for the interfaces between the board and + the FPGA + +- ``system_qsys.tcl`` --- also called **platform designer**; sources + the *base design first*, then the *board design*, and afterwards it + contains all the IP instances and connections that must be added on + top of the sourced files, to complete the design of the project + (these are specific to the combination of this carrier and board) + +- ``system_constr.sdc`` --- contains clock definitions and other path + constraints + +- ``system_top.v`` --- contains everything about the HDL part of the + project; it instantiates the ``system_wrapper`` module, IO buffers, + I/ODDRs, modules that transform signals from LVDS to single-ended, + etc. The I/O ports of this Verilog module will be connected to actual + I/O pads of the FPGA + +Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Some carriers have a different name for these files, for example A10SoC +has constraints file for both PL side and PS side: + +- a10soc_plddr4_assign.tcl --- constraints file for the PL +- a10soc_system_assign.tcl --- constraints file for the PS + +.. _AD-FMCOMMS2-EBZ: https://www.analog.com/en/design-center/evaluation-hardware-and-software/evaluation-boards-kits/EVAL-AD-FMCOMMS2.html + +.. |HDL overall system| image:: ./sources/base_platform.svg diff --git a/docs/user_guide/build_hdl.rst b/docs/user_guide/build_hdl.rst new file mode 100644 index 000000000..17d89a830 --- /dev/null +++ b/docs/user_guide/build_hdl.rst @@ -0,0 +1,842 @@ +.. _build_hdl: + +Build an HDL project +=============================================================================== + +**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 to build any +HDL project from the repository: + +#. Install the required FPGA design suite. We use `AMD Xilinx Vivado`_ and + `Intel Quartus Prime Pro and Standard`_. + You can find information about the proper version in our + `release notes `__. + Make sure that you're always using the latest release. +#. The proper Vivado/Quartus version can be found in: + + - Starting with ``hdl_2021_r1`` release branch: + :git-hdl:`master:scripts/adi_env.tcl` + - For ``hdl_2019_r2`` and older: + :git-hdl:`hdl/projects/scripts/adi_project_xilinx.tcl ` for Vivado, and + :git-hdl:`hdl/projects/scripts/adi_project_intel.tcl ` for Quartus. + +#. Download the tools from the following links: + + - `AMD tools `__ (make sure you're + downloading the proper installer! For full installation, it is + better to choose the one that downloads and installs both Vivado + and Vitis at the same time) + - `Intel + tools `__ + +#. After you have installed the above mentioned tools, you will need the + paths to those directories in the following steps, so have them in a + note +#. We are using `git `__ for version control and + `GNU Make `__ to build the + projects. Depending on what OS you're using, you have these options: + +.. collapsible:: For Windows environment with Cygwin + + Because GNU Make is not supported on Windows, you need to install + `Cygwin `__, which is a UNIX-like environment + and command-line interface for Microsoft Windows. You do not need to + install any special package, other than **git** and **make**. + + After you have installed Cygwin, you need to add your FPGA Design Tools + installation directory to your PATH environment variable. You can do + that by modifying your **~/.bashrc** file, by adding the following lines + **changed accordingly to your installation directories**. For example: + + .. code-block:: bash + :linenos: + + export PATH=$PATH:/cygdrive/path_to/Xilinx/Vivado/202x.x/bin + export PATH=$PATH:/cygdrive/path_to/Xilinx/Vivado_HLS/202x.x/bin + export PATH=$PATH:/cygdrive/path_to/Xilinx/Vitis/202x.x/bin + export PATH=$PATH:/cygdrive/path_to/Xilinx/Vitis/202x.x/gnu/microblaze/nt/bin + export PATH=$PATH:/cygdrive/path_to/Xilinx/Vitis/202x.x/gnu/arm/nt/bin + export PATH=$PATH:/cygdrive/path_to/Xilinx/Vitis/202x.x/gnu/microblaze/linux_toolchain/nt64_be/bin + export PATH=$PATH:/cygdrive/path_to/Xilinx/Vitis/202x.x/gnu/microblaze/linux_toolchain/nt64_le/bin + export PATH=$PATH:/cygdrive/path_to/Xilinx/Vitis/202x.x/gnu/aarch32/nt/gcc-arm-none-eabi/bin + export PATH=$PATH:/cygdrive/path_to/intelFPGA_pro/2x.x/quartus/bin + + Replace the **path_to** string with your path to the installation folder + and the **tools version** with the proper one! + +.. collapsible:: How to verify your environment setup + + Run any of the following commands. These commands will return a valid path + if your setup is good. + + .. code-block:: bash + + [~] which git + [~] which make + [~] which vivado + [~] which quartus + +Setup the HDL repository +------------------------------------------------------------------------------- + +These designs are built upon ADI's generic HDL reference designs framework. +ADI does not distribute the bit/elf files of these projects so they +must be built from the sources available :git-hdl:`here `. To get +the source you must +`clone `__ +the HDL repository. +This is the best method to get the sources. Here, we are +cloning the repository inside a directory called **adi**. Please refer +to the :ref:`git_repository` section for more details. + +.. code-block:: bash + + [~] mkdir adi + [~] cd adi + [~] git clone git@github.com:analogdevicesinc/hdl.git + +.. warning:: + + Cloning the HDL repository is done now using SSH, because of + GitHub security reasons. Check out this documentation on `how to deal + with SSH keys in + GitHub `__. + Both for `Cygwin `__ and + `WSL `__ it is + necessary to create a unique SSH key. If you use WSL,to get the best + performance, you must clone your hdl repository in the WSL file system. + For example: (:code:`\\\\wsl.localhost\\Ubuntu\\home\\username\\hdl`) + +The above command clones the 'default' branch, which is the 'master' for +HDL. The 'master' branch always points to the latest stable release +branch, but it also has features **that are not fully tested**. If you +want to switch to any other branch you need to checkout that branch: + +.. code-block:: bash + + [~] cd hdl/ + [~] git status + [~] git checkout hdl_2021_r2 + +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. + +.. code-block:: bash + + [~] git fetch origin # this shows you what changes will be pulled on your local copy + [~] git rebase origin/hdl_2021_r2 # this updates your local copy + +Building the projects +------------------------------------------------------------------------------- + +.. caution:: + + Before building any project, you must have the environment prepared and the + proper tools. See `Tools`_ section on what you need to download and + `Environment`_ section on how to set-up your environment. + +Building an Intel 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. + +.. code-block:: bash + + cd projects/adrv9371x/a10soc + make + +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. + +.. note:: + + 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``\ + +Checking the 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 it is called 'adrv9371_a10soc_quartus.log' +and is inside the 'projects/adrv9371x/a10soc' directory. + +Quick (or detailed) check on files. If you are seeking support from us, +this is the most relevant information you can provide + +.. warning:: + + Do NOT copy-paste ``make`` command line text + +.. code-block:: bash + + ls -ltr projects/adrv9371x/a10soc + tail projects/adrv9371x/a10soc/adrv9371x_a10soc_quartus.log + +And finally, if the project was built is successfully, the **.sopcinfo** and +**.sof** files should be in the same folder. + +.. code-block:: bash + + ls -ltr projects/adrv9371x/a10soc/*.sopcinfo + ls -ltr projects/adrv9371x/a10soc/*.sof + +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. + +.. collapsible:: Building an Intel project in WSL - known issues + + For a10Soc and s10Soc projects it's very possible to face the following + error when you try to build the project: + + .. warning:: + + Current module quartus_fit was + unexpectedly terminated by signal 9. This may be because some system + resource has been exhausted, or quartus_fit performed an illegal + operation. + + It can also happen that "**make**" gets stuck when + synthesizing some IPs. These errors may appear because your device does + not have enough RAM memory to build your FPGA design. This problem can + be solved if you create a Linux Swap file. + + You can find more information about what a swap file is at this link: + `SwapFile `__. + + Depending on the size of the project, more or less virtual memory must + be allocated. If you type in the search bar **System Information**, you + can see Total Physical Memory and Total Virtual Memory of your system. + For example, for the AD9213 with S10SoC project, it was necessary to + allocate 15 GB of virtual memory, to be able to make a build for the + project. To create a swap file you can use the following commands: + + .. code-block:: bash + + :~$ sudo fallocate -l "memory size (e.g 1G, 2G, 8G, etc.)" /swapfile + :~$ sudo chmod 600 /swapfile + :~$ sudo mkswap /swapfile + :~$ sudo swapon /swapfile + + If you want to make the change permanent: + + .. code-block:: bash + + # in /etc/fstab file type the command: + /swapfile swap swap defaults 0 0 + + If you want to deactivate the swap memory: + + .. code-block:: bash + + :~$ sudo swapoff -v /swapfile + +.. collapsible:: Building manually in Quartus GUI + + .. warning:: + + We do not recommend using this flow, in general people are losing a lot + of valuable time and nerve during this process. + + 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. + + 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. + + .. code-block:: bash + + cd c:/github/hdl/projects/daq2/a10soc + 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. + +Building an AMD project +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An AMD 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. The way of building a project in Cygwin and WSL is the same, +with small differences. In this example, it is building the 'DAQ2' +project on the 'ZC706' carrier. + +.. code-block:: bash + + cd projects/daq2/zc706 + make + +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. + +On projects which support this, some ``make`` parameters can be added, to +configure the project (to see if your project has such things, enter in the +**system_project.tcl** file and check there). + +The result of the build, if parameters were used, will be in a folder named +by the configuration used: + +**Example 1** + +running this command + +``make RX_LANE_RATE=2.5 TX_LANE_RATE=2.5 RX_JESD_L=8 RX_JESD_M=4 RX_JESD_S=1 RX_JESD_NP=16 TX_JESD_L=8 TX_JESD_M=4 TX_JESD_S=1 TX_JESD_NP=16`` + +will create a folder named + +``RXRATE2_5_TXRATE2_5_RXL8_RXM4_RXS1_RXNP16_TXL8_TXM4_TXS1_TXNP16`` +because of truncation of some keywords so the name will not exceed the limits +of the Operating System (``JESD``, ``LANE``, etc. are removed) of 260 +characters. + +**Example 2** + +running this command + +``make LVDS_CMOS_N=1`` + +will create a folder named + +``LVDSCMOSN1`` + +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. + +.. code-block:: bash + + export ADI_USE_OOC_SYNTHESIS=y + export ADI_MAX_OOC_JOBS=8 + cd projects/daq2/zc706 + make + +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 not cleared as with normal compile flow. + +.. caution:: + + Starting with Vivado 2020.2, Out-of-Context is the + default mode. There is no need to set ADI_USE_OOC_SYNTHESIS variable. + + Set: + + .. code-block:: bash + + export ADI_USE_OOC_SYNTHESIS=n + + only in case you want to use Project Mode. + +Checking the 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. + +.. code-block:: bash + + 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`` command 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. + +.. code-block:: bash + + ls -ltr library/axi_ad9144 + tail library/axi_ad9144/axi_ad9144_ip.log + +Checking the 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. + +.. code-block:: bash + + 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. + +.. warning:: + + Do NOT copy-paste ``make`` command line text + +.. code-block:: bash + + ls -ltr projects/daq2/zc706 + tail projects/daq2/zc706/daq2_zc706_vivado.log + +And finally, if the project build is successful, the .xsa file should be +in the '.sdk' folder. + +.. code-block:: bash + + ls -ltr projects/daq2/zc706/daq2_zc706.sdk + +You may now use this '.xsa' file as the input to your no-OS and/or Linux +build. + +Starting with Vivado 2019.3, the output file extension was changed from +.hdf to .xsa. + +.. collapsible:: Building an AMD project in WSL - known issues + + For some projects it is very possible to face the following error when you make a + build: + + .. warning:: + + $RDI_PROG" "$@" crash" "Killed "$RDI_PROG" "$@" + + This error may appear because your device does not have enough + RAM memory to build your FPGA design. + + For example, the project AD-FMCDAQ3-EBZ with Virtex UltraScale+ VCU118 + (XCVU9P device) requires 20GB (typical memory) and a peak of 32GB RAM + memory. The following link shows the typical and peak Vivado memory usage + per target device: `MemoryUsage + `__. + + This problem can be solved if a linux Swap file is created. You can + find more information about what a swap file is at this link: + `SwapFile `__ + + To create a swap file you can use the following commands: + + .. code-block:: bash + + :~$ sudo fallocate -l "memory size (e.g 1G, 2G, 8G, etc.)" /swapfile + :~$ sudo chmod 600 /swapfile + :~$ sudo mkswap /swapfile + :~$ sudo swapon /swapfile + + If you want to make the change permanent: + + .. code-block:: bash + + # in /etc/fstab file type the command: + /swapfile swap swap defaults 0 0 + + If you want to deactivate the swap memory: + + .. code-block:: bash + + :~$ sudo swapoff -v /swapfile + +.. collapsible:: Building manually in Vivado GUI + + .. warning:: + + We do not recommend using this flow, in general people are losing a lot + of valuable time and nerve during this process. + + In Vivado (AMD 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. + + .. code-block:: + + cd c:/github/hdl/library/axi_ltc2387 + source ./axi_ltc2387_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. + + 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: + + .. code-block:: bash + + cd c:/github/hdl/projects/cn0577/zed + 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 (IP Integrator), generate all the + IP targets, synthesize the netlist and implementation. + +Supported targets of ``make`` command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + `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/daq2/a10soc' or 'hdl/projects/daq2/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/daq2', it builds all the carriers ('kc705', 'a10soc', +'kcu105', 'zc706' 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 (AMD only). | ++------------------+--------------------------------------------------+ +| | make -C library all; ## build **ALL** library | +| | components inside 'library' (AMD only). | ++------------------+--------------------------------------------------+ +| | make -C projects/daq2/zc706 all; ## build | +| | DAQ2_ZC706 (AMD) project. | ++------------------+--------------------------------------------------+ +| | make -C projects/daq2/a10soc all; ## build | +| | DAQ2_A10SOC(Intel) project. | ++------------------+--------------------------------------------------+ +| | make -C projects/daq2 all; ## build DAQ2 **ALL** | +| | carrier (including Intel & AMD) 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 all tool and temporary files in the | +| | current folder, its sub-folders and from all the | +| | IPs that are specified in the Makefile file; | +| | 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 daq2.a10soc ; ## build | +| | projects/daq2/a10soc. | ++------------------+--------------------------------------------------+ +| | make daq2.zc706 ; ## build projects/daq2/zc706. | ++------------------+--------------------------------------------------+ + +Tools and their versions +------------------------------------------------------------------------------- + +Tools +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ADI provides reference designs for both Intel and AMD. Please note +that we have no preference over Intel or AMD; 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.** + +.. list-table:: Tools + :widths: auto + :header-rows: 1 + + * - Notes + - Intel + - AMD + * - Main tools + - Quartus + - Vivado + * - EDK tools + - QSys + - IP Integrator + * - SDK tools + - Eclipse-Nios, Eclipse-DS5 + - Eclipse + * - Building library + - :green:`Do nothing. Quartus only needs the _hw.tcl and QSys parses them + whenever invoked` + - :red:`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 + - 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. + - 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. + * - SDK (Microblaze/Nios) + - Use SOPCINFO and SOF files + - Use XSA file + * - SDK (ARM/FPGA combo) + - :red:`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` + - :green:`Same procedure as Microblaze` + * - Upgrading/Version changes (non-ADI cores) + - :green:`Quartus automatically updates the cores. Almost hassle-free for + most of the cores` + - :red:`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 AMD and Intel IPs may or may not +work across versions. We can only assure you that they are tested and +**work only for the versions we specify**. + +The projects are usually upgraded to the latest tools after they are +publicly released. The used tool versions can be found in the +`release notes `__ +for each branch. The script, which builds the project always double +checks the used tools version, and notifies the user if he or she is trying +to use an unsupported version of tools. + +.. note:: + + 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. + +Environment +------------------------------------------------------------------------------- + +As said above, our recommended build flow is to use **make** and the +command line version of the tools. This method 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 it with the +package name. + +You may have to install ``git`` (sudo apt-get install git) +and the Intel and AMD 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. + +.. code-block:: bash + + 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. + +.. code-block:: bash + + 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 + +A very good alternative to Cygwin is +`WSL `__. The +manual changes to your ``.bashrc`` should look like: + +.. code-block:: bash + + export PATH=$PATH:/opt/path_to/Vivado/202x.x/bin:/opt/Vitis/202x.x/bin + export PATH=$PATH:/opt/path_to/quartus/bin + +If you do not want to install Cygwin, there might still be some +alternative. 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" does support make. +If you are an AMD user, use the 'gnuwin' installed as part of the SDK, +usually at ``C:\Xilinx\Vitis\202x.x\gnuwin\bin``. + +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. + +#. fsbl.elf +#. zynq.bif +#. u-boot.elf +#. and if you're using ZCU102, then bl31.elf and pmu.elf + +Next, what your project needs, is the ``uImage`` (for Zynq based +carriers) or ``Image`` (for Zynq UltraScale - ZCU102 and ADRV9009-ZU11EG +carriers) or ``zImage`` (for Intel based carriers) file that you will find +in the ``zynq-common`` or ``zynqmp-common``, ``socfpga_arria10_common`` or +``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 file you will find in the +`References`_ section or in the ReadMe.txt file from ``boot`` partition. + +.. collapsible:: How to build the boot image BOOT.BIN in WSL + + After obtaining .xsa file, you must be sure that you have done source for + Vivado and Vitis. To create boot.bin is recommended to run + build_boot_bin.sh in terminal.To do this, the file can be called in the + following manner: + + .. code-block:: bash + + chmod +x build_boot_bin.sh + usage: build_boot_bin.sh system_top.xsa u-boot.elf [output-archive] + + You can download the script by accessing the following link: + `build_boot_bin.sh `__. + +References +------------------------------------------------------------------------------- + +- `How to build the Zynq boot image + BOOT.BIN `__ +- `How to build the ZynqMP boot image + BOOT.BIN `__ +- `Building the ADI Linux + kernel `__ + +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 (AMD 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 their explanations. + +AMD: Vivado +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: + + 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 analog.com:user:axi_clkgen:1.0 axi_hdmi_clkgen" invoked from within + "set axi_hdmi_clkgen [create_bd_cell -type ip -vlnv analog.com:user:axi_clkgen:1.0 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. + +.. code-block:: + + 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. + +.. _AMD Xilinx Vivado: https://www.xilinx.com/support/download.html + +.. _Intel Quartus Prime Pro and Standard: https://www.intel.com/content/www/us/en/products/details/fpga/development-tools/quartus-prime/resource.html diff --git a/docs/user_guide/customize_hdl.rst b/docs/user_guide/customize_hdl.rst new file mode 100644 index 000000000..ba6a498ef --- /dev/null +++ b/docs/user_guide/customize_hdl.rst @@ -0,0 +1,17 @@ +.. _customize_hdl: + +Customize HDL projects +=============================================================================== + +Here can be found a collection of wiki pages, each providing examples how to +modify and customize the HDL reference designs. + +- `A simple BBP for RF Transceivers`_ +- `Model based design for SDR`_ +- `Integrate FIR filters into the FMCOMMS2 HDL design`_ + +.. _A simple BBP for RF Transceivers: https://wiki.analog.com/resources/fpga/docs/hdl/xcomm2ip + +.. _Model based design for SDR: https://www.analog.com/en/analog-dialogue/articles/using-model-based-design-sdr-1.html + +.. _Integrate FIR filters into the FMCOMMS2 HDL design: https://wiki.analog.com/resources/fpga/docs/hdl/fmcomms2_fir_filt diff --git a/docs/user_guide/docs_guidelines.rst b/docs/user_guide/docs_guidelines.rst index a75997810..019c6b72d 100644 --- a/docs/user_guide/docs_guidelines.rst +++ b/docs/user_guide/docs_guidelines.rst @@ -17,7 +17,7 @@ Templates are available: * :git-hdl:`docs/library/template_ip` (:ref:`rendered `). * :git-hdl:`docs/library/template_framework` (:ref:`rendered `). -* :git-hdl:`docs/projects/template` (:ref:`rendered `). +* :git-hdl:`docs/projects/template_project` (:ref:`rendered `). Remove the ``:orphan:`` in the first line, it is to hide the templates from the `TOC tree `_. @@ -119,7 +119,6 @@ Renders as string = "Hello world" print(string) - Images -------------------------------------------------------------------------------- @@ -179,7 +178,6 @@ consider requesting or creating one. Link-like roles use the :code:`:role:\`text \`` synthax, like external links, but without the undescore in the end. - Color role ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -247,6 +245,10 @@ The ez role creates links to the Analog Devices Inc. EngineerZone support websit The role syntax is :code:`:ez:\`community\``, for example, :code:`:ez:\`fpga\`` gets rendered as :ez:`fpga`. +For Linux Software Drivers, it is :code:`:ez:\`linux-software-drivers\``. + +For Microcontroller no-OS Drivers it is :code:`:ez:\`microcontroller-no-os-drivers\``. + Vendor role ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -425,3 +427,23 @@ Global options for HDL directives Use the `hide_collapsible_content` to set the default state of the collapsibles, if you set to False, they be expanded by default. + +Common sections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The **More information** and **Support** sections that are present in +the HDL project documentation, are actually separate pages inserted as links. +They're located at hdl/projects/common/more_information.rst and /support.rst, +and cannot be referenced here because they don't have an ID at the beginning +of the page, so not to have warnings when the documentation is rendered that +they're not included in any toctree. + +They are inserted like this: + +.. code-block:: + + .. include:: ../common/more_information.rst + + .. include:: ../common/support.rst + +and will be rendered as sections of the page. diff --git a/docs/user_guide/git_repository.rst b/docs/user_guide/git_repository.rst new file mode 100644 index 000000000..3d72646e8 --- /dev/null +++ b/docs/user_guide/git_repository.rst @@ -0,0 +1,189 @@ +.. _git_repository: + +HDL Git repository +=============================================================================== + +All the HDL sources can be found in the following git repository: + +:git-hdl:`/` + +We assume that the user is familiar with `git `__. +Knows how to +`clone `__ +the repository, how to check its +`status `__ or how to +`switch `__ +between branches. + +.. note:: + + A basic git knowledge is required in order to work with these source files, + if you do not have any, don't worry! + + There are a lot of great resources and tutorials about git all over the + `web `__. + + +If you want to pull down the sources as soon as possible, just do the +following few steps: + +#. Install Git from `here `__ +#. Open up Git bash, change your current directory to a place where you + want to keep the hdl source +#. Clone the repository using + `these `__ + instructions + +Folder structure +------------------------------------------------------------------------------- + +The root of the HDL repository has the following structure: + +.. code-block:: + + . + +-- .github + +-- docs + +-- library + +-- projects + +-- scripts + +-- Makefile + +-- README.md + +-- LICENSE + +The repository is divided into 5 separate sections: + +- **.github** with all our automations regarding coding checks, GitHub actions +- **docs** with our GitHubIO documentation and regmap source files +- **library** with all the Analog Devices Inc. proprietary IP cores and + hdl modules, which are required to build the projects +- **projects** with all the currently supported projects +- **scripts** with our environment scripts that set tools versions, etc. + +The file **.gitattributes** is used to properly `handle +different `__ +line endings. And the **.gitignore** specifies intentionally untracked +files that Git should ignore. The root **Makefile** can be used to build +all the project of the repository. To learn more about hdl **Makefiles** +visit the :ref:`Building & Generating programming files ` section. + +The projects are structured as follows +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: + + . + +-- docs + +-- library + +-- projects + ¦   +-- ad40xx_fmc + ¦   +-- ad4110 + ¦ . + ¦   +-- common + ¦   +-- dac_fmc_ebz + ¦   ¦   +-- common + ¦   ¦   +-- a10soc + ¦   ¦   +-- vcu118 + ¦   ¦   . + ¦   ¦   +-- zcu102 + ¦   ¦   +-- Makefile + ¦   ¦   +-- Readme.md + ¦ . + ¦   +-- scripts + ¦ . + ¦   +-- Readme.md + ¦   +-- Makefile + ¦   +-- wiki_summary.sh + +-- README.md + +Besides the project folders, there are two special folders inside the +**/hdl/projects**: + +- **common**: This folder contains all the base designs, for all + currently supported FPGA development boards. Be aware if you see your + board on this list, it does not necessarily mean that you can use it + with your FMC board. +- **scripts**: In all cases, we are interacting with the development + tools (Vivado/Quartus) using Tcl scripts. In this folder are defined + all the custom Tcl processes, which are used to create a project, + define the system and generate programming files for the FPGA. + +Inside a project folder, you can find folders with an FPGA carrier name +(e.g. ZC706) which in general contains all the carrier board specific +files, and a folder called **common** which contains the project +specific files. If you can not find your FPGA board name in a project +folder, that means your FPGA board with that particular FMC board is not +supported. + +The library are structured as follows +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: + + . + +-- library + ¦   +-- ad463x_data_capture + ¦   +-- axi_ad3552r + ¦   +-- axi_ad4858 + ¦   +-- axi_ad5766 + ¦   +-- axi_ad7606x + ¦   +-- axi_ad7616 + ¦   +-- axi_ad7768 + ¦   +-- axi_ad777x + ¦   +-- axi_ad9122 + ¦   . + ¦   +-- common + ¦   . + ¦   +-- interfaces + ¦   +-- jesd204 + ¦   +-- scripts + ¦   . + ¦   +-- Makefile + +-- projects + +-- README.md + +The library folder contains all the IP cores and common modules. An IP, +in general, contains Verilog files, which describe the hardware logic, +constraint files, to ease timing closure, and Tcl scripts, which +generate all the other files required for IP integration (\*_ip.tcl for +Vivado and \*_hw.tcl for Quartus) . + +.. note:: + + Regarding Vivado, all the IPs must be 'packed' before being used in a + design. + + To find more information about how to build the libraries, please visit + the :ref:`Building & Generating programming files + ` section. + + +Repository releases and branches +------------------------------------------------------------------------------- + +The repository may contain multiple branches and tags. The +:git-hdl:`master ` branch +is the development branch (latest sources, but not stable). If you check +out this branch, some builds may fail. If you are not into any kind of +experimentation, you should only check out one of the release branch. + +All our release branches have the following naming convention: +**hdl\_**\ [year_of_release]\ **\_r**\ [1 or 2]. (e.g. +:git-hdl:`hdl_2014_r2 `) + +ADI does two releases each year when all the projects get an update to +support the latest tools and get additional new features. \*\* The +master branch is always synchronized with the latest release.*\* If you +are in doubt, ask us on :ez:`fpga`. + +.. note:: + + You can find the release notes on the GitHub page of the + repository: + + https://github.com/analogdevicesinc/hdl/releases + + The latest version of tools used on master can be found at: + :git-hdl:`master:scripts/adi_env.tcl` (*required_vivado_version* and + *required_quartus_version* variables). For Intel Quartus Standard, the version + is specified in each project that uses it, depending on the carrier. diff --git a/docs/user_guide/hdl_coding_guideline.rst b/docs/user_guide/hdl_coding_guideline.rst new file mode 100755 index 000000000..73c0983fd --- /dev/null +++ b/docs/user_guide/hdl_coding_guideline.rst @@ -0,0 +1,868 @@ +.. _hdl_coding_guideline: + +ADI HDL coding guideline +=============================================================================== + +1. Introduction +------------------------------------------------------------------------------- + +This document contains coding and documentation guidelines which must be +followed by all HDL projects. The purpose of this document is to +establish a set of rules that specify the layout, naming conventions and +some general coding practices for the HDL modules implementation. +Specific HDL coding practices meant to obtain maximum performance from a +FPGA design are described by external documents such as +`[1] `__ +and +`[2] `__ +and are not included in this document. + +There are two types of rules: *should* and *must* rules + * *Should* rules are advisory rules. They suggest the recommended way of doing things. + * **Must** rules are mandatory requirements. + +The coding rules are intended to be applied to HDL modules written using +VHDL or Verilog. + +When an external IP is used, the naming conventions practiced by the IP +*should* be kept, even if they do not match the rules specified in this +document. + +2. Coding style +------------------------------------------------------------------------------- + +A. Layout +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**A1** + +Spaces **must** be used instead of tabs. + +This allows the code to be properly visualized by any editor. **Do not** +leave spaces at the end of a line. The following editor settings **must** +be used: *Tab Size*: 2, *Indent Size*: 2. + +**A2** + +One white space **must** be inserted around operators, such as +=, ==, &&, \|\|, &, \|, ^, etc. + +.. _example-a2: + +Incorrect: + +.. code-block:: + + if((my_signal1==1'b0)&&(my_bus[3:0]==4'd5)) + +Correct: + +.. code-block:: + + if ((my_signal == 1'b0) && (my_bus[3:0] == 4'd5)) + +**A3** + +The *always* block *should* have a space before \*\*@\*\* symbol. + +.. _example-a3: + +Incorrect: + +.. code-block:: + + always@(posedge clk) begin + ... + end + +Correct: + +.. code-block:: + + always @(posedge clk) begin + ... + end + +**A4** + +The Verilog ``begin``/``end`` block **must** always be used, +even if there is only one statement. This makes adding lines of code +much easier and with fewer errors. + +**A5** + +Indentation levels **must** be used to show code nesting. Blank +lines may be used as desired to improve code readability, but *not* in +all cases. + +.. _example-a5: + +Incorrect: + +.. code-block:: + :linenos: + + if (my_signal == 1'b0) begin + if (my_bus[3:0]==4'd5) begin + statement1; + statement2; + end + statement3; + statement4; + end + else + statement5; + +Correct: + +.. code-block:: + :linenos: + :emphasize-lines: 2-4,7 + + if (my_signal == 1'b0) begin + if (my_bus[3:0] == 4'd5) begin + statement1; + statement2; + end + statement3; + statement4; + end else begin + statement5; + end + +**A6** + +In a ``case`` definition, indentation levels **must** be used to +offset the statements that are encapsulated, but the use of blank lines +can be used or omitted to best show the statement groupings (if really +necessary). ``end`` should be indented as in the correct example. + +.. _example-a6: + +Incorrect: + +.. code-block:: + :linenos: + + case ( my_bus[3:0] ) + 4'b0000 : my_signal1 = TRUE; + 4'b0001 : my_signal1 = FALSE; + 4'b0010 : + begin + my_signal1 = TRUE; + my_signal2 = FALSE; + end + 4'b0100 : my_signal2 = FALSE; + default : my_signal1 = TRUE; + endcase + +Correct: + +.. code-block:: + :linenos: + :emphasize-lines: 2-4 + + case (my_bus[3:0]) + 4'b0000: begin + my_signal1 = TRUE; + end + 4'b0001: begin + my_signal1 = FALSE; + end + 4'b0010: begin + my_signal1 = TRUE; + my_signal2 = FALSE; + end + 4'b0100: begin + my_signal2 = FALSE; + end + default: begin + my_signal1 = TRUE; + end + endcase + +**A7** + +Alignment **should** be used in declarations, assignments, +multi-line statements, and end of line comments. The code **must** be +written in a tabular format. + +.. _example-a7: + +Incorrect: + +.. code-block:: + :linenos: + + reg[3:0] my_signal1; // description + reg[31:0] my_decoded_signal1; // description + reg[4:0] my_signal2, my_signal3; // description + wire[2:0] my_select; // description + +Correct: + +.. code-block:: + :linenos: + + reg [ 3:0] my_signal1; // description + reg [31:0] my_decoded_signal1; // description + reg [ 4:0] my_signal2; // description + reg my_signal3; // description + + wire [ 2:0] my_select; // description + +**A8** + +Parentheses **must** be used around all boolean statements and +in complex equations, in order to force the order of operations and +avoid confusion. Complex boolean expressions *should* be expressed as +multi-line aligned statements. + +.. _example-a8: + +Incorrect: + +.. code-block:: + :linenos: + + if ((my_signal1 && your_signal1) || (my_signal2 && your_signal2) || (my_signal3 && your_signal3)) begin + my_signal1 = TRUE; + my_delayed_signal1 = !your_signal; + end + +Correct: + +.. code-block:: + :linenos: + :emphasize-lines: 1-3 + + if ((my_signal1 && your_signal1) || + (my_signal2 && your_signal2) || + (my_signal3 && your_signal3)) begin + my_signal1 = TRUE; + my_delayed_signal1 = !your_signal; + end + +**A9** + +A line **must** not contain more than one statement. **Do not** +concatenate multiple statements on the same line. + +.. _example-a9: + +Incorrect: + +.. code-block:: + + upper_en = (p5type && xadr1[0]); lower_en = (p5type && !xadr1[0]); + +Correct: + +.. code-block:: + + upper_en = (p5type && xadr1[0]); + lower_en = (p5type && !xadr1[0]); + +**A10** + +In module instances: + +**A10.1** + +**All** parameters and ports, **must** be written on a +separate line, even if there are few of them or their names are short. + +.. _example-a10.1: + +Incorrect: + +.. code-block:: + + my_module #(.PARAMETER1 (PARAMETER1)) i_my_module (.clk (clk)); + +Correct: + +.. code-block:: + :linenos: + + my_module #( + .PARAMETER1 (PARAMETER1) + ) i_my_module ( + .clk (clk)); + +**A10.2** + +When instantiating a module, the label of the module instance +**must** be on a separate line, with the closing parenthesis of the +parameters list (if that's the case) and the opening parenthesis of the +ports list. The closing parenthesis of the ports list must be right next +to the last parenthesis of the last port. + +.. _example-a10.2: + +.. code-block:: + :linenos: + :emphasize-lines: 4 + + my_module #( + .PARAMETER1 (PARAMETER1), + .PARAMETER2 (PARAMETER2) + ) i_my_module ( + .clk (clk), + .rst (rst), + .data_in (data_in), + .en (en), + .response_out (response_out)); + +**A10.3** + +Commented parts of code **must** not be added to the master +branch (i.e if, case, module instances, etc). + +**A11** + +In module declarations: + +**A11.1** + +Verilog modules **must** use Verilog-2001 style parameter +declarations. This increases legibility and consistency. + +.. _example-a11.1: + +.. code-block:: + :linenos: + :emphasize-lines: 1-4,19,20 + + module my_module #( + parameter PARAMETER1 = 0 + ) ( + input clk, + input rst, + input [7:0] data_0, + input [7:0] data_1, + input enable, + input valid, + + // interface 1 + input interf1_clk, + inout interf1_some_signal, + output [15:0] interf1_data_i, + output [15:0] interf1_data_q, + + // interface 2 + input interf2_some_signal, + output interf2_data_out + ); + +**A11.2** + +Comments are allowed inside a module declaration **only** for +separating the interfaces by specifying the name and giving +supplementary explanations. + +**A11.3** + +When declaring a module, the closing parenthesis of the +parameters list **must** be on the same line with the last parameter and +with the opening parenthesis of the ports list (as shown in the correct +examples). + +**A11.4** + +After ``endmodule`` there **must** be only one newline, and +nothing else after. + +**A12** + +Ports **must** be indicated individually; that is, one port per +line must be declared, using the direction indication and data type with +each port. + +**A13** + +Signals and variables **must** be declared individually; that +is, one signal/variable per line **must** be declared. + +**A14** + +All ports and signals **must** be grouped by interface. Group +ports declaration by direction starting with input, inout and output +ports. + +**A15** + +The clock and reset ports **must** be declared first. + +**A16** + +Verilog wires and registers declarations **must** be grouped in +separate sections. **Firstly** register types and then wire types. + +**A17** + +The source files *should* have the format shown in Annex 1 for +Verilog code and Annex 2 for VHDL code. + +B. Naming Conventions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**B1** + +All the names in the source code **must** be written in English. + +**B2** + +Names **must** start with a letter, be composed of alphanumeric +characters or underscores **[A-Z, a-z, 0-9,\_]**. + +**B3** + +All modules, signal and register names **must** be lower case, +delimited by underscores \_. + +.. _example-b3: + +.. code-block:: + :linenos: + + module my_module ( + input ena_fft, + input ena_mdi, + input fft_in, + output mdi_out, + output [15:0] my_signal1 + ); + +**B4** + +A file **must** contain a single module. File name **must** be +the same as the module name. For sub-modules the name **must** be +composed in the following way: + +.. code-block:: + + _. + +**B5** + +All parameter names **must** be upper case with underscore +delimiters. + +**B6** + +Signals names *should* be composed in the following way: + +.. code-block:: + + [interface|clock domain]_[_ns][_l][_p][_n][_m1][_m2][_s] + +The suffix component may be used as described below and, in the case of +multiple suffixes being used in the same signal name, must only be used +in the order specified in the signal name descriptions above. + +``*_ns`` - State machine next state. + +``*_l`` - Latch output. Optional for signals leaving top-level module +or sub-module, required for signals internal to a module + +``*_p`` - Positive side of differential signal. + +``*_n`` - Negative side of differential signal. - Active low signal. +Can also be used for negative side of differential signal. + +``*_m1/\_m2`` - Used to describe registers synchronizers +(e.g. up_ack_m1, up_ack_m2) + +``*_s`` - Used to qualify wires/signals (e.g. up_ack_s) + +This rule is useful for complex modules where it is possible to +incorrectly use a signal if its name does not contain a suffix to +specify its purpose. Generally this rule can lead to an unnecessary +naming complexity and thus can be overlooked unless it is absolutely +necessary. + +**B7** + +Ports names *should* be composed in the following way: + +.. code-block:: + + _[_clk][_rst][_p][_n] + +``*_clk`` - Clock signal. Exception: Signals whose names obviously +indicate clocks (e.g. system_clock or clk32m), or when specifying a +clock with a certain frequency (in this case clk *should* be used as a +prefix: e.g. clk_625mhz) + +``*_rst / \_rstn`` - Reset signal (e.g. module_rst). Exception: Signals +whose names obviously indicate resets. + +``*_p`` - Positive side of differential signal. + +``*_n`` - Active low signal. Can also be used for negative side of +differential signal. + +**B8** + +Global text macros specified by the ```define`` directive +**must** be preceded with the top-level module name, as in: + +.. code-block:: + + _ + +**B9** + +Consistent usage in the spelling and naming style of nets and +variables **must** be used throughout the design. + +**B10** + +Abbreviations used in a module **must** be documented and +uncommon abbreviations *should* be avoided. + +**B11** + +Reset and clock names **must** remain the same across +hierarchy. + +C. Comments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**C1** + +Comments **must** be used to describe the functionality of the +HDL code. Liberal use of comments is strongly encouraged. Adding obvious +comments is discouraged. Basically, extensive comments that proceed +blocks of code, coupled with sparse back references, guide the reader +through the code. + +**C2** + +Each functional section of the code *should* be preceded by +comments describing the code's intent and function. + +**C3** + +Unusual or non-obvious implementations **must** be explained and +their limitations documented with a comment. + +**C4** + +Each port declaration *should* have a descriptive comment, +**only** on the preceding line. + +**C5** + +Other declarations, such as regs, wires, local parameters, +*should* have a descriptive comment. Either on the same line +(discouraged), or on the preceding line. This rule is optional for +auto-generated code. + +**C6** + +All synthesis-specific directives **must** be documented where +used, identifying the reason they are used, the tool and the directive +used. + +**C7** + +The comments inserted in the code **must** comply with the +format shown in Annex 1 for Verilog code and Annex 2 for VHDL code. + +D. General +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**D1** + +A file **must** contain a single module. + +**D2** + +A file **must** contain either: digital-only Verilog code (files +with .v extension); analog-only Verilog code (files with .va or .vams +extension); or mixed-signal Verilog code (files with .vams extension). + +**D3** + +Symbolic constants (local parameter) *should* be used for +register field values rather than fixed numerical constants. The fields +may be one or more bits or the entire register. + +**D4** + +Port connection width **must** match. In module instantiations, +nets connected to ports must have the same width as the respective port +declaration. + +**D5** + +The ranges in both the vector port declaration and the +net/variable declaration **must** be equal. + +**D6** + +Operands sizes **must** match. No expression may have its size +implicitly extended or reduced. In a ``case`` statement, all the +``case`` item expressions and the ``case`` expression must have the same +size. + +**D7** + +Combinational logic **must** be specified completely (i.e., a +value must be assigned to the logic outputs for all input combinations). +In a construct derived from either a ``case`` or an ``if`` statement, +the outputs may be assigned default values before the ``case`` or ``if`` +statement, and then the logic is completely specified. + +**D8** + +The sensitivity list of Verilog ``always`` and VHDL ``process`` +constructs **must** be completely specified. + +**D9** + +Modules **must** be instantiated with all I/O: port names +and signal connections must be listed on all module instantiations. Do +not leave any input ports open (even if they are unused), always tie +them to 0 or 1. Leave unused outputs open **but do** list them. + +**D10** + +A ```timescale`` directive that is best for simulation *should* +be used in Verilog modules. + +**D11** + +Compile warnings **must** be treated as potential errors and +*should* always try to be resolved. In case a warning is not resolved +its cause and effects must be fully understood. + +**D12** + +Critical warnings **must** be treated and fixed. + +**D13** + +Each file **must** contain a license header, and when changes +are made to a file, when making a PR, the year *should* be updated to +the current year. + +3. Annexes +------------------------------------------------------------------------------- + +Annex 1 Verilog file format +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: verilog + :linenos: + + // *************************************************************************** + // *************************************************************************** + // Copyright (C) year-year Analog Devices, Inc. All rights reserved. + // + // In this HDL repository, there are many different and unique modules, consisting + // of various HDL (Verilog or VHDL) components. The individual modules are + // developed independently, and may be accompanied by separate and unique license + // terms. + // + // The user should read each of these license terms, and understand the + // freedoms and responsabilities that he or she has by using this source/core. + // + // This core is distributed in the hope that it will be useful, but WITHOUT ANY + // WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + // A PARTICULAR PURPOSE. + // + // Redistribution and use of source or resulting binaries, with or without modification + // of this file, are permitted under one of the following two license terms: + // + // 1. The GNU General Public License version 2 as published by the + // Free Software Foundation, which can be found in the top level directory + // of this repository (LICENSE_GPL2), and also online at: + // + // + // OR + // + // 2. An ADI specific BSD license, which can be found in the top level directory + // of this repository (LICENSE_ADIBSD), and also on-line at: + // https://github.com/analogdevicesinc/hdl/blob/master/LICENSE_ADIBSD + // This will allow to generate bit files and not release the source code, + // as long as it attaches to an ADI device. + // + // *************************************************************************** + // *************************************************************************** + + `timescale 1ns/100ps + + module prescaler #( + // range = 1-16 + parameter FIRST_PARAMETER = 8, + // range = N/A + parameter SECOND_PARAMETER = 12 + ) ( + input core_32m_clk, // 32 MHz clock + input system_clk, // system clock + input scan_mode_test, // scan mode clock + input reset_n, // active low hard reset, synch w/ + // system_clk + output reg div16_clk, // input clock divided by 16 + output reg div16_clk_n // input clock divided by 16 and inverted + ); + // local parameters + + // registers declarations + + reg [3:0] count; // 4-bit counter to make clock divider + reg [3:0] count1; // 4-bit counter to make clock divider + + // wires declarations + + wire [3:0] count1_ns; // clock divider next state input + + // functions definitions + + // this block updates the internal counter + always @(posedge core_32m_clk or negedge reset_n) begin + if (!reset_n) begin + count <= 4'b0000; + end else begin + // update counter + count <= count + 4'b0001; + end + end + + // this block updates the output clock signals + always @(scan_mode_test or system_clk or count) begin + if (!scan_mode_test) begin + // normal operation clock assign + div16_clk = count[3]; + div16_clk_n = ~count[3]; + end else begin + // scan mode clock assign + div16_clk = system_clk; + div16_clk_n = system_clk; + end + end + + // Modules Instantiations + + endmodule + +Annex 2 VHDL file format +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: vhdl + :linenos: + + -- *************************************************************************** + -- *************************************************************************** + -- Copyright (C) year-year Analog Devices, Inc. All rights reserved. + -- + -- In this HDL repository, there are many different and unique modules, consisting + -- of various HDL (Verilog or VHDL) components. The individual modules are + -- developed independently, and may be accompanied by separate and unique license + -- terms. + -- + -- The user should read each of these license terms, and understand the + -- freedoms and responsabilities that he or she has by using this source/core. + -- + -- This core is distributed in the hope that it will be useful, but WITHOUT ANY + -- WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + -- A PARTICULAR PURPOSE. + -- + -- Redistribution and use of source or resulting binaries, with or without modification + -- of this file, are permitted under one of the following two license terms: + -- + -- 1. The GNU General Public License version 2 as published by the + -- Free Software Foundation, which can be found in the top level directory + -- of this repository (LICENSE_GPL2), and also online at: + -- + -- + -- OR + -- + -- 2. An ADI specific BSD license, which can be found in the top level directory + -- of this repository (LICENSE_ADIBSD), and also on-line at: + -- https://github.com/analogdevicesinc/hdl/blob/master/LICENSE_ADIBSD + -- This will allow to generate bit files and not release the source code, + -- as long as it attaches to an ADI device. + -- + -- *************************************************************************** + -- *************************************************************************** + + entity prescaler is + Port ( + core_32m_clk : in std_logic, -- 32 MHz clock + system_clk : in std_logic, -- system clock + scan_mode_test : in std_logic, -- scan mode clock + reset_n : in std_logic, -- active low hard reset, synch + -- w/ system_clock + div16_clk : out std_logic, -- input clock divided by 16 + div16_clk_n : out std_logic -- input clock divided by 16 + -- and inverted + ); + end prescaler; + + architecture Behavioral of prescaler is + + -- Components Declarations + + -- Local Types Declarations + + -- Constants Declarations + + -- Signals Declarations + signal count : std_logic_vector(3 downto 0); -- 4-bit counter to + -- make clock divider + signal count_ns : std_logic_vector(3 downto 0); -- clock divider next + -- state input + + -- Module Implementation + begin + + -- This process updates the internal counter + process(core_32m_clk) + begin + if (rising_edge(core_32m_clk)) then + if (reset_n = '0') then + -- reset counter + count <= "0000"; + else + -- update counter + count <= count + "0001"; + end if; + end if; + end process; + + -- This process updates the output clock signals + process(scan_mode_test, system_clk, count) + begin + if (scan_mode_test = '0') then + -- normal operation clock assign + div16_clk <= count(3); + div16_clk_n <= not count(3); + else + -- scan mode clock assign + div16_clk <= system_clk; + div16_clk_n <= system_clk; + end if; + end process; + + end Behavioral; + +4. References +------------------------------------------------------------------------------- + +`[1] Philippe Garrault, Brian Philofsky, "HDL Coding Practices to Accelerate +Design Performance", Xilinx, 2006 +`__ + +`[2] Peter Chambers, "The Ten Commandments of Excellent Design", VLSI +Technology, 1997 +`__ + +`[3] "Verilog Coding Techniques, v3.2", Freescale Semiconductor, 2005 +`__ + +`[4] Jane Smith, "Verilog Coding Guidelines, Rev. B", Cisco Systems 2000 +`__ diff --git a/docs/user_guide/index.rst b/docs/user_guide/index.rst index eb36ea1f6..2935f3e93 100644 --- a/docs/user_guide/index.rst +++ b/docs/user_guide/index.rst @@ -6,9 +6,40 @@ User Guide .. toctree:: :hidden: + Introduction + Git repository + Releases + Build an HDL project + HDL architecture + IP cores Porting reference designs + Customize HDL projects + HDL coding guideline Documentation guidelines + Third party forks +`Analog Devices, Inc.`_ provides FPGA reference designs for selected hardware +featuring some of our products interfacing to publicly available FPGA +evaluation boards. + +This wiki documentation explains the HDL resources of these reference designs. + +Contents +------------------------------------------------------------------------------- + +#. :ref:`introduction` +#. :ref:`git_repository`: Our HDL GitHub repository +#. :ref:`releases`: Releases and supported tool versions +#. :ref:`build_hdl`: Building and generating the programming files +#. :ref:`architecture`: HDL project architecture explained +#. :ref:`ip_cores`: List of IP cores #. :ref:`porting_project`: How to port a project to a non-supported carrier +#. :ref:`customize_hdl`: Using and modifying the HDL design +#. :ref:`hdl_coding_guideline`: The Verilog/VHDL coding guidelines that the + HDL team is following #. :ref:`docs_guidelines`: Documentation guidelines +#. :ref:`third_party`: Third party forks with derived work +#. :dokuwiki:`Reference designs using AMD Xilinx hardware ` +#. :dokuwiki:`Reference designs using Intel hardware ` +.. _Analog Devices, Inc.: https://www.analog.com/en/index.html diff --git a/docs/user_guide/introduction.rst b/docs/user_guide/introduction.rst new file mode 100644 index 000000000..5e4b3c016 --- /dev/null +++ b/docs/user_guide/introduction.rst @@ -0,0 +1,34 @@ +.. _introduction: + +Introduction +=============================================================================== + +The main purpose of this user guide is to help the user understand and use +(modify or otherwise) the HDL resources provided by `Analog Devices, Inc.`_, +and to provide advices and instructions for using these resources. +These resources are found on the GitHub, the +:git-hdl:`HDL repository `. + +After reading this guide, the user should be able to build a specific project +from the :git-hdl:`HDL repository ` and be able to modify +(if so desire) the digital data path implemented in the FPGA. +Furthermore, all ADI developed and supported IPs are presented in detail. + +At the same time, this user guide does not intend to be a guide for any third +party tool. To understand and use the HDL framework efficiently the user needs +to have a **solid understanding on how an FPGA works, to be familiar with all +the design tools and flows**. + +If somebody does not have this knowledge we highly recommend to make some +general research and go through some basic tutorials with the targeted +development platform. At the vendor's support pages you can find an abundance +of information: + +* `AMD Xilinx support`_ +* `Intel support`_ + +.. _Analog Devices, Inc.: https://www.analog.com/en/index.html + +.. _AMD Xilinx support: https://www.xilinx.com/support.html + +.. _Intel support: https://www.intel.com/content/www/us/en/programmable/support/support-resources.html diff --git a/docs/user_guide/ip_cores.rst b/docs/user_guide/ip_cores.rst new file mode 100644 index 000000000..9196681dd --- /dev/null +++ b/docs/user_guide/ip_cores.rst @@ -0,0 +1,74 @@ +.. _ip_cores: + +ADI IP cores +=============================================================================== + +Here you can find documentations of all the available ADI IP cores. + +Other useful information: + +- `Use ADI IPs`_ +- `Creating a new IP`_ + +Frameworks +------------------------------------------------------------------------------- + +- `JESD204 Interface Framework `__ +- :ref:`SPI Engine ` + +ADC/DAC +------------------------------------------------------------------------------- + +- `Generic AXI ADC `__ +- `Generic AXI DAC `__ +- `AXI_AD3552R `__ +- `AXI_AD7606X `__ +- `AXI_AD7616 `__ +- `AXI_AD7768 `__ +- `AXI_AD777x `__ +- `AXI_AD9265 `__ +- `AXI_AD9361 `__ +- `AXI_AD9467 `__ +- `AXI_AD9671 `__ +- `AXI_AD9783 `__ +- `AXI_AD9963 `__ +- `AXI_ADAQ8092 `__ + +DMA +------------------------------------------------------------------------------- + +- :ref:`High-Speed DMA Controller (AXI_DMAC) ` + +Video +------------------------------------------------------------------------------- + +- `AXI_HDMI_TX `__ +- `AXI_HDMI_RX `__ + +Utilities +------------------------------------------------------------------------------- + +- `AD_DDS `__ +- `AXI_ADC_DECIMATE `__ +- `AXI_ADC_TRIGGER `__ +- `AXI_CLKGEN `__ +- `AXI_DAC_INTERPOLATE `__ +- `AXI_FAN_CONTROL `__ +- `AXI_LASER_DRIVER `__ +- `AXI_LOGIC_ANALYZER `__ +- `AXI_PWM_GEN `__ +- `AXI_SYSID `__ +- `AXI_TDD `__ +- `UTIL_AXIS_FIFO `__ +- `UTIL_AXIS_FIFO_ASYM `__ +- `UTIL_CPACK `__ +- `UTIL_EXTRACT `__ +- `UTIL_MII_TO_RMII `__ +- `UTIL_UPACK `__ +- `UTIL_RFIFO `__ +- `UTIL_WFIFO `__ +- `UTIL_VAR_FIFO `__ + +.. _Use ADI IPs: https://wiki.analog.com/resources/fpga/docs/hdl/use_adi_ips + +.. _Creating a new IP: https://wiki.analog.com/resources/fpga/docs/hdl/creating_new_ip_guide diff --git a/docs/user_guide/porting_project.rst b/docs/user_guide/porting_project.rst index fcd48a21f..137349b8c 100644 --- a/docs/user_guide/porting_project.rst +++ b/docs/user_guide/porting_project.rst @@ -7,8 +7,9 @@ In general, a given reference design for an FMC board is deployed to just a few carriers, although several :git-hdl:`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 +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. @@ -27,26 +28,31 @@ Quick Compatibility Check .. 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. + specifications and requirements defined in the ANSI/VITA 57.1/57.4 FPGA + Mezzanine Card Standard (if not otherwise stated on board's wiki page). -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 + 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. + +There are three types of FMC connectors: LPC (Low Pin Count), HPC (High Pin +Count) and FMC+ (VITA 57.4). + +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. .. tip:: - First, always check out the already available :git-hdl:`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 + First, always check out the already available + :git-hdl:`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. The most important things to check before porting are related to the ANSI/VITA -57.1 standard (the list is not necessarily exhaustive): +57.1/57.4 standard (the list is not necessarily exhaustive): - Power and ground lines - 3P3V/3P3VAUX/12P0V/GND - VADJ - adjustable voltage level power from the carrier, each board has a @@ -58,11 +64,11 @@ The most important things to check before porting are related to the ANSI/VITA .. attention:: - To check all the requirements, please refer to the ANSI/VITA 57.1 standard. + To check all the requirements, please refer to the ANSI/VITA 57.1/57.4 + 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. - .. tip:: Make sure that you have reviewed all the documentation and design files in @@ -77,32 +83,32 @@ components of it. The user should look at it as a suggestion only. .. tip:: - In :git-hdl:`/projects/common `/ + In :git-hdl:`projects/common `/ you can find templates for the *system_top.v*, *Makefile*, etc. to help you when creating a new project. -Example with a Xilinx board +Example with an AMD Xilinx board ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In this section, we are presenting all the necessary steps to create a base -design for the Xilinx ZCU102 development board. +design for the AMD :xilinx:`ZCU102` development board. -First, you need to create a new directory in *~/projects/common* with the name +First, you need to create a new directory in ``hdl/projects/common`` with the name of the carrier. .. code:: bash - cd projects/common - mkdir zcu102 + ~/hdl$ cd projects/common + ~/hdl/projects/common$ mkdir zcu102 The **zcu102** directory must contain the following files: -- **zcu102_system_bd.tcl** - This script describes the base block design +- **zcu102_system_bd.tcl** - this script describes the base block design - **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 +- MIG configuration file (if needed) - this file can be borrowed from 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 @@ -129,13 +135,14 @@ The **sys_zynq** constant variable should be set in the following way: - 0 - 7 Series FPGA (e.g. Kintex7, Virtex7) - 1 - Zynq7000 SoC -- 2 - Zynq Ultrascale+ SoC +- 2 - Zynq UltraScale+ SoC +- 3 - Versal 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). +steps should be taken (the `A10SoC`_ carrier was used as an example). The following files should be created or copied into the directory: @@ -158,66 +165,70 @@ process: Project files ------------------------------------------------------------------------------- -Project files for Xilinx boards +Project files for AMD boards ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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: +all the projects files from an already existing project and to modify those +files to support the new carrier. -- **system_project.tcl** - This script is creating the actual Vivado project +A project for an AMD FPGA board should contain the following files: + +- **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_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 +- **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_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_constr.xdc** - constraints 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 - *.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. +- **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 + **.srcs/sources_1/bd/system/hdl/system_wrapper.v**. + Fixing the instantiation of the wrapper module in most cases eliminates + all the errors. -- **Makefile** - This is an auto-generated file, but after updating the carrier +- **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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -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: +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 to modify those +files to support the new carrier. -- **system_project.tcl** - This script is creating the actual Quartus project +A project for an Intel FPGA board should contain the following files: + +- **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. Again, 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_constr.sdc** - contains clock definitions and other path constraints -- **system_top.v** - Top wrapper file of the project. The I/O ports of this +- **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 +- **Makefile** - this is an auto-generated file, but after updating the carrier name, it should work with the new project without an issue. Tips @@ -226,8 +237,8 @@ Tips Generating the FMC I/O constraints ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The easiest way of writing the constraints for FMC I/O pins is making use of the -script :git-hdl:`projects/scripts/adi_fmc_constr_generator.tcl`. +The easiest way of writing the constraints for FMC I/O pins is making use +of the script :git-hdl:`projects/scripts/adi_fmc_constr_generator.tcl`. Required setup: @@ -244,10 +255,10 @@ Required setup: 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) . But before sourcing or -calling it, your current directory needs to be -:git-hdl:`projects`// +To use this script you can source it in any Tcl shell or simply call the +adi_fmc_constr_generator.tcl **with argument(s) **. +But before sourcing or calling it, your current directory needs to be +:git-hdl:`projects`//. For example: @@ -256,8 +267,8 @@ For example: - :code:`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 -. +If sourced **without argument(s)**, then you can simply call ``gen_fmc_constr +``. For example: @@ -270,7 +281,7 @@ For example: (:git-hdl:`projects/common `//_.txt). 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 +(AMD board) or **fmc_constr.tcl** (Intel board). If ran from an open Vivado project, the generated file will be automatically added to the project. .. _creating_fmc: @@ -302,6 +313,8 @@ To create a carrier common FMC connections file: * If the carrier has more FMC ports, the script should be called with: * One parameter indicating the FMC port: fmc_lpc/hpc, fmc0/1, fmcp0/1 - (see projects/common//\*.txt). + (see **projects/common//\*.txt**). * Two parameters indicating both FMC ports in the desired order for projects that use both FMC connectors. + +.. _A10SoC: https://www.intel.com/content/www/us/en/products/details/fpga/development-kits/arria/10-sx.html diff --git a/docs/user_guide/releases.rst b/docs/user_guide/releases.rst new file mode 100644 index 000000000..d6b348693 --- /dev/null +++ b/docs/user_guide/releases.rst @@ -0,0 +1,157 @@ +.. _releases: + +Releases +=============================================================================== + +The HDL is released as git branches bi-annually. The release branches +are created first and then tested before being made official. That is, +the existence of a branch does not mean it is a fully tested release. + +Also, the release branch is tested **only** on certain versions of the tools +and may **not** work with other versions of the tools. +The projects that are tested and supported in a release branch are listed +along with the ADI library cores that are used. + +The release branch may contain other projects that are in development; +one must assume these are **not** tested, therefore **not** supported by +this release. + +Porting a release branch to another Tool version +------------------------------------------------------------------------------- + +It is possible to port a release branch to another tool version, though +not recommended. The ADI libraries should work across different versions +of the tools, but the projects may not. The issues are most likely with +the Intel and AMD Xilinx cores. If you must still do this, note the +following: + +First, disable the version check of the scripts. + +The ADI build scripts are making sure that the releases are being run on +the validated tool version. It will promptly notify the user if he or +she trying to use an unsupported version of tools. You need to disable +this check by setting the environment variable ``ADI_IGNORE_VERSION_CHECK``. + +Second, make Intel and AMD IP cores version change. + +The Intel projects should automatically be changed by Quartus. The +Vivado projects are a bit tricky. The GUI automatically updates the +cores, but the **Tcl flow does not**. + +Thus, it may be easier to create the project file with the supported version +first, then opening it with the new version. +After which, update the Tcl scripts accordingly. + +The versions are specified in the following format. + +.. code-block:: tcl + :linenos: + + add_instance sys_cpu altera_nios2_gen2 16.0 + set sys_mb [create_bd_cell -type ip -vlnv xilinx.com:ip:microblaze:9.5 sys_mb] + +You should now be able to build the design and test things out. In most +cases, it should work without much effort. If it doesn't, do an +incremental update and debug accordingly. + +Release branches +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. list-table:: + :widths: 20 20 20 20 20 + :header-rows: 1 + + * - Releases + - Intel + - AMD Xilinx + - Release notes + - List of supported projects and IP cores + * - :git-hdl:`master` + - Quartus Pro 23.2 + - Vivado 2023.1 + - + - + * - :git-hdl:`hdl_2021_r2 ` + - Quartus Pro 21.4 + - Vivado 2021.2 + - `Release notes 2021_R2 `_ + - `Wiki list for hdl_2021_r2 `_ + * - :git-hdl:`hdl_2021_r1 ` + - Quartus Pro 21.2 + - Vivado 2021.1 + - `Release notes 2021_R1 `_ + - `Wiki list for hdl_2021_r1 `_ + * - :git-hdl:`hdl_2019_r2 ` + - Quartus Pro 19.3 + - Vivado 2019.1 + - `Release notes 2019_R2 `_ + - `Wiki list for hdl_2019_r2 `_ + * - :git-hdl:`hdl_2019_r1 ` + - Quartus Pro 18.1 + - Vivado 2018.3 + - `Release notes 2019_R1 `_ + - `Wiki list for hdl_2019_r1 `_ + * - :git-hdl:`hdl_2018_r2 ` + - Quartus Pro 18.0 + - Vivado 2018.2 + - `Release notes 2018_R2 `_ + - `Wiki list for hdl_2018_r2 `_ + * - :git-hdl:`hdl_2018_r1 ` + - Quartus Pro 17.1.1 + - Vivado 2017.4.1 + - `Release notes 2018_R1 `_ + - `Wiki list for hdl_2018_r1 `_ + * - :git-hdl:`hdl_2017_r1 ` + - Quartus Pro 16.1 + - Vivado 2016.4 + - `Release notes 2017_R1 `_ + - `Wiki list for hdl_2017_r1 `_ + * - :git-hdl:`hdl_2016_r2 ` + - Quartus Pro 16.0 + - Vivado 2016.2 + - `Release notes 2016_R2 `_ + - `Wiki list for hdl_2016_r2 `_ + * - :git-hdl:`hdl_2016_r1 ` + - Quartus Pro 15.1 + - Vivado 2015.4.2 + - `Release notes 2016_R1 `_ + - `Wiki list for hdl_2016_r1 `_ + * - :git-hdl:`hdl_2015_r2 ` + - Quartus Pro 15.0.2 + - Vivado 2015.2 + - `Release notes 2015_R2 `_ + - `Wiki list for hdl_2015_r2 `_ + * - :git-hdl:`hdl_2015_r1 ` + - Quartus Pro 14.1 + - Vivado 2014.4.1 + - `Release notes 2015_R1 `_ + - `Wiki list for hdl_2015_r1 `_ + * - :git-hdl:`hdl_2014_r2 ` + - Quartus Pro 14.0 + - Vivado 2014.2 + - `Release notes 2014_R2 `_ + - `Wiki list for hdl_2014_r2 `_ + * - :git-hdl:`hdl_2014_r1 ` + - Quartus Pro 14.0 + - Vivado 2013.4 + - `Release notes 2014_R1 `_ + - `Wiki list for hdl_2014_r1 `_ + + +About the tools we use +------------------------------------------------------------------------------- + +When Intel or AMD have a new release, we usually follow them and update our +tools in a timely manner. + +Changing the version of tool used on a branch is done by updating the +git-hdl:`adi_env.tcl ` script. + +If the tool version is not the one you want to use, keep in mind that when +making a setup, you will have to build the software files with the same +version, otherwise you might encounter problems in your setup. + +For example, you want to use an older version of Vivado on the master branch +which uses a newer one. Then you will need to manually build the software +files from the master branch, with the same version of Vitis too. Or for +Linux, to use the proper version of CROSS_COMPILE, etc. diff --git a/docs/user_guide/sources/base_platform.svg b/docs/user_guide/sources/base_platform.svg new file mode 100755 index 000000000..aebc43092 --- /dev/null +++ b/docs/user_guide/sources/base_platform.svg @@ -0,0 +1,2913 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + MEMORY INTERCONNECT + + + + + + + + + + + + + + + + + + + + + A10GX/A10SOCKCU105/ZCU102 + FMC CONNECTOR + + Shared GT*/XCVR + + + RX JESD LINK + + EyeScan + + + + RX JESD IP + + + + + + + + + + + + + + + + + + + + + TX JESD IP + + + + + + + + + + TX JESD LINK + + + + + + DAC core frame + + + + DAC INTERFACE + + + + + + + + + + IQ Correction + + + + + + + + + PRBS + PATTERN + DDS + DMA + + + + + + DAC CHANNEL + + DAC CORE + + + + + + + + + + DAC core frame + + + + ADC INTERFACE + + + + + + + + ADC CHANNEL + ADC CORE + + + + + + + + + + + + + + + + + + IQ Corr + + + + + + PNMON + + + + + + + + + DC Filter + + + + + + + + + + + + + + + + + + + + + + + + ADC PACK + + + + ADC DMA + + + DAC DMA + + + + + DAC UNPACK + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Receive path + + + + Transmit path + + + + + + + + + + + + + + + + + Ethernet + UART + DDRx + SPI + I2C + Interrupts + Microblaze / Nios II + SoC / Zynq + Timer + + + diff --git a/docs/user_guide/third_party.rst b/docs/user_guide/third_party.rst new file mode 100644 index 000000000..1f79e3d24 --- /dev/null +++ b/docs/user_guide/third_party.rst @@ -0,0 +1,31 @@ +.. _third_party: + +Third party forks +=============================================================================== + +All the IPs and projects that are part of our HDL repository are tested +by the ADI team. + +In some cases, there are third-party forks that either add new projects +with our evaluation boards on unsupported carriers, or add some +functionality that is not found in our ADI HDL repository. + +As we cannot maintain and test these repositories, they still can be +helpful, so we're listing them here. + +.. list-table:: + :widths: 20 40 40 + :header-rows: 1 + + * - Description + - Repository link + - ADI HDL PR link + * - AXI_AD6679 IP support + - https://github.com/edowson/adi-hdl + - https://github.com/analogdevicesinc/hdl/pull/566 + * - ADI-FMCOMMS2 on A10SoC + - https://github.com/johnathan-convertino-afrl/hdl + - https://github.com/analogdevicesinc/hdl/pull/966 + * - Fork from HDL of ArrowElectronics + - https://github.com/ArrowElectronics/hdl + -