Coding guidelines

From Zet
Jump to: navigation, search

This coding guidelines are created to have a common style among all developers. These rules apply for Verilog source files, as they are the ones used in the project.

1. All source files should start with the standard copyright header.

  • On the first line a brief description of the module
  • On the following line the Copyright holder for that file
  • Following, the GPLv3 preamble. This is an example:
/*
 *  Instruction decoder for Zet
 *  Copyright (C) 2010  Zeus Gomez Marmolejo <zeus@aluzina.org>
 *
 *  This file is part of the Zet processor. This processor is free
 *  hardware; you can redistribute it and/or modify it under the terms of
 *  the GNU General Public License as published by the Free Software
 *  Foundation; either version 3, or (at your option) any later version.
 *
 *  Zet is distrubuted in the hope that it will be useful, but WITHOUT
 *  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 *  or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
 *  License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with Zet; see the file COPYING. If not, see
 *  <http://www.gnu.org/licenses/>.
 */

2. Each file must contain only one single module. In addition, the module name must be exactly the same as the file name plus the .v extension. For example, the file zet_core.v should contain only the module zet_core.

3. For modules that belong to a core, their name should be first the name of the core and then the submodule. The top level module for the core should simply have the name of the core as the module name. For example, the decode module of zet core should be named zet_decode. The top level module for the zet core should be named zet.

4. All module names, inputs, outputs, wires and regs should be in lower case. This means that all filenames and directories must be in lowercase too.

5. All wires and register declarations must come first in the module. As there are some simulators that doesn't allow using them before declaring them. In addition, never do a direct assignment in the declaration, use the assign keyword:

wire ps_ibf;
...
assign ps_ibf = ibf;

6. Everything must be written in English.

7. Every input, output, register and wire must have a one line comment describing its purpose.

Inputs and outputs

8. All inputs and outputs from a module must end in _i and _o respectively.

9. All module instantiations and module declarations must name explicitly inputs and outputs. Each input or output must be in a single line. For example, the instantiation of ps2_keyb_xtcodes would be as follows:

ps2_keyb_xtcodes keyb_xtcodes (
  .at_code_i (q[7:1]),
  .xt_code_o (xt_code)
);

White space

10. Never use a TAB character, indentation must use 2 space characters. There shouldn't be any trailing spaces left on any line. To accomplish this, it's always useful to turn on visible TABs and trailing spaces in the editor. For example, the Kate editor supports these. You can use the following sed command to perform this substitution in a file name file.v:

sed 's/ \{1,\}$//' file.v | sed 's/\t/  /' > file.v.new; mv file.v.new file.v

11. Code inside the module must be indented. This is to easily identify where the module starts and ends. Example:

module a (
);
  wire b;
endmodule