Strong enums (#892)

* Added new strongly-typed enum construct called "StrongEnum". "StrongEnum" will automatically generate annotations that HDL backends can use to mark components as enums

Removed "override val width" constructor parameter from "Element" so that classes with variable widths, like the new strong enums, can inherit from it

Changed the parameter types of certain functions, such as "switch", "is", and "LitArg.bindLitArg" from "Bits" to "Element", so that they can take the new strong enums as arguments

* Added tests for the new strong enums

* Changed StrongEnum exception names and made sure in StrongEnum tests that the correct types of exceptions are thrown

* Fixed bug where an enum's global annotation would not be set if it was used in multiple circuits

Made styling changes to StrongEnum.scala

* Reverted accidental changes to the AnnotatingDiamond test

* Changed the API for casting non-literal UInts to enums

Added an isValid function that checks whether or not enums have valid values

Calling getWidth on an enum's companion object now returns a BigInt instead of an Int

* Casting a literal to an enum using the StrongEnum.castFromNonLit(n) function is now simply a wrapper for StrongEnum.apply(n)

* Fixed compilation bug

* * Added "next" method to EnumType
* Renamed "castFromNonLit" to "fromBits"

* The FSM example in the test/scala/cookbook now uses StrongEnums

* * Changed strong enum API, so that users no longer have to declare both a class and a companion object for each strong enum

* Strong enums do not have to be static any longer

* * Added scope protections to ChiselEnum.Value so that users cannot call it
outside of a ChiselEnum definition

* Renamed ChiselEnum.Value type to ChiselEnum.Type so that we can give
it a companion object just like UInt and Bool do

* * Moved strong enums into experimental package
* Non-literal UInts can now be cast to enums with apply() rather than
fromBits()
* Reduced code-duplication by moving some functions from EnumType and
Bits to Element

1 files changed, 5 insertions, 5 deletions

diff --git a/src/main/scala/chisel3/util/Conditional.scala b/src/main/scala/chisel3/util/Conditional.scala
index bf2d4268..3630f8ad 100644
--- a/src/main/scala/chisel3/util/Conditional.scala
+++ b/src/main/scala/chisel3/util/Conditional.scala
@@ -24,7 +24,7 @@ object unless {  // scalastyle:ignore object.name
   * user-facing API.
   * @note DO NOT USE. This API is subject to change without warning.
   */
-class SwitchContext[T <: Bits](cond: T, whenContext: Option[WhenContext], lits: Set[BigInt]) {
+class SwitchContext[T <: Element](cond: T, whenContext: Option[WhenContext], lits: Set[BigInt]) {
   def is(v: Iterable[T])(block: => Unit): SwitchContext[T] = {
     if (!v.isEmpty) {
       val newLits = v.map { w =>
@@ -60,19 +60,19 @@ object is {   // scalastyle:ignore object.name
   // TODO: Begin deprecation of non-type-parameterized is statements.
   /** Executes `block` if the switch condition is equal to any of the values in `v`.
     */
-  def apply(v: Iterable[Bits])(block: => Unit) {
+  def apply(v: Iterable[Element])(block: => Unit) {
     require(false, "The 'is' keyword may not be used outside of a switch.")
   }
 
   /** Executes `block` if the switch condition is equal to `v`.
     */
-  def apply(v: Bits)(block: => Unit) {
+  def apply(v: Element)(block: => Unit) {
     require(false, "The 'is' keyword may not be used outside of a switch.")
   }
 
   /** Executes `block` if the switch condition is equal to any of the values in the argument list.
     */
-  def apply(v: Bits, vr: Bits*)(block: => Unit) {
+  def apply(v: Element, vr: Element*)(block: => Unit) {
     require(false, "The 'is' keyword may not be used outside of a switch.")
   }
 }
@@ -91,7 +91,7 @@ object is {   // scalastyle:ignore object.name
   * }}}
   */
 object switch {  // scalastyle:ignore object.name
-  def apply[T <: Bits](cond: T)(x: => Unit): Unit = macro impl
+  def apply[T <: Element](cond: T)(x: => Unit): Unit = macro impl
   def impl(c: Context)(cond: c.Tree)(x: c.Tree): c.Tree = { import c.universe._
     val q"..$body" = x
     val res = body.foldLeft(q"""new SwitchContext($cond, None, Set.empty)""") {