QuEST/FPGA/Verilog Coding Guideline

Page 1 of 9

FPGA VERILOG HDL CODING GUIDELINES

Version 1.0

QuEST Global Engineering Services Pvt. Ltd.

Copyright
Notification:

This document is the property of QuEST Global Engineering

Services Pvt. Ltd. No part of this document may be reproduced
except as authorized by written permission from QuEST Global
Engineering Services Pvt. Ltd. The copyright and the foregoing
restriction extend to reproduction in all media.

Format ID:

QuEST/wFM/128 V4.0

FPGA Verilog HDL Coding Guidelines

QuEST Controlled

QuEST/FPGA/Verilog Coding Guideline

Page 2 of 9

Amendment Record
Version

1.0

Date

28-Jan2015

Author

Soumya
Jose

FPGA Verilog HDL Coding Guidelines

Reviewed By

Jobin Cyriac

Approved
By

Shaji NM

Change Description

Updated version on
IntraQuest Release

QuEST Controlled

QuEST/FPGA/Verilog Coding Guideline

Page 3 of 9

1 Introduction
This document defines the general guidelines to be followed in the coding of Verilog HDL
models and Verilog HDL test benches. Coding guidelines helps to improve the quality,
readability and maintainability of the developed Verilog codes.
If under any circumstances, the coding guidelines are violated, the reasons should be
well thought about and clearly explainable.

2 General Coding Guidelines

2.1 General Rules

Follow consistent writing style and naming conventions to maintain the

readability of the entire code.

Implement a functionality using minimum assignments and minimum amount of

code to improve the readability of the code and the simulation speed.

One line shall contain only one statement of code and set the maximum length
of the line to 80 characters.

Proper

indentation

provides

readability.

Use

three

space

characters

for

indentation and keep the same indentation throughout the code. Do NOT use
TAB character for indentation since TAB character spacing is editor dependant.

Blank lines or dashed lines may be used wherever necessary to improve

readability. For readability, at least one space shall be provided before and after
assignment operator. It is better to align assignment operators in consecutive
assignment statements.

The declaration of identifiers and the comments for the signal declaration shall
be aligned vertically to improve the readability.

Code shall be free of syntax errors.

The basic functionality of the code shall be verified by the developer.

Temporary assignments shall not be used unless necessary.

The keyword begin should appear on a line by itself so it can line up with its end
statement. The begin/end block should always be used, even if there is only one
statement. This makes adding lines of code much easier with fewer errors.

2.2 Naming Conventions

This section includes the general naming conventions to be followed in Verilog
coding. Specific naming conventions will be detailed in subsequent sections.
FPGA Verilog HDL Coding Guidelines

QuEST Controlled

QuEST/FPGA/Verilog Coding Guideline

Page 4 of 9
1. Always use meaningful name to describe the functionality of an identifier or a
block of code.
2. Modules shall have unique names.
3. Active low signals/variables shall be suffixed with _n. For example active low
reset signal shall be represented as reset_n or rst_n.
4. For input clock signals with fixed frequency, frequency of operation shall be
indicated in the signal name as suffix. For example clk_4m_in represents an
input clock with 4MHz frequency.
5. All modules and signal names will be lower case, delimited by underscores _.
6. The modules and signal names shall be limited to maximum of 16 characters
including_.
7. System verilog, verilog, VHDL keywords must not be used for signal names.
8. Use only characters A to Z, a to z, underscore (_), and numerals (0 to 9) in
identifier names.
9. The first letter of an identifier shall be an alphabet.
10. The name of constants and generics shall be in upper case.

2.3 Rules for Commenting

1. Proper comments make a code readable and maintainable. So make a habit of
commenting the code.
2. All the comments shall be in English.
3. Place the comments near to the part of the code they describe.
4. Make proper indentation and alignment for the comments to improve the
readability.

The

comments

shall

be

descriptive

enough

to

explain

the

functionality of the code portion.

5. Each Verilog HDL file shall have a file header with the following minimum
information
a. Name of the project
b. Name of the design unit
c. Description of the functionality of the current design file
d. Information of the author(s)
e. Target devices, if applicable
f.

Tool versions or dependencies

g. Revision history
FPGA Verilog HDL Coding Guidelines

QuEST Controlled

QuEST/FPGA/Verilog Coding Guideline

A generic file header format is shown in Section 4.1.

Page 5 of 9

6. Each functional section of the code must be preceded by comments describing

the codes intent and function.
7. Unusual or non obvious implementations must be explained and their limitations
documented with a comment.
8. Detailed documentation must be provided for cases in which a designer decides
to group unrelated signals together.
9. Old code or unused code must be deleted as opposed to commented out.
10. Each port declaration must have a descriptive comment, preferably on the same
line. If the comment is not on the same line, it should be on the preceding line.
11. For other declarations, such as nets and variables, it is recommended to have a
descriptive comment, preferably on the same line. If the comment is not on the
same line, it should be on the preceding line. Optional for auto-generated code.
12. Gated clock usage that is not inferred by tools must be documented in the code.
13. Multicycle paths must be documented in the code.
14. All synthesis-specific directives must be documented where used, identifying the
reason they are used, the tool and the directive used.
For example, when synthesis-specific directives such as KEEP attribute is used,
it shall be properly documented
15. Compiler directives such as ifdef, else and endif must have a comment where
used, describing the usage of the directive.

