how_to_write_VHDL.txt

How to write VHDL coding style
==============================

Contents:
1) Introduction
2) Coding style
3) RTL development views
4) State machines
5) Clocked and combinatorial process
  a) RTL (Register Transfer Level)
  b) No latches
  c) Sensitivity list
  d) Limited use of variables
  e) Avoiding delta-delay problems with derived clocks
  f) Default only use positive edge triggered flip-flops
  g) Use reset to clear flip-flops only
  h) Clock domain crossing
  i) Register outputs
6) No-variables method
7) Gaisler two-process method 
8) Directory structure
9) Naming conventions
  a) Language key words
  b) Files, entities, architectures
  c) Library directory
  d) Constants and generics
  e) Variables
  f) Signals
  g) Types
  h) Processes, instances, generates
  i) Procedures, functions
  j) Packages
  k) Do not use other HDL reserved words
10) Coding conventions
  a) Default use descending bus order
  b) Default use named association for the generic map and port map
  c) Component instantiation
  d) Only use IEEE.std_logic_1164 and IEEE.numeric_std libraries
  e) Do not use the BLOCK statement
  g) Do not use CONFIGURATIONs
  h) Avoid embedded, tool-specific synthesis commands
  i) Use enumerate values for FSM states
11) File layout
  a) Copyright statement
  b) Purpose and description
  c) Put entity, architecture and configuration in same file
  d) Port order
  e) Declaration order
  f) Avoid mixing structural and RTL description code in the same architecture
  g) Comment
  h) Indent and alignment
  i) TABs and spaces - Do not use TABs
  j) Line length
  k) Use separate line for each statement
  l) Place each declaration on a separate line
12) Standard packages
13) Use of records
14) Use of two-dimensional arrays
15) Use of constants, generics and packages
16) Functions
17) Procedures
18) Test benches
  a) Verifying a DUT
  b) Test bench interface packages and components
  c) Multi-level test bench
  d) Self checking and self stopping
  e) Python test case using MM interface
  f) Coverage for regressiontest
19) DP streaming component development example
20) Simulation and synthesis debugging


1) Introduction

The basic idea of the VHDL coding style discussed here is that the structure
and naming of the code closely reflects the task that the code performs. In
summary the key aspects of this VHDL coding style are:

 * a structured hierarchy of the design
 * a structured way of naming all elements in the VHDL
 
The VHDL coding style may be used as a cosmetic step during or at the end of a
VHDL implementation. However the coding style can also be used as an integral
part of the development. Not only after the coding has been done but rigth from
the start and during all phases of the coding. In this way the coding style
becomes more than just a matter of cosmetics, in fact it then is a valuable
tool for developing robust and correct code.

Something about VHDL and digital design:

VHDL has its flaws (e.g. why is the INTEGER type resticted to <= 32 bit), but
is a good language for describing and implementing digital design.
Writing VHDL may look like programming software like C but it is fundamentally
different. In particularly writing VHDL differs from sequential programming
because digital designs are:

- massively parallel, e.g. each register, RAM or LUT (lookup table) acts as a
  parallel entity
- restricted by low level details like e.g. multiple clock domains and hardware
  specific resources

Some more aspects of digital design are:

- digital design often needs to cover the entire range from high level
  application function to low level physical aspects of the targeted hardware.
  Modular design and using hierachy help to separate these two levels. However
  the targeted hardware often changes with every new project, this means that
  digital design will inherently always involve also low level implementation
  develoments.
- The VHDL language offers many language constructs, but not all of these are 
  possible or wise to use for describing hardware.

Using a proper coding style helps to cope with these aspects of VHDL and digital
design and to make good code that will work on the hardware (in time and with
quality). Note that many of the coding style aspects discussed here in fact
apply to any programming  language (C, MATLAB, Python, TCL, BASH, Erlang, ...).



2) Coding style
  
The subsequent sections describe the coding style. Following a coding style is
not a burden or something to do afterwards as a code clean up session. Instead
following a coding style is an important development method at any stage of the
code writing development. Proper code without loose ends is important because
in combination with some testing this ensures that the code is correct. Dirty
code may pass the testing as well, but does not give the same level of
confidence that the code is correct. It is often impossible to cover all
conditions in the tests. Therefore proper coding is an integral part of robust
development. At the end of the development you have a polished code that
performs what it needs to do and a test bench to confirm that it is correct.
E.g. similar as a piece of music the code and the comment should have no false
notes. The code should flow like a melody and all parts should be in harmony.
 
