---
sidebar_position: 1
---

```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

import TOCInline from '@theme/TOCInline';

<TOCInline toc={toc} />

### 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 don't want to override `typeName` over and over! Is there any easy way to generate a `typeName`?

Yes, with the experimental `HasAutoTypename` trait. This trait can be mixed into your `Bundle`s to automatically generate a tuple-like `typeName` for them, based on the constructor parameters of that `Bundle`. Let's look at the previous examples:

```scala mdoc:invisible:reset
import chisel3._
```

```scala mdoc:silent
class MyBundle[T <: Data](gen: T, intParam: Int) extends Bundle {
  override def typeName = s"MyBundle_${gen.typeName}_${intParam}"
  // ...
}
```

```scala mdoc
new MyBundle(UInt(8.W), 3).typeName
```

```scala mdoc:invisible:reset
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)
}
```

Auto-generated `typeName`s take the form of `{Bundle Name}_{Parameter Value 1}_{Parameter Value 2}_{...}`, and so our `MyBundle` can be equivalently expressed with:
```scala mdoc:silent
import chisel3.experimental.HasAutoTypename
class MyBundle[T <: Data](gen: T, intParam: Int) extends Bundle with HasAutoTypename {
  // ...
  // Note: No `override def typeName` statement here
}
```

```scala mdoc
new MyBundle(UInt(8.W), 3).typeName
```

### Can I name my bundles in FIRRTL, so I don't generate extremely long bundle types?

Yes, using the `HasTypeAlias` trait. FIRRTL has a construct to alias a bundle type with a type alias like so:

```
circuit Top :
  type MyBundle = { foo : UInt<8>, bar : UInt<1>}
  
  module Top :
    //...
```

These can be automatically emitted from Chisel by mixing `HasTypeAlias` into a user-defined `Record`, and implementing a field named `aliasName` with a `RecordAlias(...)` instance.

```scala mdoc:silent
import chisel3.experimental.{HasTypeAlias, RecordAlias}

class AliasedBundle extends Bundle with HasTypeAlias {
  override def aliasName = RecordAlias("MyAliasedBundle")
  val foo = UInt(8.W)
  val bar = Bool()
}
```

Let's see what happens when we generate FIRRTL using this `Bundle`:

```scala mdoc:invisible
def emitFIRRTL(gen: => RawModule): String = {
  ChiselStage.emitCHIRRTL(gen)
}
```
```scala mdoc
emitFIRRTL(new Module {
  val wire = Wire(new AliasedBundle)
})
```

`HasTypeAlias` also supports nested bundles, too:
```scala mdoc:silent
class Child extends Bundle with HasTypeAlias {
  override def aliasName = RecordAlias("ChildBundle")
  val x = UInt(8.W)
}

class Parent extends Bundle with HasTypeAlias {
  override def aliasName = RecordAlias("ParentBundle")
  val child = new Child
}
```
```scala mdoc
emitFIRRTL(new Module {
  val wire = Wire(new Parent)
})
```

### Why do I keep seeing _stripped suffixing everywhere in my FIRRTL? I didn't specify that in my `aliasName`.

You're using an `Input(...)` or `Output(...)` in conjunction with an aliased `Record` that contains a `Flipped(...)`. These flipped values are stripped by `Input` and `Output` which fundamentally changes the type of the parent `Record`:

```scala mdoc:silent
class StrippedBundle extends Bundle with HasTypeAlias {
  override def aliasName = RecordAlias("StrippedBundle")
  val flipped = Flipped(UInt(8.W))
  val normal = UInt(8.W)
}
```

```scala mdoc
emitFIRRTL(new Module {
  val in = IO(Input(new StrippedBundle))
})
```

Note how the bundle type doesn't contain a `flip flipped : UInt<8>` field, and the alias gains a `"_stripped"` suffix! This `Bundle` type is no longer the same as the one we wrote in Chisel, so we have to distinguish it as such.

By default, the suffix appended to `Record` names is `"_stripped"`. This can be defined by users with an additional string argument passed to `RecordAlias(alias, strippedSuffix)`:

```scala mdoc:silent
class CustomStrippedBundle extends Bundle with HasTypeAlias {
  override def aliasName = RecordAlias("StrippedBundle", "Foo")
  val flipped = Flipped(UInt(8.W))
  val normal = UInt(8.W)
}
```

```scala mdoc
emitFIRRTL(new Module {
  val in = IO(Input(new CustomStrippedBundle))
})
```

### 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.
