Difference: VHDLCodeStyle (1 vs. 17)

Revision 17
27 Oct 2009 - Main.JanMichel
Line: 1 to 1
Changed:
<
<
META TOPICPARENT name="HadesDaqDocumentation"
>
>
META TOPICPARENT name="VHDLCodeInformation"
 

Hardware programming guidelines

Revision 16
08 Apr 2009 - Main.MarekPalka
Line: 1 to 1
 
META TOPICPARENT name="HadesDaqDocumentation"
Line: 30 to 30
 
  • Signal names should be verbose: don't save characters
  • Use a scheme that clearly marks signals as belonging to the same part of logic, for instance timing_counter, timing_counter_reset, timing_counter_stop
  • Names of processes and instances should have a distinct namespace such as THE_* or PROC_*
Changed:
<
<
>
>
  • Processname has to be different then signal names
  • Processnames are unique
 

Lower / Upper Case

  • capital letters for ports, like DATA0, CLK and so on
Line: 45 to 46
  with positive logic and use this in the entity
  • All Ports have a _IN respectively _OUT postfix to show their direction. Exceptions: CLK, RESET, CLK_EN, STAT, CTRL as well as top level ports with a verbose name like TX_DATA.
  • Signals leaving an entity should always be registered. Don't forward combinatorial information to the next entity!
Added:
>
>
  • Defined signals are to be used (unused signals generates generates warnings)
 

Prefixes for Signals

  • Depending on how they are generated, signals should have one of the following prefixes
Revision 15
19 Feb 2009 - Main.MichaelBoehmer
Line: 1 to 1
 
META TOPICPARENT name="HadesDaqDocumentation"
Line: 65 to 63
 
    • Keep debugging signals that might be useful later when debugging the whole system!

Resets

Changed:
<
<
  • Use synchronous resets only, never asynchronous!
>
>
  • Use synchronous resets only, never asynchronous! This may not be true for Lattice, but only Xilinx devices.
  • Lattice ECP2M series: if you want to use the GSR network, be sure that
    1. your reset set there is really asynchronous
    2. no logic is included in the signal (i.e. use an external pin for the GSR net)
    3. you force the mapper to use the GSR with your signal (LPF: USE_GSR NET "netname";)
    4. the mapper really followed your command
    5. this issue is still under investigation! -- MichaelBoehmer - 19 Feb 2009
 
  • Watch out for clock domains! (example: TRBnet regIO "general reset" signal is driven by 100MHz clock, but is used in frontend handling logic with 40MHz clock like in the RICH ADCM, so a short pulse on "general reset" may be missed on the slow flipflops, or even worse, lead to metastability).
  • All registers (including state machines) should have a reset
    • Exceptions: Data registers like shift registers that are only read when another flag signal is set and can remain invalid until they are written
Revision 14
16 Feb 2009 - Main.MichaelBoehmer
Line: 1 to 1
 
META TOPICPARENT name="HadesDaqDocumentation"
Line: 46 to 46
 
  • If in the top-level there are low-active ports, then append a "_N" to the name and introduce a signal with positive logic and use this in the entity
  • All Ports have a _IN respectively _OUT postfix to show their direction. Exceptions: CLK, RESET, CLK_EN, STAT, CTRL as well as top level ports with a verbose name like TX_DATA.
Added:
>
>
  • Signals leaving an entity should always be registered. Don't forward combinatorial information to the next entity!
 

Prefixes for Signals

  • Depending on how they are generated, signals should have one of the following prefixes
Line: 65 to 66
 

Resets

  • Use synchronous resets only, never asynchronous!
Added:
>
>
  • Watch out for clock domains! (example: TRBnet regIO "general reset" signal is driven by 100MHz clock, but is used in frontend handling logic with 40MHz clock like in the RICH ADCM, so a short pulse on "general reset" may be missed on the slow flipflops, or even worse, lead to metastability).
 
  • All registers (including state machines) should have a reset
    • Exceptions: Data registers like shift registers that are only read when another flag signal is set and can remain invalid until they are written
Line: 132 to 136
 
trbnet/special Special purpose entities like top level entities
Changed:
<
<

Implementaion Help from Xilinx

>
>

Implementation Help from Xilinx

 

* TimingConstraintsGuide6i_7i_8i.pdf: Very useful information about constraints.
Revision 13
13 Feb 2009 - Main.AttilioTarantola
Line: 1 to 1
 
META TOPICPARENT name="HadesDaqDocumentation"
Line: 98 to 98
 
  • One blank line between processes, components ...
  • Three lines between logical sections
  • Signal, types, constants, port names etc. grouped in logical parts (one line space beetween them)
Changed:
<
<
>
>
  • Here you can find a VHDL code example:
