Skip to content

v3.0.0
Compare
Choose a tag to compare
@ucbjrl ucbjrl released this 25 Nov 00:40
· 119 commits to release since this release
v3.0.0
78bfa07

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.

Assets 2
Loading