Dcs Vhdl Coding Rules Es v4 4

7/29/2019 Dcs Vhdl Coding Rules Es v4 4

1/54

Tampere University of Technology (TUT) - Jan 2009

VHDL Co d i n g Ru l e sTampere University of TechnologyDepartment of Computer Systems

Version 4.4 J an 2009


2/54

Tampere University of Technology (TUT) - Jan 2009#2/40

I n d e x

Purpose

Summary of rules and guidelines

Rules 11 topics

Guidelines 14 topics

Extra slides

z Few additions to rules and guidelines


3/54


Pu r p o s e o f VH DL Co d i n g R u l e s Prevent harmful or unpractical ways of

coding Introduce a common, clear appearance for

VHDL Increase readability for reviewing purposes Not to restrict creativity in any way

Bad example:A_37894 :process( xR, CK , dat ai , DATAO )

BEGIN

if( XR = 1 ) THEN DATAO


4/54


A b o u t Co d i n g Ru l e s This guide has

1. Rules

2. Guidelines

z Both are first listed shortly and

explained later in detail


5/54


1. Entity portsz Use only modes IN and OUT with

z names have suffixes _in or _out

z Only types STD_LOGIC and STD_LOGIC_VECTOR

z Use registered outputs

2. A VHDL file and the entity it contains have the

same namez One entity+architecture per file

3. Every entity has a testbench

4. Synchronous processz always sensitive only to reset and clock

z clock event is always to the rising edge

z all control registers must be initialized in reset

Ru l e s (1 ) Ru l e s (1 ) Ru l e s (1 )


6/54


Ru l e s (2 ) Ru l e s (2 ) Ru l e s (2 )

5. Combinatorial processs sensitivity list includesall signals that are read in the processz Complete if-clauses must be used. Signals are

assigned in every branch.6. Use signal naming conventions

7. Indexes of STD_LOGIC_VECTOR are definedas DOWNTO

8. Use named signal mapping in componentinstantiation, never ordered mapping

9. Avoid of magic numbers, use constants or

generics instead10. Use assertions

11. Write enough comments


7/54


Gu i d e l i n e s (1 ) Gu i d e l i n e s (1 ) Gu i d e l i n e s (1 )

1. Every VHDL file starts with a header2. Indent the code, keep lines shorter than 76 characters

3.Use descriptive names.4. Use conventional architecture names

5. Label every process and generate-clause6. Clock is named cl k and async. active-low reset r s t _n7. Intermediate signals define source and destination blocks

8. Instance is named accroding to entity name9. Use FOR GENERATE for repetitive instances

10. Guidelines for naming conventions

11. Prefer generics to package constants12. Avoid assigning bit vector literals. Use conversion functions13. Prefer arrays over multiple signals. Use loops.14. Avoid variables inside processes


8/54


Gu i d e l i n e s (2 ) Gu i d e l i n e s (2 ) Gu i d e l i n e s (2 )

Avoid mixing of different coding styles (register transfer level,structural, gate level)

Use correct spacing. Align colons and port maps

Declare signals in consistent groups


9/54


Ru l e s y o u c a n n o t r e f u s e


10/54


En t i t y p o r t sUse only modes I Nand OUT in the port

z Names have corresponding post-fixes

Use only signal types STD_LOGI C andSTD_LOGI C_VECTOR in the portsOutput of a block should always come directly

from a register

Use only port modes I Nand OUT.

Use only types STD_LOGI C and STD_LOGI C_VECTOR.

Use only port modes I Nand OUT.

Use only types STD_LOGI C and STD_LOGI C_VECTOR.

entityentity

harmful in most cases

harmful within chip (most cases)

comb

STD_LOGIC_VECTOR (n:0)n+1STD_LOGIC

INTEGER

goodgood

harmful


11/54


F i l e c o n t e n t s a n d n am in gOne VHDL file should contain one entity

and one architecture, file named as

ent i t yname. vhdPackage name should be

