VHDL Coding Rules

Tampere University of Technology

Institute of Digital and Computer Systems

VHDL Coding Rules, page 1

Purpose of VHDL Coding Rules

• Introduce a common, clear appearance for VHDL.

• Increase readability for reviewing purposes.
• Prevent harmful or unpractical ways of coding.
• Not to restrict creativity in any way.

A_37894 :process(xR,CK ,datai , DATAO )

BEGIN
if(XR =’1’ )THEN DATAO<= "1010";end if;
if(CK’event) THEN if CK = ‘1’ THEN
for ARGH in 0
to 3 Loop DATAO(ARGH) <=datai(ARGH);
end Loop;end if;
end process;

VHDL Coding Rules, page 2

File contents and naming
• One VHDL file should contain one entity and one architecture.
• VDHL file has the same name than the entity in the file, in lower
case.
File content File name
One entity, one arch entityname.vhd
One entity entityname_ent.vhd
One architecture entityname_archname_arch.vhd
More than one architecture entityname_arch.vhd
One configuration entityname_cfgname_cfg.vhd
More than one configuration entityname_cfg.vhd
Package entityname_pkg.vhd
Test bench entityname_tb.vhd

• Configurations are not used for code which will be synthesised *.

* Note: Some VHDL simulators may need the configuration. It is recommended that the configuration is
included in the same file with the entity and the architecture. The configuration part is separated from the
synthesised code with pragmas:
-- translate off
and
-- translate on

Rule: A VHDL file and the entity it contains have the same name.
VHDL Coding Rules, page 3
File header

• Every VHDL file starts with standard header:

• Dependency -field is not needed.

--------------------------------------------------------------------
-- Project : project or course name
-- Author : Teemu Teekkari
-- Date : 01/09/03 14:05:01
-- File : example.vhd
-- Design : Course exercise 1
--------------------------------------------------------------------
-- Description : Example header
--------------------------------------------------------------------
-- $Log$
--------------------------------------------------------------------

Rule: Every VHDL file starts with a standard header.

VHDL Coding Rules, page 4
Code appearance: General

• VHDL code must be indented

– Much easier to read.

• Indentation is three spaces

– Fixed inside a project.
– Comment lines are indented like regular code.
• Maximum length of a line is 78 characters
– In VHDL language it is very easy to divide lines.

Rule: Use indentation. Keep lines shorter than 78 characters.

VHDL Coding Rules, page 5
Code appearance: Spacing
• Condition expressions are written inside parenthesis.
• There is a space outside parenthesis, but not inside.

IF (rst_n = '0') THEN

• There is a space after a comma, but not before:

digital_phase_locked_loop : PROCESS (rst_n, clk)

• There is a space on both sides of “=>”, “<=“, “:=”, “>”, “<“, “=“,
“/=“, “+”, “-”, “&”, “AND”, “OR”, “XOR” etc:

data_output <= ((('0' & a) + ('0' & b)) AND c);

• You may omit the space from the sides of “*” and “/”:

data_output <= a*b + c;

VHDL Coding Rules, page 6

Code appearance: Aligning I

• One line of code should contain just one one statement.

• In the entity port declaration reserve one line completely for
each signal.
• Align the colons in the entity port:

ENTITY pokerhand IS
PORT (
rst_n : IN STD_LOGIC;
clk : IN STD_LOGIC;
card_0_in : IN STD_LOGIC_VECTOR(5 DOWNTO 0);
card_1_in : IN STD_LOGIC_VECTOR(5 DOWNTO 0);
card_2_in : IN STD_LOGIC_VECTOR(5 DOWNTO 0);
card_3_in : IN STD_LOGIC_VECTOR(5 DOWNTO 0);
card_4_in : IN STD_LOGIC_VECTOR(5 DOWNTO 0);
hand_out : OUT STD_LOGIC_VECTOR(3 DOWNTO 0)
);
END pokerhand;

VHDL Coding Rules, page 7

Code appearance: Aligning II

• Align colons inside one signal declaration group:

-- control signals
SIGNAL select_0 : STD_LOGIC_VECTOR(31 DOWNTO 0);
SIGNAL select_1 : STD_LOGIC_VECTOR(31 DOWNTO 0);
SIGNAL state : STD_LOGIC_VECTOR(31 DOWNTO 0);

