---
layout: docs
title:  "Naming Cookbook"
section: "chisel3"
---

```scala mdoc:invisible
import chisel3._
import circt.stage.ChiselStage
def emitSystemVerilog(gen: => RawModule): String = {
  val prettyArgs = Array("--disable-all-randomization", "--strip-debug-info")
  ChiselStage.emitSystemVerilog(gen, firtoolOpts = prettyArgs)
}
```
# Naming Cookbook

### I still have _T signals, can this be fixed?

See the next answer!

### I have so many wires with the same name, like `x`, `x_1` and `x_2`. How can I make them easier to understand?

Signals with `_T` names or names that Chisel has to uniquify
often are intermediate values generated within loops, function calls, or `when` predicates.
They can also be consumed by verification statements like `assert` or `prints`.
In these cases, the compiler plugin often can't find a good prefix for the generated
intermediate signals and can't name them at all or has to make up a unique name for them.

We recommend you manually insert calls to `prefix` to clarify these cases:

```scala mdoc:silent
import chisel3.experimental.prefix
class ExamplePrefix extends Module {

  Seq.tabulate(2) { i =>
    Seq.tabulate(2) { j =>
      prefix(s"loop_${i}_${j}"){
        val x = WireInit((i*0x10+j).U(8.W))
        dontTouch(x)
      }
    }
  }
}
```
```scala mdoc:verilog
emitSystemVerilog(new ExamplePrefix)
```
### How can I get better names for code generated by `when` clauses?

The `prefix` API can help with code inside `when` clauses:

```scala mdoc:silent
class ExampleWhenPrefix extends Module {

  val in = IO(Input(UInt(4.W)))
  val out = IO(Output(UInt(4.W)))

  out := DontCare

  Seq.tabulate(2) { i =>
    val j = i + 1
    prefix(s"clause_${j}") {
      when (in === j.U) {
        val foo = Reg(UInt(4.W))
        foo := in + j.U(4.W)
        out := foo
      }
    }
  }
}
```
```scala mdoc:verilog
emitSystemVerilog(new ExampleWhenPrefix)
```

### I still see _GEN signals, can this be fixed?

`_GEN` signals are usually generated from the FIRRTL compiler, rather than the Chisel library. We are working on
renaming these signals with more context-dependent names, but it is a work in progress. Thanks for caring!

### How do I make my modules have more stable names instead of 'Module_1' and 'Module_42'?

This is an example of the module instability problem, which results from several modules all sharing the exact same name. To fix this, you must add more specificity to your `Module`'s name to avoid these name collisions.

This can be done by leveraging the `desiredName` and `typeName` APIs. 
`desiredName` is for indicating the names of `Modules` (e.g. influenced by the parameters passed in), and `typeName` is useful for modules which are type-parameterized by subclasses of `Data`. Overriding `desiredName` can reduce or even eliminate name collisions. For instance, suppose your module looks like the following:

```scala mdoc:silent
class MyModule[T <: Data](gen: T) extends Module {
  // ...
}
```

We can override `desiredName` of the module to include the type name of the `gen` parameter like so:

```scala mdoc:invisible:reset
import chisel3._
import chisel3.util.Queue
import circt.stage.ChiselStage
def emitSystemVerilog(gen: => RawModule): String = {
  val prettyArgs = Array("--disable-all-randomization", "--strip-debug-info")
  ChiselStage.emitSystemVerilog(gen, firtoolOpts = prettyArgs)
}
```

```scala mdoc
class MyModule[T <: Data](gen: T) extends Module {
  override def desiredName = s"MyModule_${gen.typeName}"
}
```

Any instances of your `MyModule` will now have Verilog module names containing the type parameter.

```scala mdoc:compile-only
val foo = Module(new MyModule(UInt(4.W))) // MyModule_UInt4
val bar = Module(new MyModule(Vec(3, UInt(4.W)))) // MyModule_Vec3_UInt4
```

Note that all base Chisel util modules, like `Queue`, already implement `desiredName` like this:

