Skip to content

Chisel v3.6.0-RC2

Pre-release
Pre-release
Compare
Choose a tag to compare
@jackkoenig jackkoenig released this 28 Feb 04:50
v3.6.0-RC2
24c7a59

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
  • Refined connection semantics (#2806)
  • 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.

Assets 2