* trigger_distributor.vhd: entity trigger distributor
 

Synchronizing - asynchronous signals and clock domains

  • Whenever using an asynchronous signal, sourced either from FPGA logic or from the outside world, use a
Line: 155 to 158
 
META FILEATTACHMENT attr="" comment="Testbench features in combination with ModelSim (clear text, etc.)" date="1170859591" name="Testbench_Features.zip" path="Testbench_Features.zip" size="8455305" user="MichaelTraxler" version="1.1"
META FILEATTACHMENT attr="" comment="General hints on synchronizers" date="1226942127" name="CrossingTheAbbyss.pdf" path="CrossingTheAbbyss.pdf" size="113602" user="MichaelBoehmer" version="1.1"
META FILEATTACHMENT attr="" comment="some technical stuff from 1990, chapter 5 has some remarks" date="1226942184" name="bigram.pdf" path="bigram.pdf" size="95030" user="MichaelBoehmer" version="1.1"
Added:
>
>
META FILEATTACHMENT attr="" comment="entity trigger distributor" date="1234527084" name="trigger_distributor.vhd" path="trigger_distributor.vhd" size="20036" user="AttilioTarantola" version="1.1"
Revision 12
19 Dec 2008 - Main.MichaelTraxler
Line: 1 to 1
 
META TOPICPARENT name="HadesDaqDocumentation"
Line: 9 to 9
  (at very high frequencies use two register)
  • never cross a clock domain without a register/FIFO
Changed:
<
<
  • always use output registers on statemachines (beware of the potential latency)
>
>
  • always use output registers on statemachines (be aware of the potential latency) code examples of the two accepted formats go in here: Jan
  • take care not to use inferred latches, most likely you don't want that.
 
  • there is no design without constraints
    1. clock (register to register)
    2. register to IO-pad
Line: 18 to 19
 
    1. use the registers in the IO pads if possible
    2. pinout file has to correspond with place and route report
Added:
>
>
  • use an automatically generated version number in the code, which should be readable for example by the slow-control channel of the TRB-Net. Code is already available from Marek.
 

Recommendations for a common VHDL code style

Revision 11
18 Dec 2008 - Main.MichaelTraxler
Line: 1 to 1
 
META TOPICPARENT name="HadesDaqDocumentation"
Added:
>
>

Hardware programming guidelines

  • Synchronous design
    • synchronization of external signals (at very high frequencies use two register)
  • never cross a clock domain without a register/FIFO

  • always use output registers on statemachines (beware of the potential latency)
  • there is no design without constraints
    1. clock (register to register)
    2. register to IO-pad
    3. IO-pad to register
    4. use the registers in the IO pads if possible
    5. pinout file has to correspond with place and route report
 

Recommendations for a common VHDL code style

Everyone agrees that it is of some advantage if we agree on some coding style to ease the maintenance
Revision 10
19 Nov 2008 - Main.MarekPalka
Line: 1 to 1
 
META TOPICPARENT name="HadesDaqDocumentation"
Line: 75 to 75
 

  • Entities should by default have a port with some status information of the entitiy which can be used for debugging, name: STAT_DEBUG
Added:
>
>

Making code "readable"

  • One blank line between processes, components ...
  • Three lines between logical sections
  • Signal, types, constants, port names etc. grouped in logical parts (one line space beetween them)
 

Synchronizing - asynchronous signals and clock domains

Revision 9
18 Nov 2008 - Main.JanMichel
Line: 1 to 1
 
META TOPICPARENT name="HadesDaqDocumentation"
Line: 78 to 78
 

Synchronizing - asynchronous signals and clock domains

Changed:
<
<
  • Whenever using an esynchronous signal, sourced either from FPGA logic or from the outside world, use a
>
>
  • Whenever using an asynchronous signal, sourced either from FPGA logic or from the outside world, use a
  synchronizer. Don't use such signal directly in synchronous logic!

  • Whenever crossing a clock domain, use a synchronizer. Either a state or pulse synchronizer will do, but don't leave it out, even if the two clock domains are sourced from the same PLL with known relationship in phase.
Added:
>
>
  • There is a special entity in the cvs, basics/signal_sync.vhd, that generates a row of flipflops
 
Revision 8
17 Nov 2008 - Main.MichaelBoehmer
Line: 1 to 1
 
META TOPICPARENT name="HadesDaqDocumentation"
Line: 76 to 76
 
  • Entities should by default have a port with some status information of the entitiy which can be used for debugging, name: STAT_DEBUG
Added:
>
>

Synchronizing - asynchronous signals and clock domains

  • Whenever using an esynchronous signal, sourced either from FPGA logic or from the outside world, use a synchronizer. Don't use such signal directly in synchronous logic!

  • Whenever crossing a clock domain, use a synchronizer. Either a state or pulse synchronizer will do, but don't leave it out, even if the two clock domains are sourced from the same PLL with known relationship in phase.

  • Just a historical note, this is a problem as old as computers are (read chapter 5): bigram.pdf
 

