You will be creating several 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 423 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
• 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>
*
* 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

The SystemVerilog coding standards are based on the ECEN 320 SystemVerilog Coding Standards. Refer to this page for details.

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>
#
# 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.