FPGA Verilog HDL Coding Guidelines

QuEST Controlled

QuEST/FPGA/Verilog Coding Guideline

Page 6 of 9

2.4 Rules for Variables, Signals and Ports

1. Try to use the same signal name throughout all levels of hierarchy, if possible,
which gives good traceability of that signal in the entire design.
2. It is recommended to order the port signals in terms of their mode. Input signals
shall be declared first, followed by bi-directional signals and lastly the output
signals. If the signals are grouped based on the functionality, the above said rule
shall be applicable within each group.
3. Always use explicit port mapping using named associations for component
instantiations. This will eliminate the port mapping error to a great extent.
4. Use clk for clock signal.
5. Use reset or rst for reset signal.
6. Use addr for address bus. For example system address can be represented by
sys_addr.
7. Use rd or re for read signal and wr or we for write signal.
8. _<clockname>_1d, _<clockname>_2d etc. shall be used for signals with one
clock delay and two clock delay etc.
9. For counters, _cnt shall be used.
10. _err shall be used to indicate the error status signal.
11. Use Enable signals (_en) and Valid signals (_valid) appropriately. Enable signal
enables or disables an option (it is a command) and Valid signal validates a data.
12. All the registered signals in an RTL shall be initialized on reset. No signal shall be
initialized on the signal declaration in an RTL code.
13. For signal assignments and signal declarations, follow the general rule of one line
per signal.
14. All the signal declarations shall be made at the beginning.

No signal shall be

declared in between each block of code.

15. Avoid writing data type conversion routines in the design wherever possible.
Instead use built in procedures in standard library.
16. No hard coded values shall be used in the code, instead use the constant name
or generic name itself. For constants use C_<CONST-NAME> and for generics
use G_<GENERIC-NAME>.

FPGA Verilog HDL Coding Guidelines

QuEST Controlled

QuEST/FPGA/Verilog Coding Guideline

Page 7 of 9

2.5 Rules for Module and Module instantiation

1. The name of the module shall be the name of the hardware modelled.
2. A file should contain single module with file name same as the name of the
module and with extension .v
3. The module name should reside on a line by itself and the opening parenthesis.
4. Only one signal/vector should be listed on each line.
5. Modules will be instantiated with their ports connected by name.
Eg. Clk_in( .clk_in ),
6. Instantiation name for
U<no.>_<module_name>

the

module

shall

follow

the

below

format

Eg. my_module U1_my_module (.my_signal1( current_signal1 ),

.my_signal2( current_signal2 )

2.6 Rules for always block

1. always blocks shall be associated with a descriptive label.
2. Sequential and combinatorial logic will not be combined in the same always block.
3. No delays (like #5) should ever be employed into synthesizable logic.
4. The sequential block is always coded with non blocking statements. There should
never be any blocking statements.
5. The sequential block is an always block with the clock (and possibly an
asynchronous reset) in the sensitivity list. Flip-flops can be set or cleared with the
asynchronous reset.
6. The combinatorial logic block is used to code all of the non-sequential logic.

2.7 Rules for defines

Defines (define compiler directive) are not used in normal module coding. They
may be used occasionally to set up some global variables in a top-level file.

FPGA Verilog HDL Coding Guidelines

QuEST Controlled

QuEST/FPGA/Verilog Coding Guideline

Page 8 of 9

3 Test Benches Specific Guidelines

1. The same test bench shall be used for both behavioural and timing simulations.
2. The file name of the test bench shall be same as the module name of the test
bench with file extension of .v
3. The module name of the test bench of a module shall be <module_name>_tb.
4. Use assertions wherever necessary (easy for debugging).
5. Self checking test benches shall generate an output file in ./output directory with
file name <module>_tb.rpt. It shall contain the following case-sensitive words.
ERROR

Will be contained in all error messages

PASS

Will be contained in all messages indicating the test

has run correctly

WARNING

Can be used for non-fatal messages

Table 1: Assertion keywords

FPGA Verilog HDL Coding Guidelines

QuEST Controlled

QuEST/FPGA/Verilog Coding Guideline

Page 9 of 9

4 Appendix
4.1 Verilog HDL File Header Format
The general Verilog HDL File header format is given below for reference. If required,
more details or fields can be added in the file header depending on project
requirements. If any project demands customer specific file headers, use that file
header.

file_header.v

4.2 Always block Header Format

FPGA Verilog HDL Coding Guidelines

QuEST Controlled