Coding Standards

Table of Contents

You will be creating several types of files to complete the laboratories in this course (SystemVerilog, Tcl, etc.). You are required to adhere to a number of coding standards for all file types as well as language-specific coding standards for all files you submit for your ECEN 320 labs. Your code will be reviewed by a TA based on these coding standards, and you may lose points on your submission for failing to follow these coding standards. This document is broken up into General Coding Standards for all files created independent of the language and Language Dependent Standards that specify standards specific to each of the languages for which you create code or files.

Each coding standard has an acronym that will be used during grading. Your feedback on coding standard violations will include the coding standard acronym instead of a detailed description of the violation. Refer to this page for details on the coding standard acronyms.

General Coding Standards

  • G1: Any code you submit must be submitted as a plain ASCII text file. Files with non-binary characters are not accepted. If you can open your file with a conventional text editor and view its contents then the file is probably a text file. As a plain ASCII text file, your file should not have any non-printable control characters anywhere within the file (these characters sometimes show up as boxes or symbol characters in a text editor).

File Header

  • G2: Every code file submitted as part of the labs must have a ‘header’ using the language specific comment mechanism (some generic text/non-code files may be required that do not require a header). The header of every file must include each of the following items:
    • G3: Opening and Closing Line: Provide a line of characters to signify the start of the comment. Provide a line of characters to signify the end of the comment.
    • G4: Filename: Clearly specify the filename of the file.
    • G5: Author: Put your full name (matching your learning suite name).
    • G6: Description: Provide at least one complete sentence describing the purpose of the file.
      • Write the description as if a company were providing this module to its users or clients. You’d want the description to be clear, well-written, and fully explain the module’s purpose in at least one complete sentence. If a single sentence isn’t enough to clearly convey the purpose of the module, adding more detail is encouraged.

The example below demonstrates an example basic header for a SystemVerilog file:

/***************************************************************************
* 
* Filename: filename
*
* Author: <Your Name>
* Description: <Provide a description of what this HDL file does>
*
****************************************************************************/

Additional items for the header may be added for different file types or for lab-specific situations.

White Space

  • G7: Sufficient white space must be provided to make the file easy to read.

White space (extra empty lines) is often used to break up text files and make them more readable. Code that is crammed together without any white space is hard to read and messy. Every source file must have ample white space to separate sections of your code into easily distinguishable code regions. Some language coding standards have specific white space requirements. Your code may be penalized if there is insufficient white space that makes the code difficult to review or read.

Line Length

  • G8: You should not have lines that are longer than 90 columns. If you have a line of code that is getting long, make sure you end it and finish the logic/code on the next line. Source code that is longer than ~90 or so columns can be difficult to read and maintain.

Indentation

  • G9: Indentation will be used in the code to show its structure. It should be clear from the indentation which structural element the text is a member of.

System Verilog Coding Standards

HDLs (Hardware Description Languages) like SystemVerilog can be difficult to understand. To make SystemVerilog code more readable and maintainable, you are required to follow strict coding standards. These standards are explained below. Each and every lab will be graded against this coding standard.

Files

  • S1: A new .sv file will be created for every SystemVerilog module you create. Only one module may be defined in a single .sv file.
  • S2: The name of any SystemVerilog file you create must match the name of the module it contains. For example, if you have a SystemVerilog file with a module named FourFunctions, the filename will be FourFunctions.sv.

Signals

  • Signal types:
    • S6: Declare module inputs as input logic.
    • S7: Declare module outputs as output logic.
    • S8: Declare internal signals as logic.

      • The keywords reg, wire, var, bit, int, genvar, etc., are NOT allowed to be used anywhere in the module.

  • Signal names:
    • S10: Use descriptive signal names or provide comments to clarify their purpose.
      • Signal names must be descriptive (e.g., clrTimer instead of n7). If a signal name is not inherently descriptive, a comment must be included to explain its purpose.
      • Be careful—what is considered “descriptive enough” is subjective. Every semester, students lose points for assuming n5 is clear when the TA does not. Err on the side of clarity or always add a comment that explains the signal’s purpose.
    • S11: Use an _n suffix for active low signals (e.g., write_n).
    • S12: Do not use initializers when declaring signals.
      • For example, this is incorrect: logic nextState = 0;.
      • Instead, declare signals like logic nextState;. If a signal needs to be initialized to some known value, use a control signal (like clr) to set it.

