VHDL Design Guidelines – Version 1.

Elaborate: Carlos Augusto Machado Monteiro

Reviewed: Caio Alonso da Costa
Rafael Nardelli

1. Abstract
This document defines a series of suggestions for digital design and VHDL coding, which the
developers must follow. The main goal of this document is reducing the probability of logical
errors and facilitate the portability of the VHDL code between designers. For a full
understanding of these guidelines, the team needs to have experience in digital design and
programmable logic.

2. Introduction
Design Process
Even though this document does not define programmable logic design process, it is wise to
comment about the philosophy of the process. The design must be well defined before the
beginning of VHDL coding. The designer is not ready for VHDL coding if the project is not
specified with time diagrams, block diagrams or text. In other words: "code is not enough". A
process is defined as an ordered and documented way for digital design. Simulation has high
importance for verification, but it must not be used to help coding. Do not create a “rough draft”
of a design, then iteratively simulate and modify it until it works since this can lead to a lack of
understanding of how and why it works. Experimental codes made to understand the syntax or a
concept must not be part of the product development and are not a good development
methodology. When the designer is creating a digital circuit, block diagram and other
architecture representations should be drawn. It is advisable to elaborate a project document and
review it with peers before VHDL coding. Explaining the project helps to find errors at the
beginning of the development process. The documentation gives a better understanding and it is
a valuable help for any changes in the future. Projects with no documentation are not
acceptable.

Synchronization
The entire FPGA design must be synchronous.
Synchronous design simply means that all data are passed through combinational logic and flip-
flops that are synchronized to a single clock.
Delay is always controlled by flip-flops, not combinational logic.
No signal that is generated by combinational logic can be fed back to the same group of
combinational logic without first going through a synchronizing flip-flop.
Clock cannot be gated – in other words, clocks must go directly to the clock input of the flip-
flops without going through any combinational logic.
One clock for the system, when possible.
Do not data signal as clock.
If the clock division is needed, use a PLL. In case that a PLL is not adequate, use the clock
enable, as in the following code.

Tools Warnings
The compilation of each sub-module must not generate any warnings.
Critical warnings are acceptable only from tool-generated files and must be analysed.
 3. Guidelines for VHDL coding
File Names
A VHDL file and the entity it contains must share the same name. The entity name must be
related with what the entity does. If the name implies more than one function, then the entity
should be divided in different components to avoid mixing different functions and hence
decreasing the possibility of confusion and error.

File Name Suffix

Use _tb for testbench files and _pkg for package files.

Naming Conventions
Do not use CamelCase. Always separate names with underscores.

Item Description
Generic, constant, type All in uppercase.
Type Use _TYPE suffix
Use the _ST_TYPE suffix after the state machine name. Example:
MULT_ST_TYPE. For the states, use the prefix ST. Example:
Type listed for state ST_WAIT, ST_SUM, ST_DECIDE. If there are more than one
machines state machine in the module, use the ST prefix followed by the state
machine name. Example: ST_MULT_WAIT, ST_MULT_SUM,
ST_MULT_DECIDE
Place _i suffixes for input, _o for output and _io for bidirectional.
This should not be done for clock and reset signals that should be
named sysclk and reset_n.
Port
In case that it is the top file, the port must have the same a name as
the pin name or a comment clarifying it.
If make sense to use a vector in the port, it must be used.
Function Use _fcn suffix
Procedure Use _proc suffix
Signal active low Use _n suffix
Registers outputs must have the suffix _reg, registers inputs must
Sequential process
have the suffix _next
Signal names that Place the component name where the signal is generated as a prefix.
interconnect modules Use _int suffix.
Use _rtl suffix in the entity name. Example: architecture mult_rtl of
Architecture
mult is
Use _inst suffix. If there is more than one instance of the same
Instances
entity, use a number after the instance, such as _inst1, _inst2, etc.

Port Types
Use only in and out ports. Avoid the use of inout, except on the top module. The use of suffixes
_i and _o helps on component’s instantiation by informing whether a port is input or output,
respectively. Port types should be declared as std_logic or std_logic_vector. Ports should never
be declared as “buffer”.
Input and Output Synchronization
All asynchronous external pads (signals related to FPGA pins) must be registered with at least 2
or 3 registers.
Every output signal of each module must be registered.

Signed and Unsigned Library

Use always IEEE.numeric_std.all instead of std_logic_arith, signed or unsigned. Avoiding these
libraries forces the designer to explicit if the signal is signed or unsigned.

Vectors
All signals used for arithmetic operations must be declared as signed, unsigned, integer or
natural with a defined range. Use std_logic_vector only for non-numeric signals, for interfacing
with third-party libraries or entity port types. Use always Y downto X.

VHDL Version
Use the IEEE 1076-1993 version.

Indentation
Do not use tabs, use auto indentation tools such as Emacs text editor.

Variables
Avoid the use of variables. Except for the following cases: loop indexes as "i" and "j”, to
simplify long lines or to make the code easier to understand. Variables should not synthesize
registers or latches.

Line length
Do not use more than 80 characters.

Operators
Put whitespaces before and after VHDL operators.

Reset and Clear

They must always be asynchronous. Example:

