22 KiB
Executable File
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:
if((my_signal1==1'b0)&&(my_bus[3:0]==4'd5))
Correct:
if ((my_signal == 1'b0) && (my_bus[3:0] == 4'd5))
A3: The always block should have a space before @ symbol.
Example:
Incorrect:
always@(posedge clk) begin
...
end
Correct:
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:
if (my_signal == 1'b0) begin
if (my_bus[3:0]==4'd5) begin
statement1;
statement2;
end
statement3;
statement4;
end
else
statement5;
Correct:
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:
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:
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:
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:
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:
if ((my_signal1 && your_signal1) || (my_signal2 && your_signal2) || (my_signal3 && your_signal3)) begin
my_signal1 = TRUE;
my_delayed_signal1 = !your_signal;
end
Correct:
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:
upper_en = (p5type && xadr1[0]); lower_en = (p5type && !xadr1[0]);
Correct:
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:
my_module #(.PARAMETER1 (PARAMETER1)) i_my_module (.clk (clk));
Correct:
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:
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:
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:
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
// ***************************************************************************
// ***************************************************************************
// 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
-- ***************************************************************************
-- ***************************************************************************
-- 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