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 One entity, one arch One entity One architecture More than one architecture One configuration File name entityname.vhd entityname_ent.vhd entityname_archname_arch.vhd entityname_arch.vhd

entityname_cfgname_cfg.vhd More than one configuration entityname_cfg.vhd entityname_pkg.vhd Package entityname_tb.vhd Test bench

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. In VHDL language it is very easy to divide lines.

Maximum length of a line is 78 characters

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 SIGNAL write_address : STD_LOGIC_VECTOR(31 SIGNAL read_data : STD_LOGIC_VECTOR(31 SIGNAL write_data : STD_LOGIC_VECTOR(31 DOWNTO DOWNTO DOWNTO DOWNTO 0); 0); 0); 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. Comment the intended function not VHDL syntax or semantics.

Do not comment things that are otherwise clear.

• •

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. VHDL reserved words. Libraries.

All names not invented by you or your team are in upper case:
– –

• •

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 RTL STRUCTURAL GATE SIMULATION TESTBENCH Implies physical logic, does not compile with RTL tools Implies physical logic, compiles with RTL tools Implies physical connections, but not any logic Gate level netlist Simulation model 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 Delay register output Delay chain Synchronisation chain Toggle output Falling edge register output Level based control, enable Triggering control, pulse Inverted or active low signal Internal signal * Com binatory signal Variable signalname_r signalname_d signalname_d0, signalname_d1,….. signalname_s0, signalname_s1,….. signalname_t signalname_f signalname_e signalname_p signalname_n signalname_i signalname_c 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. In this case it might be best to shorten the entity name.

Exception is possible in case the entity name is very long

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. Before the process. After the process.

Label is written two times in the code:
– –

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 … Control inputs Data inputs Outputs

Signals inside a group should be further grouped as follows:
– – –

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 Example:
state1 sel=‘1’
output=“01”

sel=‘0’

sel=‘1’

sel=‘0’

state3
output=“11”

state2
output=“10”

sel=‘0’

sel=‘1’
VHDL Coding Rules, page 35

Safe Coding: State Machine

State machine example:

next_state <= state2; END IF; WHEN state3 => output <= “11”; IF (sel = ‘1’) THEN next_state <= state1; ELSE next_state <= state3; END IF; WHEN OTHERS => output <= “00”; next_state <= state1; END CASE; END PROCESS combinational; -- process to hold synchronous elements sequential:PROCESS (rst_n, clk) BEGIN IF (rst_n = ‘0’) THEN current_state <= state1; ELSIF (clk’EVENT AND clk = ‘1’) THEN current_state <= next_state; END IF; END PROCESS sequential; END;

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

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. If you do, keep them in a separate block.

Avoid instantiating library primitives
– –

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

Sign up to vote on this title
UsefulNot useful