-- address and data signals

SIGNAL read_address : STD_LOGIC_VECTOR(31 DOWNTO 0);
SIGNAL write_address : STD_LOGIC_VECTOR(31 DOWNTO 0);
SIGNAL read_data : STD_LOGIC_VECTOR(31 DOWNTO 0);
SIGNAL write_data : STD_LOGIC_VECTOR(31 DOWNTO 0);

VHDL Coding Rules, page 8

Code appearance: Aligning III

• Align the " =>" in port maps:

i_pokerhand : pokerhand
PORT MAP (
rst_n => rst_n,
clk => clk,
card_0_in => card_0_i,
card_1_in => card_1_i,
card_2_in => card_2_i,
card_3_in => card_3_i,
card_4_in => card_4_i,
hand_out => hand_i
);

Guideline: Use correct spacing. Align colons and port maps.

VHDL Coding Rules, page 9
Commenting I

• Comment everything you feel needs commenting.

– Think of yourself reading the code after a decade.
• Do not comment things that are otherwise clear.
– Comment the intended function not VHDL syntax or
semantics.
• A comment is placed before the part of code to be commented.
• A comment is indented like regular code.
– A comment usually does not start from the far left.
• Keep a comment in one place. Never copy the same comment to
another place.

VHDL Coding Rules, page 10

Commenting II

• Large comment is used mostly before processes:

----------------------------------------------------------
-- Parity bit is calculated for the DATA_INPUT signal.
----------------------------------------------------------
parity_calculation : PROCESS (rst_n, clk)
BEGIN
IF (rst_n = '0') THEN
parity <= '0';
ELSIF (clk‘EVENT and clk = '1') THEN
parity <= data_input(3) XOR data_input(2)
XOR data_input(1) XOR data_input(0);
END IF;
END PROCESS parity_calculation;

VHDL Coding Rules, page 11

Commenting III

• One-liners are used in other cases:

parity_calculation : PROCESS (rst_n, clk)

BEGIN
IF (rst_n = '0') THEN
be <= (OTHERS => '0');
ELSIF (clk‘EVENT and clk = '1') THEN
-- write lower 16-bit word
IF (state = "011") THEN -- alternative place
be <= "0011";
-- write higher 16-bit word
ELSIF (state = "101") THEN -- alternative place
be <= "1100";
ELSE
be <= "0000";
END IF;
END IF;
END PROCESS parity_calculation;

Rule: Write enough comments. Never comment self-evident things.

VHDL Coding Rules, page 12
Naming in general I

• Entity, signal and process names should be descriptive.

• On the other hand too long names may cause trouble.
• Average length of a good name might be 8 to 16 characters
– Process names may be longer than other names.
• When inventing names, noun should come first, then a verb
– For example: processor_interrupt
– Not: interrupt_processor
• Names are derived from English language.

VHDL Coding Rules, page 13

Naming in general II

• All names you invent are written in lower case, including:

– Entity, architecture, configuration and package names.
– Signal, variable and constant names.
– Procedure and function names.
– Process, instantiation and generation labels.
• All names not invented by you or your team are in upper case:
– VHDL reserved words.
– Libraries.
• Never mix upper and lower case letters in any single token.
• Use only characters 'A' .. 'Z', '0' .. '9' and underscore '_'.
example_process : PROCESS (rst_n, clk)
BEGIN
...

Rule: Names invented by you in lower case. Others in upper case.

VHDL Coding Rules, page 14
Naming: Architecture

• Architecture name should be one of following:

BEHAVIORAL Implies physical logic, does not compile with RTL tools
RTL Implies physical logic, compiles with RTL tools
STRUCTURAL Implies physical connections, but not any logic
GATE Gate level netlist
SIMULATION Simulation model
TESTBENCH Test bench

Rule: Use only conventional architecture names.

VHDL Coding Rules, page 15
Naming: Signals I

• Descriptive signal naming is very important

