Re: [oc] Coding Conventions are up

To: "OpenCores" <cores@opencores.org>

Subject: Re: [oc] Coding Conventions are up

From: "Ovi Lupas" <olupas@opencores.org>

Date: Sun, 13 Feb 2000 15:23:48 +0200

Reply-To: cores@opencores.org

Sender: owner-cores@opencores.org

Since we are at the Coding Conventios definition, I would like to add some features :

VHDL source layout

All models shall be fully documented with explanatory comments in English. The comments shall be placed close to the part of code they describe; a description only in the file header without comments in the executable part is not acceptable. All comments shall be indented and aligned for good readability. The comments shall be descriptive and not just direct translations or repetitions of the VHDL code. The purpose of comments is to allow the function of a model,package or testbench to be understood by a designer not involved in the development of the VHDL code.

Each file shall include a header, as a minimum containing the following information :

name of the design unit in the file;
file name;
purpose of the code, description of hardware modeled;
limitations to the model and known errors, if any, including any assumptions made;
design library where the code is intended to be compiled in;
list of all analysis dependencies, if any;
author(s) including full address;
simulator(s), simulator version(s) and platform(s) used;
change list, containing version numbers, author(s), the dates and a description of all changes performed.

Each subprogram declaration, subprogram, process, block shall be immediately preceded by a description of its function, including any limitations and assumptions. For subprograms, the parameters and result shall also be described.

Attached is, as an example, the layout of the TxUnit of the miniUART device that can be found in CVS.

Please feel free to comment. ;-)

>Any positive Criticism is Welcome @
>mailto: harish@opencores.org

For me, any criticism is most welcomed... ;-))

regards, Ovidiu

--===========================================================================-- -- -- S Y N T H E Z I A B L E miniUART C O R E -- -- www.OpenCores.Org - January 2000 -- This core adheres to the GNU public license -- -- Design units : miniUART core for the OCRP-1 -- -- File name : TxUnit.vhd -- -- Purpose : Implements an miniUART device for communication purposes -- between the OR1K processor and the Host computer through -- an RS-232 communication protocol. -- -- Library : uart_lib.vhd -- -- Dependencies : IEEE.Std_Logic_1164 -- --===========================================================================-- ------------------------------------------------------------------------------- -- Revision list -- Version Author Date Changes -- -- 0.1 Ovidiu Lupas 15 January 2000 New model -- olupas@opencores.org ------------------------------------------------------------------------------- -- Description : The TxUnit is the transmitter of the miniUART device. It sends 1 Start bit, 8 data bits and 1 Stop bit. ------------------------------------------------------------------------------- -- Entity for the Tx Unit -- ------------------------------------------------------------------------------- library ieee; use ieee.std_logic_1164.all; use ieee.numeric_std.all; library work; use work.Uart_Def.all; ------------------------------------------------------------------------------- -- Transmitter unit ------------------------------------------------------------------------------- entity TxUnit is port ( Clk : in Std_Logic; -- Clock signal ......................... DataO : in Std_Logic_Vector(7 downto 0)); end entity; --================== End of entity ==============================-- ------------------------------------------------------------------------------- -- Architecture for TxUnit ------------------------------------------------------------------------------- architecture Behaviour of TxUnit is ----------------------------------------------------------------------------- -- Signals ----------------------------------------------------------------------------- ........ begin ----------------------------------------------------------------------------- -- Implements the Tx unit ----------------------------------------------------------------------------- process(Clk,Reset,Enable,Load,DataO,TBuff,TReg,tmpTRegE,tmpTBufE) variable tmp_TRegE : Std_Logic; constant CntOne : Unsigned(3 downto 0):="0001"; begin ................... end process; end Behaviour; --=================== End of architecture ====================--