FPGA的Verilog代码编写规范

注：以R起头的是对编写Verilog代码的IP设计者所做的强制性规定，以G起头的条款是建议采用的规范。每个设计者遵守本规范可锻炼命名规范性。

4 注释(Comments)

注释可用于描述 Verilog HDL代码的功能，特别需要提醒设计者注意的是，只依靠读代码很难理解的设计意图必须在代码中添加注释加以说明。

4.1 文件头(File Headers)

每一个可综合的Verilog RTL级电路模块、虚拟器件和测试模块文件必须具有下面格式的文件头。设计规范规定：文件头的格式必须与下面的格式一致，以便于将来可用软件对模块代码进行分析处理。文件头中大写的关键词可以用来检索。下面的这个模板可以保证文件头的一致性。下面所示的文件头只是最小要求。在“REUSE ISSUE”段之后，还可以再添加其他的文件头.另外，有关版权的文件头也应该包括在文件头中。

// +FHEADER-----------------------------------------------------------------

// Optional Copyright (c)

// Optional Company Confidential

// ----------------------------------------------------------------------

// FILE NAME :

// DEPARTMENT :

// AUTHOR:

// AUTHOR’S EMAIL :

// --------------------------------------------------------------------

// RELEASE HISTORY

// VERSION DATE AUTHORDESCRIPTION

// 1.0 YYYY-MM-DD name

// ---------------------------------------------------------------------

// KEYWORDS : General file searchinGkeywords, leave blank if none.

//-----------------------------------------------------------------------

// PURPOSE : Short description of functionality

// ----------------------------------------------------------------------

// PARAMETERS

// PARAM NAME  RANGE : DESCRIPTION : DEFAULT : UNITS

// e.g.DATA_WIDTH [32,16] : width of the data : 32 :

// ----------------------------------------------------------------------

// REUSE ISSUES

// Reset Strategy :

// Clock Domains :

// Critical TiminG:

// Test Features :

// Asynchronous I/F :

// Scan Methodology :

// Instantiations :

// Synthesizable (y/n) :

// OtheR:

// -FHEADER-------------------------------------------------------------

R 4.1 每个文件必须有文件头(header)

每一个文件必须包括如上面代码段所示的文件头。其中，所有的区域都必须包括在内，甚至空的数据段。

原因：按照规范编写的标准文件头便于建立公司内部的设计信息查询系统。

R 4.2 使用文件头界定标记 [+FHEADER & -FHEADER]

标签+FHEADER& -FHEADER一定要用来定义头信息的界限。(the boundary of the 文件头
information)

原因：这是识别文件头的简单方法，标明该头是文件头，便于用文本工具自动地查询存档的资料。

R 4.3 文件头内必须包含文件名

文件头中必须包含文件名

原因：这样做提供了一种简单的方法以便用文本处理工具自动地查询相关的设计文件。

R 4.4 文件头中必须包含联系方式

文件头中必须包含有关本代码的多种信息，其中包括开发小组的名称、作者名、版本历史、作者电话、电子邮件和邮寄地址。

原因：必要时可以找到原作者询问只从设计文档无法理解的问题。

R 4.5 文件头包含发布历史

文件头必须要包含进入虚拟器件(VC)库的修改历史，最近的修改列于最后。日期格式必须采用YYYY-MM-DD。这个信息对于集成器是有用的。本地的修改历史不应该包含其中。

原因：要求去记录设计的修改历史。

R 4.6 文件头包含一个关键字段

文件头必须包含便于搜索的关键字段。该字段应该包含有关本模块功能的简要说明，或是能与本模块配合运行的总线和系统的名称。

原因：关键字可提供快速的搜索机制，便于自动文本处理工具在庞大的虚拟器件 (VC)库中搜索合适的器件。如果没有关键字，该条目应该空着。

例子：sdram, address decoder, coldfire, sbus, amba,usb2.0

R 4.7 文件头必须包含一段描述模块功能的说明

文件头必须包含一段描述本模块功能的说明，而不是如何操作或运行方式的说明。

原因：有助于对模块功能的理解。

R 4.8 文件头必须包含参数描述文件的名和路径

文件头必须包含描述本模块代码所使用的参数文件的名和路径。缺省值必须都在参数文件中列出。有效值域也必须标出。

原因：有助于对Verilog HDL代码的理解

R 4.9 复位策略必须在头文件中说明

在头文件中必须详细说明复位策略。包括说明是同步复位还是异步复位，是内部复位还是外部上电复位，是硬复位还是软复位，以及该模块是否能用单个复位来调试。

原因：改善代码的可读性，突出重点和必需的综合步骤。

R 4.10 对时钟域(clock domain)的说明

在头文件中必须详细说明所有的时钟和时钟策略。

原因：说明内部生成的时钟或是分频的时钟，便于对代码和时钟策略的理解。

R 4.11 对关键布线路径的说明

包括外部时机关系的决定性的时机必须记录。文件头的位置可以包含含有决定性的时机的文件名(如creation guide)

原因：建立时机和输出时机关系突出了必需的综合和测试。

R 4.12 记录测试的特点

任何具体的代码中的用于提高测试速度的测试特色必须记录。

原因：一旦可视化部件被集成，这点可用来改善对代码的理解和测试。

例子：parallel clocking, BIST

R 4.13 需要详细的异步接口

异步接口必须包括时间关系和相关频率

原因：有助于对设计的理解，并且有助于决定是否需要额外的同步的stages用于一个不同目标的应用。

R 4.14 标明扫描方法的风格

有关于扫描风格的标注必不可缺

原因：有助于设计的集成

例子：Mux-D oRLSSD

R 4.15 文档实例化

文件头必须包括有关于文档内每一个单元、模块、函数调用、任务是如何实例化的部分。(参考R 4.30, R 7.4, G 10.23)

原因：标明必须用于重定义技术的区域，并且帮助理解设计层次。

例子：实例化 mux2s cell, decode task

原因：绝大部分由实例组成的模块。

R4.16 标明可综合能力

综合结构的能力必须以指定的YES或NO标明

原因：直接标明模块的使用路径(如：是否该模块可被用于仿真)

G 4.17 其他头文档(OtheRheadeRdocumentation)

建议文件头包含额外的相关信息——这些信息用于集成器或可以使代码更易理解。这一部分信息有助于设计者的判断，并可保持附加信息点的位置连续性。