packagename_pkg. vhd

Test bench name should bet b_ent i t yname. vhd

A VHDL f ile and the entity it contains have the same name.A VHDL file and the entity it contains have the same name.


12/54


T e s t b e n c h

Each entity requires at least one testbenchz Design without a testbench is useless

Prefer self-checking testbenchesz Cannot assume that the verifier looks at the magic

spots in waveform

z (Occasionally, TB just generates few inputs to show theintended behavior in common case)

Informs whether the test was successful or not

There can be several test benches for testingdifferent aspects of the design

z Code coverage should be as high as possiblez Verify correct functionality with different generic values

Every entity needs a testbench.Every entity needs a testbench.


13/54


Se q u e n t i a l /s y n c h r o n o u s p r o c e s s Sensitivity list of a synchronous process has

always exactly two signalsz Clock, rising edge used, named cl kz Asynchronous reset, active low, named r s t _n

Signals that are assigned inside sync process, willbecome D-flip flops at synthesis

Never give initial value to signal at declarative part

z It is not supported by synthesis (but causes only awarning)

SI GNAL mai n_st at e_r : st at e_t ype : = "11110000" ;

Assign values for control registers during reset

z (Xilinx FPGAs may be exceptions to this rule)

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


14/54


Se q u e n t i a l /s y n c h r o n o u s p r o c e s s (2 ) Correct way of defining synchronous process:cmd_r egi st er : PROCESS ( r st _n, cl k)

BEGI N

I F ( r st _n = ' 0' ) THENcmd_r ' 0' ) ;

ELSI F ( cl k EVENT AND cl k = ' 1' ) THEN

cmd_r


15/54


Com b i n a t o r ia l /a s y n c h r o n o u s p ro c e s sAn asynchronous process must have all

inputsignals in the sensitivity listz

If not, simulation is not correctzTop-3 mistake in VHDL

z Input signals are on the right side ofassignment or in conditions (i f, f or )

z Automatic check: vcom check_synthesis

If-clauses must be completez Cover all cases, e.g. with el se branch

z All signals assigned in every branchz Otherwise, youll get latches (which are evil)

Include all input signals of combinatorial process in thesensitivity list.

Include all input signals of combinatorial process in the

sensitivity list.


16/54


Com b i n a t o r i a l /a s y n c h . p r o c e s s (2 ) An example of an asynchronous process:decode : PROCESS ( cmd_r , bi t _i n, enabl e_i n)BEGI N

I F ( cmd_r = mat ch_bi t s_c) THEN

mat ch_0


17/54


T h e s e nam in g c o n v e n t i o n s a r e m u s tGeneral register output si gnal name_r

Combinatorial signal si gnal name

Input port por t name_i n

Output port por t name_out

Constant const ant name_c

Generic gener i cname_gVariable var i abl ename_v

Use these naming conventions.Use these naming conventions.


18/54


S i g n a l t y p e sDirection of bits in STD_LOGI C_VECTOR

is always DOWNTO

Size of the vector should beparameterized

Usually the least significant bit is

numbered as zero (not one!):SI GNAL dat a_r : STD_LOGI C_VECTOR( dat awi dt h_g- 1DOWNTO 0) ;

Use package numeric_std forarithmetic operations

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


19/54


Nam e d s ig n a l m a p p i n g in i n s t a n t i a t i o n sAlways use named signal mapping, never

ordered mappingi _dat amux : dat amux

PORT MAP (

sel _i n => sel _ct r l _dat amux,

dat a_i n => dat a_ct r l _dat amux,

dat a_out => dat a_dat amux_al u) ;

This mapping works even if the declaration

order of ports in entity changes

Always use named signal mapping in component instantiations,never ordered mapping.

Always use named signal mapping in component instantiations,never ordered mapping.


20/54


A v o id m a g i c n um b e r s A v o id m a g i c n um b e r s

Magic number is an unnamed and/or ill-documented numerical constant

