Coding HDL for Reviewability Paper D4 Ben Cohen ( VhdlCohen Training/Consulting ) vhdlcohen@aol.com vhdlcohen@

1. 2002 MAPLD International Conference Coding HDL for Reviewability Paper D4 • Ben Cohen (VhdlCohen Training/Consulting )vhdlcohen@aol.com vhdlcohen@klabs.org

2. NOTATION VHDL Coding Styles and Methodologies, 2nd Edition , Ben Cohen, ISBN 0-7923-8474-1 Kluwer Academic Publishers, 1999 VHDL Answers to Frequently Asked Questions, 2nd Edition, Ben Cohen, ISBN 0-7923-8115-7, Kluwer Academic Publishers, 1998 Component Design by Example, Ben Cohen, isbn 0-9705394-0-1 VhdlCohen Publishing, 2001 Real Chip Design and Verification Using Verilog and VHDL, isbn 0-9705394-2-8 VhdlCohen Publishing, 2002 http://www.sunburst-design.com/ Reuse Methodology Manual for System-on-a-Chip Designs, Third EditionMichael Keating, Pierre Bricaud, ISBN 1-4020-7141-8 Kluwer Academic Publishers2002 Issue/Concern Solution Cummings

3. Many Facets of HDL to Consider in Reviewability RESETS REQUIREMENTS CLOCKS RELIABILITY ARCHITECTURE HDL TIMING PARTITIONING SAFETY STYLE DOCUMENTATION SYNTHESIS INTERFACES TECHNOLOGY

4. Review Purpose-- Synthesizable Designs -- • Verify design meets requirements • Functional (per specifications) • Environmental (e.g., radiation, clock, synchronization, packaging) • Technology (e.g. IPs, device, tools, libraries) • Understand architecture • Partitioning, hierarchy • Operations • Timing • Synthesizability • Reuse • Style (e.g., FSM, structure, IOs) • documentation

5. Review Purpose -- Verification Designs -- • Verify adequacy of verification processes • Testplan and design requirements • Directed tests/Random tests • Hot tests (RTL -> Synthesis -> Board System Test) • Understand verification architecture • Types of BFMs and automatic verifiers • BFM synchronization methods • Transaction definition styles • Subblock verification approaches • Partitioning, hierarchy • Operations • Reuse • Style • documentation

6. Spiral / Waterfall Design Processeshttp://www.eng.uwaterloo.ca/~msci738/clippings/00000059.pdf Spiral Waterfall

7. Waterfall vs Spiralhttp://www.cu.edu/~irm/about_irm/self_study/96_method.html

8. Recognizes that people make mistakes and no decision can be absolute. • Forces accountability by having clearly defined stages where activities are frozen and placed under change order control.

9. Observed Facts Requirements Change! • Initial goals / algorithms / interfaces not defined    • Existing IPs/reusable designs not do exactly what is wanted.    • Implementer may come up with a better idea than system engineering • Design does not meet timing/power/accuracy as implemented. Guideline for Review: • Document design requirements and changes. Little changes can get lost very easily in this give an take • Reference / copy pertinent requirements into HDL code

10. Where are Things Going Wrong? • Design Process • Requirements • What design shall do • Implementation & synthesis • How partitioned, at what level, IP reuse • Multi-user design environment • Verification • Subblock, unit, system • Documentation • English ... Drawings ... Timing ... Coding • Reviews • At every step of process • Design Guidelines • Generic rules enforced through reviews • OBSERVED • Difficulty in tracing design performance to requirements, if any! • Design has failure in field • Design cannot be easily reused or modified • Difficulty in debug, reuse, and increase in total costs • Designs written at too low level (creates comprehension and debug difficulties) • Designs not conformant to recommended rules and guidelines for readability, reuse, synthesis

