Skip to content

Latest commit

 

History

History
108 lines (78 loc) · 4.64 KB

CODING_STYLE.md

File metadata and controls

108 lines (78 loc) · 4.64 KB

RISC-V Steel Coding Style Guides

Table of Contents

RISC-V Steel Verilog Style Guide

Introduction

Verilog-2001 is the main design language for RISC-V Steel IP.

Verilog can be written in vastly different styles, which can lead to code conflicts and code review latency.

This style guide aims to promote Verilog readability for RISC-V Steel IP. The goals are to:

  • promote consistency
  • promote best practices
  • increase code sharing and re-use

This style guide defines style for Verilog-2001 code, both synthesizable and test bench code.

Basic style elements

  • Use Verilog-2001 conventions, files named as module.v, one file per module
  • Only ASCII, 100 chars per line, no tabs, two spaces per indent for all paired keywords.
  • C++ style comments //
  • For multiple items on a line, one space must separate the comma and the next character
  • Include whitespace around keywords and binary operators
  • No space between case item and colon, function/task/macro call and open parenthesis
  • Line wraps should indent by four spaces
  • begin must be on the same line as the preceding keyword and end the line
  • end must start a new line

Naming conventions

  • Use lower_snake_case for instance names, signals, declarations, variables, types
  • Use ALL_CAPS for parameters, enumerated values, constants and define macros
  • Main clock signal is named clock. All clock signals must start with clock_
  • Reset signals are active-low and synchronous, default name is reset_n
  • Signal names should be descriptive and be consistent throughout the hierarchy. Avoid abbreviations

Suffixes for signals and types

  • Do not add suffixes like _i, _o or _io to indicate the direction of module ports
  • Active low signals should use _n

Language features

  • Use full port declaration style for modules, any clock and reset declared first
  • Use named parameters for instantiation, all declared ports must be present, do not use .*
  • Top-level parameters is preferred over `define globals
  • Use symbolically named constants instead of raw numbers
  • Local constants should be declared localparam
  • Sequential logic must use non-blocking assignments
  • Combinational blocks must use blocking assignments
  • Use of latches is strongly discouraged, use flip-flops when possible
  • The use of X assignments in RTL is strongly discouraged
  • Prefer assign statements wherever practical.
  • Always define a default case
  • When printing use 0b and 0x as a prefix for binary and hex. Use _ for clarity, e.g. 0x0000_0000
  • Use logical constructs (i.e ||) for logical comparison, bit-wise (i.e |) for data comparison
  • Bit vectors and packed arrays must be little-endian, unpacked arrays must be big-endian
  • FSMs: no logic except for reset should be performed in the process for the state register

RISC-V Steel C Style Guide

Introduction

C is the primary language used in software development for RISC-V Steel IP.

Like Verilog, C code can be written in vastly different styles, which can lead to code conflicts and code review latency.

This style guide aims to promote readability for RISC-V Steel software source code. The goals are to:

  • promote consistency
  • promote best practices
  • increase code sharing and re-use

Basic style elements

  • All source code must be clang-formatted
  • The .clang-format file with the style definitions can be found in the root folder of RISC-V Steel repository

Naming conventions

  • Use lower_snake_case for variables, functions and arguments
  • Use UpperCamelCase for structs
  • Use ALL_CAPS for enums, constants, register addresses and compiler macros
  • Names should be descriptive and be consistent. Avoid abbreviations

License Notice

This work, "RISC-V Steel Coding Style Guides", is adapted from "lowRISC Verilog Coding Style Guide" by lowRISC, used under CC BY 4.0.

RISC-V Steel Coding Style Guides is licensed under a different license, the MIT License.