Code Aesthetics

Summary

This document is in addition to the BSG SystemVerilog Coding Guidelines. All rules in that file should be obeyed. This document augments that documents with a few aesthetic guidelines. This document is intended to provide more rigid structure for coding style and file structure.

References

BSG SystemVerilog Coding Guidelines

Freescale Verilog Guidelines

Google C++ Style Guide

lowRISCV Verilog Coding Style Guide

Verilog Style

No tabs in files, anywhere. People get different results based on their editor.
- Exception: Makefiles. Tabs should be used to indent recipes, but not for general alignment

Align all things that have parallel structure (begin/end, case/endcase, commas, periods, etc.). This makes it easier to check the code and find the matching component.

  if (x_p)  // notice how matching inputs are aligned
    begin: foo
      adder     (this_input, that_input, another_input);
    end
  else
    begin: bar
      wow_adder (this_input,          3, another_input);
    end


  if (foo)    // notice alignment of if/else, begin/end
      x = 3;  // and optional alignment of x = statement.
  else
    begin
      x = 1;
  	y = 0;
    end

Use localparam keyword for derived parameters and input parameters that should not be set by the party instantiating the module.
Localparams in port lists are allowed, but only for sizing ports. Other generated localparams should go near their consumers.
Prefer input [1:0] to input logic [1:0] and output [1:0] to output logic [1:0]
- Ports with no type default to ‘wire’. This forces you to use an ‘assign’ for outputs, preventing inferred latches. Since BSG style is to latch inputs and have combinatorial outputs, this style conveys hardware intent.
Ports and parameters should not have the module name as a prefix, since that is redundant. In some cases, the wires in the parent module may use the module name of the child to disambiguate.
```
  module foo 
    #(parameter bar_p = "inv")
     (input [bar_p-1:0] baz_i  // not foo_baz_i
      );

  foo
   #(.bar_p(foo_bar_p))
   inst
    (.baz_i(foo_baz_li));
```
Signals corresponding to a pipeline stage in a module which has multiple stages should have a pipeline stage suffix
- foobar_ex1_lo
- barbaz_tv_n
‘0’, ‘1’, ‘2’, and ‘8’ (when used as byte width) are the only allowable magic numbers. Else, consider strongly the use of a localparam.
Prefer packages over `includes.
- `defines are scoped globally, so defining them within packages makes no functional difference, as long as proper include guards are used.
- BlackParrot flist style is to compile all packages first, so most tools will be forced to include definitions in the correct order.
Import packages within modules (not other headers) to avoid global ($root) package imports

Modules are named *.v, headers and packages are named *.vh

  foo_pkg.vh:

  package foo_pkg;
    localparam baz_gp = 1’b0;

    `include “foo_defines.vh”
    `include “bar_defines.vh”
  endpackage;

  foo.v:

  module foo
   import foo_pkg::*;
   #(parameter a = "inv")

Syntactic style

snake_case for all identifiers.
- No capital letters in the source code except in comments or in strings.
2 spaces per indent.
Code inside of a module should be idented once.
Newline at end of file (helps some old unix tools).

-Space between type and width e.g. logic [1:0], not logic[1:0].

-Space between keywords and operators.

begin : // this
if(x)   // this
begin:  // not this
if (x)  // not this

Per BSG SystemVerilog Style Guide, all generate blocks should be labeled.
Lines should not exceed 100 (soft limit) or 120 (hard limit) columns
- Exception: macro definition parameter lists and usage must be one line to satisfy some tools. Macro bodies should be broken up with backslashification.
- When breaking lines start the newline with the operator or the first operand.
```
  foo = super_long_name_that_wraps
        + other_name;
  foo = 
    super_long_name_that_wraps + other_name;
```

Lists should be formatted in one of the following ways:

  (all, one, line)

  (all
   ,one
   ,line
   )

  (spaces, after, commas, horizontally)
  (but
   ,not
   ,vertically
   )

  // Except for between commas and keywords
  , parameter p
  ...
  , input  i
  , output o
  )

Declarations and instantations should be formatted in one of the following ways: // Module declaration module foo #(parameter width_p = “inv” // note alignment , parameter height_p = “inv” // space between , and parameter ) (input [width_p-1:0] bar_i // port names aligned , input [height_p-1:0] baz_i // space between , and input );

  // Module instantiation
  foo 
   #(.width_p(3)   // # indented by 1 space
     ,.height_p(5) // no space between , and .
     )
   inst                   // inst name aligned with #    
    (.bar_i(foo_bar_li)   // parentheses of parameters and ports aligned
     ,.baz_i(foo_baz_li)
     );

  // Can combine parameter or port lists to one line
  foo 
   #(.width_p(3) ,.height_p(5))
   inst                     
    (.bar_i(foo_bar_li), .baz_i(foo_baz_li));

  // Struct declaration
  typedef struct
  {
    logic [1:0] bar; // fields aligned
    logic       baz;
    foobar_s    boo;
  }  foo_s;      // Two spaces to break up struct name from field declarations

  // Enum declaration
  typedef enum
  {
    e_zop  = 2’b00  // All values assigned, rather than default
    ,e_bar = 2’b01  // Values aligned
    ,e_baz = 2’b10
  } foo_e;