At intermediate steps in the coding of the sources should be committed in SVN. 
Such a step e.g. can be a cosmetic improvement, a correction or an added
feature. The SVN commits can be seen as hooks that a mountaineer uses to secure
the climb. The hooks (SVN commits) help to ensure that we develop in atomic
steps. The hooks are useful for doing a 'diff' to highligth the changes or to
see the progress by reading the commit comments. Typically we seldomly need to
fall back to the hooks (i.e. return to a previous state in SVN). The hooks (SVN
commits) help to stay on the rigth track and at any time during the development
they show a tractable trace towards the end result. By developing in small
steps, each with clear added value, we break down a complex problem into an
easier problem.

Obsolete or redundant code like declarations, assignments, comments, etc have
to be removed already during development, because they obscure the true working
of the code. It is like with the construction of a building. During the work
the place needs to remain tidy and once it is finished the scaffoldings are not
left behind.

Some important aspects of the coding style are:

- Use symmetry and similarity, e.g. similar functions should look similar in
  code. This not only applies within a file, but also between files and in
  fact throughout the entire development directory.
- Use consistent names for related designs, entities, functions, etc. E.g.
  there are components common_round, common_resize, common_requantize. Then
  it would be 'wrong' to call a new related component common_clipper instead
  of common_clip.
- The code complexity must be equal or less than complexity of the problem.
  Make use of the redundancy and don't care situations in the problem to
  simplify the code.
- The comment must have added value and be phrased correctly.
- Avoid redundant code, e.g.:
  . Move the same code in both the 'then' and the 'else' of an 'if' statement
    above the 'if'
  . Consider making a component of it or a function
- Use mininmal interfaces, i.e. structure the design such that the blocks have
  clear tasks to do without too much interdependencies.
- Use interface names that describe the output of a task
- Minimize the amount of control. Only gently touch the input so much as to get
  to the required output.  Too much control conditions are hard to cover in
  testing and harder to understand. A sign of too much control can be e.g.:
  . Any control at all (always consider whether you can do without)
  . A conditional statement with more than 2 levels
  . Avoid unneccessary restrictions, make use of redundancy and don't care
    situations
  . A power of 2 counter wraps automatically, no need to check for max
  . Do not force invalid data to a value, let it hold its current value
- The code should always look clear. If the code looks not in harmony or 'ugly'
  then this can be improved for sure. The cause can be e.g.:
  . The function interfaces have not been placed at the rigth place. 
  . The problem is not clearly understood yet.
  The solution is e.g.:
  . Determine what is the IO and what realy needs to be done and when.
  . Break the problem down into atomic steps that each reveal a clear action
    for solving the problem.
  . Find the resemblence in other problems that have already been solved,
    identify what is the difference or perhaps there is no real difference.
  . Reuse existing components.
  . Try to let the default behaviour be the wanted behaviour.
- Perhaps the only excuse for an 'ugly' solution is when the input is presented
  in an 'ugly' way and you can not change this (e.g. because it comes from an
  existing device). However this then may be handled by first defining a 
  component that 'beautifies' the input, so that the rest of the problem 
  solution can again be implemented in harmoneous VHDL.
- Use names that are accurate, i.e. not too specific and not to broad
- From input to output the code names and functionality should gradualy change.
  E.g. similar as Escher's metamorphosis transformation drawings, e.g. with
  birds on one side that gradually change into fishes on the other side. Note
  e.g. the symmetry and similarity of the internal streaming interface names
  from rx input via control to tx output in eth.vhd:
  
  SIGNAL rx_adapt_sosi        : t_dp_sosi;
  SIGNAL rx_crc_sosi          : t_dp_sosi;
  SIGNAL rx_hdr_sosi          : t_dp_sosi;
  SIGNAL rx_channel_sosi      : t_dp_sosi;
  SIGNAL demux_sosi_arr       : t_dp_sosi_arr(0 TO c_mux_nof_ports-1);
  SIGNAL eth_rx_sosi          : t_dp_sosi;
  SIGNAL rx_frame_*
  SIGNAL eth_tx_sosi          : t_dp_sosi;
  SIGNAL mux_sosi_arr         : t_dp_sosi_arr(0 TO c_mux_nof_ports-1);
  SIGNAL tx_mux_sosi          : t_dp_sosi;
  SIGNAL tx_hdr_sosi          : t_dp_sosi;
  
  
  
3) RTL development views

Basicly there are four views on RTL code:

a) as text
b) as schematic (drawing flipflops and combinatorial logic like 'and','or', mux,
   demux, +, * etc at RTL level or of components at structural level)
c) as a timing diagram (like the Modelsim wave window)
d) state machine drawing using state circles and arrows between them

