Skip to content
Snippets Groups Projects
Commit 0021dd31 authored by Eric Kooistra's avatar Eric Kooistra
Browse files

Copied from https://svn.astron.nl/UniBoard_FP7/UniBoard/trunk/Firmware/doc/howto/

parent 75d2546d
Branches
No related tags found
1 merge request!100Removed text for XSub that is now written in Confluence Subband correlator...
Show whitespace changes
Inline Side-by-side
doc/how_to_write_VHDL.txt 0 → 100644
+ 1462
− 0
View file @ 0021dd31
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
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 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.
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
close to its group or central at the top.
e) Declaration order
In the declaration section of an architecture, if possible place declarations
in the following order:
• Local types
• Local constants
• Local functions, procedures
• Signals
The detailed declaration order should as much as possible follow the functional
flow from component input to output and from begin to end of the architecture.
f) Avoid mixing structural and RTL description code in the same architecture
In general a architecture contains only RTL code (ie. with process statements)
or it only instantiates other components to create structure. An exception
is eg. the use of some low level components from common library in an 'rtl'
architecture. Keeping only structural instantiations in a 'str' architecture
makes the functionality more clean and therefor more clear.
g) Comment
Typically the HDL code needs to be self explanatory, i.e. properly set up, so
there is no need for comment. The purpose of the module can be described in the
HDL source (e.g. above the entity) or in a seperate design document.
In some cases inline comment is needed though to help the reader. Try to write
the comment such that it is still valid even if thecode is changed. Care must
betaken that the comment is up to date and accurate. This is often what is not
the case, because most designers will forget to update the comment as well when
they modify the code. This is a good reason to minimize the amount of comment,
because inaccurate comment is worse than no comment.
In any case the comment should not explain the VHDL syntax (the assumption is
that the reader knows VHDL). Comment should also not be used to disable
obsolete code, because we have SVN to keep the obsolete data. In general
comment should also not be used as a compile option, because for that generate
statements should be used.
h) Indent and alignment
Default use a fixed indent of 2 spaces. VHDL has BEGIN and END statements that
group a section so 2 spaces indent is sufficient, however eg. 4 spaces is also
allowed. Within one file the indent should be fixed. Take care of proper
alignment, e.g. all declared signals should be aligned at the colon ':'.
i) TABs and spaces - Do not use TABs
Using TABs is not allowed in the source code, because they have different sizes
in different editors which can disturb the layout. Instead set the editor to
fill in 2 spaces when the TAB key is used. Note setting the TAB size to 2 spaces
is not enough, set TAB such that it truely prints 2 spaces.
j) Line length
For the purpose and description try to keep the comment line lenght <= 80 to
allow printing it in courrier on an A4 without line wraps. For the rest of the
file the line length can be larger up to about ~200, such that they still fit
on a screen.
k) Use separate line for each statement
l) Place each declaration on a separate line
12) Standard packages
For signed and unsigned only use (so do not use other packages with similar
functions):
LIBRARY IEEE;
USE IEEE.STD_LOGIC_1164.ALL;
USE IEEE.NUMERIC_STD.ALL;
13) Use of records
Using records makes signal interfaces more clear. Typically the input signals
of an interface are grouped into one record and the output signals of that
interface are grouped into another related record. Defining too many different
types of records also makes the VHDL less readable, because it is then not
easy to remember what each record type means. For the main Memory Mapped (MM)
and Streaming (ST, also called DP for data path) interfaces it appears possible
to define just a few standard record types that can be used in all MM and ST
components. These records are defined in:
- MM : common_mem(pkg).vhd
- ST : dp_stream(pkg).vhd
14) Use of two-dimensional arrays
Multi-dimensional arrays can be declared and indexed in several ways:
a) As matrix of elements -> index(I,J):
TYPE t_sl_matrix IS ARRAY(INTEGER RANGE<>, INTEGER RANGE <>) OF STD_LOGIC;
TYPE t_data_matrix IS ARRAY (0 TO c_nof_tlen-1, 0 TO c_nof_input-1) OF STD_LOGIC_VECTOR(g_data_w-1 DOWNTO 0);
SIGNAL a_mat : t_sl_matrix(0 TO c_nof_tlen-1, 0 TO c_nof_input-1);
SIGNAL d_mat : t_data_matrix;
b) As array of arrays -> index(I)(J):
-- The element range needs to be set in the TYPE.
TYPE t_sosi_2arr IS ARRAY (INTEGER RANGE <>) OF t_dp_sosi_arr(0 TO c_nof_input-1);
SIGNAL a_sosi_2arr : t_sosi_2arr(0 TO c_nof_tlen-1);
c) As a 1-dimensional array --> index( I * length(J) + J)
d) As a fixed number of declared 1 dim arrays --> index I in name and J in arr
SIGNAL input_arr0 : t_dp_sosi_arr(0 TO c_nof_input-1);
SIGNAL input_arr1 : t_dp_sosi_arr(0 TO c_nof_input-1);
SIGNAL input_arr2 : t_dp_sosi_arr(0 TO c_nof_input-1);
SIGNAL input_arr3 : t_dp_sosi_arr(0 TO c_nof_input-1);
Of course option d) is less nice, because the number of I arrays is fixed in
declared row names. However for some cases it may be appropriate. Options a)
and b) are the true 2-dim arrays. Option a) has the disadvantage that the
elements can only be assigned per element, it is not possible to assign all J
with an 1-dim array of equal length. This is possible with option b), but
option b) has the disadavantage that the length of the element array must be
known at the TYPE definition. Typically option b) then requires to define this
2-dim array in a module package, because only then the TYPE can be used in
multiple files. E.g.:
c_<module_name>_nof_j_max = 32;
TYPE t_<module_name>_i_j_2arr IS ARRAY (INTEGER RANGE <>) OF t_dp_sosi_arr(c_<module_name>_nof_j_max-1 DOWNTO 0);
out_sosi_2arr : t_<module_name>_i_j_2arr(g_nof_i-1 DOWNTO 0, g_nof_j-1 DOWNTO 0);
An alternative can be to not use a 2-dim array like a) or b) but instead use an
aggregate 1-dim array like c). E.g.:
out_sosi_arr : OUT t_dp_sosi_arr(g_nof_i*g_nof_j-1 DOWNTO 0);
The advantage of such an aggregate 1-dim array is that it can be entirely set
by means of generics. The disadvantage is that the 2-dim indexing is a bit
more complicated and that the 2-dim properties of a signal do not show as such
in a Wave Window. A way around is to internally still declare a local signal
of a true 2-dim array type like a) and use that to monitor the 1-dim port
signal. E.g. for port out_sosi_arr above this then yields out_sosi_matrix below:
SIGNAL out_sosi_matrix : t_integer_matrix(g_nof_i-1 DOWNTO 0, g_nof_j-1 DOWNTO 0);
p_wires : PROCESS(out_sosi_arr)
BEGIN
FOR I IN g_nof_i-1 DOWNTO 0 LOOP
FOR J IN g_nof_j-1 DOWNTO 0 LOOP
out_sosi_matrix(I,J) <= out_sosi_arr(I*g_nof_j+J);
END LOOP;
END LOOP;
END PROCESS;
15) Use of constants, generics and packages
How to define a constant and where depends on the function of the constant.
Constants can be define at:
1) Locally in the architecture
2) As default value of a generic that typically does not need to be changed
3) As a global constant in a package that can be used directly in any
architecture that uses this package
4) As a global constant in a package that is used as default value for a
generic
The advantage of using generics is that the parameter can be changed by the
block that instantiates it. If the generic is propagated to up the hierarchy
then it can be controlled in a test bench, which is useful to verify multiple
generic settings in simulation without having to edit the code.
The disadvantage of using generics to pass on constant values is that this
can bother the user with detailed knowledge of the component.
Constants in a package are useful to make them known in lower hierarchy blocks
wthout having to pass them on via the entity generics. The limitation of
constants in packages is that they can only be changed by editing the file.
16) Functions
Functions have input arguments and return a single value. Functions cannot
wait for a clock, so they work combinatorially (= immediately). Functions
are useful to:
- derive constant or generic values that depend on input conditions
- map a signal to an other signal, eg. to change the order in an array
For many examples of reusable functions and some procedures see:
- common_pkg.vhd
- dp_stream_pkg.vhd
17) Procedures
Procedures have input, output or inout arguments and no return value:
- A procedure with only inputs seems not useful.
- A procedure can drive one or more outputs. Procedures can wait for a
clock, so they can output (generate) a sequence in time. This is useful
in a test bench.
- Using an inout argument is useful if the procedure needs to maintain some
storage, eg. the previous value of the current output. The storage cannot
be defined inside the procedure. The inout argument is connected to a
a signal that is declared outside the procedure to act as the storage.
When using in, out and inout arguments the difference between a procedure
and an entity becomes small. The advantage of an entity is that it can have
internal state (storage) and components are more intuitive for creating
schematic structure and hierarchy. A prodedure can be synthesized, but
typically procedures are more used in test benches and entities are more used
in synthesizable code.
The signal connected to a procedure output can be an array(I) element
provided that the index I comes from a GENERATE statement. If the index I
comes from a LOOP statement then the compiler gives Error: "(vcom-1450)
Actual (indexed name) for formal "output argument" is not a static signal
name"
For many examples of reusable procedures and some functions see:
- tb_common_pkg.vhd
- tb_dp_pkg.vhd
18) Test benches
A device under test (DUT) can be a component, a module or a complete VHDL
design that will run on the FPGA. In general all components, modules and
designs should have a VHDL test bench to verify the working of the it.
Consider that if you do not make a test bench for some component then you
should not have made that component. If it is not worth testing it is not worth
implementing. This rule can help development to focus on the functionality that
is realy essential for the design.
Test benches are equally important as the design itself. Therefore the test
bench code should also be well structured.
Test bench code does not get into the FPGA, so therefore it is kept in a
separate directory together with behavioral VHDL models of some peripherals
(like e.g. an ADC or an I2C slave).
The testing of a DUT in simulation is called 'verification'. The testing of a
DUT on FPGA hardware is called 'validation'.
a) Verifying a DUT
Test benches provide the envrionment in VHDL to verify a device under test
(DUT). The DUT can be anything between low component or an entire system.
The test bench environment consists of:
- Stimuli that drive inputs of the DUT (e.g. clk, data)
- The DUT
- Behavioral models that model a external device (e.g. a sensor, an ADC)
- Verification that check outputs of the DUT
The verification can be:
- Monitoring (e.g. manually observing a signal in the Wave window)
- Logging to a file that can be check by means of a diff with a golden
reference file.
- Self checking (comparing the DUT output with pre-calculated reference
data or with stored golden reference data)
b) Test bench interface packages and components
The following packages provide useful procudures for making test benches:
- tb_common_pkg - General flow
- tb_common_mem_pkg - MM interfacing
- tb_dp_pkg - DP interfacing
The tst/ module provides file IO.
c) Multi-level test bench
A test bench can have generics that allow the multiple variations of the
test bench to be instantiated in a higher level test bench. This multi-test
bench can then simulate these variations in parallel and serve as a
regression test for the DUT.
These DUT regresssion test benches can again be instantiated in yet another
test bench to have a system level regression test bench.
For self stopping test benches the tb_end signal needs to be output via the
test bench entity, such that the multi-level test bench can issue its tb_end
when all tb instances have raised their tb_end.
d) Self checking and self stopping
The preferred scheme is a self checking and self stopping test bench that
reports errors if they occur and runs as long as necessary. This is useful
when the test bench is ran manually and moreover it prepares the test bench
to be used in a regression test.
Errors can be reported via ASSERT or REPORT with SEVERITY ERROR.
A simulation of a test bench can be stopped automatically be stopping all
toggling when the stimuli have finished. Typically all toggling can be
stopped by making tb_end <= '1' and using tb_end in the clock statement, eg:
clk <= NOT clk OR tb_end AFTER clk_period/2;
For some IP stopping the clocks and applying the resets using tb_end is not
enough to stop the simulation, apparently because some process still keeps
on free running (eg. a VCO in a PLL). In those cases the simulation can be
forced to stop by asserting a FAILURE:
REPORT "Tb simulation finished." SEVERITY FAILURE;
The disadvantage of this scheme is that it can be confusing that the test
went OK but finishes with a failure. A better solution is therefore to
still tb_end <='1' to signal the end of the simulation, but use the Modelsim
'when' command to actually stop the simulation. The when command can be
issued only when a simulation is loaded:
when -label tb_end {tb_end == '1'} {echo "Tb simulation finished" ; stop ;}
e) Python test case using MM interface
For DUT with an MM interface the stimuli and verification can be done using
a Python test case. The Python test case then communicates with the DUT
in Modelsim via file IO.
The Python test case can stop the simulation by raising tb_end via a
dedicated file IO handler, eg similar as used for polling the simulation
time.
19) DP streaming component development example
a) DP component example: dp_packet_merge.vhd
The description in dp_packet_merge.vhd explains how a DP streaming component
with flow control can be developed. It also explains how to do this within
the Gaisler two-process method.
b) DP test bench example: tb_dp_example_no_dut.vhd
The tb_dp_example_no_dut.vhd provides an example test bench without DUT that
describes and shows how a streaming DP component can be verified using
stimuli procedures and verification procedures from tb_dp_pkg.
20) Simulation and synthesis debugging
a) Compile errors
Most compile errors are easily fixed. Fix the first 1 or 2 errors first and
then recompile, because some more errors may then disappear as well and new
error may appear. Sometimes it is more difficult to identify the cause of a
compile error. Then first carefully read the error message and eg. use Modelsim
'verror <error message number>' and/or Google (part) of the error message
to get more info. If the cause still is notclear then try to isolate the cause
by commenting out more and more parts of the code until the error disappears.
b) Simulation error
Make sure that the simulation has loaded the implementations of all components
(eg. there are no empty black boxes and all memory initialization files have
been found). Most simulation errors can be debugged by tracing the signals in
the Wave Window and through the source code. It is almost never necessary use
break points and to step through the VHDL code.
c) General debugging
- Try to consider a bug as a valuable insight into how the design is (not)
working. When the bug is fixed the design will be better then it was before.
- Discuss the debug steps with one or more colleges to get fresh ideas and to
avoid misconceptions and blind spots
- Narrow down the problem till it disappears and then build up the design again
till it reappears.
- Make step by step changes, that are sufficiently small to isolate the
problem.
- Compare the design that fails with a working design (eg. a previous version)
and identify the differences.
- In case of IP related bugs carefully read the manual (again), search the web
for reports on how to tackle IP problems
- Stay calm and carefully observe the results of each debug step to determine
the best next step
- A bug that takes longer than expected to solve can feel like a burden (eg.
due to project time pressure, due to lack of progress, due to incompetence),
be open about this when discussing this with collegues ('sof' = share our
feelings).
d) Hardware debugging
A device under test (DUT) can be simulated using a VHDL test bench. With proper
models of the DUT environment the simulation of DUT should use the same result
as when running the synthesized DUT on FPGA hardware. If there does occur a
mismatch between simulation and hardware behaviour then check the following:
- In case of a new board:
. are the chips mounted correctly and are the chip type numbers correct
. are the values of e.g. termination resistors and capacitors correct
- In case of a new FPGA:
. First try all FPGA interfaces using Xilinx/Altera reference designs that
have been shown to work on development boards that use the same FPGA
. Ask on-site help of an Xilinx/ALtera engineer to speed up learning curve
on debugging the FPGA IO (especially transceivers and DDR memory).
. is the FPGA type used for synthesis correct?
. do you use the latest version of the synthesis tools, because with new
FPGAs there may be important tool updates
- Is the still board oke, ie is eg unb_minimal still working? Are the board
power supplies oke and if nescessary are external clock and PPS connected?
- If the design did work and now does not anymore recall what source files were
modified.
- If an old design still worked then use a clean SVN check out and a clean
build to go back to this design. If this design works then go to newer
version in SVN and try that on hardware. Continue this kind of binary search
until the SVN version that works and the next that does not have been found.
Check the SVN log and the SVN diff of the file(s) that differ to determine
how these diff can cause the malfunctioning.
- Be precise in noticing what exactly is not working without jumping to
conclusions too soon. First observe and analyse the bug to obtain as much
clues as possible.
- Is the environment model sufficiently accurate? If feasible try to improve
the model.
- If the simulation works but on hardware it fails, then check that all
generics and derived constants that are different on hardware have scaled
accordingly. Maybe a generic or derived constant is hardcode and keeps its
simulation value, which is then wrong for hardware.
generic is hardcoded and keeps its model value instead
- Check all warnings in the synthesis and fitter reports.
- Does the synthesized DUT pass the timing constraints? If not then first fix
this.
- Is the resource usage per instance as expected or is there functionality
that gets optimized away unitentionally? --> search for 'away' in the
synthesis report.
- Is the pin definitions file correct and complete?
- Are the RAM initializations files found by the synthesis tool? --> eg. for
the Nios program, a BG, the coefficients of a FIR filter
- Are the constraint files found and interpreted correct by the synthesis tool?
- Does the RTL code have special VHDL constructions that migth be interpreted
differently by the synthesis tool (e.g. comparing std_logic_vectors of
different length --> better compare them as unsigned values)?
- Are the process sensitivity lists complete (no used inputs missing)? -->
search for 'sensitivity' in the synthesis report.
- Are there no latches in the design? --> search for 'latch' in the synthesis
report.
- There should not be any combinational loops in the design, --> search for
'combinational loop' in the fitter report.
- Are there uninitialized signal values that may be interpreted differently in
synthesis? --> eg. use the c_dp_siso_rst/rdy/hold/flush constants to default
assign a record signal rather than assigning each record field individually
to avoid missing a field.
- Are the RAM block initializations the same for both the simulation and
synthesis?
- Are the correct clocks and resets connected to the different clock domains?
- In case of occasional failure on hardware maybe a clock domain crossing is
not done properly.
- Are the signal (pulses) and busses transferred properly accross clock
domains?
- Does the (software) functionality take account of the latency that it takes
to let a signal reliably cross a clock domain?
- For DDR3 and gigabit transceiver IP there may be an IP toolkit option to
observe IP internal status via JTAG
- For bugs that take weeks to solve consider asking help from an external
(Altera or Xilinx) engineer that knows the IP.
If this all does not help to identify the cause then:
- Add some more DUT signals to a monitor MM register that can be accessed via
the 1GbE control interface
- Do a functional simulation of the post synthesis netlist of the design (ie
without the timing, but with the FPGA logic) to verify whether synthese has
interpreted the RTL the same as the simulator.
- Use e.g. Altera SignalTap or Xilinx ChipScope to add an embedded logic
analyser to the DUT that can be accessed via JTAG.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment