109 lines
4.2 KiB
Markdown
109 lines
4.2 KiB
Markdown
# 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
|
|
```
|