Prof. John Nestor ECE Department Lafayette College Easton, Pennsylvania ECE Senior Design I Lecture 9 - Coding Guidelines / Debugging Fall 2008 Reading: Colwell, “The Power of the Most Likely”, Colwell, “If You Didn’t Test It, It Doesn’t Work” Beware the Stick source:

ECE 491 Fall 2008Lecture 9 - Data Comm.2 Where we are  Last Time:  Verification & Testbenches  Requirements Analysis  Today:  Coding Guidelines  Debugging

ECE 491 Fall 2008Lecture 9 - Data Comm.3 Motivation for Coding Guidelines  Avoid common errors and pitfalls  Latch inferences  Simulation/Synthesis mismatch  Timing problems  Make designer’s intent clear  To others who use your designs  To yourself when you use or re-use your own designs

ECE 491 Fall 2008Lecture 9 - Data Comm.4 Coding Guideline Overview 1.General 2.Hierarchy & Module Instantiation 3.Combinational Logic 4.Sequential Logic 5.Finite State Machines

ECE 491 Fall 2008Lecture 9 - Data Comm.5 1. General Guidelines 1.1Create a separate Verilog file for each module. Name each file.v. 1.2Limit lines to 120 characters or less. 1.3Avoid tabs when indenting, since they will not indent the same on all editors. 1.4Use a fixed number of spaces (e.g. 2, 4) for each level of indentation. 1.5Include a header for each Verilog file which lists the module name, a brief description of the module function, author name(s), creation date, version, and revision history (use the template created by the ISE “Edit” menu for convenience).

ECE 491 Fall 2008Lecture 9 - Data Comm.6 1. General Guidelines (cont’d) 1.6Use uniform naming conventions for your design files. A good example of naming guidelines is given in [1]: Use lowercase letters for all signal names, variable names, and port names with the underscore character “_” as a “word separator. Use all uppercase letters for symbolic constants and instance names. Use meaningful names for all signal names, variable names, and port names (e.g. ram_address instead of ra). Avoid nonsense names and offensive names - you never know who may look at your code! Use the name clk as the name for the clock signal. If there are multiple clock signals, name them clk1, clk2, etc. Use the same name for all clock signals that are driven from the same source. Use the name rst as the name for the resent signal (rst_n if it is active low).

ECE 491 Fall 2008Lecture 9 - Data Comm.7 1. General Guidelines (cont’d) 1.6Use uniform naming conventions for your design files. (Optional) Use the following “extensions” to identify common signal types:

