FPGA编码规范（verilog版）1.0.doc

FPGA编码规范（verilog版）修订记录：修订日期修订者修订内容1.02009-7-9曹艳平安丰军产生此文件1. 目的FPGA设计更多的是一种工程，而不是一种个人艺术。由于大型产品的开发通常由很多的人协同作战，如果不统一编程规范，最终合到一起的程序，其可读性将较差，这不仅给代码的理解带来障碍，增加维护阶段的工作量，同时不规范的代码隐含错误的可能性也比较大。为了加强项目管理，方便设计人员之间的协同工作，帮助后续人员顺利地理解项目，减少错误以及优化代码质量，有必要制定一种比较统一的FPGA设计规范。本文的目的就在于初步尝试在公司内部建立一种FPGA的编码规范，文中的许多细节需要大家在工作中实践并讨论确定。由于公司目前所用到的FPGA器件以Xilinx的产品为主，所用硬件描述语言以Verilog为主，所以本文主要针对Xilinx的产品和Verilog语言编写。在使用其他厂家的FPGA芯片，使用其他的硬件描述语言（如VHDL等），本文也可作为参考。2. 指导方针本文从命名规范、注释和文本规范、编码原则、状态机设计规范、目录划分和工具设定五个方面阐述了FPGA编码规范。规范分为规则、建议、经验三类：规则表示强制执行项目，除非出现特别特殊的情况，否则要严格遵守，违反的情况必须出具书面说明并得到主管批准；建议表示推荐，非强制，在大多数的情况下要遵循，在特殊情况下可以突破这一规则；经验表示这是好的经验，是设计人员的项目经历，可作为设计参考。3. 命名规范规则3.1：区分大小写所有的信号（signal），变量（variable）以及模块（module）的名字都用小写字母，常量名（参数（parameter）和宏（macro）用大写字母。不要依赖大小写给标识符增加语义。说明：这样做是为了和业界的习惯保持一致，避免了在大小写敏感的工具中可能会遇到的问题（verilog语言是大小写敏感），同时也可以很容易地从代码中辨认出参数（parameter）。示例：不好的 好的parameter width 16； parameter WIDTH = 16；inputwidth-1 : 0 DataIn； inputWIDTH-1 : 0 data_in；规则3.2：模块命名1在系统设计阶段应该为顶层文件和每个一级模块进行命名。2顶层文件命名方法是：芯片名称缩写+_top；3一级模块命名的方法是：将模块英文名称的各个单词首字母组合起来，形成3到5个字符的缩写。若模块的英文名只有一个单词，可取该单词的前3个字母。一级模块定义：在顶层文件中例化的模块。4对于二级以下模块（含二级模块），命名方法是：一级模块名字_模块功能缩写；示例：FPGA芯片rf_fpgav5的顶层文件命名为rf_fpgav5_top；一级模块Arithmatic Logical Unit命名为alu；一级模块Data Memory Interface命名为dmi；一级模块Decoder命名为dec；一级模块CPU里面的二级模块，功能是完成flash的控制功能，命名为：cpu_flash_ctl；规则3.3：信号命名1信号的命名由几个单词连接而成，用下划线（_）来分隔名字中的不同部分；2尽量使用缩写，缩写要求能基本表明本单词的含义；单词除常用的缩写方法外（如：clock-clk, write-wr, read-rd等），一律取该单词的前34个字母（ 如：frequency-freq, variable-var 等）；3信号名长度不要太长，原则上不超过28个字符；4. 不能用”reg”作为最后的后缀名，因为综合工具会给寄存器加上reg，如果命名里就用reg作为后缀，则扰乱了网表的可读性。常用单词的缩写方法见附录1。说明：这样可以增强程序的可读性，并能避免标示符过于冗长。示例：不好的 好的wire 9:0 addresscontrolenable; wire9:0 addr_ctl_enreg 15:0 i,q; reg15:0 fir_out_datai; reg15:0 fir_out_dataq;规则3.4：避免关键字在RTL 源码的设计中任何元素包括端口、信号、变量、函数、任务、模块等的命名都不能取Verilog 和VHDL 语言的关键字。规则3.5：文件名命名文件名要和模块名相同，在一个文件中只用一个模块，在不同的层级上尽量使用统一的信号名；这样容易跟踪信号，网表调试也容易。规则3.6：时钟和复位信号命名对于时钟信号使用前缀clk_* ，并使用有含义的缩写构成时钟信号，对于同一个时钟信号，在所有的模块中名字保持一致。对于复位信号使用前缀rst_*，并使用有含义的缩写构成复位信号，对于同一个复位信号，在所有的模块中名字保持一致。示例：clk_lbus_33m，clk_base_92m16，rst_lbus_n；规则3.7：低电平有效信号命名对于低电平有效的信号，使用后缀*_n；示例：rst_lbus_n，ad7680_cs_n；规则3.8：仿真文件命名用于仿真测试的文件的名字与被测试模块名字一一对应，添加后缀*_tb；规则3.9：声明所有使用的信号模块中所有用到的信号必须在信号声明部分进行声明；如果一个信号名没做声明Verilog将假定它为一位宽的wire变量。建议3.1：前缀使用系统级信号命名使用前缀sys_*，时钟和复位信号除外；建议3.2：后缀使用1异步信号命名使用后缀*_a；2三态信号命名使用后缀*_z；3多周期路径第n 个周期使用的信号使用后缀*_pn；4使用触发器或者SRL延迟n clk cycle的信号使用后缀*_ln；建议3.3：模块之间接口信号命名模块之间的接口信号，命名分为两个部分，第一部分表明数据方向，其中数据发出方在前，数据接收方在后，第二部分为数据名称；若某个信号从一个模块传递到多个模块，其命名应视信号的主要路径而定，在不同的子模块中尽量采用相同的名字；端口和连接端口的信号尽可能采用相同的名字。示例：cpu_mmu_wr_req，该信号含义为CPU模块到MMU的写请求。建议3.4：跨时钟域信号命名用于跨时钟域信号传递消除亚稳态的两级寄存器，前一个寄存器输出信号命名为 *_meta，第二个寄存器使用*_meta作为输入，*_sync作为输出；4. 注释和文本规范注释和文本规则具体示例请参阅附录文件“example.v”。规则4.1：文件头每个设计文件开头应包含如下注释内容：公司名称；作者；创建时间；文件名；所属项目；顶层模块；所需库；使用的仿真器和综合工具（运行平台和版本）；模块名称及实现功能和关键特性描述；文件创建和修改记录（包括修改版本号，修改时间，修改人名字，修改内容）。规则4.2：注释使用1. 使用/进行的注释行在/后加一个空格，并以分号结束；2. 使用/* */进行的注释，/*和*/各占用一行，并且顶头。3. 尽量在每个always块之前加一段注释，增加可读性和便于调试。4. 注释应该与代码一致，修改程序的时候一定要修改相应的注释；5. 注释不应重复代码已表明的内容，而是简介式点明程序的突出特征。示例：/ Edge detector used to synchronize the input signal；/*Edge detector used to synchronize the input signal；*/规则4.3：端口定义1端口定义按照功能块划分，每个功能块中按照输入，输出，双向的顺序，各个功能块之间要有空行或注释作为间隔；2每行声明一个端口并有注释，注释在同一行；3用下述顺序声明端口，不同类型的端口声明使用一个空行间隔：Inputs：clocksresetsenablesother control signalsdata and address linesOutputs：clocksresetsenablesother control signalsdata and address lines规则4.4：时延单位和精度定义在模块端口声明之前定义时延单位和时延精度，和文件头及端口声明各有一个空行间隔，格式为：timescale 1ns / 100ps；规则4.5：模块区域划分模块按照下列功能块顺序组织： 文件头时延单位和时延精度端口声明参数声明信号声明逻辑功能各个功能块之间要有空行或注释作为间隔；规则4.6：独立成行每一行语句独立成行。尽管VHDL 和Verilog 都允许一行可以写多个语句，但每个语句独立成行可以增加可读性和可维护性。规则4.7：缩进1用缩进提高续行和嵌套语句得可读性。2缩进一般采用两个空格，如果空格太多则在深层嵌套时限制行长。3禁止使用TAB 键来进行缩进，因为不同的编辑器对TAB键的解释不一致；规则4.8：总线顺序总线的有效位顺序定义从MSB到LSB，如data4:0； 规则4.9：例化1模块名、模块例化名统一，例化前加大写“Un_”区分，其中n表示多次例化标识；2使用名字相关的显式映射而不要采用位置相关的映射；3输入和输出每类端口之间一个空行来提高可读性；4模块例化时不允许存在未连接的信号。这样可以提高代码的可读性和方便debug 连线错误。规则4.10：空行分节书写，各节之间加1到多个空行。如每个always，initial语句都是一节。每节基本上完成一个特定的功能，即用于描述某几个信号的产生。在每节之前有几行注释对该节代码加以描述，至少列出本节中描述的信号的含义。规则4.11：空格1不同变量，以及变量与符号、变量与括号之间都应当保留一个空格；2Verilog关键字与其它任何字符串之间都应当保留一个空格；3逻辑运算符，算术运算符，比较运算符的两侧各留一个空格，与变量分割开来；4单操作数运算符例外，直接位于操作数前，不适用空格；规则4.12：语句对齐1同一个层次的所有语句左端对齐；2Initial、always等语句块的begin关键词跟在本行的末尾，相应的end关键词与Initial、always对齐。这样做的好处是避免因begin独占一行而造成行数太多。3Initial、always等语句块的关键词顶头书写。建议4.1：保持注释比例使用适当的注释来解释所有的always 进程、函数、端口定义、信号含义、变量含义或信号组、变量组以及常量的意义等。注释应该放在它所注释的代码附近，要求简明扼要，只要足够说明设计意图即可，避免过于复杂；保持20%25%的注释率。注释描述代码的功能，而不是行为。示例：这样注释纯粹是废话 / Increment addraddr = addr + 1b1;这样注释就好得多 / Move the read addr to the next elementaddr = addr + 1b1;建议4.2：无效代码无效代码删除掉，不要注释；建议4.3：模块互联1顶层模块应只是内部模块间的互联，尽量避免再做逻辑，如不能出现对reg变量赋值等。这样做的目的是为了能更有效的综合，因为在顶层模块中出现中间逻辑，综合工具不能把子模块中的逻辑综合到最优。2端口连接时避免使用表达式；建议4.4：数值分组书写数值时每隔4个bit用下划线（“_”）隔开，如32h0000_0000。建议4.5：不直接使用数字在设计中不要直接使用数字，作为例外，可以使用0 和1。建议采用参数定义代替直接的数字。同时，在定义常量时，如果一个常量依赖于另一个常量，建议在定义该常量时用表达式表示出这种关系。用parameter或define来定义变量，禁止使用defparams。示例：不好的编码风格 好的编码风格wire 7:0 my_in_bus; define MY_BUS_SRIE 8reg 7:0 my_out_bus; wire MY_BUS_SRIE-1:0 my_in_bus; reg MY_BUS_SRIE-1:0 my_out_bus;建议4.6：行长度保持每行小于或等于80个字符，如超出，则要换行。这样做都是为了提高代码得可读性，留出边空，方便打印，保持代码的清晰，美观和层次感。示例：不好的例子：if( ( my_signal1 & your_signal1 ) | ( my_signal2 & your_signal2 ) | ( my_signal3 & your_signal3 ) ) begin正确的例子：if( ( my_signal1 & your_signal1 ) | ( my_signal2 & your_signal2 ) | ( my_signal3 & your_signal3 ) ) begin经验4.1：代码拷贝代码需要拷贝时，注意修改相应的注释，以免产生错误的指导，导致理解上的错误。5. 编码原则规则5.1：避免使用latch避免使用产生任何latch。产生latch的情况有：组合逻辑中if语句缺乏else字句，case语句中各个条件所处理的变量不同；避免方法是：对所有输入条件都给出输出，在最终优先级的出发上使用else语句而不用elsif。规则5.2：定义完整的敏感表1对于组合模块，敏感表中必须包含被always所利用的所有信号，这通常意味着所有出现的赋值语句右边和条件表述式中的信号，可使用always *；2对于时序模块，敏感表必须包含时钟、异步复位信号；3确保敏感列表中不包含不必要信息，否则会降低仿真性能。规则5.3：模块输出寄存器化对所有模块输出加一级寄存器。这样做使输出驱动强度和输入延迟可预测，使得模块的综合过程更简单。规则5.4：优先级用括号来表示执行的优先级，而不是依靠操作符本身的优先顺序；规则5.5：根据功能选用条件语句有优先级的建议使用if语句；case语句用于描述平行逻辑，即须确保不同的条件是互斥的； 规则5.6：总线对齐赋值或者条件判断时要注明比特宽度，注意表达式的位宽匹配。规则5.7：禁止组合环禁止组合环（就是没有寄存器的反馈环路。这种结构在仿真和综合的时候都会有问题）组合环非常难以测试，因为它很难设成一个已知的状态。规则5.8：阻塞赋值和非阻塞赋值1时序逻辑使用非阻塞赋值；2latch使用非阻塞赋值；3组合逻辑使用阻塞赋值；4同一个always模块不容许同时有阻塞赋值和非阻塞赋值；5不要在不同的always中对同一变量赋值；6如果要用always语句同时进行时序和组合逻辑建模时，一定使用非阻塞赋值；规则5.9：禁止使用内部三态禁止使用内部三态电路，建议用多路选择电路代替内部三态电路。规则5.10：禁止使用任务RTL级代码禁止使用task；原因是task根据调用的情况不同，可综合成组合逻辑电路，也可综合成时序逻辑电路，增加了电路的歧义性。规则5.11：CASE语句1case语句中如果不需要优先级，那么必须确保不同的条件是互斥的；2case语句必须覆盖所有的条件，不管是指定还是用default语句。如果可能的话在default语句中把x值赋给输出；3在每个case语句中都要使用begin/end结构，并使用缩格；规则5.12：数值指定宽度对于数值一律指定进制和宽度，否则默认数值宽度是32bit，会导致比预想的大得多的算术单元；规则5.13：显式表明条件显式表明判决条件。示例：不好的if ( signal_ctl ).好的if ( signal_ctl = 1b1 ).建议5.1：区分关键路径关键路径和非关键路径逻辑放在不同模块。建议5.2：保持一个模块一个时钟尽可能在整个设计中只使用一个主时钟，同时只使用同一个时钟沿，主时钟走全局时钟网络；跨时钟域信号使用两级reg去除亚稳态。这样可以让综合器综合出更优的结果。建议5.3：时钟使用1时钟信号选用全局时钟缓冲器BUFG；2避免使用门控时钟；3避免使用内部产生时钟信号；4不要用时钟或复位信号作数据或使能信号，也不能用数据信号作为时钟或复位信号；5时钟信号必须连接到全局时钟管脚上，禁止用计数器分频后的信号做其它模块的时钟，而要用改成时钟使能的方式，否则这种时钟满天飞的方式对设计的可靠性极为不利，也大大增加了静态时序分析的复杂性。建议5.4：复位信号1. 复位信号采用异步低电平有效信号；外部复位信号连接到芯片全局复位输入端（这些管脚提供较低的抖动）；复位使初始状态可预测，防止出现禁用状态；为避免释放复位时和时钟冲突，复位信号要同步化。2. 确保所有寄存器只被简单的复位信号控制，尽可能避免内部产生的条件复位信号，建议模块内所有寄存器应在同一时间内被复位。3. 复位的条件表达式及命名要和always敏感列表中的描述相统一，并且一定要使用异步复位。所有的复位必须低有效。建议5.5：避免例化具体门级电路在设计中避免实例化具体的门级电路。门级电路可读性差，且难于理解和维护，如果使用特定工艺的门电路，设计将变得不可移植。如果必须实例化门电路，建议采用独立于工艺库的门电路。建议5.6：使用函数如果同一段代码需要重复多次，尽可能使用函数，以避免冗长的逻辑和子表达式；如果有可能，可以将函数通用化，以使得它可以复用。注意，内部函数的定义一般要添加注释，这样可以提高代码的可读性；建议5.7：避免振荡器避免使用负延触发的双稳态多谐振荡器（flip flop）。建议5.8：插入单位延迟采用intra-assignment timing delay（在非阻塞赋值前人为加入一个很小单位的延时）。这种描述的好处之一是：它简单模拟了赋值过程寄存器内部的clock-to-output 的延时，在做行为级功能仿真的时候，也可以发现一些由于寄存器固有延迟造成的时序和功能问题。该单位延迟定义为parameter，名字为UDLY（仿真用的单位延迟）；建议5.9：变量赋值的唯一性不要在一个always块里给多个变量赋值。如果将一组条件相同的变量写在一个always块中有更利于可读性的提高和功能的实现时候，可有例外情况，但需尽量多加注释，增加可读性。建议5.10：参数传递需要传递参数的模块，在多次例化的时候统一都传递参数；不要例化同一个模块，有的传参数，有的不传。经验5.1：IO转换速率对于关键的输出可以在IO中选择快速转换速率，这会降低输出时延，但会增加地弹；经验5.2：不依赖FPGA自身的上电复位不要依赖于FPGA自身的上电复位，使用一个主复位信号复位所有的FF；经验5.3：充分利用FPGA硬件资源尽量充分利用用FPGA内部的乘法器、Block RAM、快速进位链、IOB寄存器等资源；6. 状态机设计规范状态机设计规范具体示例请参阅附录文件“fsm_example.v”。规则6.1：状态定义状态定义用parameter 定义，不使用define 宏定义的方式。define 宏定义在编译时自动替换整个设计中所定义的宏，而parameter 仅仅定义模块内部的参数，定义的参数不会与模块外的其他状态机混淆。规则6.2：保持层次使有限状态机FSM保持在层次中的自己所在的那一级，不允许综合工具在输出和下一个状态译码逻辑之间共享资源；规则6.3：处理所有状态必须包括对所有状态都处理；不能出现无法处理的状态使状态机失控；建议6.1：三段式状态机状态机要写成3段式的(这是最标准的写法)，第一个产生sequential的状态寄存器；第二个产生下一状态的组合逻辑；第三个为输出的组合逻辑。建议6.2：状态机完备性一个完备的状态机（健壮性强）应该具备初始化(reset)状态和默认(default)状态。经验6.1：状态机类型选择有限状态机使用moore比mealy模型好，moore模型状态只与当前状态有关系，mealy模型与当前状态和输入都有关系。经验6.2：状态机安全性状态机中的When others（default）语句，作用只是指定了状态机的初始状态，而不能保证将电路状态从非法跳回默认状态。原因是综合工具默认将从非法状态跳回合法状态的电路综合掉了，可以使用安全状态机选项使其不被综合掉。7. 目录结构和工具设定规则7.1：目录划分每个设计至少有四个主要的目录：src，sim，syn，lib；src目录包含了原有的设计源文件；lib包含了所有的外部文件；syn目录包含了所有的综合以及P&R后产生的输出文件。sim目录包含所有的仿真文件。规则7.2：资源共享资源共享的应用限制在同一个module里；尽可能将Critical path上所有相关逻辑放在同一个module里。Critical path 所在的module与其他module 分别综合，对critical path采用速度优先的综合策略，对其它module采用面积优先的综合策略。这样综合工具才能最大限度地发挥其资源共享综合作用，发挥其最佳综合效果；规则7.3：组合逻辑限于本模块组合电路设计中应当没有层次，每个模块输出尽量采用寄存器输出形式，做到这一点，对约束比较方便；同一条路径上的组合逻辑尽可能分散在各个module里，这对综合非常有利，可以方便的达到速度面积双赢的目的；模块按功能合理划分，模块大小适中，一般为2000门左右，具体按照综合工具性能确定；规则7.5：重视告警所有RTL级代码必须通过编译和综合。必须没有错误，必须重视工具产生的警告信息确认每条警告含义，避免因此使设计的实现产生隐患。建议7.1：共享操作符可用综合工具自动决定是否共享相同的子表达式，但综合工具只能共享* + - = =。为了使代码更加具备通用性和可移植性，最好在代码中用临时变量存储子表达式来共享操作符。经验7.1：模块大小划分通常会推荐将模块划分得越小越好，事实上要从实际的设计目标面积和时序要求出发，好的时序规划和合适的约束条件要比电路的大小对综合时间的影响要大，要依照设计的目标来划分模块；最好在设计阶段就做好时序规划，通过综合的约束scripts来满足时序规划，这样就能获得既满足性能的结果，又使得综合时间最省；从代码设计讲，5005000行的长度是合适的。经验7.2：注意芯片数据流利用有适当管脚定位约束的数据流：xilinx器件中的数据流是在水平方向上的，原因是进位链在垂直方向上&三态缓冲线在水平方向上排列&块之间也有水平方向上的直接连接；为了利用数据流，地址和数据管脚必须放在芯片的左侧&右侧，同时注意进位链是从下而上的，所以将最低位放在最下面，控制信号放在芯片的上部&下部。经验7.3：速度与面积编写代码和设计电路，综合考虑速度和面积，原则是：向关键路径（部分）要时间，向非关键路径（部分）要面积。未获得更高的速度，尽量减少关键路径上的LUT技术，尽量压缩线延时；为获得更小的面积，在非关键路径（部分）上尽量优化电路结构，压缩面积。当然随着工具的发展，上述设计技巧可能在绝大部分情况下工具可以代劳。以上经验是为了让大家在遇到困难时，不至于束手无策，可以尝试以上经验。经验7.4：合理选择加法器合理选择加法电路，使用圆括号处理多个加法器。示例：z = a + b + c + d;串行加法电路，面积小，但整体速度慢。但是。如果d是关键路径，其他信号是非关键路径；或者，设计中关键路径与a、b、c、d无关，则采用这种方式。z = ( a + b ) + ( c + d );面积大，但整体速度快。如果对a、b、c、d的时序要求都比较苛刻，应当采用这种方法。经验7.5：条件语句选用通常case结构速度较快，占用面积大，用case语句实现对速度要求高的编解码电路；if语句速度慢，但占用面积小，可用它实现对面积较高要求，速度无特殊要求的设计。为避免较大路径延时，不要使用特别长的嵌套if结构，如果条件没有优先级，建议合并if语句中各条件；用if语句实现对延时要求苛刻的路径时，应将最高优先级给最迟到达的关键信号。有时，为了兼顾面积和速度，可将if和case语句合用。经验7.6：资源共享利用资源共享减少逻辑模块的数量。示例：没有资源共享用了4个加法器完成。 只用2个选择器和1个加法器if ( sel = 1b1 ) begin if ( sel = 1b1 ) beginsum = a + b ; temp1 = a;else temp2 = b; sum = c + d ; elseend temp1 = c; temp2 = d; end sum = temp1 +temp2;经验7.7：可能的关键路径可能成为关键路径的电路有：比较器，多路选择器，distributedRAM，乘法器，加法器等，尤其是比较大的情况，建议做方案时针对这些电路进行速度评估，决定是否要pipeline。经验7.8：关键路径的约束针对关键路径，进行位置约束。如果发现关键路径和相关LUT距离太远，可通过floorplanner手工布线，形成位置约束文件，指导布局布线。经验7.9：扇出限定可以通过综合工具，也可以手动编码复制寄存器来处理高扇出网络。综合选型中的最大扇出（MAX FANOUT）限定在100500。经验7.10：全局约束利用四种全局约束来对设计进行全局约束：周期（对每个时钟），偏置输入，偏置输出，管脚到管脚。也许还会有针对多周期路径，失败路径和关键路径的其他约束，但必须从指定的四个全局约束开始。经验7.11：full case和parallel_