verilog注释及vscode插件terosHDL

模型功能

• 实现代码的注释的方法
• 基于vscode的文档自动生成

模型框图

`timescale 1ns / 1ps
/*

*/
// *******************************************************************************
// Company: Fpga Publish
// Engineer: FP 
// 
// Create Date: 2024/03/24 12:39:43
// Design Name: 
// Module Name: verilog_demo
// Project Name: 
// Target Devices: ZYNQ7010 | XCZU2CG | Kintex7
// Tool Versions: 2021.1 || 2022.2
// Description: 
//         * 
// Dependencies: 
//         * 
// Revision: 0.01 
// Revision 0.01 - File Created
// Additional Comments:
// 
// *******************************************************************************
module verilog_demo #(
    //mode
    parameter MD_SIM_ABLE = 0,
    //number
    
    //width
    parameter WD_ERR_INFO = 4
   )(
    //! system signals
    input           i_sys_clk   ,  
    input           i_sys_resetn,  
    //! @virtualbus uart_interface @dir out
    output          m_uart_0_mtx, //! uart master tx
    input           m_uart_0_mrx, //! uart master rx
    //! @end 
    //! error info feedback
    output   [WD_ERR_INFO-1:0]  m_err_verilog_info1
);
//========================================================
//function to math and logic

//========================================================
//localparam to converation and calculate

//========================================================
//register and wire to time sequence and combine
// ----------------------------------------------------------
// 
//========================================================
//always and assign to drive logic and connect

//========================================================
//module and task to build part of system

//========================================================
//expand and plug-in part with version 

//========================================================
//ila and vio to debug and monitor

endmodule
              
/* end verilog

*/

实现步骤

1. verilog的注释语法和C语言一样
2. 文件头注释模型源自vivado自动生成的模板
3. 端口列表的注释语法源自vscode的插件terosHDL
4. 为了统一和适应verilog描述的特点，将注释分为两层：

• 结构层： // ================
• 内容层： // ----------------

5. 结构层负责划分verilog的语法区域，使得语法的调用顺序满足要求

• 常数声明 》 变量声明 》 逻辑赋值 》 模块调用 》 任务调度 》 插入逻辑 》 在线调试
• 虽然大部分的编辑器都支持赋值先于声明，但是modelsim不支持，为了兼容，还是要求设计结构保持最规范的顺序

6. 内容层则是负责将各个独立的内容在某个结构中的分布区分出来

• 大部分的情况下，一个内容会分布在多个结构中
• 为了方便查找，可以对相同的内容进行编号，方便查找
• 当然，也可以简单的作为分割逻辑功能的分割线

7. markdown的拓展

• 如源码所示，利用双语法注释，可以实现markdown的注释
• 目前主要是用于插入一些复杂的计算公式和需要成表格的注释
• 当然，也可以进行状态机的插入，但是terosHDL可以自动识别，所以该功能就没有很大的必要

8. terosHDL的拓展

• 需要归入文档的注释需要在//后面增加!符号，常规注释直接使用//
  • 一般来说，除了逻辑实现方法这类需要和代码一起阅读的注释，其他的注释都需要加入文档
  • 这个更多取决于文档的要求，可以根据个人的代码规范进行区分
  • 笔者更喜欢使用vscode将所有非判断注释都加入文档
• 插入时序图
  • 这个语法可以在插件的帮助文档中获取
  • 当然，如果用过wavedrom这个基于json的时序图绘制软件，那就会简单很多
  • 具体的例子如下：

//! { signal: [
//!  { name: "clk",  wave: "P......" },
//!  { name: "bus",  wave: "x.==.=x", data: ["head", "body", "tail", "data"] },
//!  { name: "wire", wave: "0.1..0." }
//! ],
//!  head:{
//!     text:'WaveDrom example',
//!     tick:0,
//!     every:2
//!   }}

• 插入状态机
  • terosHDL支持自动识别状态机并插入到对应的位置
  • 同时会显示状态机的跳转条件，可以用于快速地分析模块的逻辑
  • 具体的效果如下：

/* @begin state machine */
//state name
localparam IDLE         = 0;
localparam START        = 1;

//state variable
reg [3:0] cstate = IDLE;

//state logic
always @(posedge i_sys_clk)
    if(!i_sys_resetn)
    begin
       cstate <= IDLE;
    end
    else
    begin
        case(cstate)
            IDLE : if(1) //whether goto next state
                begin  
                    if(1) //which state to go
                    begin
                        cstate <= START;
                    end
                end
            default: cstate <= IDLE;
        endcase
    end
/* @end state machine  */
![](https://img2024.cnblogs.com/blog/2030044/202403/2030044-20240324132201588-982651260.png)

• 除了文档外，还有一些原理图查看、仿真模板生成等功能
  • 这些功能笔者一般在vivado完成，就没有进行过多的探索，这个可能需要java的支持，感兴趣可以自行按照教程添加

最终效果

terosHDL导出的html效果文件

调用接口

• 无调用模型库