如何从凿子解读生成的Verilog中的注释？

Question

以下是PassTrough模块中的一些通用Verilog： https://github.com/freechipsproject/chisel-bootcamp/blob/master/2.1_first_module.ipynb

module PassTrough( // @[:@3.2]
  input        clock, // @[:@4.4]
  input        reset, // @[:@5.4]
  input  [9:0] io_in, // @[:@6.4]
  output [9:0] io_out // @[:@6.4]
);
  assign io_out = io_in; // @[buffer.scala 10:10:@8.4]
endmodule

是否有任何资源可以理解注释中的内容。我可以看到它们与原始scala文件中的代码位置有关，但想了解更多详细信息。

// @[buffer.scala 10:10:@8.4]

对此行进行更详细的说明会很有用。

Answer 1

这些是源定位符，将显示在生成的FIRRTL或Verilog中。这些告诉您源文件（Chisel或FIRRTL）中的哪一行用于在下游FIRRTL或Verilog中生成特定行。

格式通常为：@[<file> <line>:<column> ...]

可能存在多个源定位器。

示例

请考虑以下示例，这些示例是从BoringUtilsSpec中提取的。显示行号（因为它是从较大的文件中提取的，所以不从零开始）与列号一起显示。您可以看到它们之间的排列方式。例如，notA的声明发生在第27行的第20列，赋值notA := ~a发生在第30行的第10列。您会看到27:20和30:10出现在FIRRTL。在Verilog中，这些内容有些合并，并且您会看到指示27:20和30:10的源定位符：

// -------------------------------------------+----+
// File: BoringUtilsSpec.scala                |    |
// -------------------------------------------+----+
// Column Number                              |    |
// -------------------------------------------+----+
//           1         2         3         4  |    |
// 01234567890123456789012345678901234567890  |    |
// -------------------------------------------+----|
     class BoringInverter extends Module { // | 24 | Line Number
       val io = IO(new Bundle{})           // |  5 |
       val a = Wire(UInt(1.W))             // |  6 |
       val notA = Wire(UInt(1.W))          // |  7 |
       val b = Wire(UInt(1.W))             // |  8 |
       a := 0.U                            // |  9 |
       notA := ~a                          // | 30 |
       b := a                              // |  1 |
       chisel3.assert(b === 1.U)           // |  2 |
       BoringUtils.addSource(notA, "x")    // |  3 |
       BoringUtils.addSink(b, "x")         // |  4 |
     }                                     // |  5 |
// -------------------------------------------+----+

这将产生以下FIRRTL：

module BoringUtilsSpecBoringInverter : 
  input clock : Clock
  input reset : UInt<1>
  output io : {}

  wire a : UInt<1> @[BoringUtilsSpec.scala 26:17]
  wire notA : UInt<1> @[BoringUtilsSpec.scala 27:20]
  wire b : UInt<1> @[BoringUtilsSpec.scala 28:17]
  a <= UInt<1>("h00") @[BoringUtilsSpec.scala 29:7]
  node _T = not(a) @[BoringUtilsSpec.scala 30:13]
  notA <= _T @[BoringUtilsSpec.scala 30:10]
  b <= a @[BoringUtilsSpec.scala 31:7]
  node _T_1 = eq(b, UInt<1>("h01")) @[BoringUtilsSpec.scala 32:22]
  node _T_2 = bits(reset, 0, 0) @[BoringUtilsSpec.scala 32:19]
  node _T_3 = or(_T_1, _T_2) @[BoringUtilsSpec.scala 32:19]
  node _T_4 = eq(_T_3, UInt<1>("h00")) @[BoringUtilsSpec.scala 32:19]
  // assert not shown

以及以下Verilog：

module BoringUtilsSpecBoringInverter(
  input   clock,
  input   reset
);
  wire  _T; // @[BoringUtilsSpec.scala 30:13]
  wire  notA; // @[BoringUtilsSpec.scala 27:20 BoringUtilsSpec.scala 30:10]
  wire  _T_3; // @[BoringUtilsSpec.scala 32:19]
  wire  _T_4; // @[BoringUtilsSpec.scala 32:19]
  assign _T = 1'h1; // @[BoringUtilsSpec.scala 30:13]
  assign notA = 1'h1; // @[BoringUtilsSpec.scala 27:20 BoringUtilsSpec.scala 30:10]
  assign _T_3 = _T | reset; // @[BoringUtilsSpec.scala 32:19]
  assign _T_4 = _T_3 == 1'h0; // @[BoringUtilsSpec.scala 32:19]
  // assert not shown
endmodule

注意事项

发电机训练营

如果您是在Chisel Bootcamp Jupyter Notebook中或通过sbt控制台/ REPL运行此程序，则源定位器可能没有什么意义，因为这里实际上没有带行的文件。

与Annotation的区别

这些源定位符不是 Annotation，以防有人碰到该名称。

Annotation是与 circuit 组件关联的元数据。源定位器（映射到FIRRTL IR中的Info）与某些源文件中的特定语句相关联。在幕后，它们只是生成并随后复制的字符串。无法保证将保留源定位器-可以任意更改或删除它们。相反，Annotation在转换过程中会保留并重命名，并且对其行为有很强的保证。

因此，如果您需要调试Chisel或FIRRTL编译器阶段，请不要依赖源定位器来获得帮助。