Guidelines

Header

/*
    Project:    MARVIN
    Sector:     RAM/COM/CPU/USB/TOP/UTILS/etc.
    Summary:    
    Authors:    
    Device:     (Optional)
*/

Merging

• Use squashing whenever possible

Code formatting

Indentation

• Syntactic indentation
• 1 tab = 4 space characters

Code blocks

• "begin" always at end of first line of block, not at begin of second line

Comments

What to comment (examples)

• Ports and parameters
• Process purpose and procedure
• Custom types
• Parameters

What not to comment (examples)

• Standard ports (e.g. clk, rst, etc.)
• Every single step of a procedure (only comment important steps and group similar steps' descriptions)

Single-line comments

• <code> // <comment>
  

• Only for long comments and comments that cover several lines of code

  // <comment>
  <code>
  

Multi-line comments

• /*
      <comment>
  */
  <code>
  

Module structure (guideline only, can be reordered for better organization)

1. parameters
2. ports
   1. inputs
   2. inouts
   3. outputs
3. types
4. parameters
5. registers
6. wires
7. processes
8. assignments

Package structure (guideline only, can be reordered for better organization)

1. types
2. parameters
3. functions

Naming

• Variable names "_" in instantiation and just "" inside module

Short forms

• Short forms for reset 🠖 rst, clock 🠖 clk, reference 🠖 ref

Capitalization

• Everything small, constants in caps

Lowactivity

• Lowactivity is represented in variable name by underscore "_" character at the end, do not use "_n"

Range and width parameter names

• Range and width parameters may use "_" to point out it is being used for a width: <NAME>_ Using W, WIDTH, RANGE, etc. is not encouraged.

Vector ranges

• Vectors [x:y] "from x downto y" (x >= y)

Types

• Types only if necessary

Values

• Small letters (b,o,d,h) for representation, not in caps

Folder structure

• Project
  • src (saucecode)
    • toplevel
    • utils (utility modules, can be used anywhere)
    • com
      • vga
      • uart
      • i2c
      • usb
    • cpu
      • cu
      • alu
    • ram
  • qsys (Platform designer files)
  • quartus (Quartus files)
  • modelsim (Modelsim files)

Verible Linter

• File has to end with newline
• One module or package per file
• Entity name has to be equal to file name