The end result is a text file, but for the development it is often useful to
also make a schematic drawing or to draw a timing diagram to better understand
the functions and their dependencies (latencies) in time. A state machine
drawing is useful to ensure that the state machine is correct. Many engineers
only use the text view as development view. However the other views can be
quite helpful to understand and improve the text code.



4) State machines

There are two types of state machine: Mealy and Moore. The difference is that
for a Moore state machine the outputs only depend on the states, whereas for a
Mealy state machine the outputs also depend on the inputs. We typically only
use the Mealy state machines.
The state machine drawing is useful for a state machine. In the drawing each
state is represented by a circle and the arrows indicate the condition for a
state change and the effect of this change on the outputs. For each circle the
sum of the arrow conditions should be '1' (i.e. TRUE).
In the RTL code all outputs get a default value and a case statement lists
the conditions and effects on the outputs per state.
Note that in fact all RTL logic can be regarded as Mealy state machines, but
for e.g. a counter it is less useful to view it as a state machine.



5) Clocked and combinatorial process

a) RTL (Register Transfer Level)
The RTL logic functionality can be described in clocked processes (registers,
flip flops) and combinatorial (transfer) processes. The convention is to
clearly separate the clocked process from the combinatorial processes, whereby
the clocked process only lists the q <= nxt_q register assignments. The nxt_q
assignments is done in a separate combinatorial process.

  p_clk : PROCESS(clk)
  BEGIN
    IF rising_edge(clk)
      q <= nxt_q;   -- q becomes its d input called nxt_q
    END IF;
  END PROCESS;

  nxt_q <= f(...);  -- concurrent statement
  
or:
  
  p_comb : PROCESS(sensitivity list)   -- process block statement
  BEGIN
    nxt_q <= f(sensitivity list)
  END PROCESS;
  
Note that this scheme describes any logic function that we need to implement.
Logic is always a clocked part and a combinatorial part (i.e. a Mealy machine).
The path delay through the combinatorial part is what determines the maximum
clock frequency. By adding more pipelining register stages the combinatorial
paths can be shortened to increase the maximum clock frequency.

Important clocking rules:
- Do not use differente clock edges. Within a clock domain one should only use
  the rising_edge(clk).
- Do not use data signals as clock. Two exceptions are at a single central 
  point or at the output pin of the FPGA. The data that is used for the clock
  must come directly from a flipflop, because for a combinatorial output
  different internal processing delays can cause glitches during the set up.
- Do not gate clocks, because within an FPGA this creates a new clock and the
  number of clock trees is limited. In an ASIC clock gating can be used to
  save power, but it then needs to be done centrally and in a controlled way 
  to ensure that no glitches will occur due to the gating logic.
- Use resets that are synchronized to their corresponding clock domain.

b) No latches
The logic must have no latches, we only use flipflops and registers. Therefore
every conditional statement (IF, CASE) should address all conditions. In VHDL
it is often possible to first assign a default value to the nxt_* signals and
then in the rest of the process assign the conditional value(s). E.g.:

  nxt_q <= q;
  IF cnt=b THEN
    nxt_q <= 0;
  END IF;

The Quartus synthesis report warns for inferred latches. These unintentional
latches must be corrected in the RTL code.
  
c) Sensitivity list
Make sure that all signals that are read in a combinatorial process are also in
the sensitivity list, because that is how the synthesis and hardware will
interpret it. The signals that are read in a combinational process are:
- Signals that are part of a condition e.g. '>, <, =' in e.g. an IF statement.
  The signal can be on either side of the condition.
- Signals that are assigned to another signal or variable, i.e. at the
  right of <= or :=.
If a signal is used but not in the sensitivity list of the combinatorial
process then the results can be different in simulation, because then the
process will not be evaluated if that input changes.
For a sequential process only asynchronous signals (rst) and the clock (clk)
are in the sensitivity list.
The Quartus synthesis report warns for incomplete sensitivity lists. These
warnings must be corrected in the RTL code.

d) Limited use of variables
Variables are preferrably not used, because they are not visible in the
ModelSim Wave window, which makes it difficult to debug them with respect to
signals.

To describe digital logic variables are not needed, using only signals is
sufficient. In fact using variables to describe digital logic is somewhat a mis
conception, because variables are assigned sequentially in a process, whereas
implemented logic is inherently parallel. For example a filter, a counter, but
also every LUT or flipflop: in hardware they all run in parallel. Signals get
their value at the end of a process, this reflects the parallel behaviour of
logic. Hence all logic can be described using only signals. The sequential
behaviour of variable resembles ordinary programming code that runs on a
processor, hence it seems that variables are added to VHDL to pamper software
designers and make VHDL look like e.g. C. In VHDL test benches variable can be
used, e.g. to access a file.

