Releases: chipsalliance/chisel
v3.0.1
chisel3 Release Notes
This release of chisel3 includes bug fixes for the following issues:
- Negative shift amounts should issue an error (#729)
- DontCare Influences Type Inference (#728)
- Mem of Vec cannot be accessed as expected (#708)
- Unhelpful Error Message Connecting Seq to Vec of different size (#482)
Additionally,
v3.0.0
chisel3 Release Notes
Code Organization
What was the old chisel repository has been split into two repositories: chisel3 and chisel-testers.
The motivation for this was to ensure testers could be written without requiring an intimate connection to core chisel. We may re-visit this decsision in the future.
We have three new chisel-related repositories: firrtl, firrtl-interpreter, and dsptools.
Within the chisel3 repository we've tried to package components logically.
The coreMacros package contains all macro definitions and is compiled first so other packages can make use of those definitions.
The chiselFrontend package contains user-facing definitions.
API definitions are found in package objects chisel3 (for pure chisel3) and Chisel (for chisel2 compatibiliy mode).
The uility classes are found in individual files in util.
Scaladoc for all chisel3 classes can be found on the chisel website at https://chisel.eecs.berkeley.edu/api/
Documentation and examples can be found on the chisel3 wiki at https://github.com/freechipsproject/chisel3/wiki
Other examples can be found in the chisel3 tests.
The Compatibility Package
In principle, you should be able to run your chisel2 projects by simply updating your libraryDependencies (if using sbt), or by othrwise substituting the chisel_2.11-2.2.38.jar with chisel3_2.11-3.0.0.jar (for releases) or
chisel_2.11-2.3-SNAPSHOT.jar with chisel3_2.11-3.1-SNAPSHOT.jar (for SNAPSHOTS).
chisel3 has a Chisel package object that attempts to provide the chisel2 API from chisel3 code.
It's not perfect, but we have been able to convert some rather large designs from chisel2 to chisel3 using this package object.
The wiki contains information on converting code from chisel2 to chisel3.
If you encounter problems, please report them to the mailing lists () or file an issue on the chisel3 GitHub repo.
If you're using chisel testers, you'll need to add either chisel-iotesters_2.11-1.1.0.jar (for releases) or chisel-iotesters_2.11-1.1-SNAPSHOT.jar (for SNAPSHOTS) to your libraryDependencies.
You may also need to make adjustments to your tester code.
See the chisel-tutorial and chisel-template repositories for examples.
Differences between the Chisel compatibility package and pure chisel3.
The compatibility package attempts to provide chisel2 semantics in chisel3.
We provide the old chisel2 constructors and utilties and the more permissive chisel2 connection logic.
Types
One of the early design goals for chisel3, was to reduce the opportunity for subtle errors to creep into a design, and reduce ambiguities concerning the author's intent.
Supporting multiple constructors where several parameter sequences were valid made it more difficult to flag possible errors.
We've eliminated the single argument form of the UInt/SInt/Bool constructors used to construct literals.
These constructors now take a single argument of type Width to specify width.
An integer (or BigInt) can be converted to a Width with the W method call:
4.Wcreates a Width type with value 4.
Generating an UInt type of width 4 becomes:
UInt(4.W)NOTE: The old constructor syntax is supported in compatibility mode.
cloneType
We're trying to make chisel hardware definitions immutable, but this requires that we are able to clone a hardware object, when we need to generate an internal object of the same type.
We'd like to provide an automatically generated cloneType for aggregate objects (Bundles, Vecs), but it is difficult to do so.
chisel3 is capable of handling more situations than chisel2 automatically, but it's not perfect.
If we cannot successfully generate a cloned type, chisel3 will generate an error and require the author provide a cloneType method for the object.
Literals
chisel3 supports a new way to define hardware literals.
The new ways of constructing a literal / data type are:
value.U, value.asUInt /* auto-determined width */
value.U(width), value.asUInt(width) /* explicit width */where value is either an Int, BigInt, or String, and width is a Width (Widths can be created from Ints using x.W)
and similar constructors for Bits, SInt (x.S), and Bool (x.B)
A few regex conversion examples are provided that can automate the transformation in package.scala.
Enums
All old APIs (with some new restrictions) are preserved without deprecation in the Chisel compatibility package, aside from the non-compile-time-checkable Map[] enum constructor which probably should have been deprecated during chisel2.
The Map[] enums have been removed from chisel3 without deprecation.
The new restriction is that nodeType (legacy API) may only be of UInt type with unspecified width. Note that Bits() creates a UInt, and if you can't control the enum values, it makes little sense to specify a bitwidth.
/** Returns n unique values of the specified type. Can be used with unpacking to define enums.
*
* nodeType must be of UInt type (note that Bits() creates a UInt) with unspecified width.
*/
val state_on :: state_off :: Nil = Enum(UInt(), 2)
val current_state = UInt()
switch (current_state) {
is (state_on) {
...
}
if (state_off) {
...
}
}Currently, due to firrtl restrictions, the minimum width of an enum is 1.W
Aggregates - Bundles
In chisel3, Bundles now support an optional field.
See OptionBundle.scala
Bundle now extends abstract class Record which extends Aggregate.
Record takes much of the code originally in Bundle, but leaves elements (ListMap[String, Data]) and cloneType unimplemented.
Bundle implements these fields (elements via reflection, cloneType with the same "best effort" attempt as before).
Library writers and power users can extend Record directly to build more interesting custom Chisel Data types.
Bundle is still the workhorse of RTL.
Since Bundle extends Record, the two are interoperable with Record becoming the type generally used within chisel3.
The current RecordSpec tests illustrate programmatically creating bundles from ListMaps directly.
See RecordSpec.scala for examples.
Aggregates - Vec
Vec's are homogeneous - all elements of a Vec must be of the same type. See Record for dynamically constructed objects with heterogeneous elements.
Vec's are useful for containing hardware elements that must be dynamically selected in the running hardware.
If you only need Chisel compile-time selection, use a Scala collection instead.
Various corner cases with Vec usage have been rounded out in chisel3.
See Bundles and Vecs and Vec.scala for examples.
Binding
chisel3 keeps track of the binding state of hardware elements and attempts to diagnose potential mistakes when binding rules are violated.
There are four major binding states:
- unbound
- literal
- IO port
- wire
The latter three are bound states.
Hardware connections (<>, :=) are only allowed between bound hardware elements.
Items that provide types for other hardware objects (Mem, Reg, Wire, Vec, Bundle) must be unbound.
An unbound type may be bound by wrapping it in a Wire().
A bound type may be unbound by wrapping it in a chiselTypeOf().
requireIsHardware and requireIsChiselType are made available in chisel3.experimental.
Direction
A bound object may have a direction.
Input(...) and Output(...) are wrappers replacing the chisel2 INPUT and OUTPUT constructor arguments.
They are recursively applied to aggregate elements and override their elements' directions.
DataMirror (node reflection APIs) have been added to chisel3.experimental.
This provides ways to query the user given direction of a node as well as the actual direction.
Direction is separated from Bindings.
Both are now fields in Data, and all nodes are given hierarchical directions (Aggregates may be Bidirectional).
The actualDirection at the Element (leaf) level should be the same as binding directions previously.
Bindings are hierarchical, children (of a, for example, Bundle) have a ChildBinding that points to their parent.
This is different than earlier versions of chisel3 where Bindings only applied at the Element (leaf) level.
Reg/Wire/Vec Initializers
The init= argument to Reg, Wire, and Vec constructors is deprecated in favor of separate constructors.
Reg(init=...) -> RegInit(...)Similarly, the next= argument to the Reg() constructor is deprecated in favor of:
Reg(next...v3.0.0-RC2
v3.0.0-RC1
- Invalidate API (#645)
Prior to this pull request, chisel automatically generated a DefInvalid for Module IO(), and each Wire() definition. This made it difficult to detect cases where output signals were never driven.
Chisel now supports a DontCare element, which may be connected to an output signal, indicating that that signal is intentionally not driven.
Firrtl will complain with a "not fully initialized" error if a signal is not driven by hardware or connected to a DontCare.
This feature is controlled by CompileOptions.explicitInvalidate and is set to false in NotStrict (Chisel2 compatibility mode), and true in Strict mode.
Please see the corresponding API tests for examples.
v3.0-SNAPSHOT_2017-10-06
- Remove warning in Queue for compatibility code (#702)
- cloneType and chiselCloneType API change (#653)
-
cloneType is now marked (through comments only) as an internal API.
-
chiselCloneType is deprecated (and changed to cloneTypeFull internally, analogous to cloneTypeWidth).
-
chiselTypeOf(data) introduced as the external API to get a chisel type from a hardware object
-
Intended usage:
Cloning is an implementation detail, and chisel types and hardware objects both should act as immutable types, with operations like Input(...), Reg(...), etc returning a copy and leaving the original unchanged. Hence, the clone operations are all deprecated.
Input(...),Output(...),Flipped(...)require the object to be unbound
-
v3.0-SNAPSHOT_2017-09-27
v3.0-SNAPSHOT_2017-09-14
This is the first Chisel3 BIG4 SNAPSHOT release to support Scala 2.12.
Unfortunately, behavior we've come to rely on when generating anonymous classes structurally has been deemed a bug in Scala 2.12 ("Inferred types for fields").
This is Chisel3 issue (#606).
The following code:
import Chisel._
class MyModule extends Module {
val io = new Bundle {
val in = UInt(INPUT, width = 8)
val out = UInt(OUTPUT, width = 8)
}
io.out := io.in
}Results in:
Error:(12, 6) value out is not a member of Chisel.Bundle
io.out := io.in
Error:(12, 16) value in is not a member of Chisel.Bundle
io.out := io.in
NOTE: This seems to be constrained to compatibility mode.
The normal chisel3 wrappers IO(), Wire() cause the inferred value to be the structural type of their argument (the behavior we desire).
As stated in Chisel3 issue (#606), the work around is to add:
scalacOptions ++= Seq("-Xsource:2.11")to your build.sbt file if you're using Chisel3 in compatibility mode with Scala 2.12.
v3.0-SNAPSHOT_2017-08-16
- Make .dir give correct direction for Module io in compatibility (#673)
- Rename userDir->specifiedDir (#671)
- README: Java package (#670)
- Give default direction to children of Vecs in compatibility code (#667)
- Don't assign default direction to Analog in Chisel._ (#664)
- Address scalastyle issues, out of date comments, extraneous imports. (#658)
- Black box top-level IO fix (#655)
- Add rebinding test (#654)
- Fix style of literal creators (#637)
- Simplify macOS install instructions (#599)
- Fixed point width inference was wrong when binary points didn't align. (#590)