Verilog Coding Guidelines- Part 5

5. FILE STRUCTURE

5.1 One file, one module

Create separate files for each modules. Name the file .v. The only exceptions for this
file naming convention shall be the technology-dependent modules (top module or macro
wrapper modules). These files shall be appropriately named like design_name_fpga.v, design_name_tsmc.v, or design_name_virtex.v.

5.2 File header

Each source file should contain a header at the top of the file in the following
format:
/////////////////////////////////////////////////////////////////
//////////
//(c) Copyright 2008 Verilog Course Team/Company Name. All rights reserved
//
// File:
// Project:
// Purpose:
// Author:
//
// $Id: index.html,v 1.1 2008/0773/23 01:55:57 VCT $
//
// Detailed description of the module included in the file.
//Include relevant part of the spec
// Logical hierarchy tree
// Block diagrams
// Timing diagrams etc.
//
/////////////////////////////////////////////////////////////////

The above example is for verilog. Change the comment characters appropriately for other source types. Example: "#" in Tcl, Perl and CSH. The presence of variable $Id$ in the header will capture the filename, user, version information every time the file is checked-in/committed.

5.3 Modification history

Each file should contain a log section at the bottom of the file in the following format:
///////////////////////////////////////////////////////////////////////
////
//
// Modification History:
//
// $Log$
//
///////////////////////////////////////////////////////////////////////

Listing the modification history at the top of the file can be annoying as one has to scroll down to reach the code every time the file is opened for reading. The variable $Log$ will cause RCS/CVS to capture the user-comments entered during each check-in/commit as comments in footer section.

5.4 Include Files

Keep the `define statements and Parameters for a design in a single separate file and name the file DesignName_params.v

Verilog Coding Guidelines - Part 4

4. DO’S AND DONT’S

4.1Use non-blocking assignments in sequential blocks

All registers assignments are concurrent. No combinatorial logic is allowed in sequential blocks. Always use non-blocking statements here.

4.2 Use blocking assignments in combinational blocks

Concurrency is not needed here. Often the combinatorial logic is implemented in multiple steps. Always use blocking statements for combinatorial blocks.

4.3 Ensure that there are no unused signals

Unused signals in the designs are often clear indication of incomplete or erroneous design. Check to make sure that design does not contain such signals.

4.3 Ensure that there are no un-driven signals

Un-driven signals in the designs are mostly clear indication of design errors. Check to make sure that design does not contain such signals.

Verilgo Coding Guidelines -Part 3

3. COMMENT

3.1 Comment blocks vs scattered comments

Describe a group of logic at the beginning of the file (in the header) or at the top of a block or group of blocks. Avoid scattering the comment for a related logic. Typically the reader would like to go through the comment and then understand the code itself. Scattered comment can make this exercise more tedious.

Example:

//File:
//purpose:
//Project:
//Author:

3.2 Meaningful comments

Do not include what is obvious in the code in your comments. The comment should typically cover what is not expressed through the code itself.

Example:

History of a particular implementation, why a particular signal is used, any
algorithm being implemented etc.

3.3 Single line comments

Use single line comments where ever possible. i.e. Use comments starting with ’//’ rather than ’/* .. */’ style. This makes it easy to cut-paste or move around the code and comments. It is also easy to follow the indentation with single line comments which makes the code more readable.

Verilog Coding Guidelines -Part 2

2. STYLE

2.1 Page width: 75 characters

Considering the limited page width supported in many terminals and printers, restrict the maximum line length to 75 characters. For reuse macros reduce this number to 72 to comply with RMM.

2.2 No tabs

Do not use tabs for indentation. Tab settings are different in different environments and hence can spoil the indentation in some setup.

2.3 Port ordering

Arrange the port list and declarations in a cause and effect order. Group the list/declaration on the basis of functionality rather than port direction etc. Specify the reset and clock signals at the top of the list.

2.4 One statement per line

Limit the number of HDL statements per line to one. Do not include multiple statements, separated by semicolon, in the same line. This will improve readability and will make it is easy to process the code using scripts and utilities.

2.5 One declaration per line

Limit the number of port, wire or reg declaration per line to one. Do not include multiple declarations, separated by commas, in the same line. This will make it easy to comment, add, or delete the declared objects.

Example:

Wrong way:
input trdy_n, stop_n;

Right way:
input trdy_n;
input stop_n;