Especially, a magic number derived fromanother is catastrophicz Eg. for-loop iterates through 2 to 30 because signal is

32b wide. What if it is only 16 bits?

Use constants or generics insteadSTD_LOGI C_VECTOR ( dat a_wi dt h_g - 1 DOWNTO 0) - - gener i c

STD_LOGI C_VECTOR ( dat a_wi dt h_c - 1 DOWNTO 0) - - const ant

States of FSM are enumerations not bit vectors Note that this document occasionally uses magic numbers to keep

examples short

Use constants or generics instead of magic numbers.Use constants or generics instead of magic numbers.


21/54


U s e a s s e r t i o n s U s e a s s e r t i o n s

Easier to find error location

Checking always on, not just in testbench

Assertions are not regarded by synthesistools no extra logicasser t ( we_i n and r e_i n) =0r epor t Two enabl e si gnal s must not act i veat t he same t i me

sever i t y war ni ng;

If condition is not true during simulation,z the report text, time stamp, component where

it happened will be printedEnsure that your initial assumptions holdz e.g. data_width is multiple of 8 (bits)

Use assertions.Use assertions.


22/54


Com m e n t t h o r o u g h l yComment the intended function

z Especially the purpose of signals

z

Not the VHDL syntax or semanticszThink of yourself reading the code after a

decade.

A comment is indented like regular codez A comment is placed with the part of code to

be commented.

Be sure to update the comments if the

code changes.z Erroneous comment is more harmful than not

having a comment at all

Pay attention to commentsPay attention to comments


23/54


Gu i d e l i n e s


24/54


I n c l u d e f i l e h e a d e r Every VHDL file starts with standard header

Example- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- - Pr oj ect : project or course name

- - Aut hor : Aul i s Kaakko ( , st udent number )

- - Dat e : 2007- 30- 11 14: 05: 01

- - Fi l e : exampl e. vhd

- - Desi gn : Cour se exer ci se 1- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- - Descr i pt i on : Thi s uni t does f unct i on X so t hat

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- - $Log$

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Every VHDL f ile starts with a standard header.Every VHDL file starts with a standard header.


25/54


Ge n e r a l c o d e a p p e a r a n c e VHDL code must be indented

z Much easier to read

Indentation is fixed inside a projectz Comment lines are indented like regular code

In (X)Emacs VHDL mode, usez Ct r l - c Ct r l - b to beautify buffer

z Ct r l - c ct r l - a Ct r l - b to align bufferMaximum length of a line is 76 characters

z In VHDL language it is very easy to divide lines

z

The commented code line should still fit to the consolewindow

Use blank lines to make code more readable

Use indentation. Keep lines shorter than 76 characters.Use indentation. Keep l ines shorter than 76 characters.


26/54


N am in g i n g e n e r a l Descriptive, unambiguous names are very

important

Names are derived from English language

Use only charactersz alphabets A . . Z , a' . . z ' ,z numbers ' 0' . . ' 9' and underscore ' _ ' .z First letter must be an alphabet

Use enumeration for coding states in FSMz Do not use: s0, s1, a, b, state0, ...z Use: idle, wait_for_x, start_tx, read_mem, ...

Average length of a good name is 8 to 16characters

Use consistent and descriptive names.Use consistent and descriptive names.


27/54


N am in g t h e a r c h i t e c t u r eArchitecture name is one of following:

behavi or al

z Implies physical logic, cannot be compiled withRTL tools

r t l

z

Implies physical logic, compiled with RTL toolsstructural

z Implies physical connections, but not any logic

Use only conventional architecture names.Use only conventional architecture names.


28/54


L a b e l t h e p r o c e s s e sLabel every pr ocess

z e.g. def i ne_next _st at e, def i ne_out put

Makes easier to identify part of the codeimplying specific logic in synthesis

Label is written two times in the code:

z Before and after the processz e.g. define_next_state: process ...

Label every process.Label every process.


29/54


C l k a n d r e s e t s i g n a l s /i n p u t sActive low reset is r s t _n

