[RFC] Literal Types

Motivation

Currently, literals have the same type as any other hardware node, and conversions back to Scala types can fail at runtime. Which hasn’t been much of a problem, because needing to extract a literal is a rare case. However new testers (#725) proposes the uniform use of literals in interfacing with the simulator, because there’s a lot of convenience functions (like binary constructors) that Scala types like Int/BigInt don’t have, as well as the ability to use bundle literal constructors (whenever that gets implemented). However, without type differentiation, failures can be pushed to runtime, which could lead to unpredictable and hidden failures.

Related issues:

• Bundle literals #418
• Statically usable literals #417

Proposal

Create a trait Literal which literal types would extend in addition to the current Data (chisel type) hierarchy.

External APIs

A sketch of the new (essentially parallel) type hierarchy would be:

• BitsLit extends Bits with Literal
  • .asInt extracts the contents as an unsigned (unless overridden) Scala Int. Runtime exception if the literal is too large to fit in a Int.
  • TODO: should there be .asLong?
  • .asBigInt extracts the contents as an unsigned (unless overridden) Scala BigInt
• UIntLit extends UInt with BitsLit
  • this provides no additional features compared to Bits
• SIntLit extends SInt with BitsLit
  • .asInt, .asBigInt will return signed instead
• BoolLit extends Bool with UIntLit
  • .asBoolean extracts the contents as a Scala Boolean
• FixedPointLit extends FixedPoint with BitsLit
  • .asFloat extracts the contents as a Scala float

TODO: Is there an advantage to type paramterize Literal by the chisel type, eg trait Literal[T <: Data] and UIntLit extends UInt with Literal[UInt]?

Internal APIs

Literal values would no longer be associated with the Chisel types (so UInt would no longer have a lit / litArg variable), they would instead be stored in their literal classes. A deprecated shim would be included for compatibility.

Primary driving example

• new testers
• any other uses?

Projected impact

Should minimally affect existing code, since literals still extend (and can be used in places that accept) their previous chisel data types. Unsafe literal extraction operations would now be deprecated.

Related issues

Bundle literal constructors (#418) would be a separate issue but use this infrastructure. Annotation macros could be used to automatically generate the parallel literal hierarchy.

• Type of issue

  • Bug report
  • Feature request
  • Other enhancement

• What is the use case for changing the behavior? Typesafe literal extraction for #725

• Impact

  • no functional change
  • API addition (no impact on existing code)
  • API modification
  • unknown

• Development Phase

  • request
  • proposal

@jackkoenig @chick

[grebe]

Agree with @chick. One use case to add to the list is constructors/factories- with something like DspComplex we want to do something different when you say DspComplex(realLit, imagLit) and DspComplex(realVar, imagVar). Ideally, the first would also have type Literal and not have any wires.

[ducky64]

Thanks for playing everyone, this is dead and pieces will be rolled into testers.