e) Avoiding delta-delay problems with derived clocks
Assigning a clock to another signal does cause a delta delay. If data is passed
on using these two (identical) clocks, then the simulation can mismatch the 
reality (synthesis). Because the data is then be captured one clock cycle later
in simulation due to the delta-delay between the rising_edge() of the two
clocks. To avoid these delta-delay problems all data processing logic
should only use the derived clock. For reset signals it is less critical,
because typically a design does and should not rely on reset release being one
cycle later or not.
Passing a clock through hierarchy does not cause delta-delays. However, for a
clock that is created inside a component and then used both internally and
externally the clock needs to be assigned to the output port via a auxiliary
signal like: clk_out <= i_clk_out, because an output port signal cannot be read
in VHDL. To avoid the delta-delay problem this implies that the derived clock
needs to be output as clk_out and then back input as clk_in. Both internally and
externally the clk_in should then be used to clock the data.

f) Default only use positive edge triggered flip-flops

g) Use reset to clear flip-flops only
Asynchronous and synchronous resets should only place flip-flops in a known
start-up state. Resets should not be used for other purposes. It should be
clear where a reset is generated and to which clock domain it belongs.

h) Clock domain crossing
Use the dedicated components from common library to cross clock domains:

- common_areset.vhd             -- for a reset
- common_async.vhd              -- for a level signal
- common_spulse.vhd             -- for a pulse signal
- common_reg_cross_domain.vhd   -- for MM data vector
- common_fifo_dc.vhd            -- for streaming data vector

i) Register outputs
Default register the outputs of a component. Typically there is then no need
to register the inputs. The output registering between components eases timing
closure within the components. Exceptions are eg. the ready output for
streaming flow control which typically needs to be combinatorial output to
maintain the ready latency.



6) No-variables method

The RTL scheme desribed at point 5) is referred to as the 'no-variables method'.
The no-variables method was used in LOFAR and is also used in the UniBoard
firmware. The no-variable method separates the clocked process that defines the
registers from the combinatorial process that defines the function. There is
only one clocked process per clock domain but there can be multiple
combinatorial proceses. The processes do not use of variables. 


7) Gaisler two-process method

The Gaisler two-process method can be regarded as a clever method that helps
to bridge the gap between a software approach (more sequential thinking) and
a hardware approach (more parallel thinking) towards developing logic. In the
Gaisler two-process method there is:

- one clocked process and
- one combinatorial process.

All local registers are grouped in a local record type such that the clocked
process becomes quite simple and uniform and whereby the functional operation
is in the combinatorial process:

  TYPE t_reg IS RECORD
    -- local registers (flip flops)
  END RECORD;
  
  CONSTANT c_reg_rst  : t_reg := (<reset values for the t_reg fields>);

  SIGNAL r, nxt_r : t_reg;
  
  -- calling the local registers 'r' also fits the Gaisler style
  -- or instead to fit the Gaisler style call 't_reg' --> 'reg_type'
  -- or instead to fit the Gaisler style call 'nxt_r' --> 'rin'
  
  -- Map t_reg outputs to entity outputs
  <entity outputs> <= r outputs;
  
  -- p_reg
  r <= nxt_r WHEN rising_edge(clk);

  p_comb : PROCESS(rst, r, <other inputs>)
    VARIABLE v : t_reg;
  BEGIN
    -- Default
    v := r;
    
    -- Functionality
    <Here the logical operations on r and the other inputs to determine
     nxt_r and the combinatorial outputs are defined.>
    
    -- Reset and nxt_register
    IF rst='1' THEN
      v := c_reg_rst;
    END IF;

    nxt_r <= v;  
  END PROCESS;
  
Note that p_reg is similar as with the RTL clocked process style defined in 5a,
but the big advantage of the Gaisler style is that all local registers get
nicely grouped into one record.
  
The single combinatorial process uses next register value variable v : t_reg
and some more auxiliary variables if necessary. The rst is applied at the end
so that it acts like a synchronous reset and then v is assigned to nxt_r. The 
variable v gets initialized with the current register value r and the rest of
the process code decribes and defines the logical operation on r and the
other process inputs to get the nxt_r. The nxt_r is only assigned to, so
therefore it is not in the sensitivity list.

The description in dp_packet_merge.vhd explains how to use v and r in p_comb.

The default/preferred coding style rule is that v is only assigned, so not
read. This means that v does not occur in an if condition and also not right
of :=. If needs to be read then first use another variable to determine this
intermediate combinatorial result based on the inputs and r, and then assign
this variable to v. In this way the use of v is focused on defining the next
input for r. Using nxt_r or v seems similar in this way, because in both
schemes they are only assigned to. A difference is that the scheme with nxt_r
uses an asynchronous rst, whereas the Gaisler scheme with v uses a synchronous
rst.