z Asynchronous set should not be used

z A register should never have bothasynchronous set and reset

Clock signal cl k

z If there are more clocks the letters "cl k"appear in every one as a postfix

When a signal ascends through hierarchy,

its name should remain the same. This isespecially important for clock signals

Use names clk and rst_n.Use names clk and rst_n.


30/54


Nam in g in t e r m e d i a t e s i g n a l s

Signals from instance a to b are named:si gnal name_a_bz Needed in structural architectures

They NEVER have "i n" or "out " specifiersz output ofa is connected to input ofb

cannot decide which postfix to choose

Abbreviated component names are handy when

names are longer than a and bWith multiple targets use signalname_from_a

component acomponent a component bcomponent bdat a_a_b

dat a_out dat a_i n

port name signal name

Intermediate signals name includes src and and dst.Intermediate signals name includes src and and dst.


31/54


N am in g t h e i n s t a n t a n c e s Component instance name is formed from the

component name

Attach prefix i _ and identifier as a postfix:

i _component name_i d : componentnamePORT MAP

e.g. i _f i f o_out : entity work.fifo

PORT MAP

This helps to track down the actual entityz From simulation results

z From synthesis results

Exceptions possible with long entity namesz In this case, it might be best to shorten the entity

name

Instance is named after the component entity.Instance is named after the component entity.


32/54


U s i n g f o r -g e n e r a t e FOR GENERATE statement is used for repetitive

instantiations of the same component

Label generate statement

Exampleg_dat amux : FOR i I N 0 TO n_mux_c- 1 GENERATEi _dat amux : dat amux

PORT MAP (

sel _ i n => sel _ i n ( i ) ,

dat a_i n => dat a_r ( i ) ,dat a_out => dat a_mux_al u( i )

) ;

END GENERATE g_dat amux;

FOR GENERATE creates identifiers (running numbers)automatically to all instances

Use FOR GENERATE for repetitive instancesUse FOR GENERATE for repetit ive instances


33/54


Re c om m e n d e d n am in g Between components si gnal name_a_b

To multiple components si gnal name_f r om_a

The only clock input port cl k Low active reset input port r s t _n

Component instances i _component name_i d

Generate statements g_component name

Prefer these naming conventionsPrefer these naming conventions


34/54


Pr e f e r g e n e r i c s P r e f e r g e n e r i c s

Basically, generic parameter is a fundamental idea in VHDLthat enables design reuse, use it.

Avoid constants (in packages or architecture)

z ifdat a_wi dt h_c is defined is package, it is impossible tohave instances with different dat a_wi dt h_c values

E.g. This limits all adders in the system to 10 bits

z With generics, it is possible to have different adders

The component size should be changed with generics NOT

by modifying the code. When the VHDL code is reused, there should be no need to read

the code except the entity definition

If there are illegal combinations of generic values, useassertions to make sure that given generics are valid

However, having many generic parameters, complicatesverification

Prefer generics to package constantsPrefer generics to package constants


35/54


A v o i d b i t v e c t o r l i t e r a l s A v o i d b i t v e c t o r l i t e r a l s

Avoid bit vector literals

Use conversion functions

Bit vectors must be edited by hand ifvector width changesst at us_r


36/54


Pr e f e r a r r a y s a n d l o o p sUse arrays and loops instead of different

namesz Array size can be generic

z Names (e.g "si gnal _0, si gnal _1, . . . " )have to be modified by handz Naturally, loop limits must be known at

compile/synthesis timepr i or i t y_encoder : PROCESS ( i nput )BEGI N

f i r st


37/54


A v o i d v a r i a b l e s i n s i d e p r o c e s s e sVariables in processes usually make

VHDL difficult to understandz Valid inside procedures fo functions

Use variables only for storing intermediatevalues

Only used as short-hand notationt mp_v : = addr _r ( 3) ( 2) ;

dat a_r ( t mp_v)


38/54


