VHDL Coding Rules

VHDL Coding Rules, page 1

VHDL Coding RulesTampere University of Technology

Institute of Digital and Computer Systems


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 )BEGINif(XR =’1’ )THEN DATAO<= "1010";end if;if(CK’event) THEN if CK = ‘1’ THENfor ARGH in 0to 3 Loop DATAO(ARGH) <=datai(ARGH);end Loop;end if;end process;


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.

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

Rule: A VHDL file and the entity it contains have the same name.

File content File nameOne entity, one arch entityname.vhdOne entity entityname_ent.vhdOne architecture entityname_archname_arch.vhdMore than one architecture entityname_arch.vhdOne configuration entityname_cfgname_cfg.vhdMore than one configuration entityname_cfg.vhdPackage entityname_pkg.vhdTest bench entityname_tb.vhd

* 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 offand

-- translate on


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.


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.


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;


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 ISPORT (

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;


Code appearance: Aligning II

• Align colons inside one signal declaration group:

-- control signalsSIGNAL 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 signalsSIGNAL 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);


Code appearance: Aligning III

• Align the "=>" in port maps:

i_pokerhand : pokerhandPORT 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.


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.


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') THENparity <= '0';

ELSIF (clk‘EVENT and clk = '1') THENparity <= data_input(3) XOR data_input(2)

XOR data_input(1) XOR data_input(0);END IF;

END PROCESS parity_calculation;


Commenting III

• One-liners are used in other cases:

parity_calculation : PROCESS (rst_n, clk)BEGINIF (rst_n = '0') THEN

be <= (OTHERS => '0');ELSIF (clk‘EVENT and clk = '1') THEN

-- write lower 16-bit wordIF (state = "011") THEN -- alternative place

be <= "0011";-- write higher 16-bit wordELSIF (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.


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.


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.


Naming: Architecture

• Architecture name should be one of following:

Rule: Use only conventional architecture names.

BEHAVIORAL Implies physical logic, does not compile with RTL toolsRTL Implies physical logic, compiles with RTL toolsSTRUCTURAL Implies physical connections, but not any logicGATE Gate level netlistSIMULATION Simulation modelTESTBENCH Test bench


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

Combinatory signal signalname_c

Variable variablename_v

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

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


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.


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 : datamuxPORT 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.


Naming: Instantiations

• Component instance name is formed from the component name by attaching the prefix “i_” and identifier as a postfix:

i_componentname_identifier : componentnamePORT 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.


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 GENERATEi_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.


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.


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.


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


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.


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)


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.


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.


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.


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.


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 signalyourself

– 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.


Safe coding: Synchronous process II

• An example of a synchronous process:

data_register : PROCESS (rst_n, clk)BEGIN

IF (rst_n = '0') THENdata_out <= (OTHERS => '0');

ELSIF (clk‘EVENT AND clk = '1') THENdata_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.


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.


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.


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_0WHEN (sel = '0')ELSE data_in_1;

• And an adder-subtractor as:

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

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


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:

state1output=“01”



sel=‘1’

sel=‘1’

sel=‘1’

sel=‘0’

sel=‘0’sel=‘0’


Safe Coding: State Machine

• State machine example: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 : state_type;

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


END IF;

WHEN state2 =>

output <= “10”;



ELSE


END IF;

WHEN state3 =>

output <= “11”;



ELSE


END IF;

WHEN OTHERS =>

output <= “00”;


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;


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.


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.


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.


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 containonly 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.


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.

Guideline: Register outputs.

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


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’) THENfirst <= i;

END IF;END LOOP;

END PROCESS priority_encoder;

• Sometimes a loop is not necessary in the first placeresult(wordwidth_g-1 DOWNTO 0)

<= a(wordwidth_g-1 DOWNTO 0) ANDb(wordwidth_g DOWNTO 0);


The End

Documents

VHDL Coding Rules