chipsalliance / chipsalliance/chisel
[RFC] Bundle and Vec .Lit and .Wire
- Dominant language
- Scala
- Stars
- 4.8k
- Forks
- 658
- Avg merge
- 18h 59m
- Merged PRs (30d)
- 14
Description
## Background
- #805 proposes Bundle literal constructors (which is new functionality that can't really be replicated in the existing API), but syntactic sugar for constructing Bundle wires with a similar syntax also has uses. As proposed, Bundle literal constructors would not be able to create eg a Bundle wire with values pre-set to IOs.
- #986 changes WireInit to WireDefault, which better reflects the underlying hardware (wires are not Regs, and cannot be initialized, but can have a default value given last-connect semantics). We currently have VecInit, which is analogous to what's now WireDefault but with no proposed replacement.
- #849 requests Vec literals, which would be useful for unpacking literal-to-bits, and for testers2 inputs and outputs.
## Proposal
- Keep the APIs between literal constructors and wire-with-default constructors separate. This is in line with the current philosophy of strict separation of types, especially when they have different functionality (eg `litOption`, `litToBoolean`). This also provides a cleaner path to literal types in the type system if we ever want to re-explore #777.
- The Lit API is the proposal in #805, which creates a literal type given literal elements. For a example Bundle, it would be;
```scala
(new MyBundle(8)).Lit(a=true.B, b=255.U)
```
for a Vec, it would be similar to VecInit where the output type is inferred from elements:
```scala
Vec.Lit( Seq(0.U, 1.U, ...) )
```
Important note: Bundle literal constructors requires an instance of the Bundle as a template, whereas Vec literal constructors do not. We cannot infer the concrete Bundle type given a companion object since there may be parameters.
- The Wire API would be similar structurally, but accept non-literal elements and return non-literal type:
```scala
(new MyBundle(8)).Wire(a=true.B, b=io.bits)
Vec.Wire( Seq(0.U, io.bits, ...) )
```
Note that this will accept any hardware type, including (but not restricted to) literals. `Vec.Wire` is equivalent to `VecInit`.
- `VecInit` would be 'deprecated' using the same mechanism we use for #986 / #1001, which will be at least standard lint rules and possibly also a deprecation.
- A similar structure would apply to `MixedVec` and `Record` (possibly - the input would be a Map of string name to value, since there's no static structure we could generate a Lit method for) types.
- Attempting to pass a non-literal into the `.Lit` method could give a good diagnostic error that suggests the use of the similar `.Wire` method.
## Questions
- Since we're introducing `Vec.Wire` (and also `MixedVec.Wire`), this is also a chance to revisit the API. Note that the Scala constructors for `Seq`/etc (nearest analogy to `Vec.Wire`) are all varargs, should `Vec.Wire` be varargs only? We could create a PML `.toVecWire` (and maybe also `.toVecLit`) which is more analogous to the Scala `.toSeq` conversions.
- Perhaps something similar should be done for the Map-to-Bundle conversions, like `.toBundleLit(bundleType)`? In this case, Record would not have a `.Lit` or `.Wire` method, and `Map.toRecordWire(recordType)` / `Map.toRecordLit(recordType)` must be used instead.
## Alternatives
- ~An alternative would be to have a single constructor that dynamically determines whether the output is of Wire or Literal type, depending on if the inputs are Literals. This should be possible implementation-wise, but could make statically typed literals more difficult if we wanted to try that again in the future, and could make code less clear where a literal is required, especially for testers2.~ This is a bad idea for functional reasons described in the comments.
---
**Type of issue**: other enhancement
**Impact**: API addition (no impact on existing code), API modification
**Development Phase**: proposal
Contributor guide
Research direction
No implementation files, entry points, or tests are named. Start by reading the related proposals #805, #986, #849, and #777, then review the unresolved API questions and comments. Done requires an agreed design for Bundle, Vec, MixedVec, and Record literal and wire APIs before implementation can be scoped.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- scala
- Domain
- compilers, embedded-iot
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100