Co n t r i b u t o r s C o n t r i b u t o r s

Version 4, Dec. 2007: E. Salminen, A. Rasmus,and A. Kulmalaz Earlier versions included also: M. Alho, K. Kuusilinna,

V. Lahtinen, H. Lampinen, J . Tomberg

See also VHDL FAQ:z http://www.vhdl.org/comp.lang.vhdl/FAQ1.html

Further reading:z M. Keating, P. Bricaud, Reuse methodology

manual: for system-on-a-chip designs, KluwerAcademic Publishers Norwell, MA, USA, 1998 /

2002, ISBN:0-7923-8175-0


39/54


T h e e n d


40/54


Ex t r a s l i d e s


41/54


I m p l y i n g l o g i c : Ge n e r a lAll functionality should be contained within

r t l architecture (leaf block)

Every block above a leaf block up to thetop level should contain only componentinstantiations and wiring (structuralarchitecture).

Constant values should not be routedthrough hierarchy

Three-state signals are not allowed inside

the chip If inverted clock is needed, introduce the

inverted clock signal yourselfz All clock and async. reset signals are generated in a

single, dedicated block


42/54


I m p l y i n g l o g i c : Ge n e r a l (2 ) Do not make self resetting blocks

All timing exceptions should be contained withina single block

Especially avoid so-called snake pathsz Snake path is a combinational path going through

many blocks of the design.

z Time budgeting of snake paths is very difficult

Sometimes it is useful to indicate bits that havebeen left off with the number of the LSBz LSB index is not 0

z For example an address bus with the two LSBs leftoff:

SI GNAL addr :STD_LOGI C_VECTOR( dat awi dt h_g- 1 DOWNTO 2) ;


43/54


Sa f e c o d i n g : M i s c e l l a n e o u sAvoid subtypes

Use only STD_LOGI C signal states ' 0' ,' 1' and ' Z'z Never refer to state ' X' in VHDL code

Do not embed synthesis script in theVHDL codez Difficult to maintain both the script and the

code

Avoid instantiating library primitives

z If you do, keep them in a separate blockz Consider Synopsys GTECH library

components


44/54


Va r i a b l e s a g a i nAvoid variables in synthesizable

codez

Variables speed up the simulationzBut safety is orders of magnitude more

important than simulation speed

Example need for a variablezXORing all bits of a vector:

pr obe_v : = ' 0' ;

FOR i I N 0 TO 31 LOOP

pr obe_v : = pr obe_v XOR dat a_i n( i ) ;END LOOP;

probe_out


45/54


O rd e r i n g o f e n t i t y s p o r t s

Ports of the entity should be grouped as:z Resets

z Clocks (preferably just one)

z Signals of group A

z Signals of group B

z Signals of group C

z One entity should have only one clock

If more than one clock is necessary,

minimize the number of blocks withmultiple clocksz Place synchronization into separate entity


46/54


O rd e r i n g : D e c l a r a t i o n s I Component and signal declarations are ordered

in groupsOne component and specific signals:

z Declaration of component Az Signals the instantiations of component A drive

z Declaration of component Bz Signals the instantiations of component B drive

z Declaration of component Cz Signals the instantiations of component C drivez

z All other signals (if any) Order of the component instantiations should be

the same than the order of the componentdeclarations


47/54


Co d e a p p e a r a n c e : A l i g n i n g I One statement per line One port declaration per line, own line also for end

parenthesis

Align the colons and port types in the entity port:ENTI TY t r ansmogr i f i er I SPORT (

r st _n : I N STD_LOGI C;cl k : I N STD_LOGI C;we_i n : I N STD_LOGI C;

cmd_0_i n : I N STD_LOGI C_VECTOR( 3- 1 DOWNTO 0) ;dat a_i n : I N STD_LOGI C_VECTOR( 5- 1 DOWNTO 0) ;val i d_out : OUT STD_LOGI C;r esul t _out : OUT STD_LOGI C_VECTOR( 6- 1 DOWNTO 0)

) ;END t r ansmogr i f i er ;

