ChiselEnum convenience functions; support string interaction

[maartenboersma]

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 request a desired merge strategy?
• Did you add text to be included in the Release Notes for this change?

Type of Improvement

• Feature (or new API)
• API modification: yes, I propose to override the toString method on ChiselEnum. I wonder if anybody out there depends on the current behavior. If so, we could rename to listValues

Desired Merge Strategy

• Squash: The PR will be squashed and merged (choose this if you have no preference).

Release Notes

Convenience functions to interact between ChiselEnum and String. Allows RTL readability improvements, especially if Enum values are not yet known at compile time (e.g. decode tables in separate files)

Reviewer Checklist (only modified by reviewer)

• Did you add the appropriate labels? (Select the most appropriate one based on the "Type of Improvement")
• Did you mark the proper milestone (Bug fix: 3.6.x, 5.x, or 6.x depending on impact, API modification or big change: 7.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) and clean up the commit message.
  • Merge: Ensure that contributor has cleaned up their commit history, then merge with Create a merge commit.

[jackkoenig]

Nit, don't add () here (that implies mutation in canonical Scala style).

More important discussion--I took a look at how this prints and I don't think this is the right .toString.

For reference, for the following example:

object EnumExample extends ChiselEnum {
  val e0, e1, e2 = Value

  val e100 = Value(100.U)
  val e101 = Value(101.U)
}

This toString is:

0 e0
1 e1
2 e2
100 e100
101 e101

Old (which I agree is bad so no issues replacing) is:

chiselTests.EnumExample$@4cd7e993

Note that the .toString for a specific value (e.g. EnumExample.e100) is:

EnumExample(100=e100)

(I'd prefer if this order were swapped, e100=100, I think it's backwards but oh well).

I think the "right" .toString would be the String concatenation of all of the values:

EnumExample(0=e0, 1=e1, 2=e2, 100=e100, 101=e101)

That would be more consistent with normal Scala toStrings (which typically do not include newlines).

I think this functionality of printing the the gtkwave compatible style is good but belongs in a method on DataMirror. Maybe something like DataMirror.gtkwaveEnumMapping or something, what do you think?

[maartenboersma]

The .toString method now does what you suggested (+ test added). I agree this makes sense.

I moved the previous functionality into a new method called asTable. I think we should not explicitly have gtkwave in any of the chisel method names. Gtkwave is just one of the waveform viewers out there.

In our environment, the Enum mappings are also parsed by other tools (simulation environment) - not just gtkwave. We chose the gtkwave filter format because we see no need to invent "yet another format".

I do like the asTable method to be a member of ChiselEnum, not hide it in DataMirror. I think dumping the ChiselEnum mappings in a machine-readable way is a pretty generic thing.