如何从凿子中破译生成的 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

是否有任何有关了解 cmets 内容的资源。我可以看到它们与原始 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的区别

这些源定位符不是Annotations，以防万一有人遇到过这个名字。

Annotations 是与 电路 组件关联的元数据。源定位器（映射到 FIRRTL IR 中的 Info）与某些源文件中的特定语句相关联。在引擎盖下，它们只是生成然后复制的字符串。无法保证源定位器会被保留——它们可能会被任意更改或删除。相反，Annotations 在转换中被保留和重命名，并且对它们的行为方式有强有力的保证。

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