Note, I've rendered the updated docs here.

Chisel and FIRRTL have long used signals with names beginning with an
underscore as an API to specify that the name does not really matter.
Tools like Verilator follow a similar convention and exclude signals
with underscore names from waveform dumps by default. With the
introduction of compiler-plugin prefixing in Chisel 3.4, the convention
remained but was hard for users to use unless the unnnamed signal
existed outside of any prefix domain. Notably, unnamed signals are most
useful when creating wires inside of utility methods which almost always
results in the signal ending up with a prefix.

With this commit, Chisel explicitly recognizes signals whos val names
start with an underscore and preserve that underscore regardless of any
prefixing. Chisel will also ignore such underscores when generating
prefixes based on the temporary signal, preventing accidental double
underscores in the names of signals that are prefixed by the temporary.

Here's a specific example of the change this makes, Given:

class Example extends Module {
  val foo, bar = IO(Input(UInt(8.W)))
  val out = {
    val port = IO(Output(UInt(8.W)))
    val _sum = foo + bar
    val _sum2 = Wire(UInt(8.W))
    _sum2 := foo + 1.U
    port := _sum + _sum2
    port
  }
}

Chisel master (and 3.4.3) currently compile this to:

module Example :
  input clock : Clock
  input reset : UInt<1>
  input foo : UInt<8>
  input bar : UInt<8>
  output out : UInt<8>

  node _out__sum_T = add(foo, bar)
  node out__sum = tail(_out__sum_T, 1)
  wire out__sum2 : UInt<8>
  node _out__sum2_T = add(foo, UInt<1>("h1"))
  node _out__sum2_T_1 = tail(_out__sum2_T, 1)
  out__sum2 <= _out__sum2_T_1
  node _out_port_T = add(out__sum, out__sum2)
  node _out_port_T_1 = tail(_out_port_T, 1)
  out <= _out_port_T_1

Now this is compiled to:

  module Example :
    input clock : Clock
    input reset : UInt<1>
    input foo : UInt<8>
    input bar : UInt<8>
    output out : UInt<8>

    node _out_sum_T = add(foo, bar)
    node _out_sum = tail(_out_sum_T, 1)
    wire _out_sum2 : UInt<8>
    node _out_sum2_T = add(foo, UInt<1>("h1"))
    node _out_sum2_T_1 = tail(_out_sum2_T, 1)
    _out_sum2 <= _out_sum2_T_1
    node _out_port_T = add(_out_sum, _out_sum2)
    node _out_port_T_1 = tail(_out_port_T, 1)
    out <= _out_port_T_1 

Note that out__sum and out__sum2 become _out_sum and _out_sum2. This change comes from Chisel effectively recognizing the leading _ is not actually part of the name, but is the signifier of a temporary so it is stripped from the "seed" and moved to the front of the final name.

Also note that _out__sum2_T becomes _out_sum2_T. This functionality looks similar to the previous paragraph, but is actually a totally different change where Chisel, again recognizing that _ is the signifier of a temporary and not really part of the name, actually ignores the leading _ for generating prefixes from signals.

Between these two changes, I think the naming behavior is a pretty nice improvement over the current behavior.

Contributor Checklist

• Did you add Scaladoc to every public function/method?
• Did you add at least one test demonstrating the PR?
• Did you delete any extraneous printlns/debugging code?
• Did you specify the type of improvement?
• Did you add appropriate documentation in docs/src?
• Did you state the API impact?
• Did you specify the code generation impact?
• Did you request a desired merge strategy?
• Did you add text to be included in the Release Notes for this change?

Type of Improvement

• new feature/API

API Impact

This adds a new API to let users creating "temporary" signals. I will note that this might have a s

Backend Code Generation Impact

This only changes names when there are vals in user's Chisel code which names that start with _. This is an extremely uncommon pattern so given the power this unlocks and the improved user API, I think this is appropriate for release in v3.5.4.

Desired Merge Strategy

• Squash

Release Notes

Define leading '_' as API for creating temporaries. Chisel will now preserve the leading _ for any val-named signal which signifies to FIRRTL and other backend tools that the name does not matter. Chisel also now ignores the leading _ in prefixes generated from such "unnamed signals" which reduces the number of cases of double __ in the middle of signal names.

Reviewer Checklist (only modified by reviewer)

• Did you add the appropriate labels?
• Did you mark the proper milestone (Bug fix: 3.4.x, [small] API extension: 3.5.x, API modification or big change: 3.6.0)?
• Did you review?
• Did you check whether all relevant Contributor checkboxes have been checked?
• Did you do one of the following when ready to merge:
  • Squash: You/ the contributor Enable auto-merge (squash), clean up the commit message, and label with Please Merge.
  • Merge: Ensure that contributor has cleaned up their commit history, then merge with Create a merge commit.