11. Observed FactsFailure in Field, and Difficult to Debug • Design requirements / implementation plans scarce(Too proprietary to be let in the field) • Poor system engineering • Requirements often defined ‘on the fly’ Code design becomes the requirement and documentation • Code documentation very poor (practically nil) • Purpose/function of objects (e.g., ports/signals) is very sparse • Operation / purpose of blocks not documented • Code often written at all structural low level • Difficult to comprehend • Almost at the schematic level (i.e., FFs, counters), but in HDL(rather than at the functional level) • NO explicit FSM machine(appears to be poorly implemented, or implemented at schematic level)

12. Observed FactsCode not Conformant to Recommended Guidelines • Level of description too low • Poor code documentation • Poor style in instantiation of subblocks (positional rather than named notation with port direction and comments) • Overuse of nested ?: (see next slide) • Code written at too low level of abstraction (causes difficulty in maintainability and creates synthesis warnings) • Unnecessary begin-end pairs (creates unnecessary code volume) • Non-recommended use of `define. Parameter definitions local to module is preferred. • Improper use of comparison operator (! Instead of ~) • Very long lines (115 characters, instead of 80 max) • Signal names not maintained across hierarchy

13. Real Examples Nested ?: and Too Low Level tant0[0] <= (~cnt[1]) ? ((~cnt[0]) ? iant0[0] : ~iant0[0]) : tant0[0]; if (cnt[1:0] == 2'b00) tant0[0] <= iant0[0]; else if (cnt[1:0] == 2'b01) tant0[0] <= ~iant0[0]; assign dout = (|ext_ce) ? do_ctl : (|gen_ce) ? do_gen : (mon_ce) ? do_rtc : (|testsel) ? iad_data : do_ctl2; tant0[0] <= (~cnt[1]) ? ((~cnt[0]) ? iant0[0] : ~iant0[0]) : tant0[0]; tant0[1] <= (cnt[1]) ? ((~cnt[0]) ? iant0[0] : ~iant0[0]) : tant0[1]; tant0[2] <= (~cnt[1]) ? ((~cnt[0]) ? iant0[2] : ~iant0[2]) : tant0[2]; tant0[3] <= (cnt[1]) ? ((~cnt[0]) ? iant0[2] : ~iant0[2]) : tant0[3]; case (cnt[1:0]) 2'b00: begin tant0[0] <= iant0[0]; tant0[2] <= iant0[2]; tant1[0] <= iant1[0]; tant1[2] <= iant1[2]; tant2[0] <= iant2[0]; tant2[2] <= iant2[2]; end

14. Observed Facts -- Schematic DiagramsEasy to Review/ Potential Problems • Schematics of designs considered easier to review • Schematics tend to be too structural • Harder for synthesis tools to optimize • But maybe a necessity to prevent replication of FFs during speed optimization from RTL synthesis tools • Schematics converted to VHDL with conversion tools • VHDL creation harder to read • VHDL is still the golden design • Maintenance become an issue • Guideline: • Use schematics with caution • Consider implications of schematics • Consider attributes to guide synthesis tools

15. Schematic Diagram Flow Clearer … But Design Too Structural! But Too structural ! Data flow clearer

16. RoughRequirements Design & Synthesize Load into FPGA & System Board FAIL PASS/FAIL? PASS DONE Observed FactsHot Verification Popular • Verification through simulation not performed • Verification at system level • No Simulation  Hot-test instead • No subblock verification • FPGAs are perceived as easy to modify and correct late in the development process. Note: This design/verification approach failed to prove effective

17. REQUIREMENTS ARCHITECTURE/ IMPLEMENTATIONDOCUMENT REQUIREMENTS ARCHITECTURE/ IMPLEMENTATIONDOCUMENT REQUIREMENTS ARCHITECTURE/ IMPLEMENTATIONDOCUMENT PACKAGES SCRIPTS LIBRARIES ALGORITHMIC/ BEHAVIORAL HDL MODEL ALGORITHMIC/ BEHAVIORAL HDL MODEL SYTHESIZABLE HDL DESIGN ALGORITHMIC/ BEHAVIORAL HDL MODEL SYTHESIZABLE HDL DESIGN SYTHESIZABLE HDL DESIGN VERIFICATION PLAN VERIFICATION PLAN VERIFICATION PLAN APPLICATION HDL DESIGN TESTBENCH HDL DESIGN APPLICATION HDL DESIGN TESTBENCH HDL DESIGN APPLICATION HDL DESIGN OTHERDOCUMENTATION & SPECIFICATIONS TESTBENCH HDL DESIGN OTHERDOCUMENTATION & SPECIFICATIONS OTHERDOCUMENTATION & SPECIFICATIONS RESULTS, SCRIPTS Information Needed for ReviewMultitude of Inter-related Files!!!

18. What is Needed • File Management System • Coding Style • Convention • Support file management style • Enhance code readability • Guidelines • Synthesis • Partitioning • FSM style • Verification • Reviewability Checklist

19. File ManagementUse of Tools • VHDLDOC -- GNU TOOL • Automatically generates hyperlinked html-documentation of VHDL Code. • Hierarchy, Ports, Generics, Packages, Source code, Documents (e.g., requirements, plans), Images • The markup-language is like the one of JAVADOC. • Runs on Unix/Linux. • Results can be made compatible with windows with awk program to correct a file naming issue.(see vhdldoc paper) • Freely available at: http://schwick.home.cern.ch/schwick/vhdldoc/Welcome.html  • Revision control system • Some RCS implementation needed to control proper file management

20. Coding Style – Realities • Users come from various disciplines (e.g., Verilog, C, Java) • Users have personal preferences in • Style • Editor • Problem approach (e.g., IPs, structural, behavioral, pipeline) • Documentation (e.g., write now, document eventually) • Management often non-supportive (or non-technical) and fails to impose style rules (… must meet the planned schedule!)

21. Needed Conventions -- Enhance code readability –Use Approved Packages – for VHDL • Use approved IEEE packages • Std_logic_1164 (accelerated in most simulators … run faster than "bit". • Numeric_Std (Synopsys packages are not only non-standard) • Provides operations on SIGNED and UNSIGNED vectors • If design also uses arithmetic operations with vectors interpreted as UNSIGNED, then use IEEE.Numeric_Std.Unsigned type • Type conversions needed if Std_logic_Vector is used • However, if Std_logic_Vector is always treated as UNSIGNED, then Numeric_Unsigned, derived from Numeric_Std can be used as an alternative. • This feature must be used with caution because it is easy to make a mistake with signed and unsigned numbers. • Text_IO • For testbench and debug

22. Needed Conventions -- Enhance code readability –Useful Packages Awaiting Approval– for VHDL • Use following useful packages, which will have a version approved by the IEEE in the future: • Numeric_extra (Mentor package for reducing Operators)(Note: IEEE is working on a reduce_pack package. See http://www.eda.org/vhdlsynth • Synopsys Std_Logic_TextIO • (Note: IEEE is working on standardizing). • Floating Point • Currently in process of standardization:http://www.eda.org/fphdl/ • DO NOT USE Synopsys Std_logic_arith • Not approved, not IEEE, not a standard!

23. Needed ConventionsUse Approved Types with Guidelines – for VHDL • Use Std_Logic Std_Logic_Vectors for ports of top-level component • Subblocks may also use • Constrained Integers • Numeric Unsigned / Signed • Use Boolean for subblocks with GREAT caution • Must NOT compile subblock separately (interpretation of “TRUE” is not necessarily consistent between subblocks) • Use records and aliases with caution • May not synthesize well

24. Port Headers Style Pg. 379 The Verilog primitive modeling style established a preference in defining port interfaces in the following order for each interface grouping(e.g., PCI bus, RS232 bus, VBUS): 1. Outputs first 2. Inputs second 3. Control signals third 4. Clock and reset last. Maintaining a consistent style is highly recommended.

25. Needed Conventions-- Notations -- • Ports/Signals/Variables • Define in lower case. This is controversial topic. * Verilog uses lower case for signals.* Many users prefer to avoid to mixed-case • Constants • Define in uppercase (e.g., WIDTH, LENGTH, SIZE, SYNC_PATTERN) • Follows C/C++ notation

26. Needed Conventions-- Notations -- • Polarity • Use _n (for negative) or _f (false) suffix to infer objects that are active low. • Registers • Use _r or _reg to denote register. • If registers are pipelined, use a number to indicate depth of pipeline: data_1r data_2r data_3r -- depth of pipeline enb_1rn enb_2rn enb_3rn -- depth + polarity

27. Clarifying Levels of Pipelining-- SinglePipeline-- Pipeline_Proc: process is begin -- process Pipeline_Proc if clk'event and clk = '1' then data_1r <= data_in; data_2r <= data_1r; data_3r <= data_2r; end if; end process Pipeline_Proc; Suffix identifies level of pipelining Data_In DATA_1R DATA_2R DATA_3R Clk

28. Clarifying Levels of Pipelining-- MultiplePipelines-- Pipeline_Proc: process is begin -- process Pipeline_Proc if clk'event and clk = '1' then cpu_data_1r <= fifo_data_1r; cpu_data_2r <= cpu_data_1r and fifo_data_1r; cpu_data_3r <= cpu_data_2r; end if; end process Pipeline_Proc; Prefix denote source of data, suffix identifies level of pipelining Data_In CPU_DATA_1R fifo_data_1r CPU_DATA_2R CPU_DATA_3R Clk

29. Pg. 34 VHDL Naming Convention Summary Suffix Explanation Example _Pkg Package identifier package Design_Pkg is _Lib Library identifier library ProjectX_Lib; _Cfg Configuration identifier configuration EEPROM_Cfg of _Typ Type or subtype identifier subtype Read_Typ is Integer range 20 downto 18; (IDLE, FETCH, DECODE, EXEC); _Enum enumerat ion type State_Enum is Integer range 15 dow nto 0; _range integer range subtype Addr_range is type Mem_array is array (0 to 1024) of STD32_stdv; _array array type Instr_rec is record … _rec record Boolean; type Pointer_acc is access _acc _pntr access

30. Pg. 34 VHDL Naming Convention Summary _f : File _r, _2r, _3r : Register and pipeline level (see next slides) _n : active Negative (low) _in, _out, _io, _tri : Direction of port ??? Controvertial ??? _nxt : FSM next state from combinational logic UPPER CASE : Constants and Generics

31. Synthesis Guidelines • Apply coding guidelines defines in Reuse Methodology Manual for System-on-a-Chip Designs, Third Edition Michael Keating, Pierre Bricaud, ISBN 1-4020-7141-8 Kluwer Academic Publishers2002 • Book considered industry standard in synthesis guidelines • Follow IEEE recommended language restrictions for synthesis from IEEE P1076.6, Standard for VHDL Register Transfer Level Synthesis • http://vhdl.org/siwg/ http://standards.ieee.org/catalog/ (Note: New version is currently in development) • The current approved version closely supports existing synthesis tools. • Apply synthesis directives (atttributes/pragmas) into HDL code • When supported by vendors, follow Verilog Synthesis Interoperability IEEE PAR 1364.1 http://www.eda.org/vlog-synth/ (Spec was approved) • Support may be available by 2003/2004 • Other references • RTL Coding and Optimization Guide for use with Design Compiler, Jack Marshall, SNUG San Jose 2002 • Device Architecture independent efficient design & coding techniques for FPGA/ASIC designs, SNUG San Jose 2002 • Verilog HDL Coding, SRS07, HDL V2.0, Motorola

32. Rate Design with OpenMore • Use OpenMore spreadsheet as starting point for measuring quality of design. Addresses: • System-Level Design Issues: Rules and Tools • RTL Coding Guidelines • Macro Synthesis Guidelines • Verification Guidelines • System -Level Verification • Deliverable Guidelines • Provides a rating measure and points to consider when reviewing a design • OpenMORE (http://www.openmore.com) is a reference scoring program for assessing the reusability of hard and soft IP cores for SoC design. MORE is an acronym that stands for Measure of Reuse Excellence and the "open" refers to the fact that everyone has access to this program. The assessment program is based on the Reuse Methodology Manual (RMM), jointly authored by Mentor and Synopsys. It includes the complete set of rules and guidelines from the Synopsys MORE program, which was itself based on the original RMM; the recently released RMM Second Edition; and key deliverables from the Virtual Socket Interface Alliance (VSIA) industry group.

33. Coding Style -- FSM • Issues • 1, 2, or more processes ? • One or more FSMs ? • Hot controversy! • “Safe” design style (i.e., recover from deadlock because of alpha particle hit or a physical defect in the target part).

34. FSM: 1, 2, or more processes? 1, 2, 3 ONE PROCESS 2 1 THREE PROCESSES 3 • Combinational logic • State memory (Flip-flops) • Outputs

35. FSM: Two or More Processes Arguments • RMM (page 110) recommendation • Many synthesis vendor recommendations • One process description enforces all outputs from registers. This may not always be desired. • Easier to make changes when access to next state is needed by other logic. • Synthesis times may vary greatly (i.e., 2 process FSMs synthesize faster). • Multiple FSMs designs more amenable to the two-process style for synchronization (one FSM knows next state of other FSM) FSM1_State_Reg FSM2_State_Reg

36. FSM: One Process Argument • Easier maintenance • Less signals/variables • No current and a next per register • Less code. That makes easier. • Can embed counters, shift registers, and other sequential logic within the SM where they are (usually) easier to understand. • Allows variables for state vectors and other intermediate nodes that would need to be signals in a two-process SM. • Timing more predictable since all outputs from SM are registered.

37. FSM: One Process Arguments • Multiple processes (SM) can be defined in one process: • Reduce the number of state variables from 10 to 5 • Reduce process overhead from 10 to 1. • Improve the clarity of the logic. • By making the state variables VHDL variables, all of the five state values can be tested at any time, by any statement. • “Need by other processes to access the "next_state" D input can be emulated with multiple variables in a single clocked process. • Code easier to understand and trace because it flows sequentially rather than jumping from process to process. • Fewer this_state/next_state confusion factors. • Output signals can be assigned in the state cases or anywhere else in the process. • Single-process style simulates much faster • Less risk of creating latches when not all objects are assigned in all paths

38. Multiple FSMsOne or more Processes? • Multiple FSMs • Smaller independent FSMs, synchronized with "enable" signals • Easier to partition functions, build, and debug • Single FSM • synchronized with "enable" variables? . • Example: Machine receives an instruction, and performs one of the following: 1. Complex arithmetic operation (multiple cycles) 2. Complex bus interface 3. Memory block transfer • If 4 FSMs, then 1. MAIN controller FSM Coordinate the "firing" of the desired FSM based upon the instruction. Return is handed back to MAIN at end of operations. 2. Complex ALU FSM 3. Complex bus interface FSM 4. Complex block transfer FSM. • If ONE FSM • One large process • Variables express various FSMs state registers • Best designed by one individual

39. Recommended StyleOne or More FSMs? • Some designs absolutely need the multiple processes style • Complexity • Potential latency • Multiple designers • Both types have their uses • Function of complexity • Simple few states (<10 ?) => One FSM • >10? state complex control machine => Multiple FSMs recommended • There is no right answer for all situationsSeveral users built complex machines with one FSM

40. “Safe” FSM Design Style • GOAL: • Recover from deadlock (alpha particle hit or a physical defect) • Synthesis tools getting better: • Reachability analysis (i.e., all the states that could possibly be reached) • Optimize away (by default) all states and transition logic that can not be reached. • Can provide safe implementation with • Directive “safe” • Avoids any possible hang conditions (if the state machine should ever reach an invalid state, it will be forced to the reset state.) • Minimal impact on the timing of the circuit • Exact Implementation (vector definition of all legal states, and action to take in fsm for all illegal states (i.e., the “when others =>”). • More costly in resources and speed (~1.7 slower) than “safe” • “Safe” directive is synthesizer dependent • attribute syn_encoding of state : signal is "safe, onehot“;

41. Coding Style --sync/async set/Resets ? • Religious issue ! • Function of libraries • FPGA FFs provide built-in asynchronous Set/Reset • Synchronous reset would cost an input, and possibly cost more area and delays (more cells needed) • Many async designs CAN NOT be proven to work with timing analysis tools and/or simulation.  • Synchronous designs are easy to analyze for timing.   • In a system with multiple clocks with different stabilization  times, each clock domain should reset synchronously within its time domain. • With synchronous reset, must make sure, that during reset the clock is running (clock source may require an input)

42. RESET Synchronous/Asynchronous/Safe? • FPGA/ASIC Technology • When are input/outputs unblocked after power-up? • When are Phase Lock Loop clocks stabilized? • Crystal oscillator start-up time • PLL lock time • When asynchronous reset takes effect? • How safe is mission critical hardware from bad resets? • Availability of flip-flops with synchronous reset pins and ability of the designer and synthesis tool to make use of those pins (with attributes or directives) • Availability of asynchronous reset pins • Internal charge pump effect • Output values during this transition time

43. Synchronous/Asynchronous/ Asynchronous Reset ON with Synchronous OFF ? • Function of technology • FPGAs are more efficient with asynchronous reset (privitives) • Reset layout • Popular approach is Asynchronous Reset ON with Synchronous OFF ? (see next slide) • Acceptable approach is synchronous reset • Not all FFs need to be reset • Reduces load on reset control • However, may be problematic on regression or self-tests.

44. Asynchronous Reset Activation and Synchronous Release           +-----+           +-----+ clock ---|>    |  clock  --|>    |          |     |           |     | reset -+-|D   Q|-----------|D   Q|---reset-out       | +--O--+           +--O--+     |____|_________________| • Reset-out active immediately, but release after two clock edges.  • Full clock period for all downstream logic to respond to reset • Puts the logic in the reset circuit, and leaves the logic on the D input untouched.

45. Lesson Learned: Protect mission critical hardware from being impacted by bad reset • Delay Power Valid using analog circuit (Not a function of clocks or resets) until all FPGA/ASIC stabilize. • Use delayed Power Valid signal as control to switch off power to mission critical hardware • Relay /Solid State switch

46. Verification GuidelinesDefine and Review Verification plan • Compliance to requirements plan • Testbench architecture with considerations to: • Reusability / ease of use / portability / verification language • Number of Bus Functional Models (BFMs) to emulate separate busses • Synchronization methods between BFMs • Transactions definition and sequencing methods • Transactions driving methods • Verification strategies for design and its subblocks • Compliance Matrix • Tools

47. Use Transaction Verification Method • Transactions defined in verification plan • READ, WRITE, RNDM_DATAm IDLE, RESET, DISPLAY, MODE, READ_UNTIL, ENVSETUP, CALL, SYNC, WAIT4INTERRUPT • Easier for reviewers • Recognize transactions asserted as directed and random tests • Relate transactions to requirements/architecture • Relate transactions to subblock testing

48. Transaction Based Testbench

49. Review Checklist • Functional requirements • System implications • Consistency/parallelism in definition of information (e.g., status register, Control bits) • Appropriate technology • Radiation / speed / density • Fault recovery • SEU / failure • Mission critical safety • Partitioning • Use of GENERATE and GENERIC / parameter features as discriminant when instantiating models with variants. • FSM approach • Resets • Coding style • Synthesis rules • Synthesis directives in code • Documentation / schematics • Verification approach