Note: avoid magic numbers in real code


48/54


Co d e a p p e a r a n c e : A l i g n i n g I I Align colons inside one signal declaration group:- - cont r ol si gnal s

SI GNAL sel ect : STD_LOGI C_VECTOR ( 2- 1 DOWNTO 0) ;

SI GNAL cmd_r : STD_LOGI C_VECTOR ( 32- 1 DOWNTO 0) ;

SI GNAL next _st at e : st at e_t ype;

- - addr ess and dat a si gnal s

SI GNAL rd_addr : STD_LOGI C_VECTOR ( 16- 1 DOWNTO 0) ;SI GNAL wr _addr : STD_LOGI C_VECTOR ( 16- 1 DOWNTO 0) ;

SI GNAL r d_dat a : STD_LOGI C_VECTOR ( 32- 1 DOWNTO 0) ;

SI GNAL wr _dat a : STD_LOGI C_VECTOR ( 32- 1 DOWNTO 0) ;


49/54


Co d e a p p e a r a n c e : A l i g n i n g I I IAlign the => in port maps:i _poker hand : poker hand

PORT MAP (

r st _n => r st _n,

cl k => cl k,car d_0_i n => car d ( i ) ,

car d_1_i n => car d ( i ) ,

car d_2_i n => car d ( i ) ,

car d_3_i n => car d ( i ) ,

car d_4_i n => car d ( i ) ,

hand_out => hand

) ;

Emacs: ct r l - c ct r l - a ct r l - b aligns thewhole buffer


50/54

Tampere University of Technology (TUT) - Jan 2009

Co d e a p p e a r a n c e : Sp a c i n gConditions are written inside parenthesis

There is a space outside parenthesis, but

not insideI F ( r st _n = ' 0' ) THEN

There is a space after a comma, but notbefore:di gi t al _phase_l ocked_l oop : PROCESS ( r st _n, cl k)

There is a space on both sides of=>, ,


51/54


Com m e n t i n g e x a m p le One-liners are used in most cases:set _byt e_enabl es : PROCESS ( r st _n, cl k)BEGI N

I F ( r st _n = ' 0' ) THENbe_r ' 0' ) ;

ELSI F ( cl k EVENT and cl k = ' 1' ) THEN

I F ( st at e_r = l o_par t _c) THEN- - wr i t e l ower 16- bi t wor dbe_r


52/54


Com m e n t i n g e x am p le (2 ) Large comment is used mostly before

processes:- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- - Par i t y bi t i s cal cul at ed f or t he DATA_I NPUT si gnal .- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

par i t y_cal cul at i on : PROCESS ( r st _n, cl k)

BEGI N

I F ( r st _n = ' 0' ) THEN

par i t y


53/54


N um e r i c p a c k a g e s (1 ) N um e r i c p a c k a g e s (1 )

numer i c_st d defines two new vector typesand operations for themz IEEE standard packagez SI GNEDvectors represent two's-complement integersz UNSI GNEDvectors represent unsigned-magnitude

integersz Functions and operators

Logical : and, or, not,...

Arithmetic : abs, +, -, *, ... Comparison : , /=, ... Shift : shift_left, rotate_left, sll,... Conversion : see next slide Misc : resize, std_match, ...

For more detail, see also:z http://www.vhdl.org/comp.lang.vhdl/FAQ1.html#4.8.1

N i k (2 )N i k (2 )


54/54

Tampere University of Technology (TUT) - Jan 2009#54/40 19.01.2005

N um e r i c p a c k a g e s (2 ) N um e r i c p a c k a g e s (2 )

Differences of packages

Source: http://dz.ee.ethz.ch/support/ic/vhdl/vhdlsources.en.html

(vis ited 02.11.2005)

Dcs Vhdl Coding Rules Es v4 4

Documents

Transcript of Dcs Vhdl Coding Rules Es v4 4