cvs organization

Line: 107 to 121
  - 24 Aug 2006

Added:
>
>

  • bigram.pdf: some technical stuff from 1990, chapter 5 has some remarks
 
META FILEATTACHMENT attr="" comment="Very useful information about constraints." date="1170859524" name="TimingConstraintsGuide6i_7i_8i.pdf" path="Timing Constraints Guide 6i_7i_8i.pdf" size="5228820" user="MichaelTraxler" version="1.1"
META FILEATTACHMENT attr="" comment="JTAG info" date="1170859557" name="XilinxJTAG.pdf" path="Xilinx JTAG.pdf" size="505233" user="MichaelTraxler" version="1.1"
META FILEATTACHMENT attr="" comment="Testbench features in combination with ModelSim (clear text, etc.)" date="1170859591" name="Testbench_Features.zip" path="Testbench_Features.zip" size="8455305" user="MichaelTraxler" version="1.1"
Added:
>
>
META FILEATTACHMENT attr="" comment="General hints on synchronizers" date="1226942127" name="CrossingTheAbbyss.pdf" path="CrossingTheAbbyss.pdf" size="113602" user="MichaelBoehmer" version="1.1"
META FILEATTACHMENT attr="" comment="some technical stuff from 1990, chapter 5 has some remarks" date="1226942184" name="bigram.pdf" path="bigram.pdf" size="95030" user="MichaelBoehmer" version="1.1"
Revision 7
17 Nov 2008 - Main.JanMichel
Line: 1 to 1
 
META TOPICPARENT name="HadesDaqDocumentation"
Line: 7 to 7
  Everyone agrees that it is of some advantage if we agree on some coding style to ease the maintenance and also reduce the number of errors when we have to merge code of different people.
Deleted:
<
<
On the following we agreed (our meeting 2006-08-22).

(please correct and add things)
 

Naming issues

Added:
>
>
  • The underscore "_" separates different parts of port and signal names
  • Signal names should be verbose: don't save characters
  • Use a scheme that clearly marks signals as belonging to the same part of logic, for instance timing_counter, timing_counter_reset, timing_counter_stop
  • Names of processes and instances should have a distinct namespace such as THE_* or PROC_*
 
Added:
>
>

Lower / Upper Case

 
  • capital letters for ports, like DATA0, CLK and so on
  • capital letters for constants, instance names and process names
  • lower case letters for signals and entities
    • Maybe one exception - if a signal is correlated with a port, I (Ingo) like copy-n-paste. Example: tmp_DATA0
Deleted:
<
<
  • The underscore "_" separates different parts of port and signal names
 
Added:
>
>

Signals and Ports

 
  • Use only postive logic for signals in entities.
  • If in the top-level there are low-active ports, then append a "_N" to the name and introduce a signal with positive logic and use this in the entity
Added:
>
>
  • All Ports have a _IN respectively _OUT postfix to show their direction. Exceptions: CLK, RESET, CLK_EN, STAT, CTRL as well as top level ports with a verbose name like TX_DATA.
 

Changed:
<
<
  • signal names should be verbose: don't save characters
  • use the scheme (if applicable): adjective->noun: example: reduced_temperature,
>
>

Prefixes for Signals

  • Depending on how they are generated, signals should have one of the following prefixes
    • buf_ : A signal to make the output of an entity readible.
    • reg_ : Output of a Flipflop
    • next_: Combinatorial signal that is fed into a fliflop
    • comb_: Combinatorial signal that is not registered
    • last_: A signal that is delayed by one clock cycle by a flipflop
 

Deleted:
<
<
  • common abbreviations:
    1. max_, ctrl_
    2. mem_, xxx
 

Comments

  • comments should tell why something is done and not what and how (this tells the code).
Added:
>
>

Code review

  • After finishing the development of an entity, please remove all unused signals, code lines introduced during debugging...
    • Keep debugging signals that might be useful later when debugging the whole system!

Resets

  • Use synchronous resets only, never asynchronous!
  • All registers (including state machines) should have a reset
    • Exceptions: Data registers like shift registers that are only read when another flag signal is set and can remain invalid until they are written
 

Processes

  • All synchronous processes use "RESET", "CLK" (if system clock is used) and "CLK_EN" as inputs
Line: 51 to 66
  counter <= (others => '0'); elsif CLK_EN = '1' then counter <= counter + 1;
Deleted:
<
<
else counter <= counter;
  end if; end if;
Changed:
<
<
end process counter1;
>
>
end process;
 

