SCOORE Coding Style

Synopsys dc_shell checks:
- No latches: Run “all_registers -level_sensitive” to list latches
- Check design: run “check_design”. It is OK to have warnings if you understand them.
- no threestate: “all_threestate -cells” should have an empty list
- full/parallel: dc_shell should automatically recognize all the case statements as full/parallel. If not, add a comment explaining why. E.g. output from dc_shell

===============================================
|           Line           |  full/ parallel  |
===============================================
|           ???            |    auto/auto     |
===============================================

Variable/Type Naming

Always use big endian. E.g. logic [n:0].

Create a typedef for each of your variables classes:

 typedef struct packed {
   BoolType              msb;
   logic [29-1:0]        mid; 
   BoolType              lsb;  
 } DataType;

All the variables should have a type ending with Type. E.g.: FooType

you should ONLY do assignments to a variable that finish either with _comb or _next.

Correct assignment examples:

 // _next variables have a flop (foo1_next has a foo1 flop output)
 foo1_next = bar1;     
 foo2_next = bar2_next; // May be too slow
 foo3_next = bar3_comb; // May be too slow

 // _comb variables are "wires" in real logic
 foo4_comb = bar4;
 foo5_comb = bar5_next; // May be too slow
 foo6_comb = bar6_comb; // May be too slow

Incorrect assignment example:

 foo1 = ...;

Comments

Do not overuse comments. Never comment “how” is done, comment “why” is done. The code explains the “how”, if it is not clear, re-structure. Code should be clean enough to understand it without comments. There are 3 keywords for comments:
- FIXME is used for functionality not working (should be fix as soon as possible)
- TODO is an improvement not implemented due to lack of time
- WARNING is for very weird behavior in a section of code

FSM Rules

Avoid tricks with encoding (one-hot, gray...). Let the tool choose. To do so, declare states as parameter:

parameter [2:0] // synopsys enum my_states
            IDDLE = 3’d0,
            S1    = 3’d1,
            ...
logic [2:0] /* synopsys enum my_states */ state;
logic [2:0] /* synopsys enum my_states */ state_next;

Remember that always @(posedge clk) are not allowed. Use flop_r as follows:

flop_r #(.Size(3), .Reset_Value(IDDLE)
 f1
 (.clk      (clk),
  .reset    (reset),
  .din      (state_next),
  .q        (state));

Big FSMs (>500LoC) should be implemented as separate module

System Verilog

Not all the System Verilog constructions are allowed (classes, unions, interfaces...). The code should constraint to:

Use const (avoid defines and ifdefs)

No more include files (*.h)

Use $bits(FooType) to know number of bits is data type.

Avoid reg/wire syntax. Use your custom types with logic.

Only use always_comb (no always @...)

Check System Verilog LRM for detailed System Verilog documentation.

Creating New Files

When creating a new file, add the same copyright notice (GPL2). Add a module description, and the file name to the xml file

Try to have only one module per Verilog file. The module name should match the Verilog file name

All file names must be lowercase

Before creating a new file check that the same functionality is not already implemented

Module Input/Output

All the clocked modules must be a “Synchronous Moore Machine”
- We use flops and pulse triggered latches. To make it transparent, use the “Synchronous Moore Machine” from the flops library
- All the inputs and outputs in the module are wires. The outputs are registered using the flops library

Flip-flops library available (storage/rtl/flop.v)
- flop: posedge flip-flop without reset
- flop_r: posedge flip-flop with reset. Reset_Value parameter can change the default reset value
- cgflop: posedge flip-flop with clock gating (enable)
- cgflop_r: posedge flip-flop with clock gating (enable) and reset

Modules without clock signal are assumed to be combinational logic only.

Port ordering: Declare one port per line. Use the following order:clock,reset, input (enable/busy, control, data), output (enable/busy, control data)

Clock/Reset

Clock properties:
- flip-flops use the posedge of the clock

Computer resets on high reset signal. Reset signal will be high for at least 32K full clock cycles. If you need to clear a table, iterate on different clock cycles (reset high)

Do not use any @(posedge ...) statement. If you need to use flip-flops use the flop library

flop #(.Size($bits(YourType))) 
  f1
   (.clk(clk), 
  .din(your_in),
  .q(your_out));

Use reset signal if necessary for functionality. Not all the modules have reset signal. RAM-like structures do not have reset signal. External state machine should clear the values if necessary.