– Other documentation may help very little.
• Recommended signal naming:
General register output signalname_r
Delay register output signalname_d
Delay chain signalname_d0, signalname_d1,…..
Synchronisation chain signalname_s0, signalname_s1,…..
Toggle output signalname_t
Falling edge register output signalname_f
Level based control, enable signalname_e
Triggering control, pulse signalname_p
Inverted or active low signal signalname_n
Internal signal * signalname_i
Com binatory signal signalname_c
Variable variablename_v

* Note: Internal signal is a signal which is later assigned to another signal, for example:
data_out <= data_out_i;

Guideline: Use signal naming conventions always when it is possible.

VHDL Coding Rules, page 16
Naming: Signals II

• Recommended name for active low reset signal is rst_n

– Asynchronous set should not be used.
– A register should never have both asynchronous set and
reset.
• Recommended name for clock signal is clk.
– If there are more clocks the letters "clk" should be present
in every one as a postfix.

VHDL Coding Rules, page 17

Naming: Signals III

• When a signal ascends through hierarchy, its name should

remain the same. This is especially important for clock signals.
• If there is possibility of ambiguities, a prefix may be added
– The prefix may be for example the instance name.
i_datamux_13 : datamux
PORT MAP (
sel_in => datamux_13_sel,
data_in => datamux_13_data_in,
data_out => datamux_13_data_out
);
• Always use named signal mapping, never ordered mapping.
• Signals from block a to b are named:
signalname_a_b
• In port names there should be a direction as a postfix (in or
out )

Guideline: Signal name should remain throughout the hierarchy.

VHDL Coding Rules, page 18
Naming: Instantiations

• Component instance name is formed from the component name

by attaching the prefix “i_” and identifier as a postfix:
i_componentname_identifier : componentname
PORT MAP (
);
• This naming convention helps to track down the actual entity
– From simulation results.
– From synthesis results.
• Exception is possible in case the entity name is very long
– In this case it might be best to shorten the entity name.

Rule: Instance is named after the component entity.

VHDL Coding Rules, page 19
Naming: Generate

• GENERATE statement should be used when multiple instances of

the same component are needed.
• GENERATE should not be used for generating other constructs.
• Form the label for generate statement as G_COMPONENTNAME :

g_datamux : FOR i IN 0 TO 15 GENERATE

i_datamux : datamux
PORT MAP (
sel_in => sel_in(i),
data_in => data_in(64*i + 63 DOWNTO 64*i),
data_out => data_out(32*i + 31 DOWNTO 32*i)
);
END GENERATE g_datamux;

Guideline: Use GENERATE for multiple instances only.

VHDL Coding Rules, page 20
Naming: Processes

• Give every process a label

– Makes easier to identify part of the code implying specific
logic in synthesis.
• Label is written two times in the code:
– Before the process.
– After the process.
• Sometimes it is useful to use signal name in a process name.
The process name can be formed as SIGNALNAME_PROCESS.

Rule: Label every process.

VHDL Coding Rules, page 21
Naming: Generics

• Names of generics should be short

– Less than 16 characters
– In synthesis block name is composed of the entity name and
the names of the generics.
– If generic names are long, the resulting block name is
awkward to use and may cause problems in back-end tools.

VHDL Coding Rules, page 22

Ordering: Entity port I

• Signals in the port of the entity should be grouped as follows:

– Resets
– Clocks
– Signals of group A
– Signals of group B
– Signals of group C
– …
• Signals inside a group should be further grouped as follows:
– Control inputs
– Data inputs
– Outputs

VHDL Coding Rules, page 23

Ordering: Entity port II

• There should be one line for one signal:

ENTITY datareg IS
PORT (
rst_n : IN STD_LOGIC;
clk : IN STD_LOGIC;
data_in : IN STD_LOGIC_VECTOR(31 DOWNTO 0);
data_out : OUT STD_LOGIC_VECTOR(31 DOWNTO 0)
);
END datareg;

• One entity should have only one clock.

• If more than one clock is necessary, the number of blocks with
multiple clocks should be minimised.

Guideline: Declare signals according to same order.

VHDL Coding Rules, page 24
Ordering: Declarations I

• Component and signal declarations are ordered in groups of

one component and specific signals:
– Declaration of component A
– Signals the instantiations of component A drive
– Declaration of component B
– Signals the instantiations of component B drive
– Declaration of component C
– Signals the instantiations of component C drive
– …
– All other signals (if any)