Parentheses
Parentheses must be used to ease the understanding of mathematical and logical expressions. Do
not rely solely on the VHDL operator precedence.
Process
Every process should have a label.
In all combinational processes every output signal must have a default attribution right after the
“begin”. This prevents undesirable latches.
All sequential processes must have a reset input (active low) that initialize all registers with
zero. It must also initialize the state machines with the initial state.
The sequential process sensibility list must have only clock and reset signal.

Clock rising edge

Inside of the sequential processes use only the function rising_edge(clock_name).

Commented blocks of code

Any disabled block of code should not be on the final release.

Comments
The comments must add value to the code and be written in a complete and clear way.
Think about yourself reading the code 10 years from now.
Update the comments when you update the code.
Wrong comment is worse than no comments.

Finite State Machine

Limit the number of inputs to 15.
Always make a state and transition diagram.
The state machines should not have more than 20 complex states. If necessary, divide it in
smaller state machines.
Use separate processes for next state logic and state register.
The signals that represent the actual and next state must have the suffixes st_reg and st_next,
respectively.
Implementation of the state machine must always be done with two processes: one process only
for registers and another one for next state logic and output logic.
Separate "data path" and "control logic" when it is convenient.

Assignments
Never assign unknown('x') or not care ('-') values to signals.
Never assign high impedance (‘z’) for internal signals. It can only be assign to pad (signal that
goes directly to a pin).

Default Values
Never use default values on signal declarations.
Constants
Use only one package file per project to define constants and components.
Do not use magic numbers. Use constants or generics.

Instances
Always use named instances (explicitly instances) instead of positional instances.

Vectors and Arrays

Always use constants or generics to define the size of a buffer, vector or array.

If then Else
When a long sequence of if-elsif is needed, use "case".

Testbenches
Each entity must have at least one testbench.
The testbench should be able to check itself so the designer doesn´t have to look at the
waveform.
There can be many testbenches for a single entity, each one testing specific features.
The testbench code coverage should be as large as possible.
Use assertions.

4. File Structure

5. Check list
This set of questions is a checklist to assist the reviewer of a VHDL code. It was based on
VHDL Design Guidelines, which is the standardization of the code.
• Is the design synchronous?
• Are there delays made with combinational circuits?
• Is there a latch?
• Is there any logic with clocks?
• In case there is more than one clock, was the circuit for clock domain change
implemented?
• In the case of clock division, were the PLL or clk_divider.vhd used?
• Is there any warning related to syntax errors in the synthesis tool?
• Is the filename the same as the entity name?
• Does the entity name resemble what the entity does?
• If it is a test bench, was the _tb suffix used in the file name?
• If it is a package, was the _pkg suffix used in the file name?
• Are GENERICS, CONSTANTS and TYPES all in uppercase?
• Do the types have the suffix _ TYPE?
• In the case of enumerated type for state machines, does it have the suffix _ST_TYPE
and states the ST_ prefix followed by the name of the state machine?
• Are the suffixes _i, _o, _io used in in, out, inout ports respectively??
• Is the clock named sysclk?
• Is the reset named reset_n?
• Are all functions named with the suffix _fcn?
• Are all procedures named with the suffix _proc?
• Do active low signals have the suffix _n?
• In sequential processes, are the registers inputs and outputs named with the suffixes
_next and _reg, respectively?
• Does the name of the architecture have the suffix _rtl?
• Does the instances have the suffix _inst?
• Were buffer or inout ports used in modules that are not the top module?
• Are all outputs of the module synchronized with at least one filp flop?
• Are all input signals (FPGA pins or std_logic_vector ports) synchronized with at least
one flip-flop?
• Was the library IEEE.numeric_std.all used?
• Were the vectors used in arithmetic operations declared as signed, unsigned, integer or
natural, with defined ranges?
• Was the type std_logic_vector used only for non-numeric signals, interfaces with third-
party libraries or interfaces with the outside world?
• Are vectors range defined Y downto X?
• Was the IEEE 1076-1993 VHDL version used?
• Is the indentation adequate?
• Were the variables used correctly?
• Is there any logic with asynchronous reset?
• Was the reset implemented as asynchronous?
• Were parentheses used to facilitate the understanding of mathematical or logical
expressions?
• Do the types conversion have an explanatory comment?
• Were labels used in all processes?
• In all combinational processes (which doesn’t have clock), right after the begin, are
there default assignments for all the output signals of the process?
• Is the falling edge of a clock used in any process?
• Are the comments useful?
• Is there any state machine with more than 15 entries?
• Is there any state machine with more than 20 complex states?
• Is there separate processes for next_state_logic and state register?
• Do the signals representing the current and next state have the suffix st_reg and st_next
respectively?
• Are the "data path" and "control logic " separated?
• Is there any signal assigned with unknown ('x'), not care ('-') oe high impedance (‘z’)
values?
• Were signals initialized in the declaration?

Instances
Were used Instances by name (explicit instance) instead of positional?

Vectors and Arrays

Were constants and generics used to determine the size of buffers, vectors and arrays?

If then Else
Are there long chains of If Then Else?

File Structure
Does the file structure agree with the design guidelines?