Synthesizable Verilog Programming Conventions and Resources

This page contains some thoughts of mine about how people should write Verilog code for Synthesis. In particular, I have some general rules that will save you much headaches if you follow. Also I have my ideas about how a Verilog file should be layed out. I also have some links to references that I have found useful on my quest to learing about synthesizable Verilog. Lastly I have a FAQ of Verilog questions that I have fielded over time and the responses I have given.

Generalized Verilog rules to live by

1. 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.
2. 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.
3. 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.
4. 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));
5. 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.

How I think all Verilog files should be laid out and naming conventions

1. define consts
2. declare outputs (these are _out)
3. declare inouts if any (these are _inout)
4. declare special inputs such as clk and reset
5. declare inputs (these are _in)
6. declare _all_ state (these are _f)
7. declare inputs to state with (these have same name as state but are _temp)
8. declare wires (naming not restricted except connections of two instantiated modules are usually of the form A_to_B_connection)
9. 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)
10. do assigns
11. do assigns to outputs
12. instantiations of other modules
13. combinational logic always @'s are next
14. 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.

Example Verilog Files that use these naming and coding conventions

• dual_fifo_to_sib.v

Links to useful resources

The book that I first learned Verilog from

• Verilog HDL: A Guide to Digital Design and Synthesis
  Author: Palnitkar, Samir
  ISBN: 0134516753
  Amazon Link
  MIT LCS Library has? Yes
  Review: I generally thought this book was a pretty good starter book. I still use it sometimes for reference, but this is not an advanced book. It is easier to read than a lot of other books on this subject. I think that a little more emphasis on what the presented code synthesizes into would have been instructive.

Documents that do a good job of explaining what Verilog synthesizes into

• HDL Chip Design: A Practical Guide for Designing, Synthesizing and Simulating ASICs and FPGAs Using VHDL and Verilog
  Author: Smith, Douglas J.
  ISBN: 0965193438
  Amazon Link
  MIT LCS Library has? Yes
  Review: I liked this book because it shows what code actually synthesizes into with actual schematics. It also shows code side by side for both VHDL and Verilog. This book is the big blue book with cartoons and the magic synthesier on the front. The only real gripe that I have with this book is that I don't like the style of some of the examples presented and I think that at times they don't make enough separation between combinational and sequential logic, but I am a stickler on that respect.
• Synopsys's Guide to HDL Coding Styles for Synthesis
  This is a guide that Synopsys provides with its design complier synthesis tool which tells what different Verilog structures synthesize into. Even if you are not using the Synopsys compiler, I recomend taking a look at this guide as I am sure other synthesizers follow similar rules.
  I don't think this is easily available on the Internet, but if you are lucky to be a MIT/LCS/CAG member this document can be found in our installed diretory in /home/cad/synopsys/syn/2000.11-SP1/doc/online/synth/synco/toc.pdf

Frequently Asked Questions

• Q: What is a 'wire reg'?
  A: Sometimes you may notice that things that you want to be a wire need to be declared as a reg in Verilog to get code to compile. These I affectionately call 'wire regs'. In Verilog things that are on the left hand side(lhs) of expressions inside of the always @ construct need to be declared as reg. This is becasue as a language construct they hold state and are not absolutely being assigned to. This does not mean that they are flip-flops. Rather if they are combinationally driven, not inside always @ (posedge clk), and not a level based latch, then they are simply wires. They still need to be declared as reg in the language, but this is more of a language problem then them actually being a flip-flop. To distinguish the different types of 'regs' I use a naming convention where flip flops have a post-pended '_f' to denote that they hold state.

If you like this page send me some e-mail at wentzlaf AT cag.lcs.mit.edu
You can also find more contact info for me on my homepage