綠葉落秋風

模型功能

• 實現代碼的注釋的方法
• 基于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效果文件

調用接口

• 無調用模型庫