ECE 491 Fall 2008Lecture 9 - Data Comm.8 1. General Guidelines (cont’d) 1.7 Use a consistent ordering for the indexes of multiple-bit vectors [high:low] to avoid accidentally reversing bits. For example: wire [7:0] a, b; wire [3:0] count ; 1.8Include comments in your code to improve readability and understandability. Don’t belabor the obvious, but explain things which are unclear from reading the code. Good places to use comments: to explain the purpose of different ports, always blocks, functions, tasks, etc. 1.9Use symbolic constants in your code instead of “magic numbers”. Use the parameter construct for local constants. Use the `define compiler directive for global constants (parameters are local to a module). 1.10(Optional) Collect related global symbolic constants into an “include file”. Use the compiler directive and use the `include compiler directive to include this file in multiple source files (this only works for `define constants).

ECE 491 Fall 2008Lecture 9 - Data Comm.9 1. General Guidelines (cont’d) 1.11Use a consistent order for module port declarations:  Inputs: Clocks Resets Enables Other control signals Data  Outputs: Clocks Resets Enables Other control signals Data  Bidirectional (inout) signals 1.12Indent declarations so that port names and signal names are aligned.

ECE 491 Fall 2008Lecture 9 - Data Comm Hierarchy & Module Instantiation 2.1Use hierarchy to break your design into pieces. 2.2Module instance names should be in all caps with a prefix “ U_ ” (e.g. U_COUNT1 ). 2.3Avoid mixing structural and behavioral code in a module – a module should usually contain either all structural code (i.e. module instantiations) or all behavioral code (i.e. always blocks, assign statements, etc.) 2.4Use the explicit connection style when instantiating modules with more than 3 ports: counter U_COUNT1 (.clk(clk1),.rst(rst),.enb(cnt_enb),.count_r(q) ); Avoid using the positional notation since this is a common source of errors.

ECE 491 Fall 2008Lecture 9 - Data Comm Combinational Logic 3.1Use functional descriptions rather than “low-level” logic descriptions. Example: assign cmp_out = (in1 == in2); // obvious! instead of assign cmp_out = ~|(in1 ^ in2); // huh? 3.2Use continuous assignment ( assign ) statements for simple combinational logic. 3.3When using always blocks for combinational logic: a.Remember to declare outputs as reg s. b.Assign outputs using the blocking assignment ( =). c.Never use assign or deassign within an always block. d.Assign a definite value to each output under all possible input conditions to avoid latch inferences. e.Use the Verilog 2001 construct when supported. f.Otherwise, make sure to include all inputs in the sensitivity list e.g.: always( in1 or in2 or in3)

ECE 491 Fall 2008Lecture 9 - Data Comm Combinational Logic 3.4Don’t use delay operators (e.g., # ) when coding for synthesis. 3.5NEVER allow cycles in combinational logic connections. This includes cycles created by connections through more than one block! 3.6When using a case or casez statement, make sure that all possible input values are covered (“full case” – use default if necessary) and that each input value is covered by one and only one branch of the case statement (“parallel case”). Do not use the “ full_case ” or “ parallel_case ” synthesis directives to try to force this, but code it directly in your case statement. 3.7Use casez to specify case values with “wild card” digits. Express “wild card” digits using ‘ ? ’ instead of ‘ z ’. Do not use the casex statement. 3.8When coding a priority encoder, use if / else if instead of case or casez.

ECE 491 Fall 2008Lecture 9 - Data Comm Basic Sequential Logic 4.1Use flip-flops for sequential logic. Never use latches. 4.2Assign registered outputs using nonblocking (<= ) assignments. 4.3Use asynchronous reset only for system reset and initialization. NEVER tie an asynchronous reset to the output of a combinational logic function! 4.4Synchronize all asynchronous inputs. 4.5Use handshaking to reliably transfer data between clock domains. 4.6Use a common clock edge for to trigger all flip-flops in your design. Don’t mix clock edges. Use the positive edge only unless absolutely necessary. 4.7If possible, use a single clock for your entire system. If that isn’t possible, synchronize signals that pass from one clock domain to another. 4.8Don’t use gated clocks. 4.9(Optional) Use “registered” outputs to improve performance and timing analysis.

ECE 491 Fall 2008Lecture 9 - Data Comm Finite State Machines 5.1Use separate always blocks for the sequential (state register) and combinational parts of the FSM. 5.2Include a synchronous reset in each FSM state register. 5.3Define state codes as symbolic constants using parameter. Assign the parameter a size to avoid errors 5.4In a large FSM, assign next state and all outputs to default values before the case statement. 5.5Assign a default next state to gracefully handle what happens if the FSM winds up in an unknown state

ECE 491 Fall 2008Lecture 9 - Data Comm.15 Debugging - What if It Doesn’t Work?  Colwell’s Advice:  Change one thing at a time  Don’t ignore the unexpected  Follow the bug trail where it leads, not where you wish it would go  Reduce complex phenomena to simple absolutes (isolate the problem)  Keep accurate lab notes (use a notebook)  Debug is an immersion activity (allocate time without distractions)  Bugs almost never live alone  Test your test equipment  Know when you’re stuck, and call in the cavalry

ECE 491 Fall 2008Lecture 9 - Data Comm.16 Debugging - What if It Doesn’t Work?  More Advice:  Code your design carefully! Follow the coding style guidelines Keep your code simple and readable Think in terms of hardware Simulate before you attempt hardware debug  Read your code carefully You see what you expect to see - look again! Use your lab partner(s) to double-check code  When there are multiple problems, look at them one at a time (but keep them all in mind)  Pay attention to ISE warnings  Isolate the problem by temporarily removing parts of the design  When all else fails, use the LEDs, 7-seg displays and the oscilloscope to monitor key signals

ECE 491 Fall 2008Lecture 9 - Data Comm.17 Some Common Errors  Implicit wire declaration of multi-bit wire // forgot to declare wire [3:0] q; counter U_COUNT(clk, enb, q, carry); assign test = (q == 4’d5);  Declared size of multi-bit wire or reg too small wire [2:0] q; // too narrow! counter U_COUNT(clk, enb, q, carry); assign test = (q == 4’d12);  Failure to use sized numbers in proper base wire [3:0] q; // too narrow! counter U_COUNT(clk, enb, q, carry); assign test = (q == 1100);

ECE 491 Fall 2008Lecture 9 - Data Comm.18 Some Common Errors  Using a derived clock that stops working on reset  Forgetting to un-comment constraints  Obscure synthesis errors due to code on “U” drive (copy to the “C” drive while working)  Failure to back up code (you’ll be sorry!)

ECE 491 Fall 2008Lecture 9 - Data Comm.19 Some Not-So-Common Errors  FSM Encoded as “1-Hot”; does not function properly without reset  Symptom: FSM fails to function unless cs is an external port  Fix: use synthesis attribute for user encoding reg [3:0] cs, ns; // synthesis attribute fsm_encoding of cs is user // synthesis attribute fsm_encoding of ns is user  Project file is corrupted  Symptom: “mapping error”  Fix: create a new project and re-import Verilog files

ECE 491 Fall 2008Lecture 9 - Data Comm.20 Some Not-So-Common Errors  Comma at end of port list  Cause: module bogus(a, b, c,);...  Symptom (when instantiating): “Error: XST: Unsupported item in port list for module  Project file is corrupted  Symptom: “mapping error”  Fix: create a new project and re-import Verilog files

ECE 491 Fall 2008Lecture 9 - Data Comm.21 Coming Up  Data Communications