Comments

  • S13: Each always_ff block and every always_comb block will be preceded by a comment describing its function and how it should operate.
  • S14: Each module instantiation should be preceded by a comment describing its purpose.

Design Requirements

  • S16: The only assignment operator allowed in an always_ff block is <=. The only assignment operator allowed in assign statements and always_comb blocks is =.
  • S17: In an always_comb block, every signal being driven must have a defined value. This requirement can be satisfied in one of two ways:
    • Assigning default values to all signals at the start of the always_comb block.
    • Including a default clause in a case statement when it is the only logic determining the signal values in the always_comb block.
    • Either or both approaches are acceptable, but at least one must be used to prevent unintended latching behavior.
  • S18: Every always_ff block must include functionality allowing the registers within the block to be set to known values via the assertion of a rst, clr, or load signal. Exceptions to this rule include:
    • Using synchronizer registers
    • Something like a shift register which will eventually shift in known data and therefore which does not necessarily require an explicit rst, clr or load signal. You must clearly document why a ‘rst’ is not used in such instances.
  • S19: Create a separate always_ff block for each register in your design. Do not assign multiple registers within a single always_ff block. Exceptions:
    • Multiple signals may be placed in the same always_ff block only if it serves as a synchronizer.
    • Closely related signals, such as synchronizers, may be grouped together.
    • When inferring BRAMs or other complex logic where FPGA primitives are automatically inferred by the synthesis tool.

Reset Requirements

  • S20: If a module requires a reset (rst), it must be structured properly to ensure correct synthesis and behavior. Specifically:
    • No code is allowed outside the if-else structure of the reset in the always_ff.
    • The reset condition must come first in the always_ff block as the condition to the if statement.
    • The reset signal must not be combined with other conditions using ||. See the note below the example for an explanation.
    • If both rst and a separate clear signal of any kind (such as clrTimer) are required, rst must take precedence within the if-else structure, with the clear signal (such as clrTimer) appearing in the else block.
    • The always_comb does not need and should not use a reset signal, but should instead rely on defaults. Only always_ff blocks need a reset signal.
    • The always_ff structure should be similar to the following:
always_ff @(posedge clk) begin
    if (rst) begin
        // Signals to be reset should be placed here
    end else begin
        // All other sequential logic and conditions for the always_ff must be placed within here
    end
end

The reason the rst should not be ORed (||) with other conditions is because doing so can prevent proper inference of asynchronous reset flip-flops. Combining rst with other logic may also introduce unintended combinational paths, which can disrupt timing and synthesis, potentially inserting additional logic between the rst and the flip-flop.

Style

  • S21: The code for different submodules in a module will be grouped together with comments separating them. For example, the statements associated with the timer circuitry will appear together, followed by the statements associated with the bit counter circuitry, followed by the state machine. Each such section of circuitry will have comments delimiting it.
  • S22: Local signal declarations (e.g., localparam, state machine signals, internal logic signals, etc.) will come just after the module definition and its port declarations.
  • S23: Naming Conventions for Signals, Modules, and Constants
    • Consistent and descriptive naming improves readability and maintainability. The following conventions apply:
    • Signal Names:
      • Use either camelCase (e.g., clearTimer, resetConfigurationRegisters) or snake_case (e.g., clear_timer, reset_configuration_registers).
      • Choose one style and be consistent throughout your code.
    • Module Names:
      • Use either PascalCase (e.g., EventCounter, InitializationRegisters) or snake_case (e.g., event_counter).
      • For this course, we will primarily use snake_case for module names.
    • Constants: (e.g., parameter or localparam types)
      • Use UPPER_SNAKE_CASE (a.k.a. SCREAMING_SNAKE_CASE) (e.g., INIT_VAL, THRESHOLD, DATA_WIDTH).

Conclusion

Why would any of this be important? This is the way that design is done in industry (except their style rules are much more extensive and may take many pages to describe). In a large design with millions of signals and thousands of modules, this adds uniformity to the design to help make the code more readable, understandable, and maintainable.