pluto_hdl_adi/.github/scripts/readme_check_guideline.md

User guide for 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 and SystemVerilog files that do not contain "tb" in their path
• uses Python 3.x

Rules that are checked

These rules can be found in the HDL coding guideline.

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:

3. -e with no file specified
   Checks all files with the properties specified above. Additionally, it modifies the module definition parentheses according to the guideline.

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

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

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

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