pluto_hdl_adi/.github/scripts/readme_check_guideline.md

# User guide for [check_guideline.py](https://github.com/analogdevicesinc/hdl/tree/master/.github/scripts/check_guideline.py)

## Prerequisites

* the script must be run while being in the root directory (/hdl)
* clean the repository to remove the files generated by Vivado
* it will be run only on Verilog files that do not contain "tb" in their path
* doesn't run on SystemVerilog files
* uses Python 3.x

## Rules that are checked

These rules can be found in the [HDL coding guideline](https://github.com/analogdevicesinc/hdl/blob/master/docs/hdl_coding_guideline.md).

### 1. License header

It checks if the license header is up-to-date, containing the current year in
the year range. Exceptions are the JESD files and the ones specified in the
`avoid_list` string list.  
If `-e` option is added, the script can update the year range.

### 2. Two or more consecutive empty lines

It checks in the whole file if there are two or more consecutive empty lines.  
If `-e` option is added, the script can remove them and leave only one empty line.

### 3. Trailing whitespace

It checks if there are whitespace characters at the end of the lines.  
If `-e` option is added, then they can be removed.

### 4. Lines after `endmodule` tag

It checks if there are  lines after it.  
If `-e` option is added, the script can remove them.

### 5. Parentheses around the module declaration

It checks if the parentheses around the module declaration (meaning `) (` for
the parameters' list) are on an empty line, right after the last parameter.  
It also checks for the closing parenthesis at the module declaration (meaning `);`)
to be on an empty line, at the beginning, right after the last I/O port line.  
If `-e` option is added, the script can put them in their proper place.

### 6. Indentation of code

It checks if all lines (except for the ones that are commented) have an indentation 
of two or multiple of two spaces.  
Other exceptions to this are the `module` line, the `endmodule` line, the `) (` 
and the `);` from the module declaration.

### 7. Position of the module instances

It checks if the parameters' list (if that's the case) is in proper position, 
meaning that the position of `#` is checked, the parameters to be specified each 
on its own line, the parentheses around the instance name and the closing parenthesis 
of the module instance.

_NOTE_: these rules are marked in the script with **GC** (stands for Guideline Check) 
in the comments.

## Changes done by the script to your files

If one wants the script to make changes in files, they will be regarding:
* license header, except for JESD files and the ones specified in `avoid_list`
* two or more consecutive empty lines
* trailing whitespaces
* lines after `endmodule` tag
* parentheses around the module declaration (meaning `) (` for the parameters'
  list and `);` for when closing the declaration)

## Ways to run the script

1. With no arguments: `python3 check_guideline.py`  
Checks all files with the properties specified above. 
Does not modify the files.

2. With arguments:
  1. `-e` with no file specified  
    Checks all files with the properties specified above. Additionally, 
    it modifies the module definition parentheses according to the guideline.

  2. `-m`
    Checks files that are given as arguments (by their names including the
    extension).

  3. `-me`
    Checks files that are given as arguments (by their names including the
    extension) and modifies the files where the guideline is not respected.

  4. `-p`
    Checks files that are given as arguments (by their relative path) and
    modifies the files where the guideline is not respected.

  5. `-pe`
    Checks files that are given as arguments (by their relative path) and
    modifies the files where the guideline is not respected.

## Examples of running

```
python3 check_guideline.py     >> warnings.txt
python3 check_guideline.py -e  >> warnings.txt
python3 check_guideline.py -m  axi_ad9783.v >> warnings.txt
python3 check_guideline.py -me axi_ad9783.v axi_ad9783_if.v up_adc_common.v >> warnings.txt
python3 check_guideline.py -p  ./library/axi_ad9783/axi_ad9783.v ./library/common/up_adc_common.v >> warnings.txt
python3 check_guideline.py -pe ./library/axi_ad9783/axi_ad9783_if.v >> warnings.txt
```