No logic should use clock as input. Clock is only passed to structures in storage library

Blocking/Non-Blocking

Only use blocking assignments (=)

Combinational blocks only use blocking assignments (=). Synchronous blocks only use non-blocking assignments (<=). Since we do not have synchronous block. We only use non-blocking assignments on low level libraries like flops & memory_bank

Use always_comb on the sensitivity list. Do not add list of parameters.

always_comb begin
  case (sel) // 
    1'b0: y = a; 
    1'b1: y = b; 
    default: y = 1'bx; 
  endcase
end

Assign to the same variable in a single always block. Group together in the same always.

Emacs Verilog Mode

Do not use tabs, write spaces instead of tabs (tab stop is 2). If you use the emacs formating parameters found at the end of this document, this will be done automatically. The reason for not having tabs is that each person has a different setup

Column width. Do not to go over 80 columns (at least it should be very rare)

Use the following style for module instantiation (spacing)

mod_name
  (.clk       (clk)
   ,.reset    (reset)
   ...

If you use emacs get verilog-mode.el and copy it to

your .emacs.d directory. Then, set this options (.emacs) ("Library/Preferences/Aquamacs Emacs/Preferences.el" for Aquamacs).

 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; Load verilog mode only when needed
 (autoload 'verilog-mode "verilog-mode" "Verilog mode" t )
 ;; Any files that end in .v should be in verilog mode
 (setq auto-mode-alist (cons  '("\\.v\\'" . verilog-mode) auto-mode-alist))
 ;; Any files in verilog mode should have their keywords colorized
 (add-hook 'verilog-mode-hook '(lambda () (font-lock-mode 1)))
 (add-hook 'verilog-mode-hook '(lambda () (add-hook 'local-write-file-hooks
         (lambda() (untabify (point-min) (point-max))))))
 (setq verilog-indent-level           2
     verilog-indent-level-module      2
     verilog-indent-level-declaration 2
     verilog-indent-level-behavioral  2
     verilog-indent-level-directive   1
     verilog-case-indent              2
     verilog-auto-newline             t
     verilog-auto-indent-on-newline   t
     verilog-tab-always-indent        t
     verilog-auto-endcomments         nil
     verilog-minimum-comment-distance 40
     verilog-indent-begin-after-if    t
     verilog-auto-lineup              '(all))

Work Methodology Rules of Thumb (SVN)

This section describes basic working methodology that you should try to follow:

Synthesize frequently. Optimize area for FPGA and maintain the ASIC frequency target.

Use SVN frequently: Update every day, commit frequently
- “svn update” before and after editing a file
- “svn commit” every time that a change compiles
- “svn add <file>” whenever you create a new file

Always use the following commit keywords:
- Design phase:
  - CODING <bla bla bla>
  - NEW FEATURE <bla bla bla>
  - INCORRECT SPEC <bla bla bla>
- Solving bugs without integrating with other modules:
  - BUG SOLVED <bla bla bla>
  - BUG FOUND <bla bla bla>
- Final integration bugs (nobody should be doing this as we still do not talk between blocks)
  - Integration solved <bla bla bla>
  - integration found <bla bla bla>

Do not work more than 8 hours without a commit

Design peer review: You should explain your design to someone else before starting implementation. The explanation should include all the modules, inputs, outputs.

Write assertions as you code. Do not add them latter

After finding a bug, add an assertion to protect against it

Write testbenches for big components. Ex: IF0, cache

Refactor whenever you see something ugly

VPI Techbench

Most of the testbenches in SCOORE use VPI and share infrastructure across tests.

The testbenches are compiled with c++ (even if it is plain c code).

Each typedef System Verilog class has an equivalent C++ class to simplify passing parameters between Verilog and C++ testbench. The C++ class is defined in the rtl directory with a _tb.h extension E.g: the C++ VPI specification scoore/common/rtl/dinst_tb.h is the equivalent to the System Verilog scoore/common/rtl/dinst.v.

SCOORE Coding Style

Contents

Coding Rules

Variable/Type Naming

Comments

FSM Rules

System Verilog

Creating New Files

Module Input/Output

Clock/Reset

Blocking/Non-Blocking

Emacs Verilog Mode

Work Methodology Rules of Thumb (SVN)

VPI Techbench

Navigation menu

Views

Personal tools

Navigation

Search

Tools