ECEN 323 Coding Standards

Table of Contents

You will be creating several different types of files to complete the laboratories in this course (SystemVerilog, tcl, assembly, memory text files, 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 323 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.

General Coding Standards

This section describes the standards that are required by all files you submit for the labs independent of the language.

File Type

Any code you submit must be submitted as a plain ASCII text file. Files that are not plain ASCII text will not be graded. 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

Every file submitted as part of the labs must have a ‘header’ using the language specific comment mechanism. The header of every file must include each of the following items:

  • Opening Line: Provide a line of characters to signify the start of the comment
  • Filename: clearly specify the filename of the file
  • Author: Put your full name (matching your learning suite name)
  • Class: Indicate the class name, section, and semester of the class <!– Using dates is becoming antiquated.
  • Date: Specify the date you first created the file –>
  • Description: Provide at least one sentence describing the purpose of the file.
  • Closing Line: Provide a line of characters to signify the end of the comment

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

/***************************************************************************
* 
* Filename: filename
*
* Author: <Your Name>
* Class: <Class, Section, Semester>
* Date: <Date file was created>
*
* Description: <Provide a brief description of what this HDL file does>
*
****************************************************************************/

Additional items may be added for different file types.

White Space

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 of the 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

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.

Language Specific Coding Standards

SystemVerilog Coding Standards

In addition to the basic header requirements described above, you need to include in your SystemVerilog file that indicates the name(s) of the modules that are defined in the file:

* Module: <module Name>

Signals

  • Use descriptive signal names clrTimer instead of n7. Other than simple iteration counters, all signals should have a descriptive name.
  • Use a _n suffix for active low signals (eg. write_n).
  • Do not give two different signals the same name but with different case (i.e. ‘HS’ and ‘hs’, or ‘nextState and ‘NextState’)

Magic Numbers

“Magic Numbers” are constants that are used within your code whose meaning or purpose are obscured or unknown. Magic numbers make it difficult to read and understand the code and even more difficult to maintain and debug. If a constant has meaning then replace the constant number with a defined constant that conveys the meaning.

Some constants directly used within your code are ok if the meaning is clear. For example, the constant ‘1’ in the code assign a = b << 1 is clear - the constant one clearly indicates a shift by one. The constant ‘0’ can also be used directly without explanation.

Constant values can be created in Verilog and SystemVerilog using parameters and local parameters as shown in the example below. By convention, constants should be CAPITALIZED.

localparam ADD_OP = 3'b000;

Note: There are several cases when constant numbers are preferred over a named constant variable. The intent of using constant variables is to provide meaning in the code. In some cases, the meaning of a fixed constant is very clear and the use of a named constant will only clutter the code. Avoid named constants for the following situations:

  • Use of “+1” or “-1”. Incrementing and decrementing are common operations in digital hardware and their meaning is very clear.
  • Fixed port widths (i.e. [7:0]). If the port widths are parameterizable then constant variables should be used.
  • Assignments to single bit signals to the value ‘0’ or ‘1’
  • Use of “0” (i.e., if a < 0) If you are unsure whether a constant should be replaced with a named constant, follow your instinct and provide a comment above the usage indicating. You will not lose points if you do not use a named constant while providing a comment.

Comments and White Space

Comments, indenting, and white space are essential for you and the TA to understand your code. The following guidelines with respect to code formatting are required for your code.

  • Comments
    • Every ‘always’ block must have a comment to briefly discuss the purpose of the block and any block-specific properties. You will lose points for every ‘always’ block that does not have a comment.
    • Module instantiations should have a brief comment
    • If the name of a signal is expressive enough (e.g. clrTimer) then a comment describing may not be needed. Otherwise, all signal declarations will have an associated descriptive comment.
  • Indentation
    • You must use proper indentation to demonstrate the structure of your code. Most editors can automatically add proper indentation. Make sure your code is properly indented when submitting your files. You will be penalized for improper indentation.
  • White Space
    • Provide at least one blank line between before and after each of the following syntactical structures
      • ‘always’ block
      • Module instantiation
    • Make sure your code is properly indented. Do not mix tabs or spaces for indentation - use tabs or spaces but not both.

SystemVerilog Style Standards

  • You cannot use always blocks: if you are using SystemVerilog you must use either always_comb or always_ff blocks.
  • always_ff blocks
    • The only assignment operator that you can use for always_ff blocks is the “<=” operator - you cannot use the “=” operator.
  • always_comb blocks
    • The only assignment operator that you can use for always_comb blocks is the “=” operator - you cannot use the “<=” operator.
    • Every always_comb block must begin by assigning default values to all signals being driven in the block.
  • Signal types:
    • Declare module inputs as input wire logic
    • Declare module outputs as output logic
    • Declare internal signals as logic
    • The keywords reg, and var are not allowed to be used, and wire can only be used for inputs as input wire logic
  • Signal/Port Types:

RISC-V Assembly Language Coding Standards

Assembly language is very terse and difficult to review and read. Several simple coding styles can make the code much easier to follow. You are required to implement the following coding standards in all of your assembly language programs:

  • Header
    • In addition to the minimum header requirements described above, list the name of each callable subroutine
      • A subroutine is any group of code that executes the ‘ret’ instruction
      • A subroutine starts with a label but often will have other labels inside of it.
      • You don’t need to provide a comment for each label (although comments with labels are helpful)
  • Indentation
    • Indent your instructions by one tab
    • Align your labels to the first column (no space or indentation)
    • Do not place an instruction and label on the same line - place the first instruction for a particular label on the line below the label
  • Comments
    • Provide a comment for each subroutine you create (a subroutine is any code that executes the ‘ret’ instruction)
  • Magic numbers
    • “Magic Numbers” are often necessary and more clear in assembly language than in other programming languages. As such, it is acceptable for a constants embedded in your code for several situations:
      • Address offsets: (i.e., -12(sp) )
    • Avoid constant magic numbers whose meaning is unclear. Use the .eqv directive to specify a constant

Sample header:

#########################################################################
# 
# Filename: filename
#
# Author: <Your Name>
# Class: <Class, Section, Semester>
# Date: <Date file was created>
#
# Description: <Provide a brief description of what this HDL file does>
#
# Functions:
#  - factorial
#
#########################################################################

TCL Coding Standards

You will be creating a variety of TCL files for initial simulations of your SystemVerilog. The purpose of these TCL simulation files is to perform a quick and dirty simulation to make sure everything is hooked up correctly and performing basic functionality. TCL simulations are usually followed by a more thorough testbench simulation provided by the instructor. This section describes the requirements for creating .tcl files for your simulation. Like all file types, you are required to follow all ‘global’ coding standards for your .tcl files (header, comments, etc.).

The following list defines the TCL specific coding standards you will need to follow to receive full credit for your TCL files.

  1. Include a restart command at the start of your file. This will force the simulation to start over every time you execute the file. If you do not need this restart command include a comment explaining why a restart command is not included.
  2. Include a run statement after the restart to perform a short run with no signals defined (i.e., something like run 20 ns). The purpose of this run command is to run your circuit without any input stimulus so you can see a change in the system when the stimulus is provided.
  3. For circuits that include a clock, define your clock (i.e., add_force clk {0} {1 5} -repeat_every 10)
  4. After defining your clock, insert another run statement such that at least two clock cycles are simulated (again, before you have set your stimulus). The purpose of this run statement is to run the clock without any initialization and put your circuit in an invalid sate. It is important to make sure you can properly reset your circuit.
  5. Simulate a reset on your system by forcing the reset signal to ‘1’ and then running and then forcing the reset signal back to ‘0’.
  6. At this point, add all the appropriate stimulus you need to test your circuit.

In addition to the structure described above, follow the guidelines listed below in your TCL files:

  • Provide a comment for every major ‘group’ of related tcl commands. Every tcl command should be in such a group and preceded by a group comment. For example, add a comment such as # Simulate btnd being pressed for 20 ns and then released.
  • Add a comment at the end of the file indicating the end of simulation: # End of simulation

.xdc Coding Standards

No comments are required for .xdc files in this course. You may use the template .xdc file provided for the Basys3 board and comment/uncomment lines of this file as needed.

Last Modified: 2024-06-01 00:07:11 +0000