VHDL Coding Rules, page 25

Ordering: Declarations II

• Order of the component instantiations should be the same than the

order of the component declarations.
• Do not give initial value to signals in the declarative part
– This is not supported by synthesis and causes a warning.

SIGNAL main_state : STD_LOGIC_VECTOR(7 DOWNTO 0) := "11110000";

Rule: Declare signals after the component that drives them.

VHDL Coding Rules, page 26
Safe coding: Signal modes

• Use only modes IN and OUT in the port of sub-blocks.

• Use only modes IN, OUT and INOUT in the port of the top-level
entity.

Rule: Use only port modes IN and OUT.

VHDL Coding Rules, page 27
Safe coding: Signal types I

• Use only signal types STD_LOGIC and STD_LOGIC_VECTOR in the

port of sub-blocks.
• Use only signal type STD_LOGIC and STD_LOGIC_VECTOR in the
port of the top-level entity.

Rule: Use only port types STD_LOGIC and STD_LOGIC_VECTOR.

VHDL Coding Rules, page 28
Safe coding: Signal types II

• Direction of bits in STD_LOGIC_VECTOR is always DOWNTO.

• Size of the vector should be parameterized
• Usually the least significant bit is numbered as zero:
SIGNAL data : STD_LOGIC_VECTOR(datawidth_g-1 DOWNTO 0);

• Sometimes it is useful to indicate bits that have been left off with
the number of the LSB
– For example an address bus with the two LSBs left off:
SIGNAL address : STD_LOGIC_VECTOR(datawidth_g-1 DOWNTO 2);

Rule: Direction of bits in a bus is always DOWNTO.

VHDL Coding Rules, page 29
Safe coding: Synchronous process I

• Processes can be divided into two groups

– Synchronous
– Asynchronous.
• A synchronous process always has exactly two signals in the
process sensitivity list
– Asynchronous reset.
– Clock.
• Clock event clause is always sensitive to the rising edge of the
clock.
• If inverted clock is needed, introduce the inverted clock signal
yourself
– All clock signals generated inside the chip should be
generated in a single, dedicated block.
– Same applies to asynchronous reset.
• Do not make self resetting blocks.
VHDL Coding Rules, page 30
Safe coding: Synchronous process II

• An example of a synchronous process:

data_register : PROCESS (rst_n, clk)

BEGIN
IF (rst_n = '0') THEN
data_out <= (OTHERS => '0');
ELSIF (clk‘EVENT AND clk = '1') THEN
data_out <= data_in;
END IF;
END PROCESS data_register;

Rule: Synchronous process is sensitive only to reset and clock.

Rule: Clock event is always to the rising edge.

VHDL Coding Rules, page 31
Safe coding: Asynchronous process I

• An asynchronous process must have all input signals in the

sensitivity list
– If this is not so the process will not simulate correctly.
• Never code combinational feedback loops.

VHDL Coding Rules, page 32

Safe coding: Asynchronous process II

• An example of an asynchronous process:

pattern_regognition : PROCESS (pattern_0, pattern_1)
BEGIN
IF (pattern_0 = "01010101") THEN
match_0 <= '1';
IF (pattern_1 = "10101010") THEN
match_both <= '1';
ELSE
match_both <= '0';
END IF;
ELSE
match_0 <= '0';
match_both <= '0';
END IF;
END PROCESS pattern_regognition;

Rule: Include all process input signals in the sensitivity list.

VHDL Coding Rules, page 33
Safe coding: Concurrent statement

• Concurrent statement is a simplified version of an

asynchronous process.
• For example a multiplexer can be coded simply as:

data_output <= data_input_0

WHEN (sel = '0')
ELSE data_in_1;

• And an adder-subtractor as:

result <= a + b
WHEN (addsub = '0')
ELSE a - b;

• It is not good practise to overlap many WHEN/ELSE statements.

VHDL Coding Rules, page 34

Safe Coding: State Machine

• State machine coding:

– Separate combinational and sequential logic to two different
process
– Use ENUM_ENCODING to define state coding
– State as enumerated type sel=‘0’