The default/preferred coding style is to treat each v field implementation for
r in a separate section in the p_comb process. The alternative would be to 
have a separate section per input and per r field, but that seems less clean
in general.

The reset is applied in p_comb so it is used as a synchronous reset, for most
functionality this is appropriate. Still the reset could instead be applied
within p_reg to have an asynchronous reset. The advantage of an asynchronous
reset is that it gets applied even without a clock. The advantage of a
synchronous reset is that its timing with respect to the clock gets taken care
of automatically like any other register data input.

In 5d it is argued to minimize the use of variables. However within p_comb for
the Gaisler method using variables is appropriate. In fact the variables are
more used as auxiliary or temporary variables, therefore they can have
insignificant names while the signals represent the function of the process and
have the significant functional names. Using variables as temporary variables
fits a sequential way of thinking and fits the VHDL definition of variables in
a VHDL process, and it does not curse with the parallel nature of digital
logic. Therefore the general rule for using variables seems to describe the
true functionality in signals and use variables only as auxiliary variables to
hold temporary results.

A variable in a process can also be used to hold a dynamic semi-constant value
that gets determined at process entry, but that does not get modified further
on, e.g. as with v_siso_arr_* in dp_bsn_align.

A mixed style is also possible whereby the t_reg record is used to have the 
clarity and ease of the single assignment clocked process, but whereby the
logical functionality is still defined in one ore more combinatorial processes
and or concurrent statements to reflect the parallel behaviour of digital 
logic.



8) Directory structure

It is proper to clearly separate the VHDL that describes logic that can run on
hardware from the VHDL that describes the test bench.

<module name>/build/sim/modelsim/
             /build/synth/quartus/
             /data/
             /src/vhdl
             /tb/vhdl



9) Naming conventions

All names and text must be in English.

All names must reflect the use at the correct level. E.g. a general purpose 
counter can be called common_cnt, while its instance is called u_rx_cnt. It
would be wrong to call the counter entity rx_cnt if it is in fact a general
purpose counter.

Names like tmp, help, cnt2 are bad. In general if you can not give an object
(e.g. a signal, an entity) a proper name then that is a sign that you do not
(yet) have a clear view on what your design should do and how it should work.
Hence spending time on defining accurate names is an integral part of proper
design.

The structure of a design consists of components and processes. A general 
naming convention is to give interfaces within the structure a name and use 
this interface name as pre, middle or post fix in the corresponding signal
names. Note that in this way the naming directly relates to creating a proper 
design structure.


a) Language key words
The convention for manually written code is to use capitals for all VHDL key
words and small characters for entities, signals etc. Underscores are used to
seperate parts of a name, so eg. my_signal_name, proc_name.


b) Files, entities, architectures
Hierarchy within a module is represented via the VHDL file naming. Typically
the entity and architecture are kept in the same file.

 - The file name is always equal to the entity name, with the suffix .vhd.
 - If a specific architecture is used, architecture filename ends with _a.vhd.
 - General package filenames end with _pkg.vhd.
 - Component declaration package filenames end with _component_pkg.vhd.

For the VHDL architecture names we use the following
category names within /UniBoard/Firmware:

  - pkg      = VHDL package
  - str      = Structure architecture containing only components
  - rtl      = RTL architecture containing Register Transfer Level code (i.e.
               processes)
  - wrap     = Wrapper structure
  - stratix4 = Wrapper structure containing Stratix4 specific components
  - beh      = Architecture containing behavioral code (e.g. for a test bench
                 model of an I2C sensor, a flash, an ADC, etc)
  - empty    = Empty architecture
  - tb       = Test bench architecture
  
The two main architecture categories are 'rtl'and 'str'. Typically the top level
components consist of 'str' architectures and the lowest level components (the
'leaves') contain the 'rtl' architectures that actually define the function.
For external IP like from the MegaWizard a 'wrap' architecture hides these IP
architectures. In practise it can occur that RTL code needs to be combined with
instantitated components, so then the architecture name is a bit arbitrary.

Putting the entity and architecture into separate files only seems useful when
the architecture is FPGA vendor specific and would cause problems if e.g. a
'stratix4' and a 'virtex6' architecture are both visible to the synthesis
tool. Keeping the package in a separate file e.g. st_pkg.vhd remains useful,
because it avoids unnecessary recompilations. The category name can then be
used in the VHDL architecture file name name by combining the entity name
with the architecture category as post fix, so:

  <entity       file name> = <entity name>.vhd
  <package      file name> = <package name>_pkg.vhd
                           = <package name>_component_pkg.vhd
  <architecture file name> = <entity name>_a_category.vhd
  
