zcy
/
pluto_hdl_adi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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 <Iulia.Moldovan@analog.com>
main
Iulia Moldovan 2023-07-20 16:04:46 +03:00 committed by imoldovan
parent bf031dff45
commit 3cee92683a
15 changed files with 5787 additions and 849 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

713
docs/hdl_coding_guideline.md
View File

@ -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:
```
<top_module_name>_<sub_module_description>.
```
**B5**: All parameter names **must** be upper case with underscore delimiters.
**B6**: Signals names *should* be composed in the following way:
```
[interface|clock domain]_<signal_name>[_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:
```
<interface_name>_<port_name>[_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:
```
<top_level_module_name>_<text macro name>
```
**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:
// <https://www.gnu.org/licenses/old-licenses/gpl-2.0.html>
//
// 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:
-- <https://www.gnu.org/licenses/old-licenses/gpl-2.0.html>
--
-- 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

66
docs/hdl_pr_process.md
View File

@ -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

526
docs/user_guide/architecture.rst Normal file
View File

@ -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 <master: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 <https://docs.xilinx.com/v/u/en-US/pg082-processing-system7>`__
(``processing_system7``)
- ``PS8`` --- `Zynq UltraScale+ MPSoC Processing
System <https://docs.xilinx.com/viewer/book-attachment/xFC3qkokxbD~75kj6nPLuw/2o4flzqn5OqWHaMHwpG3Qg>`__
(``zynq_ultra_ps_e``)
- ``Versal`` --- `Versal ACAP
CIPS <https://docs.xilinx.com/r/en-US/pg352-cips/Overview>`__
(``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 <master:projects/scripts/adi_board.tcl>`; 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 <https://github.com/analogdevicesinc/hdl/tree/master/library/axi_hdmi_tx>`__.
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 <https://www.xilinx.com/products/boards-and-kits/ek-a7-ac701-g.html>`__
- JTAG
- HPC (2 GTP @ 6.6 Gbps)
- ---
- 3.3V/**\*2.5V**/1.8V
- Artix-7
* - `Cora Z7-07S <https://digilent.com/reference/programmable-logic/cora-z7/start>`__
- SD card
- ---
- ---
- ---
- Zynq-7000
* - `KC705 <https://www.xilinx.com/products/boards-and-kits/ek-k7-kc705-g.html>`__
- JTAG
- HPC (4 GTX @ 10.3125 Gbps)
- LPC (1 GTX @ 10.3125 Gbps)
- 3.3V/**\*2.5V**/1.8V
- Kintex-7
* - `KCU105 <https://www.xilinx.com/products/boards-and-kits/kcu105.html>`__
- JTAG
- HPC (8 GTH @ 16.3 Gbps)
- LPC (1 GTH @ 16.3 Gbps)
- **\*1.8V**/1.5V/1.2V
- Kintex UltraScale
* - `Microzed <http://zedboard.org/product/microzed>`__
- JTAG
- ---
- ---
- ---
- Zynq-7000
* - `VC707 <https://www.xilinx.com/products/boards-and-kits/ek-v7-vc707-g.html>`__
- JTAG
- HPC (8 GTX @ 12.5 Gbps)
- HPC (8 GTX @ 12.5 Gbps)
- **\*1.8V**/1.5V/1.2V
- Virtex-7
* - `VC709 <https://www.xilinx.com/products/boards-and-kits/dk-v7-vc709-g.html>`__
- JTAG
- HPC (10 GTH @ 13.1 Gbps)
- ---
- **\*1.8V**
- Virtex-7
* - `VCK190 <https://www.xilinx.com/products/boards-and-kits/vck190.html>`__
- SD card
- FMC+ (12 GTY @ 28.21 Gbps)
- FMC+ (12 GTY @ 28.21 Gbps)
- **\*1.5V**/1.2V
- Versal AI Core
* - `VCU118 <https://www.xilinx.com/products/boards-and-kits/vcu118.html>`__
- JTAG
- FMC+ (24 GTY @ 28.21 Gbps)
- LPC
- **\*1.8V**/1.5V/1.2V
- Virtex UltraScale+
* - `VCU128 <https://www.xilinx.com/products/boards-and-kits/vcu128.html>`__
- JTAG
- FMC+ (24 GTY @ 28.21 Gbps)
- ---
- **\*1.8V**/1.5V/1.2V
- Virtex UltraScale+ HBM
* - `VMK180 <https://www.xilinx.com/products/boards-and-kits/vmk180.html>`__
- SD card
- FMC+ (12 GTY @ 28.21 Gbps)
- FMC+ (12 GTY @ 28.21 Gbps)
- **\*1.5V**/1.2V
- Versal Prime Series
* - `ZC702 <https://www.xilinx.com/products/boards-and-kits/ek-z7-zc702-g.html>`__
- SD card
- LPC
- LPC
- 3.3V/**\*2.5V**/1.8V
- Zynq-7000
* - `ZC706 <https://www.xilinx.com/products/boards-and-kits/ek-z7-zc706-g.html>`__
- SD card
- HPC (8 GTX @ 10.3125 Gbps)
- LPC (1 GTX @ 10.3125 Gbps)
- 3.3V/**\*2.5V**/1.8V
- Zynq-7000
* - `ZCU102 <https://www.xilinx.com/products/boards-and-kits/ek-u1-zcu102-es2-g.html>`__
- 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 <https://www.avnet.com/wps/portal/us/products/avnet-boards/avnet-board-families/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 <https://www.altera.com/products/boards_and_kits/dev-kits/altera/kit-a10-gx-fpga.html>`__
- LPC ()
- HPC (8 x 17.4 Gbps)
* - `A10SoC <https://www.altera.com/products/boards_and_kits/dev-kits/altera/arria-10-soc-development-kit.html>`__
- HPC (8)
- LPC (8)
* - `S10SoC <https://www.intel.com/content/www/us/en/products/details/fpga/development-kits/stratix/10-sx.html>`__
- 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 <https://www.altera.com/products/boards_and_kits/dev-kits/altera/kit-a10-gx-fpga.html>`__
- **\*1.8V**/1.5V/1.35V/1.2V
- **\*1.8V**/1.5V/1.35V/1.2V
* - `A10SoC <https://www.altera.com/products/boards_and_kits/dev-kits/altera/arria-10-soc-development-kit.html>`__
- **\*1.8V**/1.5V/1.35V/1.25V/1.2V/1.1V
- **\*1.8V**/1.5V/1.35V/1.2V/1.1V
* - `S10SoC <https://www.intel.com/content/www/us/en/products/details/fpga/development-kits/stratix/10-sx.html>`__
- **\*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
``<project_name>.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

842
docs/user_guide/build_hdl.rst Normal file
View File

@ -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 <https://github.com/analogdevicesinc/hdl/releases>`__.
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 <master:projects/scripts/adi_project_xilinx.tcl>` for Vivado, and
:git-hdl:`hdl/projects/scripts/adi_project_intel.tcl <master:projects/scripts/adi_project_intel.tcl>` for Quartus.
#. Download the tools from the following links:
- `AMD tools <https://www.xilinx.com/support/download.html>`__ (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 <https://www.intel.com/content/www/us/en/programmable/downloads/download-center.html>`__
#. 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 <https://git-scm.com/>`__ for version control and
`GNU Make <https://www.gnu.org/software/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 <https://www.cygwin.com/>`__, 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 <master:/>`. To get
the source you must
`clone <https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository>`__
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 <https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent>`__.
Both for `Cygwin <https://www.cygwin.com/>`__ and
`WSL <https://learn.microsoft.com/en-us/windows/wsl/install/>`__ 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 <https://linuxize.com/post/create-a-linux-swap-file/>`__.
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
<https://www.xilinx.com/products/design-tools/vivado/vivado-ml.html#memory>`__.
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 <https://linuxize.com/post/create-a-linux-swap-file/>`__
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 <https://www.gnu.org/software/make/manual/make.html>`__ 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 <https://github.com/analogdevicesinc/hdl/releases>`__
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 <https://github.com/analogdevicesinc/hdl/releases>`__. 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 <https://github.com/analogdevicesinc/hdl/blob/master/projects/scripts/adi_project_xilinx.tcl#L4>`__)
or
(`./hdl/projects/scripts/adi_project_intel.tcl <https://github.com/analogdevicesinc/hdl/blob/master/projects/scripts/adi_project_intel.tcl#L5>`__),
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 <https://www.cygwin.com>`__. 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 <https://learn.microsoft.com/en-us/windows/wsl/install/>`__. 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 <https://wiki.analog.com/resources/tools-software/linux-software/zynq_images/windows_hosts>`__
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 <https://wiki.analog.com/resources/tools-software/linux-software/build-the-zynq-boot-image>`__.
References
-------------------------------------------------------------------------------
- `How to build the Zynq boot image
BOOT.BIN <https://wiki.analog.com/resources/tools-software/linux-software/build-the-zynq-boot-image>`__
- `How to build the ZynqMP boot image
BOOT.BIN <https://wiki.analog.com/resources/tools-software/linux-software/build-the-zynqmp-boot-image>`__
- `Building the ADI Linux
kernel <https://wiki.analog.com/resources/tools-software/linux-drivers-all>`__
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 <analog.com:user:axi_clkgen:1.0> 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

17
docs/user_guide/customize_hdl.rst Normal file
View File

@ -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

28
docs/user_guide/docs_guidelines.rst
View File

@ -17,7 +17,7 @@ Templates are available:
* :git-hdl:`docs/library/template_ip` (:ref:`rendered <template_ip>`). * :git-hdl:`docs/library/template_ip` (:ref:`rendered <template_ip>`).
* :git-hdl:`docs/library/template_framework` (:ref:`rendered <template_framework>`). * :git-hdl:`docs/library/template_framework` (:ref:`rendered <template_framework>`).
* :git-hdl:`docs/projects/template` (:ref:`rendered <template_project>`). * :git-hdl:`docs/projects/template_project` (:ref:`rendered <template_project>`).
Remove the ``:orphan:`` in the first line, it is to hide the templates from the Remove the ``:orphan:`` in the first line, it is to hide the templates from the
`TOC tree <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree>`_. `TOC tree <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree>`_.
@ -119,7 +119,6 @@ Renders as
string = "Hello world" string = "Hello world"
print(string) print(string)
Images Images
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
@ -179,7 +178,6 @@ consider requesting or creating one.
Link-like roles use the :code:`:role:\`text <link>\`` synthax, like external Link-like roles use the :code:`:role:\`text <link>\`` synthax, like external
links, but without the undescore in the end. links, but without the undescore in the end.
Color role 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\`` The role syntax is :code:`:ez:\`community\``, for example, :code:`:ez:\`fpga\``
gets rendered as :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 Vendor role
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -425,3 +427,23 @@ Global options for HDL directives
Use the `hide_collapsible_content` to set the default state of the collapsibles, Use the `hide_collapsible_content` to set the default state of the collapsibles,
if you set to False, they be expanded by default. 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.

189
docs/user_guide/git_repository.rst Normal file
View File

@ -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 <https://git-scm.com/>`__.
Knows how to
`clone <https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository>`__
the repository, how to check its
`status <https://git-scm.com/docs/git-status>`__ or how to
`switch <https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging>`__
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 <http://lmgtfy.com/?q=git+tutorial>`__.
If you want to pull down the sources as soon as possible, just do the
following few steps:
#. Install Git from `here <https://git-scm.com/>`__
#. Open up Git bash, change your current directory to a place where you
want to keep the hdl source
#. Clone the repository using
`these <https://help.github.com/articles/cloning-a-repository/>`__
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 <https://help.github.com/articles/dealing-with-line-endings/>`__
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 <build_hdl>` 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
<build_hdl>` section.
Repository releases and branches
-------------------------------------------------------------------------------
The repository may contain multiple branches and tags. The
:git-hdl:`master <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 <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.

868
docs/user_guide/hdl_coding_guideline.rst Executable file
View File

@ -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] <http://www.xilinx.com/support/documentation/white_papers/wp231.pdf>`__
and
`[2] <http://www.asic-world.com/code/verilog_tutorial/peter_chambers_10_commandments.pdf>`__
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::
<top_module_name>_<sub_module_description>.
**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]_<signal_name>[_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::
<interface_name>_<port_name>[_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::
<top_level_module_name>_<text macro name>
**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:
// <https://www.gnu.org/licenses/old-licenses/gpl-2.0.html>
//
// 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:
-- <https://www.gnu.org/licenses/old-licenses/gpl-2.0.html>
--
-- 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
<http://www.xilinx.com/support/documentation/white_papers/wp231.pdf>`__
`[2] Peter Chambers, "The Ten Commandments of Excellent Design", VLSI
Technology, 1997
<http://www.asic-world.com/code/verilog_tutorial/peter_chambers_10_commandments.pdf>`__
`[3] "Verilog Coding Techniques, v3.2", Freescale Semiconductor, 2005
<http://courses.cit.cornell.edu/ece576/Verilog/FreescaleVerilog.pdf>`__
`[4] Jane Smith, "Verilog Coding Guidelines, Rev. B", Cisco Systems 2000
<http://www.engr.sjsu.edu/cpham/VERILOG/VerilogCodingStyle.pdf>`__

31
docs/user_guide/index.rst
View File

@ -6,9 +6,40 @@ User Guide
.. toctree:: .. toctree::
:hidden: :hidden:
Introduction <introduction>
Git repository <git_repository>
Releases <releases>
Build an HDL project <build_hdl>
HDL architecture <architecture>
IP cores <ip_cores>
Porting reference designs <porting_project> Porting reference designs <porting_project>
Customize HDL projects <customize_hdl>
HDL coding guideline <hdl_coding_guideline>
Documentation guidelines <docs_guidelines> Documentation guidelines <docs_guidelines>
Third party forks <third_party>
`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:`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:`docs_guidelines`: Documentation guidelines
#. :ref:`third_party`: Third party forks with derived work
#. :dokuwiki:`Reference designs using AMD Xilinx hardware <resources/alliances/xilinx>`
#. :dokuwiki:`Reference designs using Intel hardware <resources/alliances/altera>`
.. _Analog Devices, Inc.: https://www.analog.com/en/index.html

34
docs/user_guide/introduction.rst Normal file
View File

@ -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 <master:/>`.
After reading this guide, the user should be able to build a specific project
from the :git-hdl:`HDL repository <master:/>` 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

74
docs/user_guide/ip_cores.rst Normal file
View File

@ -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 </resources/fpga/peripherals/jesd204>`__
- :ref:`SPI Engine <spi_engine>`
ADC/DAC
-------------------------------------------------------------------------------
- `Generic AXI ADC <axi_adc_ip>`__
- `Generic AXI DAC <axi_dac_ip>`__
- `AXI_AD3552R <axi_ad3552r>`__
- `AXI_AD7606X <axi_ad7606x>`__
- `AXI_AD7616 <axi_ad7616>`__
- `AXI_AD7768 <ad7768>`__
- `AXI_AD777x <ad777x>`__
- `AXI_AD9265 <axi_ad9265>`__
- `AXI_AD9361 <axi_ad9361>`__
- `AXI_AD9467 <axi_ad9467>`__
- `AXI_AD9671 <axi_ad9671>`__
- `AXI_AD9783 <axi_ad9783>`__
- `AXI_AD9963 <axi_ad9963>`__
- `AXI_ADAQ8092 <adaq8092>`__
DMA
-------------------------------------------------------------------------------
- :ref:`High-Speed DMA Controller (AXI_DMAC) <axi_dmac>`
Video
-------------------------------------------------------------------------------
- `AXI_HDMI_TX <axi_hdmi_tx>`__
- `AXI_HDMI_RX <axi_hdmi_rx>`__
Utilities
-------------------------------------------------------------------------------
- `AD_DDS <dds>`__
- `AXI_ADC_DECIMATE <axi_adc_decimate>`__
- `AXI_ADC_TRIGGER <axi_adc_trigger>`__
- `AXI_CLKGEN <axi_clkgen>`__
- `AXI_DAC_INTERPOLATE <axi_dac_interpolate>`__
- `AXI_FAN_CONTROL <axi_fan_control>`__
- `AXI_LASER_DRIVER <axi_laser_driver>`__
- `AXI_LOGIC_ANALYZER <axi_logic_analyzer>`__
- `AXI_PWM_GEN <axi_pwm_gen>`__
- `AXI_SYSID <axi_sysid>`__
- `AXI_TDD <axi_tdd>`__
- `UTIL_AXIS_FIFO <util_axis_fifo>`__
- `UTIL_AXIS_FIFO_ASYM <util_axis_fifo_asym>`__
- `UTIL_CPACK <util_cpack>`__
- `UTIL_EXTRACT <util_extract>`__
- `UTIL_MII_TO_RMII <util_mii_to_rmii>`__
- `UTIL_UPACK <util_upack>`__
- `UTIL_RFIFO <util_rfifo>`__
- `UTIL_WFIFO <util_wfifo>`__
- `UTIL_VAR_FIFO <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

147
docs/user_guide/porting_project.rst
View File

@ -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 <projects/common>` carriers, although several :git-hdl:`FPGA boards <projects/common>`
are supported in ADI's HDL repository. The simple reason behind this practice is 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 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 of human resources, and would increase the required time for testing.
general rule of thumb is to support a given project with a fairly popular
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 carrier (e.g. ZC706 or A10SoC), which is powerful enough to showcase the board
features and maximum performance. features and maximum performance.
@ -27,26 +28,31 @@ Quick Compatibility Check
.. note:: .. note::
All ADI's FPGA Mezzanine Cards (FMC) are designed to respect all the 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 specifications and requirements defined in the ANSI/VITA 57.1/57.4 FPGA
Card Standard (if not otherwise stated on board's wiki page). If the new FPGA Mezzanine Card Standard (if not otherwise stated on board's wiki page).
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 two types of FMC connectors: LPC (Low Pin Count) and HPC (High Pin If the new FPGA carrier is fully compliant with this standard, there
Count). In general, an FMC board is using the FMC connector type that has enough 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 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 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. a carrier with an FMC LPC can host a board just with an FMC LPC connector.
.. tip:: .. tip::
First, always check out the already available :git-hdl:`base designs <projects/common>`. First, always check out the already available
If your board is present among our supported base designs, you do not need to :git-hdl:`base designs <projects/common>`.
verify the following things and you can jump to the Project creation 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. section.
The most important things to check before porting are related to the ANSI/VITA 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 - Power and ground lines - 3P3V/3P3VAUX/12P0V/GND
- VADJ - adjustable voltage level power from the carrier, each board has a - 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:: .. 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 The above few hints do not cover all the FMC standards and you
may miss something that can prevent the porting of the project. may miss something that can prevent the porting of the project.
.. tip:: .. tip::
Make sure that you have reviewed all the documentation and design files in 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:: .. tip::
In :git-hdl:`/projects/common </projects/common>`/<carrier_name> In :git-hdl:`projects/common <master:projects/common>`/<carrier_name>
you can find templates for the *system_top.v*, *Makefile*, etc. to help you you can find templates for the *system_top.v*, *Makefile*, etc. to help you
when creating a new project. 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 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. of the carrier.
.. code:: bash .. code:: bash
cd projects/common ~/hdl$ cd projects/common
mkdir zcu102 ~/hdl/projects/common$ mkdir zcu102
The **zcu102** directory must contain the following files: 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 - **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 will contain I/O definitions for GPIO, switches, LEDs or other peripherals of
the board the board
- MIG configuration file (if needed) - This file can be borrowed for the golden - MIG configuration file (if needed) - this file can be borrowed from the
reference design of the board golden reference design of the board
- Other constraints files if needed - Other constraints files if needed
You should define the board and its device in the project flow script 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) - 0 - 7 Series FPGA (e.g. Kintex7, Virtex7)
- 1 - Zynq7000 SoC - 1 - Zynq7000 SoC
- 2 - Zynq Ultrascale+ SoC - 2 - Zynq UltraScale+ SoC
- 3 - Versal
Example with an Intel board Example with an Intel board
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To create a new base design for a given Intel FPGA carrier board, the following 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: The following files should be created or copied into the directory:
@ -158,66 +165,70 @@ process:
Project files 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 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 all the projects files from an already existing project and to modify those
files to support the new carrier. A project for a Xilinx FPGA board should files to support the new carrier.
contain the following files:
- **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 and runs the synthesis/implementation of the design. The name of the carrier
from inside the file, must be updated. from inside the file, must be updated.
- **system_bd.tcl** - In this file is sourced the *base* design's Tcl script - **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 and the **board** design's Tcl script. Again, the name of the carrier must be
updated. updated.
- **system_constr.xdc** - Constraint file of the board design. Here are defined - **system_constr.xdc** - constraints file of the **board** design.
the FMC I/O pins and board specific clock signals. All the I/O definitions Here are defined the FMC I/O pins and board specific clock signals.
must be updated, with the new pin names. 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 - **system_top.v** - top wrapper file, in which the **system_wrapper.v**
instantiated, and a few I/O macros are defined. The I/O port of this Verilog module is instantiated, and a few I/O macros are defined.
module will be connected to actual I/O pads of the FPGA. The simplest way to The I/O port of this Verilog module will be connected to actual I/O pads
update the *system_top* is to let the synthesis fail and the tool will tell of the FPGA. The simplest way to update the **system_top** is to let
you which ports are missing or which ports are redundant. The first thing to the synthesis fail and the tool will tell you which ports are missing
do after the failure is to verify the instantiation of the system_wrapper.v. or which ports are redundant.
This file is a tool generated file and can be found at The first thing to do after the failure, is to verify the instantiation
*<project_name>.srcs/sources_1/bd/system/hdl/system_wrapper.v*. Fixing the of the **system_wrapper.v**.
instantiation of the wrapper module in most cases eliminates all the errors. This file is a tool-generated file and can be found at
If you get errors that you cannot fix, ask for support. **<project_name>.srcs/sources_1/bd/system/hdl/system_wrapper.v**.
Fixing the instantiation of the wrapper module in most cases eliminates
all the errors.
- **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. name, should work with the new project without an issue.
Project files for Intel boards Project files for Intel boards
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To follow the project framework as much as possible the easiest way is to copy 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 all the projects file from an already existing project and to modify those
to support the new carrier. A project for an Intel FPGA board should contain the files to support the new carrier.
following files:
- **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 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 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. 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 - **system_qsys.tcl** - in this file is sourced the **base** design's Tcl
and the *board* design's Tcl script. Again, the name of the carrier must be script and the **board** design's Tcl script. Again, the name of the carrier
updated. 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 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 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 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. 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. name, it should work with the new project without an issue.
Tips Tips
@ -226,8 +237,8 @@ Tips
Generating the FMC I/O constraints Generating the FMC I/O constraints
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The easiest way of writing the constraints for FMC I/O pins is making use of the The easiest way of writing the constraints for FMC I/O pins is making use
script :git-hdl:`projects/scripts/adi_fmc_constr_generator.tcl`. of the script :git-hdl:`projects/scripts/adi_fmc_constr_generator.tcl`.
Required setup: Required setup:
@ -244,10 +255,10 @@ Required setup:
Calling the script: Calling the script:
To use this script you can source it in any tcl shell or simply call the To use this script you can source it in any Tcl shell or simply call the
adi_fmc_constr_generator.tcl with argument(s) <fmc_port>. But before sourcing or adi_fmc_constr_generator.tcl **with argument(s) <fmc_port>**.
calling it, your current directory needs to be But before sourcing or calling it, your current directory needs to be
:git-hdl:`projects`/<project>/<carrier> :git-hdl:`projects`/<project>/<carrier>.
For example: For example:
@ -256,8 +267,8 @@ For example:
- :code:`tclsh ../../scripts/adi_fmc_constr_generator.tcl fmc0 fmc1` - :code:`tclsh ../../scripts/adi_fmc_constr_generator.tcl fmc0 fmc1`
(the project uses two FMC ports at a time) (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
<fmc_port>. <fmc_port>``.
For example: For example:
@ -270,7 +281,7 @@ For example:
(:git-hdl:`projects/common <projects/common>`/<carrier>/<carrier>_<fmc_port>.txt). (:git-hdl:`projects/common <projects/common>`/<carrier>/<carrier>_<fmc_port>.txt).
The generated file will appear in the current directory as **fmc_constr.xdc** 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. project, the generated file will be automatically added to the project.
.. _creating_fmc: .. _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: * 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 * One parameter indicating the FMC port: fmc_lpc/hpc, fmc0/1, fmcp0/1
(see projects/common/<carrier>/\*.txt). (see **projects/common/<carrier>/\*.txt**).
* Two parameters indicating both FMC ports in the desired order for projects * Two parameters indicating both FMC ports in the desired order for projects
that use both FMC connectors. that use both FMC connectors.
.. _A10SoC: https://www.intel.com/content/www/us/en/products/details/fpga/development-kits/arria/10-sx.html

157
docs/user_guide/releases.rst Normal file
View File

@ -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 <hdl_2021_r2:>`
- Quartus Pro 21.4
- Vivado 2021.2
- `Release notes 2021_R2 <https://github.com/analogdevicesinc/hdl/releases/tag/2021_R2>`_
- `Wiki list for hdl_2021_r2 <https://wiki.analog.com/resources/fpga/docs/hdl/downloads_2021_r2>`_
* - :git-hdl:`hdl_2021_r1 <hdl_2021_r1:>`
- Quartus Pro 21.2
- Vivado 2021.1
- `Release notes 2021_R1 <https://github.com/analogdevicesinc/hdl/releases/tag/2021_R1>`_
- `Wiki list for hdl_2021_r1 <https://wiki.analog.com/resources/fpga/docs/hdl/downloads_2021_r1>`_
* - :git-hdl:`hdl_2019_r2 <hdl_2019_r2:>`
- Quartus Pro 19.3
- Vivado 2019.1
- `Release notes 2019_R2 <https://github.com/analogdevicesinc/hdl/releases/tag/2019_R2>`_
- `Wiki list for hdl_2019_r2 <https://wiki.analog.com/resources/fpga/docs/hdl/downloads_2019_r2>`_
* - :git-hdl:`hdl_2019_r1 <hdl_2019_r1:>`
- Quartus Pro 18.1
- Vivado 2018.3
- `Release notes 2019_R1 <https://github.com/analogdevicesinc/hdl/releases/tag/2019_R1>`_
- `Wiki list for hdl_2019_r1 <https://wiki.analog.com/resources/fpga/docs/hdl/downloads_2019_r1>`_
* - :git-hdl:`hdl_2018_r2 <hdl_2018_r2:>`
- Quartus Pro 18.0
- Vivado 2018.2
- `Release notes 2018_R2 <https://github.com/analogdevicesinc/hdl/releases/tag/2018_R2>`_
- `Wiki list for hdl_2018_r2 <https://wiki.analog.com/resources/fpga/docs/hdl/downloads_2018_r2>`_
* - :git-hdl:`hdl_2018_r1 <hdl_2018_r1:>`
- Quartus Pro 17.1.1
- Vivado 2017.4.1
- `Release notes 2018_R1 <https://github.com/analogdevicesinc/hdl/releases/tag/2018_R1>`_
- `Wiki list for hdl_2018_r1 <https://wiki.analog.com/resources/fpga/docs/hdl/downloads_2018_r1>`_
* - :git-hdl:`hdl_2017_r1 <hdl_2017_r1:>`
- Quartus Pro 16.1
- Vivado 2016.4
- `Release notes 2017_R1 <https://github.com/analogdevicesinc/hdl/releases/tag/2017_R1>`_
- `Wiki list for hdl_2017_r1 <https://wiki.analog.com/resources/fpga/docs/hdl/downloads_2017_r1>`_
* - :git-hdl:`hdl_2016_r2 <hdl_2016_r2:>`
- Quartus Pro 16.0
- Vivado 2016.2
- `Release notes 2016_R2 <https://github.com/analogdevicesinc/hdl/releases/tag/2016_R2>`_
- `Wiki list for hdl_2016_r2 <https://wiki.analog.com/resources/fpga/docs/hdl/downloads_2016_r2>`_
* - :git-hdl:`hdl_2016_r1 <hdl_2016_r1:>`
- Quartus Pro 15.1
- Vivado 2015.4.2
- `Release notes 2016_R1 <https://github.com/analogdevicesinc/hdl/releases/tag/2016_R1>`_
- `Wiki list for hdl_2016_r1 <https://wiki.analog.com/resources/fpga/docs/hdl/downloads_2016_r1>`_
* - :git-hdl:`hdl_2015_r2 <hdl_2015_r2:>`
- Quartus Pro 15.0.2
- Vivado 2015.2
- `Release notes 2015_R2 <https://github.com/analogdevicesinc/hdl/releases/tag/2015_R2>`_
- `Wiki list for hdl_2015_r2 <https://wiki.analog.com/resources/fpga/docs/hdl/downloads_2015_r2>`_
* - :git-hdl:`hdl_2015_r1 <hdl_2015_r1:>`
- Quartus Pro 14.1
- Vivado 2014.4.1
- `Release notes 2015_R1 <https://github.com/analogdevicesinc/hdl/releases/tag/2015_R1>`_
- `Wiki list for hdl_2015_r1 <https://wiki.analog.com/resources/fpga/docs/hdl/downloads_2015_r1>`_
* - :git-hdl:`hdl_2014_r2 <hdl_2014_r2:>`
- Quartus Pro 14.0
- Vivado 2014.2
- `Release notes 2014_R2 <https://github.com/analogdevicesinc/hdl/releases/tag/2014_R2>`_
- `Wiki list for hdl_2014_r2 <https://wiki.analog.com/resources/fpga/docs/hdl/downloads_2014_r2>`_
* - :git-hdl:`hdl_2014_r1 <hdl_2014_r1:>`
- Quartus Pro 14.0
- Vivado 2013.4
- `Release notes 2014_R1 <https://github.com/analogdevicesinc/hdl/releases/tag/2014_R1>`_
- `Wiki list for hdl_2014_r1 <https://wiki.analog.com/resources/fpga/docs/hdl/downloads_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 <master:scripts/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.

2913
docs/user_guide/sources/base_platform.svg Executable file
View File

File diff suppressed because it is too large Load Diff
Side by Side

After

Width:  |  Height:  |  Size: 136 KiB

31
docs/user_guide/third_party.rst Normal file
View File

@ -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
-