pluto_hdl_adi/docs/hdl_coding_guideline.md

# 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