Instead of this file name post fixes also braces () as with (pkg) and with
(architecture category) have been used in the file name, but it appears that
'make' under Linux can not cope well with using braces in the file names.
Therefore do not use braces () in the file names.


c) Library directory
Within a library of that has several files all files should start with the
same prefix. That prefix corresponds to the library directory name and is 
typically also used for all items in a library_pkg.vhd file it that is used.

For example some module called ST could look like:

  /modules/st/sim/modelsim/st.mpf      -- modelsim project file
           st/src/vhdl/st.vhd          -- top ST entity with str architecture
                       st_pkg.vhd      -- file name postfix '_pkg'
                       st_ctrl.vhd
                       st_ctrl_tx.vhd
                       st_calc.vhd
                       st_calc_a_str.vhd  -- file name post fix '_a_' + 
                                          -- architecture name
           st/tb/vhdl/tb_st.vhd        -- test bench for st
                      tb_tb_st.vhd     -- test bench of multiple tb_st
                      tb_st_calc.vhd   -- test bench for st_calc
        
In this example the '_tx' functionality in st_ctrl_tx is specific to st_ctrl,
therefore it is not put in a more general seperate module. A general type
of IO like an I2C interface would be kept as a seperate module so that it
can be used easily within other modules.

This ST module may be used in different modules or designs, typically using
generics to adapt it to the design specific requirements (e.g. word width)


d) Constants and generics
All constant values must be identified by a name in order to easily search for
them. It is not allowed to used numbers directly in statements. Entity port
widths must be defined via generics, even if a range is fixed. This to clearly
distinghuis the meaning of the range value. For some port widths the generic
may even allow choosing another value dependent on the usage. Furthermore
constants and generics have to be clearly distinghuised from signals. Therefore
use prefixes:

. c_      constant
. k_      constant 
. g_      generic

For example:

  CONSTANT c_word_sz    : NATURAL := 4;
  CONSTANT c_byte_w     : NATURAL := 8;
  CONSTANT c_word_w     : NATURAL := c_byte_w*c_word_sz;

The k_ prefix is rarely used, but it can e.g. be used as a reference for the
actual constant:

  CONSTANT k_sel : STD_LOGIC_VECTOR(c_max_w-1 DOWNTO 0) := "000";                             -- c_max_w = 3
  CONSTANT c_sel : STD_LOGIC_VECTOR(c_actual_w-1 DOWNTO 0) := k_sel(c_actual_w-1 DOWNTO 0);   -- c_actual_w = 2 <= c_max

or e.g. as a local constant in a package that should not be used outside that
package.

e) Variables
Similar variables have to be distinghuised from signals. Therefore use pre fix:

. v_      variable
. v       next value for local register record in Gaisler two-process method


f) Signals
Signals do not have to have a prefix or a post fix to identify them as signals,
instead for signals a pre or post fix is better used to clarify its functional
meaning:

. _ack     acknowledge
. _adr     address
. _addr    address
. _address address
. _arr     array
. _avail   available
. _bi      bit index, or byte index
. buf      buffer, memory
. _clk     clock (used in a rising_edge process)
. clr      clear
. cnt      counter
. ctrl     control
. _cpx     complex
. _cplx    complex
. _complex complex
. _cur     current
. _d       delayed signal
. _dat     data
. _data    data
. _dec     decode
. _decode  decode
. _depth   depth, size
. _dis     disable
. _dly     delayed signal
. dp_      data path streaming interface signal
. _done    done
. _ely     early signal, equivalent to 'nxt_' and to the opposite of '_dly'
. _early   early signal
. _en      enable
. _enc     encode
. _encode  encode
. _eof     end of frame
. _eop     end of packet
. _err     error
. _evt     event
. _fevt    falling event
. ff       flipflop
. fifo     first in first out
. hdr      header
. i_       internal copy of an output signal
. in       input
. io       input/output
. _i       internal auxiliary signal, where signal 'x_i' closely relates to 'x'
. _im      imaginary
. _imag    imaginary
. _late    late signal
. _lat     latency
. _latency latency
. _len     length in e.g. bytes or data words
. mem      memory
. _max     maximum
. _min     minimum
. _miso    master in slave out
. _mosi    master out slave in
. mm_      memory mapped interface signal
. _n       active low
. _N       negative pin of a differential signal
. nat      natural
. nof_     number of
. next_    next functional value
. nxt_     next value of a register, e.g. q <= nxt_q
. ofs      offset
. offset   offset
. out      output
. _org     original
. _p       pipeline delay (or early)
. _pp      pipeline delay two clock cycles
. _ppp     pipeline delay three clock cycles
. _P       positive pin of a differential signal
. _phs     phase
. pulse    pulse
. prev_    previous signal value, equivalent to '_dly'
. r        local register record in Gaisler two-process method
. ram      memory
. rd       read
. _re      real
. _real    real
. read     read
. _rdy     ready
. _reg     registered signal
. _revt    rising event
. req      request
. rst      reset
. rsl      resolution
. rcv      receive
. rx       receive
. s_       state machine state enumerate name
. sel      select
. _siso    source in sink out
. _sosi    source out sink in
. sl       standard logic
. slv      standard logic vector
. _sof     start of frame
. _sop     start of packet
. st_      state machine state name
. st_      streaming interface signal
. _size    size, depth
. _sz      size in e.g. bytes
. _sync    synchronisation
. this_    this_ signal as related to some next_ signal
. tr       transmit/receive, transceiver
. tx       transmit
. _val     valid
. _vec     vector
. _wi      word index
. wr       write
. write    write
. _w       width in bits
. x        times, e.g. clk_2x
. xmt      transmit
. zdly     z^(-1) DSP sample period delay

