ADI HDL coding guidelines

1. Introduction

This document contains coding and documentation guidelines which must be followed by all HDL projects. The purpose of this document is to establish a set of rules that specify the layout, naming conventions and some general coding practices for the HDL modules implementation. Specific HDL coding practices meant to obtain maximum performance from a FPGA design are described by external documents such as [1] and [2] and are not included in this document.

There are two types of rules: should and must rules

• Should rules are advisory rules. They suggest the recommended way of doing things.

• Must rules are mandatory requirements.

The coding rules are intended to be applied to HDL modules written using VHDL or Verilog.

When an external IP is used, the naming conventions practiced by the IP should be kept, even if they do not match the rules specified in this document.

2. Coding style

A. Layout

A1

Spaces must be used instead of tabs.

This allows the code to be properly visualized by any editor. Do not leave spaces at the end of a line. The following editor settings must be used: Tab Size: 2, Indent Size: 2.

A2

One white space must be inserted around operators, such as =, ==, &&, ||, &, |, ^, etc.

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.

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.

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.

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.

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.

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.

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.

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.

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 main 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.

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.

A18

Local parameters must be declared first, before declaring wires or registers.

localparam   LOCAL_PARAM1;
localparam   NEXT_LOCAL_PARAM;
localparam   LOCAL_PARAM2;

reg  [ 3:0]  my_signal1;
reg  [ 4:0]  my_signal2;
reg          my_signal3;

wire [ 2:0]  my_wire1;
wire         my_wire2;

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 _.

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

// ***************************************************************************
// ***************************************************************************
// 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/main/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 (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/main/LICENSE_ADIBSD
--      This will allow to generate bit files and not release the source code,
--      as long as it attaches to an ADI device.
--
-- ***************************************************************************
-- ***************************************************************************

entity prescaler is
  Port (
    core_32m_clk      : in  std_logic,    -- 32 MHz clock
    system_clk        : in  std_logic,    -- system clock
    scan_mode_test    : in  std_logic,    -- scan mode clock
    reset_n           : in  std_logic,    -- active low hard reset, synch
    -- w/ system_clock
    div16_clk         : out std_logic,    -- input clock divided by 16
    div16_clk_n       : out std_logic     -- input clock divided by 16
     -- and inverted
  );
end prescaler;

architecture Behavioral of  prescaler is

-- Components Declarations

-- Local Types Declarations

--  Constants Declarations

-- Signals Declarations
  signal count        : std_logic_vector(3 downto 0); -- 4-bit counter to
  -- make clock divider
  signal count_ns     : std_logic_vector(3 downto 0); -- clock divider next
  -- state input

-- Module Implementation
begin

  -- This process updates the internal counter
  process(core_32m_clk)
  begin
    if (rising_edge(core_32m_clk)) then
      if (reset_n = '0') then
        -- reset counter
        count <= "0000";
      else
        -- update counter
        count <= count + "0001";
      end if;
    end if;
  end process;

  -- This process updates the output clock signals
  process(scan_mode_test, system_clk, count)
  begin
    if (scan_mode_test = '0') then
      -- normal operation clock assign
      div16_clk <= count(3);
      div16_clk_n <= not count(3);
    else
      -- scan mode clock assign
      div16_clk <= system_clk;
      div16_clk_n <= system_clk;
    end if;
  end process;

end Behavioral;

4. References

[1] Philippe Garrault, Brian Philofsky, “HDL Coding Practices to Accelerate Design Performance”, Xilinx, 2006

[2] Peter Chambers, “The Ten Commandments of Excellent Design”, VLSI Technology, 1997

[3] “Verilog Coding Techniques, v3.2”, Freescale Semiconductor, 2005

[4] Jane Smith, “Verilog Coding Guidelines, Rev. B”, Cisco Systems 2000