Verilog rules that can save your breath !

This article contains some thoughts of mine about how and engineer should write Verilog code for Synthesis, general rules that will save you headaches if you follow, and how a Verilog file should be layed out.

Rules:

• If you don't know what hardware the code you just wrote is, neither will the synthesizer.
• Remember that Verilog is a Hardware Description Language (HDL) and as such it describes hardware not magical circuits that you can never actually build.
• You should be able to draw a schematic for everything that you can write Verilog for.
• Be sure to know what part of your circuit is combinational and which parts are sequential elements. If you do not know or the code is written to be too hard to figure this out, the synthesizer will probably not be able to figure it out either. I recomend making the combinational logic very separate from sequential logic. This prevents errors later. It also prevents level high latches from being synthesized where you meant to have flip-flops. I also recomend having a naming convention such that you can tell what is a state holding element at all times. I use "_f" post-pended to all registers that are flip-flops.
• I recomend having a style for your inputs and outputs. I list them in the following order: outputs, inouts, special inputs such as clk and reset, inputs.
• When instantiating a module, always put the names of the signals that you are conecting to inside of the module with the notations where you have period, module signal name, thing you are connecting. This prevents errors when you change underlying modules or someone resorts the parameters.
• Unlike a language like C which is rather strongly typed, in Verilog, which is also strongly typed, everyting is of the same type and it is easy to reorder parameters and not get errors becasue everything is just a wire.
• Example of wrong module instantiation: nand2 my_nand(C, A, B);
• Example of correct module intantiation: nand2 my_nand(.out(C), .in1(A), .in2(B));
• Make your circuit synchronous whenever possible. Synchronous design is much easier than asynchronous.
• Also reduce the number of clock domains and clock boundaries whenever possible.
• Also remember that crossing clock domains in FPGAs is difficult because LUT's glitch in different ways than normal circuits. This causes problems with asynchronous circuits.

Verilog files should be laid out like this..

• define consts
• declare outputs (these are _out)
• declare inouts if any (these are _inout)
• declare special inputs such as clk and reset
• declare inputs (these are _in)
• declare _all_ state (these are _f)
• declare inputs to state with (these have same name as state but are _temp)
• declare wires (naming not restricted except connections of two instantiated modules are usually of the form A_to_B_connection)
• declare 'wire regs' (naming not restricted except connections are usually of the form A_to_B_connection and variables that are going to be outputs, but still need to be read and you don't want inouts get _internal postpended)
• do assigns
• do assigns to outputs
• instantiations of other modules
• combinational logic always @'s are next
  do the always @ (posedge clk ...) and put reset values here and assign _temps to _f's (ie state <= next_state). I personally think that there should be no conbinational logic inside of always @(posedge clk's) with the exception of conditional assignment (write enables) becasue all Verilog synthesizers understand write enables on flip-flops.