Chisel v5.0.0-RC1

Features

• Add EphemeralSimulator API (by @GeorgeLyon in #3142)
  • Introduce chisel3.simulator.EphemeralSimulator for ephemeral scenarios (such as scala-cli)
• [svsim] Add option to wait for a VCS license if one is unavailable (by @GeorgeLyon in #3149)
• intmodule exporting (by @darthscsi in #3148)
  Generate implementation-specific intirnsics.
• Implement typeName API for stable Module names (by @jared-barocsi in #3130)
  This gives a flexible way to generate a stable name for a Chisel type, which is useful for problems like generating stable names for Modules and Queues
• More Circt intrinsic wrappers (IsX, PlusArgsTest, PlusArgsValue) (by @darthscsi in #2958)
  Add support for Circt intrinsics.
• Added .exclude to Connectable (by @azidar in #3172)
  Added .exclude mechanism on Connectable to enable never connecting to/from the marked fields using any connectable operator.
• Add an annotation for specifying module port conventions (by @rwy7 in #3030)
• Patch VecInit.fill(0) invocation to successfully compile and yield a zero-width Vec (by @jared-barocsi in #3171)
  Fix VecInit.fill(0) calls so that they compile and yield 0-width Vecs

API Modification

• Fix Printf macro to catch s-interpolator usages in Scala 2.13 (by @adkian-sifive in #3143)
  Fix issue with printf macro error checking to catch s-interpolator usages in Scala 2.13
• Remove _compatAutoWrapPorts no-op method (by @seldridge in #3164)
• Emit annotations in the .fir file (by @jackkoenig in #3180)
  • Annotations are now emitted in the .fir file instead of in an auxiliary .anno.json file.
  • Serialized FIRRTL is now spec v2.0.0

API Deprecation

• Deprecate ChiselStage$.elaborate (by @seldridge in #3160)
• Deprecate Scala 2.12 in Chisel 3.6 through the compiler plugin (by @jared-barocsi in #3146)
  Deprecate Scala 2.12 for Chisel 3.6 and later versions

Fixes

• Fix naming for RHS of named unapply expressions (by @jackkoenig in #3163)
  This results in previously unnamed signals receiving names from the compiler plugin.
• Report firtool version when firtool invocation errors (by @jackkoenig in #3174)

Documentation

• mdoc-ify intrinsic explanation (by @mwachs5 in #3152)
  Use mdoc to compile check the intrinsics explanation doc
• update website and explanations menus to match eachother (by @mwachs5 in #3154)
  [Website] Update Explanation Menus to align with eachother
• Fix three broken links in README.md Documentation section (by @aswaterman in #3166)
• [CI] Add Release Notes Automation (by @jackkoenig in #3170)
• Update README.md for Chisel 5 (by @jackkoenig in #3093)

Dependency Updates

• Bump to firtool 1.37.0 (by @jackkoenig in #3155)
• Bump to firtool 1.38.0 (by @jackkoenig in #3179)
  See firtool release notes.

Build and Internal Changes

• [CI] Revamp VecSpec (by @jackkoenig in #3159)
• Added definition identifiers (by @azidar in #3135)
• [CI] Require PRs to main to be labeled (by @jackkoenig in #3168)
• [CI] Install firtool in the publish step (by @jackkoenig in #3176)
• rewrite mill build scripts for chisel5. (by @sequencer in #3045)

Full Changelog: v5.0.0-M2...v5.0.0-RC1

Chisel v3.6.0

The primary change in Chisel v3.6.0 is the transition from the Scala FIRRTL Compiler to the new MLIR FIRRTL Compiler. This will have a minimal impact on typical Chisel user APIs but a large impact on custom compiler flows. For more information, please see the ROADMAP.

Try it out using this Scastie! Also check out the API Docs.

Highlights

• New implementation of the FIRRTL compiler
  • The new FIRRTL compiler has been rewritten using MLIR.
  • Faster, better SystemVerilog emission, and a growing open-source community.
  • This version was released against firtool v1.37.0.
• Refined connection semantics (#2806)
  • Flexible yet safe.
  • See the documentation.
• Paths in source locators (#2791)
  • Source locators now include a distinguishing path from the root of your workspace.
  • This enables errors that point to your specific line of Chisel from MFC.
• Error reporting that includes a source line and caret
  • This works both for errors detected during Chisel elaboration and during MFC compilation

Deprecations

Note that many more deprecations are coming before the release of 3.6.0.

• Compatibility mode (import Chisel._)
• The Scala FIRRTL Compiler (import firrtl._)
  • This includes custom annotations and transformations
• FixedPoint and related APIs
• Intervals and related APIs
• All public APIs in package chisel3.internal, these should never have been public
• group API
• chisel3.stage.ChiselStage, use circt.stage.ChiselStage instead
• forceName on components, MFC only supports forceName on module instances
• loadMemoryFromFile SFC Details (#2986)
• Protobuf emission
• CIRCTStage
• NoRunFirrtlCompilerAnnotation
• LegacyModule, LegacyBlackbox, and ImplicitInvalidate

For users who wish to continue using the Scala FIRRTL Compiler or other removed APIs for the time being, please see Migration Off Deprecated Features below.

Removals

Many APIs deprecated in Chisel 3.5 have been removed in Chisel 3.6.
This includes (but is not limited to):

• cloneType is now generated for Records, it is an error to implement cloneType manually
• MultiIOModule (use Module)
• Parenthesized forms of zero-arity methods (eg. .asUInt() is removed, use .asUInt)
• RawModule.getPorts and chisel3.getModulePorts
• stop with non-zero return code
• APIs expecting hardware Strings (printf, assert, and assume) will error if you use a Data in an s-interpolated String (s"..."), use cf"..." instead.

Performance Improvements

The MLIR FIRRTL Compiler is much faster than the Scala FIRRTL Compiler (3-7x). Users should should substantial speedups by switching to using MFC.

In addition, while there have been many performance improvements to Chisel itself included in the 3.5 release line, there are some new improvements that only apply to 3.6. Preliminary results show a speedup of 22% and 5% reduction in heap use. These results are sensitive to particular user designs so actual results may vary.

• Optimize internal _ids datastructure to reduce its size: #2866
• Avoid creating unnecessary clones: #2611
  • eg. IO(Input(UInt(8.W))) will now create only a single UInt object instead of 3
• Removed reflective naming which removes an iteration of all Data within a Module: #2562
• Removed TransitNames and thus 2 vars from every HasId: #2604
• Improve performance of ChiselEnum annotations (#2923)

Other Changes

• New warnings for mismatched widths in dynamic bit selection of UInts
• Add experimental Instantiate API for multiply instantiating modules
• Support generate structured decoder with DecodeTable
• SystemVerilog Parameters for BlackBoxes are now emitted in alphabetical order
• Several APIs were moved between packages inside of chisel3
  • eg. chisel3.experimental.ChiselEnum was moved to package chisel3
• CIRCT Intrinsics
• Tweak MuxLookup API and add MuxLookup.fromEnum

Migration from Chisel 3.5

3.6.0 includes everything from 3.5.6 and before. Some features are newly deprecated in 3.5.6 that are removed in 3.6.0. Please bump to 3.5.6 before attempting to upgrade to 3.6.0.

Migration Off Deprecated Features

All users are encouraged to stop using deprecated features and migrate to the MLIR FIRRTL Compiler; however this may be difficult for some users. For users who depend on deprecated features for which there is no obvious replacement, please reach out to the Chisel developers by filing an issue: https://github.com/chipsalliance/chisel3/issues.

For those who cannot migrate yet and would like to suppress warnings about moving off of the Scala FIRRTL Compiler, you can use Scala's configurable warning support, to suppress the specific warnings. The easiest way to do this is to add the following Scalac option to your build flow: -Wconf:msg=Importing from firrtl:s". This will silence the warnings telling you to move off of SFC.

Chisel v3.6.0-RC3

The primary change in Chisel v3.6.0 is the transition from the Scala FIRRTL Compiler to the new MLIR FIRRTL Compiler. This will have a minimal impact on typical Chisel user APIs but a large impact on custom compiler flows. For more information, please see the ROADMAP.

Try it out using this Scastie! Also check out the API Docs.

Highlights

• New implementation of the FIRRTL compiler
  • The new FIRRTL compiler has been rewritten using MLIR.
  • Faster, better SystemVerilog emission, and a growing open-source community.
  • This version was released against firtool v1.37.0.
• Refined connection semantics (#2806)
  • Flexible yet safe.
  • See the documentation.
• Paths in source locators (#2791)
  • Source locators now include a distinguishing path from the root of your workspace.
  • This enables errors that point to your specific line of Chisel from MFC.
• Error reporting that includes a source line and caret
  • This works both for errors detected during Chisel elaboration and during MFC compilation

Deprecations

Note that many more deprecations are coming before the release of 3.6.0.

• Compatibility mode (import Chisel._)
• The Scala FIRRTL Compiler (import firrtl._)
  • This includes custom annotations and transformations
• FixedPoint and related APIs
• Intervals and related APIs
• All public APIs in package chisel3.internal, these should never have been public
• group API
• chisel3.stage.ChiselStage, use circt.stage.ChiselStage instead
• forceName on components, MFC only supports forceName on module instances
• loadMemoryFromFile SFC Details (#2986)
• Protobuf emission
• CIRCTStage
• NoRunFirrtlCompilerAnnotation
• LegacyModule, LegacyBlackbox, and ImplicitInvalidate

For users who wish to continue using the Scala FIRRTL Compiler or other removed APIs for the time being, please see Migration Off Deprecated Features below.

Removals

Many APIs deprecated in Chisel 3.5 have been removed in Chisel 3.6.
This includes (but is not limited to):

• cloneType is now generated for Records, it is an error to implement cloneType manually
• MultiIOModule (use Module)
• Parenthesized forms of zero-arity methods (eg. .asUInt() is removed, use .asUInt)
• RawModule.getPorts and chisel3.getModulePorts
• stop with non-zero return code
• APIs expecting hardware Strings (printf, assert, and assume) will error if you use a Data in an s-interpolated String (s"..."), use cf"..." instead.

Performance Improvements

The MLIR FIRRTL Compiler is much faster than the Scala FIRRTL Compiler (3-7x). Users should should substantial speedups by switching to using MFC.

In addition, while there have been many performance improvements to Chisel itself included in the 3.5 release line, there are some new improvements that only apply to 3.6. Preliminary results show a speedup of 22% and 5% reduction in heap use. These results are sensitive to particular user designs so actual results may vary.

• Optimize internal _ids datastructure to reduce its size: #2866
• Avoid creating unnecessary clones: #2611
  • eg. IO(Input(UInt(8.W))) will now create only a single UInt object instead of 3
• Removed reflective naming which removes an iteration of all Data within a Module: #2562
• Removed TransitNames and thus 2 vars from every HasId: #2604
• Improve performance of ChiselEnum annotations (#2923)

Other Changes

• New warnings for mismatched widths in dynamic bit selection of UInts
• Add experimental Instantiate API for multiply instantiating modules
• Support generate structured decoder with DecodeTable
• SystemVerilog Parameters for BlackBoxes are now emitted in alphabetical order
• Several APIs were moved between packages inside of chisel3
  • eg. chisel3.experimental.ChiselEnum was moved to package chisel3
• CIRCT Intrinsics
• Tweak MuxLookup API and add MuxLookup.fromEnum

Migration from Chisel 3.5

3.6.0-RC3 includes everything from 3.5.6 and before. Some features are newly deprecated in 3.5.6 that are removed in 3.6.0-RC3. Please bump to 3.5.6 before attempting to upgrade to 3.6.0-RC3.

Migration Off Deprecated Features

All users are encouraged to stop using deprecated features and migrate to the MLIR FIRRTL Compiler; however this may be difficult for some users. For users who depend on deprecated features for which there is no obvious replacement, please reach out to the Chisel developers by filing an issue: https://github.com/chipsalliance/chisel3/issues.

For those who cannot migrate yet and would like to suppress warnings about moving off of the Scala FIRRTL Compiler, you can use Scala's configurable warning support, to suppress the specific warnings. The easiest way to do this is to add the following Scalac option to your build flow: -Wconf:msg=Importing from firrtl:s,msg=Importing from firrtl:s". This will silence the warnings telling you to move off of SFC.

Chisel v5.0.0-M2

Features

• add MuxLookup.fromEnum (by @albertchen-sifive in #3071)
  add chisel3.util.MuxLookup.fromEnum
• Fix FIRRTL spec emission and bump to spec 1.2.0 (by @jackkoenig in #3094)
  Fix emission of FIRRTL spec in emitted .fir. Now emitting FIRRTL version 1.2.0.
• add curried MuxLookup.apply, deprecate old apply (by @albertchen-sifive in #3095)
  Add a new version of MuxLookup.apply that takes two parameter lists instead of one. This helps the scala compiler report better type errors.
• Introduce svsim, a low level library for simulating SystemVerilog using Verilator and VCS. (by @GeorgeLyon in #3121)
  Added svsim, a new library for compiling and controlling SystemVerilog simulations in Scala using Verilator or VCS.
• Add Simulator class for simulating Chisel modules with svsim (by @GeorgeLyon in #3136)
  • Added chisel3.simulator.Simulator for simulating Chisel modules with svsim

API Modification

• Removed innards and NotStrict for CompileOptions, and object Chisel (by @azidar in #3055)
  Removal of Chisel and the NotStrict compile options.
• Remove compile options everywhere in Chisel internals. (by @azidar in #3056)
  Removed CompileOptions trait and associated code, as it is now unnecessary.
• Remove LegacyModule and LegacyBlackBox (by @azidar in #3058)
  Removed LegacyModule and LegacyBlackBox. Users should instead now extend Module or BlackBox.
• [nfc] Remove two unused SFC annotations (by @seldridge in #3102)
• Remove ImplicitInvalidate (by @azidar in #3096)
  Remove ImplicitInvalidate - now users must explicitly assign DontCare to a module, at instantiation site, rather than this happening automatically because the module extended ImplicitInvalidate.
• Remove reflectivelyFindIO, its unused (by @azidar in #3106)

Performance

• Make return value of Serializer.lazily lazy (by @jackkoenig in #3122)
  Reduce peak memory usage during .fir serialization by using lazy intermediate data structures.

Fixes

• Fix paper cut: bad message on calling litValue on Bundle containing DontCare (by @chick in #3043)
  There is now a better message when calling litValue on a Bundle that contains a DontCare
  that shows the Bundle and fields
• Disallow --target-dir in ChiselStage$ (by @seldridge in #3063)
• Remove deprecated CIRCT Options (by @seldridge in #3101)
• Detect bound hardware when processing record elements (by @adkian-sifive in #3037)
  Using bound hardware as an Element for a Record will now throw a better error message
• Actually fail on compilation errors and fix issue with older gcc versions (by @GeorgeLyon in #3132)

Documentation

• Fix broken cookbook link (by @mwachs5 in #3073)
  Fix broken link in the cookbook about resolving UInt index mismatches
• Update README, fix link to roadmap.md (by @jensengrey in #3091)
• Update README.md, fix scala version support badge (by @seanjensengrey in #3119)

Dependency Updates

• Bump CIRCT to 1.34.0 (by @seldridge in #3079)
• Bump to firtool 1.35.0 (by @jackkoenig in #3128)
  Bump to firtool 1.35.0, see release notes: https://github.com/llvm/circt/releases/tag/firtool-1.35.0
• Bump to firtool 1.36.0 (by @jackkoenig in #3133)
  Bump to firtool 1.36.0, see release notes: https://github.com/llvm/circt/releases/tag/firtool-1.36.0

Build and Internal Changes

• Let sbt-dynver control the SBT version (by @jackkoenig in #3064)
  Change SNAPSHOT versioning scheme to be derived from git describe --tag. SNAPSHOTs will now be unique per push to main.
• [CI] Do full unshallow clone for publish job (by @jackkoenig in #3069)
• Use -std=c++11 for Verilator 5.0 support (by @seldridge in #3066)
• Require unshallow clone to publish in SBT (by @jackkoenig in #3070)
• Release Chisel v5.0.0-M1 (by @jackkoenig in #3087)
• Simplify assertKnownWidth to Verilog test (by @seldridge in #3078)
• Add VSCode devcontainer config (by @GeorgeLyon in #3083)
  Added standard config for VSCode dev containers that can get developers up and running with just Docker and VSCode. To use, simply open the repo in VSCode and choose "Rebuild and Reopen in Container".
• More VSCode Devcontainer Improvements (by @GeorgeLyon in #3120)
• Add SBT aliases for formatting including SBT files (by @jackkoenig in #3125)
• Fix svsim to publish as part of unipublish (by @jackkoenig in #3127)
• [devcontainer] Use CIRCT full source bundle instead of git (by @GeorgeLyon in #3139)

Full Changelog: v5.0.0-M1...v5.0.0-M2

Chisel v5.0.0-M1

API Modification

• [chisel5] git subtree add FIRRTL (by @seldridge in #2982)
• [chisel5] Build FIRRTL in-tree, not published dependency (by @seldridge in #2983)
• [chisel5] Remove SFC Compiler from FIRRTL Subtree (by @seldridge in #2984)

Build and Internal Changes

• Chisel5 publishing (by @jackkoenig in #3044)
  Change published artifact from edu.berkeley.cs::chisel3 to org.chipsalliance::chisel. Set up automated publishing for 5.0-SNAPSHOT (to s01.oss.sonatype.org because Chips Alliance is a relatively new Sonatype organization). Merge old firrtl, chisel3-macros, chisel3-core, and chisel3 artifacts into a single artifact: chisel.
• Update Mergify config and add generation script to this repository (by @jackkoenig in #3059)
• [CI] Add integrationTests for execution-driven tests (by @jackkoenig in #3061)

Full Changelog: a005498...v5.0.0-M1

Chisel v3.6.0-RC2

Note: These release notes are a work-in-progress

The primary change in Chisel v3.6.0 is the transition from the Scala FIRRTL Compiler to the new MLIR FIRRTL Compiler. This will have a minimal impact on typical Chisel user APIs but a large impact on custom compiler flows. For more information, please see the ROADMAP.

Try it out using this Scastie! Also check out the API Docs.

Highlights

• New implementation of the FIRRTL compiler
  • The new FIRRTL compiler has been rewritten using MLIR.
  • Faster, better SystemVerilog emission, and a growing open-source community.
  • This version was released against firtool v1.31.0.
• Refined connection semantics (#2806)
  • Flexible yet safe.
  • See the documentation.
• Paths in source locators (#2791)
  • Source locators now include a distinguishing path from the root of your workspace.
  • This enables errors that point to your specific line of Chisel from MFC.
• Error reporting that includes a source line and caret
  • This works both for errors detected during Chisel elaboration and during MFC compilation

Deprecations

Note that many more deprecations are coming before the release of 3.6.0.

• Compatibility mode (import Chisel._)
• The Scala FIRRTL Compiler (import firrtl._)
  • This includes custom annotations and transformations
• FixedPoint and related APIs
• Intervals and related APIs
• All public APIs in package chisel3.internal, these should never have been public
• group API
• chisel3.stage.ChiselStage, use circt.stage.ChiselStage instead
• forceName on components, MFC only supports forceName on module instances
• loadMemoryFromFile SFC Details (#2986)
• Protobuf emission
• CIRCTStage
• NoRunFirrtlCompilerAnnotation

For users who wish to continue using the Scala FIRRTL Compiler or other removed APIs for the time being, please see Migration Off Deprecated Features below.

Removals

Many APIs deprecated in Chisel 3.5 have been removed in Chisel 3.6.
This includes (but is not limited to):

• cloneType is now generated for Records, it is an error to implement cloneType manually
• MultiIOModule (use Module)
• Parenthesized forms of zero-arity methods (eg. .asUInt() is removed, use .asUInt)
• RawModule.getPorts and chisel3.getModulePorts
• stop with non-zero return code

Performance Improvements

The MLIR FIRRTL Compiler is much faster than the Scala FIRRTL Compiler. Users should should substantial speedups by switching to using MFC.

In addition, while there have been many performance improvements to Chisel itself included in the 3.5 release line, there are some new improvements that only apply to 3.6. Preliminary results show a speedup of 11% and 8% reduction in heap use. These results are sensitive to particular user designs so actual results may vary.

• Optimize internal _ids datastructure to reduce its size: #2866
• Avoid creating unnecessary clones: #2611
  • eg. IO(Input(UInt(8.W))) will now create only a single UInt object instead of 3
• Removed reflective naming which removes an iteration of all Data within a Module: #2562
• Removed TransitNames and thus 2 vars from every HasId: #2604
• Improve performance of ChiselEnum annotations (#2923)

Other Changes

• New warnings for mismatched widths in dynamic bit selection of UInts
• Add experimental Instantiate API for multiply instantiating modules
• Support generate structured decoder with DecodeTable
• SystemVerilog Parameters for BlackBoxes are now emitted in alphabetical order
• Several APIs were moved between packages inside of chisel3
  • eg. chisel3.experimental.ChiselEnum was moved to package chisel3
• CIRCT Intrinsics

Migration from Chisel 3.5

3.6.0-RC2 includes everything from 3.5.6 and before. Some features are newly deprecated in 3.5.6 that are removed in 3.6.0-RC2. Please bump to 3.5.6 before attempting to upgrade to 3.6.0-RC2.

Migration Off Deprecated Features

All users are encouraged to stop using deprecated features and migrate to the MLIR FIRRTL Compiler; however this may be difficult for some users. For users who depend on deprecated features for which there is no obvious replacement, please reach out to the Chisel developers by filing an issue: https://github.com/chipsalliance/chisel3/issues.

For those who cannot migrate yet and would like to suppress warnings about moving off of the Scala FIRRTL Compiler, you can use Scala's configurable warning support, to suppress the specific warnings. The easiest way to do this is to add the following Scalac option to your build flow: -Wconf:msg=Importing from firrtl:s,msg=Importing from firrtl:s". This will silence the warnings telling you to move off of SFC.

Known Issues

The MLIR FIRRTL Compiler (firtool) published MacOS Binaries not fully statically compiled (until firtool 1.32.0)

A common issue MacOS users might see is something like:

dyld[47398]: Library not loaded: '/usr/local/opt/zstd/lib/libzstd.1.dylib'
  Referenced from: 'firtool'
  Reason: tried: '/usr/local/opt/zstd/lib/libzstd.1.dylib' (no such file), '/usr/local/lib/libzstd.1.dylib' (no such file), '/usr/lib/libzstd.1.dylib' (no such file)

The workaround is to install zstd, eg. with Homebrew brew install zstd.

This was fixed in firtool 1.32.0, although that particular version of firtool should not be used

Firtool 1.32.0 should be avoided

There is a known bug when using SyncReadMems with size == 1 and write-first read-under-write behavior. This most often happens when using chisel3.util.Queue with useSyncReadMem == true (and entries == 1). See llvm/circt#4734 for more details.

Chisel v3.6.0-RC1

Note: These release notes are a work-in-progress

The primary change in Chisel v3.6.0 is the transition from the Scala FIRRTL Compiler to the new MLIR FIRRTL Compiler. This will have a minimal impact on typical Chisel user APIs but a large impact on custom compiler flows. For more information, please see the ROADMAP.

Try it out using this Scastie! Also check out the API Docs.

Highlights

• New implementation of the FIRRTL compiler
  • The new FIRRTL compiler has been rewritten using MLIR.
  • Faster, better SystemVerilog emission, and a growing open-source community.
  • This version was released against firtool v1.30.0.
• Refined connection semantics (#2806)
  • Flexible yet safe.
  • See the documentation.
• Paths in source locators (#2791)
  • Source locators now include a distinguishing path from the root of your workspace.
  • This enables errors that point to your specific line of Chisel from MFC.

Deprecations

Note that many more deprecations are coming before the release of 3.6.0.

• Compatibility mode (import Chisel._)
• The Scala FIRRTL Compiler (import firrtl._)
  • This includes custom annotations and transformations
• FixedPoint and related APIs
• Intervals and related APIs
• All public APIs in package chisel3.internal, these should never have been public
• group API
• chisel3.stage.ChiselStage, use circt.stage.ChiselStage instead
• forceName on components, MFC only supports forceName on module instances
• loadMemoryFromFile SFC Details (#2986)

For users who wish to continue using the Scala FIRRTL Compiler or other removed APIs for the time being, please see Migration Off Deprecated Features below.

Removals

Many APIs deprecated in Chisel 3.5 have been removed in Chisel 3.6.
This includes (but is not limited to):

• cloneType is now generated for Records, it is an error to implement cloneType manually
• MultiIOModule (use Module)
• Parenthesized forms of zero-arity methods (eg. .asUInt() is removed, use .asUInt)
• RawModule.getPorts and chisel3.getModulePorts
• stop with non-zero return code

Performance Improvements

While there have been many performance improvements included in the Chisel 3.5 release line, there are some new improvements that only apply to 3.6. Preliminary results show a speedup of 11% and 8% reduction in heap use. These results are sensitive to particular user designs so actual results may vary.

• Optimize internal _ids datastructure to reduce its size: #2866
• Avoid creating unnecessary clones: #2611
  • eg. IO(Input(UInt(8.W))) will now create only a single UInt object instead of 3
• Removed reflective naming which removes an iteration of all Data within a Module: #2562
• Removed TransitNames and thus 2 vars from every HasId: #2604
• Improve performance of ChiselEnum annotations (#2923)

Other Changes

• Add experimental Instantiate API for multiply instantiating modules
• Support generate structured decoder with DecodeTable
• SystemVerilog Parameters for BlackBoxes are now emitted in alphabetical order
• Several APIs were moved between packages inside of chisel3
  • eg. chisel3.experimental.ChiselEnum was moved to package chisel3
• CIRCT Intrinsics

Migration from Chisel 3.5

3.6.0-RC1 includes everything from 3.5.6 and before. Some features are newly deprecated in 3.5.6 that are removed in 3.6.0-RC1. Please bump to 3.5.6 before attempting to upgrade to 3.6.0-RC1.

Migration Off Deprecated Features

All users are encouraged to stop using deprecated features and migrate to the MLIR FIRRTL Compiler; however this may be difficult for some users. For users who depend on deprecated features for which there is no obvious replacement, please reach out to the Chisel developers by filing an issue: https://github.com/chipsalliance/chisel3/issues.

For those who cannot migrate yet and would like to suppress warnings about moving off of the Scala FIRRTL Compiler, you can use Scala's configurable warning support, to suppress the specific warnings. The easiest way to do this is to add the following Scalac option to your build flow: -Wconf:msg=Importing from firrtl:s,msg=Importing from firrtl:s". This will silence the warnings telling you to move off of SFC.

Known Issues

The MLIR FIRRTL Compiler (firtool) published MacOS Binaries not fully statically compiled

A common issue MacOS users might see is something like:

dyld[47398]: Library not loaded: '/usr/local/opt/zstd/lib/libzstd.1.dylib'
  Referenced from: 'firtool'
  Reason: tried: '/usr/local/opt/zstd/lib/libzstd.1.dylib' (no such file), '/usr/local/lib/libzstd.1.dylib' (no such file), '/usr/lib/libzstd.1.dylib' (no such file)

The workaround is to install zstd, eg. with Homebrew brew install zstd.

This is true at least as of firtool 1.31.0 but will hopefully be fixed in a future firtool release.

Chisel v3.5.6

Deprecation

• Deprecate TruthTable.sort (#2935)
• Promote ChiselEnum user APIs from experimental (#2929)

Performance

• Implement compressed Namespace (#2856)
• Improve performance of ChiselEnum annotations (#2923)
• TruthTable improvements: structural equality (#2935)

BugFix

• Fix names of OpaqueTypes in fullModulePorts (#2845)
• Make PriorityMux stack safe (#2854)
• Fix string interpolation in util.exprimental.decode.bitset (#2882)
• Check for Vec subaccess in NamedComponent and throw a nicer error (#2907)

Other

• Add versionScheme (PVP) to SBT publish settings (#2871)

Chisel v3.6.0-M2

Note: These release notes are a work-in-progress

The primary change in Chisel v3.6.0 is the transition from the Scala FIRRTL Compiler to the new MLIR FIRRTL Compiler. This will have a minimal impact on typical Chisel user APIs but a large impact on custom compiler flows. For more information, please see the ROADMAP.

Try it out using this Scastie!

Highlights

• New implementation of the FIRRTL compiler
  • The FIRRTL compiler has been rewritten using MLIR.
  • Faster, better SystemVerilog emission, and a growing open-source community.
  • See CIRCT.
• Refined connection semantics (#2806)
  • Flexible yet safe.
  • See the documentation.
• Paths in source locators (#2791)
  • Source locators now include a distinguishing path from the root of your workspace.
  • This enables errors that point to your specific line of Chisel from MFC.

Deprecations

Note that many more deprecations are coming before the release of 3.6.0.

• Compatibility mode (import Chisel._)
• The Scala FIRRTL Compiler
• FixedPoint and related APIs
• Intervals and related APIs

Removals

Many APIs deprecated in Chisel 3.5 have been removed in Chisel 3.6.
This includes (but is not limited to):

• MultiIOModule (use Module)
• Parenthesized forms of zero-arity methods (eg. .asUInt() is removed, use .asUInt)
• RawModule.getPorts and chisel3.getModulePorts
• stop with non-zero return code

Performance Improvements

While there have been many performance improvements included in the Chisel 3.5 release line, there are some new improvements that only apply to 3.6. Preliminary results show a speedup of 11% and 8% reduction in heap use. These results are sensitive to particular user designs so actual results may vary.

• Optimize internal _ids datastructure to reduce its size: #2866
• Avoid creating unnecessary clones: #2611
  • eg. IO(Input(UInt(8.W))) will now create only a single UInt object instead of 3
• Removed reflective naming which removes an iteration of all Data within a Module: #2562
• Removed TransitNames and thus 2 vars from every HasId: #2604

Other Changes

• SystemVerilog Parameters for BlackBoxes are now emitted in alphabetical order

Migration

3.6.0-M2 includes everything from 3.5.5 and before. Some features are newly deprecated in 3.5.5 that are removed in 3.6.0-M2. Please bump to 3.5.5 before attempting to upgrade to 3.6.0-M2.

Additional Changes since 3.6.0-M1

• Bump CIRCT support (originally chisel-circt) from 0.5.0 to 0.8.0 (#2878)
• Fix string interpolation in util.exprimental.decode.bitset (#2882)
• Bugfix waiveEach not casting. Add waiveAllAs (#2894)
• [circt] Cleanup CIRCT error behavior (#2896, #2892)
• Take into account opaque members in squeeze functions (#2904)
• Clarify mismatched width error message (#2917)
• Fix bug where Flipped did not properly flip (#2919)
• Fix lazy cloning (#2921)

For complete changes since 3.6.0-M1, run

git log --oneline $(git merge-base origin/master v3.6.0-M1)..$(git merge-base origin/master v3.6.0-M2)

Chisel v3.6.0-M1

Note: These release notes are a work-in-progress

The primary change in Chisel v3.6.0 is the transition from the Scala FIRRTL Compiler to the new MLIR FIRRTL Compiler. This will have a minimal impact on typical Chisel user APIs but a large impact on custom compiler flows. For more information, please see the ROADMAP.

Try it out using this Scastie!

Highlights

• New implementation of the FIRRTL compiler
  • The FIRRTL compiler has been rewritten using MLIR.
  • Faster, better SystemVerilog emission, and a growing open-source community.
  • See CIRCT.
• Refined connection semantics (#2806)
  • Flexible yet safe.
  • See the documentation.
• Paths in source locators (#2791)
  • Source locators now include a distinguishing path from the root of your workspace.
  • This enables errors that point to your specific line of Chisel from MFC.

Deprecations

Note that many more deprecations are coming before the release of 3.6.0.

• Compatibility mode (import Chisel._)
• The Scala FIRRTL Compiler

Performance Improvements

While there have been many performance improvements included in the Chisel 3.5 release line, there are some new improvements that only apply to 3.6. Preliminary results show a speedup of 11% and 8% reduction in heap use. These results are sensitive to particular user designs so actual results may vary.

• Optimize internal _ids datastructure to reduce its size: #2866
• Avoid creating unnecessary clones: #2611
  • eg. IO(Input(UInt(8.W))) will now create only a single UInt object instead of 3
• Removed reflective naming which removes an iteration of all Data within a Module: #2562
• Removed TransitNames and thus 2 vars from every HasId: #2604

Other Changes

• SystemVerilog Parameters for BlackBoxes are now emitted in alphabetical order

Migration

3.6.0-M1 includes everything from 3.5.5 and before. Some features are newly deprecated in 3.5.5 that are removed in 3.6.0-M1. Please bump to 3.5.5 before attempting to upgrade to 3.6.0-M1.