Entities

  • Entities should by default have a port with some status information of the entitiy which can
Changed:
<
<
be used for debugging. STATUS_XXX
>
>
be used for debugging, name: STAT_DEBUG
 

cvs organization

Line: 75 to 87
 
Module + Path Description
trbnet Application independent base package
trbnet/xilinx Xilinx dependent stuff, like fifos
Added:
>
>
trbnet/lattice lattice dependent stuff, like fifos
trbnet/basics Basic design blocks like simple roms
trbnet/special Special purpose entities like top level entities
 

Implementaion Help from Xilinx

Revision 6
21 Jul 2008 - Main.MichaelTraxler
Line: 1 to 1
 
META TOPICPARENT name="HadesDaqDocumentation"
Line: 44 to 44
  use ieee.std_logic_1164.all

-- purpose: simple counter, multipurpose
Changed:
<
<
counter1: process (CLK) -- no CLK_EN, RESET for synchronous reset
>
>
COUNTER1: process (CLK) -- no CLK_EN, RESET for synchronous reset
  begin if rising_edge(CLK) then if RESET = '1' then
Revision 5
07 Feb 2007 - Main.MichaelTraxler
Line: 1 to 1
 
META TOPICPARENT name="HadesDaqDocumentation"
Added:
>
>
 

Recommendations for a common VHDL code style

Everyone agrees that it is of some advantage if we agree on some coding style to ease the maintenance
Line: 74 to 76
 
trbnet Application independent base package
trbnet/xilinx Xilinx dependent stuff, like fifos
Added:
>
>

Implementaion Help from Xilinx

* TimingConstraintsGuide6i_7i_8i.pdf: Very useful information about constraints.

  - 24 Aug 2006
Added:
>
>

META FILEATTACHMENT attr="" comment="Very useful information about constraints." date="1170859524" name="TimingConstraintsGuide6i_7i_8i.pdf" path="Timing Constraints Guide 6i_7i_8i.pdf" size="5228820" user="MichaelTraxler" version="1.1"
META FILEATTACHMENT attr="" comment="JTAG info" date="1170859557" name="XilinxJTAG.pdf" path="Xilinx JTAG.pdf" size="505233" user="MichaelTraxler" version="1.1"
META FILEATTACHMENT attr="" comment="Testbench features in combination with ModelSim (clear text, etc.)" date="1170859591" name="Testbench_Features.zip" path="Testbench_Features.zip" size="8455305" user="MichaelTraxler" version="1.1"
Revision 4
04 Sep 2006 - Main.MichaelTraxler
Line: 1 to 1
 
META TOPICPARENT name="HadesDaqDocumentation"

Recommendations for a common VHDL code style

Line: 7 to 7
 

On the following we agreed (our meeting 2006-08-22).
Changed:
<
<
(please correct and add things I forgot)
>
>
(please correct and add things)
 

Naming issues

Line: 74 to 74
 
trbnet Application independent base package
trbnet/xilinx Xilinx dependent stuff, like fifos
Changed:
<
<

-- MichaelTraxler - 24 Aug 2006
>
>
- 24 Aug 2006
 
Revision 3
01 Sep 2006 - Main.IngoFroehlich
Line: 1 to 1
 
META TOPICPARENT name="HadesDaqDocumentation"

Recommendations for a common VHDL code style

Line: 14 to 14
 
  • capital letters for ports, like DATA0, CLK and so on
  • capital letters for constants, instance names and process names
  • lower case letters for signals and entities
Added:
>
>
    • Maybe one exception - if a signal is correlated with a port, I (Ingo) like copy-n-paste. Example: tmp_DATA0
 
  • The underscore "_" separates different parts of port and signal names

  • Use only postive logic for signals in entities.
Line: 62 to 63
  be used for debugging. STATUS_XXX
Added:
>
>

cvs organization

The cvs modules should be organized in order to prevent copying the source code around. General idea: everything what is of common interest have to go into a dedicated module (like trbnet). Projects will have different modules

Module + Path Description
trbnet Application independent base package
trbnet/xilinx Xilinx dependent stuff, like fifos
 

-- MichaelTraxler - 24 Aug 2006
Revision 2
24 Aug 2006 - Main.IngoFroehlich
Line: 1 to 1
 
META TOPICPARENT name="HadesDaqDocumentation"

Recommendations for a common VHDL code style

Line: 41 to 41
  use ieee.std_logic_1164.all

-- purpose: simple counter, multipurpose
Changed:
<
<
counter1: process (CLK, RESET, CLK_EN)
>
>
counter1: process (CLK) -- no CLK_EN, RESET for synchronous reset
  begin if rising_edge(CLK) then if RESET = '1' then
 
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Hades Wiki? Send feedback
Imprint (in German)
Privacy Policy (in German)