APPENDIX A CODING GUIDELINES There have been many sets of coding guidelines published for Ver- ilog, but historically they have focused on the synthesizable subset and the target hardware structures. Writing testbenches involves writing a lot of code and also requires coding guidelines. These guidelines are designed to enhance code maintainability and read- ability, as well as to prevent common or obscure mistakes. Guidelines can The specifics of a guideline may not be important. It is the fact that be customized. it is specified and that everyone does it the same way that is impor- tant. Many of the guidelines presented here can be customized to your liking. If you already have coding guidelines, keep using them. Simply augment them with the guidelines shown here that are not present in your own. Define guide- Coding guidelines have no functional benefits. Their primary con- lines as a group, tribution is toward creating a readable and maintainable design. then follow Having common design guidelines makes code familiar to anyone them. familiar with the implied style, regardless of who wrote it. The pri- mary obstacle to coding guidelines are personal preferences. It is important that the obstacle be recognized for what it is: personal taste. There is no intrinsic value to a particular set of guidelines. The value is in the fact that these guidelines are shared by the entire group. If even one individual does not follow them, the entire group is diminished. Enforce them! Guidelines are just that: guidelines. The functionality of a design or testbench will not be compromised if they are not followed. What Writing Testbenches using SystemVerilog 371 Coding Guidelines will be compromised is their maintainability. The benefit of follow- ing guidelines is not immediately obvious to the author. It is there- fore a natural tendency to ignore them where inconvenient. Coding guidelines should be enforced by using a linting tool or code reviews. See the Verifica- The guidelines presented in this appendix are simple coding guide- tion Methodol- lines. For methodology implementation guidelines, refer to the Ver- ogy Manual for ification Methodology Manual for SystemVerilog. That book is SystemVerilog. entirely written as a series of guidelines to implement a state of the art verification methodology using SystemVerilog. FILE STRUCTURE Use an identical directory structure for every project. Using a common directory structure makes it easier to locate design components and to write scripts that are portable from one engi- neer's environment to another. Reusable components and bus-func- tional models that were designed using a similar structure will be more easily inserted into a new project. Example project-level structure: .../bin/ Project-wide scripts/commands doc/ System-level specification documents SoCs/ Data for SoCs/ASICs/FPGA designs boards/ Data for board designs systems/ Data for system designs mech/ Data for mechanical designs shared/ Data for shared components At the project level, there are directories that contain data for all design and testbench components for the project. Components shared, unmodified, among SoC/ASIC/FPGA, board and system designs and testbenches are located in a separate directory to indi- cate that they impact more than a single design. At the project level, shared components are usually verification and interface models. Some “system” designs may not have a physical correspondence and may be a collection of other designs (SoCs, ASICs, FPGAs and 372 Writing Testbenches using SystemVerilog File Structure boards) artificially connected together to verify a subset of the sys- tem-level functionality. Each design in the project has a similar structure. Example of a design structure for an SoC: SoCs/name/ Data for ASIC named "name" doc/ Specification documents bin/ Scripts specific to this design tl/ Transaction-level model rtl/ Synthesizable model syn/ Synthesis scripts & logs phy/ Physical model and SDF data verif/ Verif env and simulation logs SoCs/shared/ Data for shared ASIC components Components shared, unmodified, between SoC designs are located in a separate directory to indicate that they impact more than a sin- gle design. At the SoC level, shared components include bus-func- tional models, processor cores, soft and hard IP and internally reused blocks. Use relative pathnames. Using absolute pathnames requires that future use of a bus-func- tional model, component or design be installed at the same location. Absolute pathnames also require that all workstations involved in the design have the design structure mounted at the same point in their file systems. The name used may no longer be meaningful, and the proper mount point may not be available. If full pathnames are required, use preprocessing or environment variables. Put a Makefile with a default 'all' target in every source directory. Makefiles facilitate the compilation, maintenance, and installation of a design or model. With a Makefile the user need not know how to build or compile a design to invoke “make all”. Top-level make- files should invoke make on lower level directories. Writing Testbenches using SystemVerilog 373 Coding Guidelines Example “all” makefile rule: all: subdirs ... SUBDIRS = ... subdirs: for subdir in $(SUBDIRS); do \ (cd $$subdir; make); \ done Use a single module, interface, program or package in a file. A file should contain a single compilation unit. This will minimize the amount of recompilation in incremental compilation simulators. It will also simplify identifying the location of components in the file system. Specify files required by the current file using the `include directive. Whether you include a file using the ‘include directive or by nam- ing it on the command line, the result is the same. A SystemVerilog compilation is the simple concatenation of all of its input files. If each file includes all of the file is depends on to compile success- fully, you only need to specify one file on the command line: the top-level file. Surround source files with ‘ifndef, ‘define and ‘endif directives. It is very likely that more than one file would depend on the same file. If each file includes all of the file it depends on, the file would included more than once, causing compilation errors. By surround- ing source files with conditional compilation directives, it will be compiled only once, even if it is included multiple times. ‘ifndef DESIGN__SV ‘define DESIGN__SV module design(...); ... endmodule ‘endif 374 Writing Testbenches using SystemVerilog File Structure Filenames Name files containing SystemVerilog source code using the *.sv suffix. Name files containing Verilog-2001 source code using the *.v suffix. SystemVerilog introduced new reserved words that may have been used as user identifiers in Verilog-2001 source code. Tools must have a way to differentiate between the two versions of Verilog. Use filename extensions that indicate the content of the file. Tools often switch to the proper language-sensitive function based on the filename extension. Use a postfix on the filename itself if different (but related) contents in the same language are provided. Using postfixes with identical root names causes all related files to show up next to each other when looking up the content of a direc- tory. Example of poor file naming: design.svt Testbench design.svb Transaction-level model design.svr RTL model design.vg Gate-level model Example of good file naming: design_tb.sv Testbench design_tl.sv Transaction-level model design_rtl.sv RTL model design_gate.v Gate-level model Writing Testbenches using SystemVerilog 375 Coding Guidelines STYLE GUIDELINES Comments Put the following information into a header comment for each source file: copyright notice, brief description, revision number and maintainer name and contact data. Example (under RCS or CVS): // // (c) Copyright MMCC, Company Name // All rights reserved. // // This file contains proprietary and confidential // information. The content or any derivative work // can be used only by or distributed to licensed // users or owners. // // Description: // This script parses the output of a set of // simulation log files and produces a // regression report. // // Maintainer: John Q. Doe <[email protected]> // Revision : $Revision$ Use a trailer comment describing revision history for each source file. The revision history should be maintained automatically by the source management software. Because these can become quite lengthy, put revision history at the bottom of the file. This location eliminates the need to wade through dozens of lines before seeing the actual code. Example (under RCS or CVS): // // History: // // $Log$ // 376 Writing Testbenches using SystemVerilog Style Guidelines Use comments to describe the intent or functionality of the code, not its behavior. Comments should be written with the target audience in mind: A junior engineer who knows the language, but is not familiar with the design, and must maintain and modify the design without the benefit of the original designer’s help. Example of a useless comment: // Increment i i++; Example of a useful comment: // Move the read pointer to the next input element i++; Preface each major section with a comment describing what it does, why it exists, how it works and assumptions on the environment. A major section could be an always or initial block, an interface, a clocking block, a task, a function, a program, a class or a package. It should be possible to understand how a piece of code works by looking