chisel
Chisel: A Modern Hardware Design Language
APACHE-2.0 License
Bot releases are visible (Hide)
- 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
-
- 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.
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,
- we've provided more support for the Invalidate API in various corner cases - (#745, #731)
- cleaned up some error messages - (#739)
- fixed some compiler and ScalaDoc warnings and added documentation - (#738, #737)
- updated some build plugins
- added issue and pull_request templates - (#713)
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.W
creates 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=...) -> RegNext(...)
InvalidateAPI
A preliminary version of the Invalidate API (requiring the author to explicitly mark unconnected output wires as DontCare) is included in this release.
Please see Unconnected Wires and InvalidateAPISpec.scala for discussion and examples.
BlackBoxes
chisel3 supports parameterized BlackBoxes.
BlackBoxes may not contain hardware since it will be silently dropped anyway.
See BlackBoxes, BlackBox.scala, and BlackBoxImpl.scala.
Clock and Reset
The clock signal was renamed from clk to clock in chisel3.
chisel3 contains more mechanisms for managing clock and reset than chisel2.
See Experimental Features, Multiple Clock Domains, MultiClockSpec.scala, and RawModuleSpec.scala
Mem
The memory API is changed from chisel2 in chisel3.
Specifically argument order is changed and core components have been renamed.
The VecLike trait has been removed from Mem since this behavior can not be guaranteed for all memories.
See Memories.
Utilities
IrrevocableIO has been added as an extension to ReadyValidIO.
It promises to not change the value of bits after a cycle where valid is high and ready is low.
Additionally, once valid is raised it will never be lowered until after ready has also been raised.
log2Up() and log2Down() are deprecated in favor of log2Ceil() and log2Floor().
Tester Support
This is an area that is undergoing active development as we try to reconcile the various tester flavors.
Currently, testers live in a separate repository: https://github.com/freechipsproject/chisel-testers.
Check its wiki page for examples.
The chisel-template and chisel-tutorial repositories also contain examples of the new chisel-testers.
Drivers
We've implemented a standard execution scheme for chisel3 libraries.
This provides per-project parameter handling and methods for constructing tool chains from the various chisel3 top-level libraries.
See Running Stuff and DriverSpec.scala
Experimental
chisel3 contains a number of experimental features.
See Experimental Features.
Annotations
chisel3 provides a mechanism to mark modules and their elements in a way that can be accessed by Firrtl transformation passes.
See Annotations Extending Chisel and Firrtl and AnnotatingDiamondSpec.scala and AnnotationNoDedup.scala.
Module Hierarchy
chisel3 has a richer Module hierarchy to deal with non-chisel IP.
See Functional Module Creation, Modules, and RawModuleSpec.scala and ExtModule.scala.