– Example:
state1
output=“01”
sel=‘1’ sel=‘1’

state3 state2
sel=‘0’ sel=‘0’
output=“11” output=“10”

sel=‘1’

VHDL Coding Rules, page 35

 Safe Coding: State Machine

• State machine example: next_state <= state2;

END IF;
TYPE state_type IS (state1, state2, state3);
WHEN state3 =>
ATTRIBUTE ENUM_ENCODING : STRING;
output <= “11”;
-- one hot encoding
IF (sel = ‘1’) THEN
ATTRIBUTE ENUM_ENCODING OF state_type : TYPE IS "001 010 100";
next_state <= state1;
SIGNAL current_state : state_type;
ELSE
SIGNAL next_state : state_type;
next_state <= state3;
BEGIN
END IF;
-- process to hold combinational logic
WHEN OTHERS =>
combinational:PROCESS (current_state, sel)
output <= “00”;
BEGIN
next_state <= state1;
CASE current_state IS
END CASE;
WHEN state1 =>
END PROCESS combinational;
output <= “01”;
-- process to hold synchronous elements
IF (sel = ‘1’) THEN
sequential:PROCESS (rst_n, clk)
next_state <= state2;
BEGIN
ELSE
IF (rst_n = ‘0’) THEN
next_state <= state1;
current_state <= state1;
END IF;
ELSIF (clk’EVENT AND clk = ‘1’) THEN
WHEN state2 =>
current_state <= next_state;
output <= “10”;
END IF;
IF (sel = ‘1’) THEN
END PROCESS sequential;
next_state <= state3;
END;
ELSE

VHDL Coding Rules, page 36

Safe coding: Variables I

• Variables can make VHDL difficult to understand.

• Use variables only when there is clear benefit from it.
• Use variables only for storing intermediate values.
• Never imply registers with variables.
• Variables speed up the simulation, so they are very useful in
code which will not be synthesised.

VHDL Coding Rules, page 37

Safe coding: Variables II

• Example of a need for a variable:

probe_v := '0';
FOR i IN 0 TO 31 LOOP
probe_v := probe_v XOR data_in(i);
END LOOP;
probe_out <= probe_v;

Rule: Use variable only when there is real benefit from it.
VHDL Coding Rules, page 38
Safe coding: Miscellaneous

• Avoid subtypes.
• Use only STD_LOGIC signal states '0', '1' and 'Z'
– Never refer to state 'X' in VHDL code.
• Avoid instantiating library primitives
– If you do, keep them in a separate block.
– Consider Synopsys GTECH library components.
• Do not embed synthesis script in the VHDL code
– Difficult to maintain both the script and the code.

VHDL Coding Rules, page 39

Implying logic: General

• All logic should be contained within the leaf blocks of the design
(RTL architecture).
• Every block above a leaf cell up to the top level should contain
only component instantiations and wiring (STRUCTURAL
architecture).
• All timing exceptions should be contained within a block.
• Constant values should not be routed through hierarchy.
• Three state signals are not allowed inside the chip.

Guideline: Place logic in leaf cells.

VHDL Coding Rules, page 40
Implying logic: Registering outputs

• Output of a block should always come directly from a

REGISTER.
• Especially avoid so-called snake paths *.
• It may be good idea to register also block inputs, but
– Area increases.
– Power consumption increases.
– Latency increases.

* Note: Snake path is a combinational path going through many blocks of the design. Time
budgeting of snake paths is difficult.

Guideline: Register outputs.

VHDL Coding Rules, page 41
Implying logic: Loops

• Loops make efficient code

– Loops are easier to modify if the logic needs to be changed.
priority_encoder : PROCESS (input)
BEGIN
first <= 127;
FOR i IN 126 DOWNTO 0 LOOP
IF (input(i) = ’1’) THEN
first <= i;
END IF;
END LOOP;
END PROCESS priority_encoder;

• Sometimes a loop is not necessary in the first place

result(wordwidth_g-1 DOWNTO 0)
<= a(wordwidth_g-1 DOWNTO 0) AND
b(wordwidth_g DOWNTO 0);

VHDL Coding Rules, page 42

The End

VHDL Coding Rules, page 43