```scala mdoc:compile-only
val fooQueue = Module(new Queue(UInt(8.W), 4)) // Verilog module would be named 'Queue4_UInt8'
val barQueue = Module(new Queue(SInt(12.W), 3)) // ... and 'Queue3_SInt12'
val bazQueue = Module(new Queue(Bool(), 16)) // ... and 'Queue16_Bool'
```

### How would I write my own `typeName` for my data types?

If you're using your own user-defined `Bundle`, you can increase the specificity of its own `typeName` by overriding it. All `Data` types have a simple default implementation of `typeName` (which is simply its class name), but you can override this yourself:

```scala mdoc:silent
class MyBundle[T <: Data](gen: T, intParam: Int) extends Bundle {
  // Generate a stable typeName for this Bundle. Two 'words' are present
  // in this implementation: the bundle's name plus its integer parameter
  // (something like 'MyBundle9')
  // and the generator's typeName, which itself can be composed of 'words'
  // (something like 'Vec3_UInt4')
  override def typeName = s"MyBundle${intParam}_${gen.typeName}"

  // ...
}
```

Now if you use your `MyBundle` in a module like a `Queue`:

```scala mdoc:compile-only
val fooQueue = Module(new Queue(new MyBundle(UInt(4.W), 3), 16)) // Queue16_MyBundle3_UInt4
```

The suggested pattern for `typeName`, and subsequently `desiredName`, is to fold single integer-like parameters with the name itself (for example, `Queue4`, `UInt3`, `MyBundle9`) to form 'words' and separate these 'words' with underscores (`Queue4_UInt3`, `FooBundle_BarType4`).

`Bundles` that have multiple integer arguments aren't presently addressed by any of the built-in modules, and so implementing a descriptive and sufficiently differentiable `typeName` for such `Bundles` is left as an exercise to the reader. However, integers should not occur with an underscore before them at the very end of the `typeName` (e.g. `MyBundle_1`) because this is the _same_ syntax used for duplicates, and so would cause confusion. Having to disambiguate modules all named `Queue32_MyBundle_4_1`, `Queue32_MyBundle_4_2`, `Queue32_MyBundle_4_3`, and so on would be undesirable, indeed!

### I want to add some hardware or assertions, but each time I do all the signal names get bumped!

This is the classic "ECO" problem, and we provide descriptions in [explanation](../explanations/naming). In short,
we recommend wrapping all additional logic in a prefix scope, which enables a unique namespace. This should prevent
name collisions, which are what triggers all those annoying signal name bumps!

### I want to force a signal (or instance) name to something, how do I do that?

Use the `.suggestName` method, which is on all classes which subtype `Data`.

### How can I omit the prefix in certain parts of the code?

You can use the `noPrefix { ... }` to strip the prefix from all signals generated in that scope.

```scala mdoc
import chisel3.experimental.noPrefix

class ExampleNoPrefix extends Module {
  val in = IO(Input(UInt(2.W)))
  val out = IO(Output(UInt()))

  val add = noPrefix {
    // foo will not get a prefix
    val foo = RegNext(in + 1.U)
    foo + in
  }

  out := add
}
```

```scala mdoc:verilog
emitSystemVerilog(new ExampleNoPrefix)
```

### I am still not getting the name I want. For example, inlining an instance changes my name!

In cases where a FIRRTL transform renames a signal/instance, you can use the `forcename` API:

```scala mdoc
import chisel3.util.experimental.{forceName, InlineInstance}

class WrapperExample extends Module {
  val in = IO(Input(UInt(3.W)))
  val out = IO(Output(UInt(3.W)))
  val inst = Module(new Wrapper)
  inst.in := in
  out := inst.out
}
class Wrapper extends Module with InlineInstance {
  val in = IO(Input(UInt(3.W)))
  val out = IO(Output(UInt(3.W)))
  val inst = Module(new MyLeaf)
  forceName(inst, "inst")
  inst.in := in
  out := inst.out
}
class MyLeaf extends Module {
  val in = IO(Input(UInt(3.W)))
  val out = IO(Output(UInt(3.W)))
  out := in
}
```
```scala mdoc:verilog
emitSystemVerilog(new WrapperExample)
```

This can be used to rename instances and non-aggregate typed signals.