For example:

  CONSTANT c_nof_mp          : NATURAL := 1;
  CONSTANT c_nof_rcu_per_mp  : NATURAL := 4;
  CONSTANT c_nof_rcu         : NATURAL := c_nof_mp * c_nof_rcu_per_mp;

  SIGNAL tbb_frame_hdr       : t_frame_hdr_arr;
  
Usage examples:

- A bus of _dat[], _val, _sync together indicates the data, whether it valid and
  the relation to some external time.
- A bus of _hdr, _dat, _val, _sof, _eof can indicate a packet with header and 
  data in a stream of words.
- At the rising clock edge the q output of a flipflop or register becomes the d
  input, therefore the d input is called nxt_q. The 'nxt_' is used as prefix for
  all register d inputs and the clocked processing only contains q <= nxt_q
  like assignments.

  
g) Types
. t_       type
. t_c_     a type for constant values, typically a record
. t_e_     an enumerate type
. t_*_enum an enumerate type
. t_reg    local registers record for Gaisler two-process method (reg_type)
. _arr     array with indexing (I)
. _2arr    two-dimensional array defined as array of arrays with indexing (I)(J), index range J is fixed by the type
. _3arr    three-dimensional array defined as array of arrays of arrays with indexing (I)(J)(K), index ranges J and K are fixed by the type
. _mat     matrix, two-dimensional array with indexing (I,J)
. _matrix  matrix, two-dimensional array with indexing (I,J)
. _cub     cube, three-dimensional array with indexing (I,J,K)
. _cube    cube, three-dimensional array with indexing (I,J,K)
. _rec     record

For example:

  TYPE t_frame_hdr_arr IS ARRAY (0 TO c_nof_rcu-1) OF t_frame_hdr_rec;
  TYPE t_sl_matrix IS ARRAY(INTEGER RANGE<>, INTEGER RANGE <>) OF STD_LOGIC;
  TYPE t_data_mat IS ARRAY (0 TO c_nof_tlen-1, 0 TO c_nof_input-1) OF STD_LOGIC_VECTOR(g_data_w-1 DOWNTO 0);
 

h) Processes, instances, generates
. p_      process name
. u_      component instance name
. gen_    generate name
. no_     'no generate' name

The clocked process that creates the registers can typically be called p_clk
or p_reg. The combinatoral processes get the name of their main output signal
or a name that reflects the task of that process.

An component instance typically gets the component name preceded by 'u_' as
instance name, or an instance name that reflects the task of the component or
the main output of the component.

Generate example:

  CONSTANT c_debug_no_cep : NATURAL := sel_sim_synth(g_sim, 0, 0);
  no_cep : IF c_debug_no_cep /= 0 GENERATE
    -- default signal assigments
  END GENERATE;
  gen_cep : IF c_debug_no_cep = 0 GENERATE
    -- instantiate module cep
  END GENERATE;

  
i) Procedures, functions

Procedures and functions may have a pre or post fix. They may also use capitals
to separate parts of their name. Less common functions and procedure should
have these prefixes in addition to their package prefix:

. func_<package_prefix>_...   function prefix
. proc_<package_prefix>_...   procedure prefix

or

. <package_prefix>_func_...   function prefix
. <package_prefix>_proc_...   procedure prefix


j) Packages

All declarations in a package must have a package_prefix. This package_prefix
must be relatively short and sufficient to give a clue one where the item
is defined. Package prefix examples:

- common_pkg       -> no prefix, this is an exception, because this package is
                      so common
- common_mem_pkg   -> '_mem_'
- dp_stream_pkg    -> '_dp_'
- diag_pkg         -> '_diag_'
- tr_nonbonded_pkg -> '_trnb_'
- ddr3_pkg         -> '_ddr3_'


k) Do not use other HDL reserved words
Avoid using reserved words from Verilog in VHDL and vice versa. Also avoid
using then eg. as record fieldname.



10) Coding conventions

a) Default use descending bus order

Descending (DOWNTO) bus order must be used whenever possible in the declaration
of arrays. Ascending (TO) bus order can be used for signals for which the
ascending number may have a specific significance (stages of a processing,
filter tap indexes, etc.).

b) Default use named association for the generic map and port map
Avoid instantiating components using positional association for generic or
ports. Using named associations avoids hard to detect errors and improves
the readability. An exception can be a component instance in a wrapper, like
the technology independent IP wrappers in RadioHDL.

c) Component instantiation
Default use entity instantiation to instantiate a component. This avoids the
need for component declarations (either locally or in a component package).

For technology independent code component instantiation is used to support
multiple IP components from different vendors or FPGA families without having
to compile this IP, because only the plain VHDL component declaration needs 
to be known.

d) Only use IEEE.std_logic_1164 and IEEE.numeric_std libraries
Do not use deprecated numeric libraries:
- Do not use bit or bit-vector. Use only STD_LOGIC and STD_LOGIC_VECTOR for
  bits and bit vectors.
- Do not use older (and unofficial) std_logic_unsigned and std_logic_signed.
- Do not used std_logic_arith.

Note that the same type (e.g. SIGNED) from different packages are actually
different and not interoperable. Mixing different types cause compatibility
issues.

e) Do not use the BLOCK statement
Because they are akward and not necessary.

g) Do not use CONFIGURATIONs
Because they are akward and not necessary.

h) Avoid embedded, tool-specific synthesis commands
Synthesis directives are best placed into constrain files. Generalized
tool-independent directives for synthesis commands are emerging. Use them
sparely and check they are supported in at least the major synthesis tools
and FPGA families.

i) Use enumerate values for FSM states
Use enumerate values for Finite State Machine (FSM) states and defined them
with a 's_' prefix. Do not hard-code FSM State Vector values (VHDL), so do
not code them explicitly.



11) File layout

a) Copyright statement

The file should start with a copyright statement that includes the date of 
creation and the author(s) and the affiliation. For example for Astron:

-------------------------------------------------------------------------------
--
-- Copyright (C) 2011
-- ASTRON (Netherlands Institute for Radio Astronomy) <http://www.astron.nl/>
-- P.O.Box 2, 7990 AA Dwingeloo, The Netherlands
--
-- This program is free software: you can redistribute it and/or modify
-- it under the terms of the GNU General Public License as published by
-- the Free Software Foundation, either version 3 of the License, or
-- (at your option) any later version.
--
-- This program is distributed in the hope that it will be useful,
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-- GNU General Public License for more details.
--
-- You should have received a copy of the GNU General Public License
-- along with this program.  If not, see <http://www.gnu.org/licenses/>.
--
-------------------------------------------------------------------------------

b) Purpose and description
Next the file should contain a 'purpose' that summarizes the purpose of the
component in one or at most two sentences. The 'description' then provides a
more detailed description of the function of the component. Optionally there
can also be a 'remarks' section that lists some particularities of the
component. For test benchches there also should be a 'usage' section that
shows how to run the testbench in simulation and that briefly describes the
expected result.

-- Purpose: 
-- Description:
-- Remarks:
-- . 
-- . 
-- Usage:        -- for test benches
-- > as 10
-- > run -all
-- The tb is self stopping and self checking


c) Put entity, architecture and configuration in same file
Use a single file for completely describe a module. Possible exception if
completely different architectures must be used e.g. for different logic
families. Limit this situation to a few low level IP modules.

Default there is only one entity and architecture in the file. Exception can
be:
- Auxiliary entities that are instantiated only in this file. The top level
  entity corresponds to the file name and needs to appear last in the file
  due to the compile order. Eg. dp_repack_data.vhd which uses local entities 
  dp_repack_in and dp_repack_out.
- Multiple architectures that to show different implementation schemes. The
  last architecture is the default. Eg. uth_rx.vhd and uth_tx.vhd.

d) Port order
Ports are listed in logic groups, with clock and reset first. Typically first
list the streaming inputs and then the streaming outputs. The MM control ports
are also grouped. In case of multiple clock domains the clock may be listed