v3.2.0-RC1

API Modification

(#1162) Move dontTouch, RawModule, and MultiIOModule out of experimental
The object dontTouch and the classes RawModule and MultiIOModule are promoted from experimental, implying their respective APIs are stable.

NOTE: There will be corresponding pull requests for the rest of the BIG10 that are impacted by these changes. This PR is required for the 3.2.0-RC1 release.

Fix

(#884) Inhibit aggressive resource file name mangling.
Minimize the name mangling of output resource files.

(#950) asBools, asBool, and chained apply on asBools

• toBools -> asBools (toBools deprecated)
• toBool -> asBool (toBool deprecated)
• Fix chaining of apply after .asBools

(#995) Support DontCare in Mux and cloneSupertype
Support DontCare in Muxes

(#1036) Fix typo in link

(#1065) RawModule with no reset should be able to use withClock method.

(#1091) Fix treatment of Vec of Analog and Vec of Bundle of Analog

Feature

(#693) Incorporate lessons learned from latest publishing.

(#718) BoringUtils / Synthesizable Cross Module References

(#819) Add width utility functions to avoid incorrect usage of bare log2Ceil().
Add helper functions UnsignedBitsRequired and UnsignedWidthRequired to provide an alternative to the potentially incorrect usage of log2Ceil to calculate wire widths.

(#820) Bundle Literals Framework

• Adds litToBigInt[Option], litToBoolean[Option], and litToDouble[Option] APIs. Deprecates previous isLit, litArg, litValue APIs, since those expose implementation details (LitArg), do not have Option variants, and may not return the type desired (BigInt/Boolean/Double).
• [internal] literals now specified in Bindings, instead of in Data subtypes.
• [internal] adds support for Bundle literals by introducing a Bundle literal binding that contains a map of leaf subelements to their literal values.
• [internal] ids are now persistent through runs, necessary to allow Bundle literals outside a Builder context (otherwise, a new IdGen is created for each element, and the ids alias).
• [internal] HasId hashcode and equals reverted to the Java Object defaults, which allows Data created outside a Builder context to be Map-indexable
• [internal] Created a ChiselContext (like DynamicContext) for global operations (like _id creation) that can be done outside a Builder context.
• [internal] lref/ref checks are more strict, but Bindings should ensure they don't trip, and cases where they do trip are likely to be FIRRTL errors.
• [internal] Made accesses to DynamicContext more strict, and will throw an error in most cases. The exceptions are error logging (errors are discarded) and getting the current Module (which will return None if outside a Builder context).

Other notes:

• Support for bundle literal extractors is not yet implemented (the TODO is intentional), proposal is to have litToBigInt[Option] do the right thing. Note that bundle subelement literals can be extracted.
• Support for generating Bundle literal constructors by macro annotation will be in a future PR. This only provides the internal framework to support Bundle literals at all. A mockup of what the generated code could look like is in the Bundle literal test case.
• litArg, litValue, isLit are deprecated globally, even in Chisel context. If anyone really cares (as in, this causes problems for someone), I can move those into the compatibility layer without the deprecation warning through implicit conversions.

(#829) Direct to firrtl
Directly translate from ChiselIR to FIRRTL without using the FIRRTL ANTLR Parser

(#833) [RFC] [Proposal] Programmatic Port Creation
Programmatic Port Creation

(#837) Add Emacs temporaries, backups to .gitignore

• Add Emacs temporaries, backups to top-level .gitignore

(#838) Add instance inline API

• Add instance inlining and flattening API

(#839) Correcting documentation errors in Arbiter.scala
Documentation Fixes in Arbiter.scala

(#840) Support for verilog memory loading.
The new annotation ChiselLoadMemoryAnnotation provides support for a memory to be
initialized during simulation. This uses the verilog $readmemh or $readmemb to provide a
text file with numeric values that can be loaded into the memory at the beginning of simulation.

Usage

Simple Memory

import chisel3.util.loadMemoryFromFile
...
// within a module
  val memory = Mem(memoryDepth, UInt(32.W))
  loadMemoryFromFile(memory, "mem_data")  // actual file name must be mem_data.txt

The default input format is hex using $readmemh. Binary text can be used instead via

  loadMemoryFromFile(memory, "mem_data", hexOrBinary = "b")

Memory can be an aggregation

class MemoryShape extends Bundle {
  val a = UInt(8.W)
  val b = SInt(8.W)
  val c = Bool()
}

class HasComplexMemory(memoryDepth: Int) extends Module {
 ...
  val memory = Mem(memoryDepth, new MemoryShape)
  loadMemoryFromFile(memory, "mem_data")

This memory will be broken up by the Firrtl compiler into three separate memories
memory_a, memory_b, memory_c
There must be a separate load file for each of these memories with the names
mem_data_a.txt, mem_data_b.txt, mem_data_c.txt

These files are not checked at compile time. It might be a good idea to give them full path names.

Input file format.

Standard verilog file compatible with $readmemh or $readmemb. Data has to exist in a text file. White space is allowed to improve readability, as well as comments in both single line and block. The numbers have to be stored as binary or hexadecimal values. The basic form of a memory file contains numbers separated by new line characters that will be loaded into the memory.

Implementation details

Using these annotations will create parallel modules using Chisel3's in-line black boxes and these parallel modules will be connected to the unaltered modules using verilog's bind statement.

(#842) Catch returns from within when blocks and provide an error message
Returns within when scopes used to give opaque error messages. Now they are caught earlier (with a stack trace) and explained in the error message.

(#843) Ignore eclipse metadata
Add Scala IDE (Eclipse) project metadata to .gitignore

(#846) Undeprecate log2Up and log2Down
Undo the deprecation of log2Up and log2Down until zero-width wires work.

(#850) Heterogeneous Vec (MixedVec)

• Add a new dynamically indexable sequence like Vec that supports different underlying widths/types.

(#851) Bump recommended Verilator version to 3.922
Update the recommended Verilator version in README.md

(#853) Ensure names work for bundles and literals.
Ensure that instanceName can be called on any signal.

(#854) Fix use of read-only refs on rhs of connect in compatibility mode
Fix bug preventing the use of the output of aggregate Muxes on the rhs of a connection in compatibility mode.

(#855) Update versions and links in README

(#857) Revert removal of bit extraction const prop for literals

(#858) Bump to Scala 2.12.6 and make it the default.
Bump Scala 2.12 to 2.12.6 and make it the default.

(#862) Add support for Input() and Output() and test for same.
Input() and Output() have been available in Chisel2 since ucb-bar/chisel2-deprecated#734. Provide support for them in the compatibility package.

(#863) Update latest release reference.
Update latest release.

(#868) Cleanup implicit conversions
Removed implicitly added identity methods .data and .target from Data and DecoupledIO, and removed .x from String, Int, Long, BigInt, and Boolean

(#873) API Documentation Improvements

• Improve API documentation using ScalaDoc groups

(#876) Minor tweaks to the style guide

(#877) [F764.1] Bump scopt from 3.6.0 -> 3.7.0

• Bump scopt from 3.6.0 -> 3.7.0

(#880) [F764.2] Add dumpAnnotations method to Driver
Add dumpAnnotations method to Driver

(#887) Give type annotation to litOption.
The litOption field currently has no type that can be inferred. Some subtypes override it and give it a type, but the original declaration should have a type so things like bundles can override it.

(#888) Bump version reference in README.md

(#892) Strong enums

• Added support for strongly-typed, self-annotating enums

(#894) Documentation tweaks

(#895) Add CODEOWNERS file

(#898) Change InlineSpec to expect "_" and not "$"

(#901) Add DataMirror.modulePorts
Add chisel3.experimental.DataMirror.modulePorts(module: BaseModule): Map[String, Data]

(#902) Modify ReadyValidIO noenq to set the data payload to DontCare.
Modified ReadyValidIO (also used in DecoupledIO) to set the data payload (.bits) to don't care when a no enqueue action (noenq) is called. This will clean up the frequently used idiom:

c.noenq
when( cond) {
  c.enq( data)
}

This currently needs to be written as:

c.noenq
c.bits := DontCare
when( cond) {
  c.enq( data)
}

It is possible that noenq was used like this in some existing code:

c.bits := 47.U
c.noenq
when( cond) {
  c.valid := true.B
}

If this was the case, then the PR will change the behavior of the circuit.
The comment for noenq is:

    /** Indicate no enqueue occurs. Valid is set to false, and bits are
      * connected to an uninitialized wire
      */

so it wasn't supposed to be used this way.

(#903) add HasBlackBoxPath to BlackBoxUtils.scala
Add HasBlackBoxPath to BlackBoxUtils.scala

(#912) Make BaseModule.name lazy

• Make BaseModule.name lazy to enable better name parameterization, e.g., a module name can now be a function of a submodule name

(#913) Add BigInt / Int to Bool conversion (0.B, 1.B)

(#914) Fix LoadMemoryTransform for Instance Annotations

(#916) Turn off strong enum annotations

(#918) Fix Queue.io.count when entries=1
Queues with depth 1 now correctly report how many entries are present.

(#920) Circleci
Add support for CircleCI builds.

(#923) Add CircleCI status badge to README

(#926) Convert to 2.1 .circleci/config.yml

(#930) Add Chisel logo to repo and README
Add SVG and PNG formatted Chisel logos

(#931) Trim Stack Trace

(#935) Add Chisel logo to README

(#936) Fix enum annotations
Turns enum annotations back on and adds a new EnumVecAnnotation that annotates vecs of enums, rather than annotating every element of a vec individually. This resolves the bug where enums that were dynamically indexed from a vec would be annotated, causing a FIRRTL error.

For the special cases where we have multidimensional vecs or vecs of bundles which have internal enum fields, the EnumVecAnnotation has a parameter called fields: Seq[Seq[String]] which describes the paths from the outermost vec to the innermost enum fields. For example, for the vec of bundles below:

class Bund extends Bundle {
    val enum_field = MyEnum()
    val inner_bundle = new Bundle {
        val inner_enum_field = MyEnum()
    }
}

val vec = Wire(3, new Bund())

The fields parameter would be Seq(Seq("enum_field"), Seq("inner_bundle", "inner_enum_field"))

(#941) Bump sbt to 1.2.6; update dependencies
Bump sbt version to 1.2.6
Update dependency versions

(#943) RFC: Add Rocket Chip-style clonemodule as CloneAndGetIO to experimental
Add Rocket Chip-style clonemodule as CloneModuleAsRecord to experimental

(#945) Make Vec cloneType keep directions of elements
Fix bug where Chisel might lose the direction of elements of Vecs

(#946) Ignore empty aggregates elements when binding aggregate direction
Empty aggregates no longer cause MixedDirectionAggregateException when included as members of Bundles

h/t @davidbiancolin for identifying and reducing the problem

(#947) Use Verilator 4.006; bump to Scala 2.12.7
Now that ucbbar/chisel3-tools has Verilator 4.006, use that for tests.

(#948) Update description given that Chisel3 has been released

(#952) Fix width inferencing issue
Restore use of width inference to set width of RegInit and WireInit when initialized with a non-literal Bits

(#956) Bump SBT from 1.2.6 to 1.2.7 to fix partial recompilation issue

(#961) Improve quality of code generation for UInt.-%
Improved code generation for modular UInt subtraction.

(#964) Add Windows setup instructions to readme

(#967) Fix build error due to scala bug #11125

(#975) Add explicit Sonatype resolvers so SNAPSHOTs can be found remotely.
NOTE: A publishLocal should replace the downloaded .ivy2/cache/... version with a pointer to the .ivy2/local/... version. To force re-fetching of the Sonatype repository version, you should delete both .ivy2/{cache,local}/... versions.

(#978) Boring utils dedup fix

• Fix BoringUtils.addSinks bug where sinks would still be
  deduplicated even if the user or BoringUtils.bore requested
  that they not be
• Correct BoringUtils.{addSinks, addSources} parameter name from
  dedup to disableDedup

(#979) Avoid procedural wire assignment in test resource
This is a test-only fix, so no release notes.

(#982) Improve chiselName to name Iterable[Data], Option[Data]
Add test for chiselNaming of Seq[Data]
For chiselName, use nameRecursively rather than matching on HasId
Move nameRecursively into Builder so it can be used elsewhere

(#985) Define Data .toString
toString now defined on Data subtypes, and handles literals properly.

(#986) WireDefault instead of WireInit, keep WireInit around
Rename WireInit to WireDefault as its semantic is not an initialization (like a register on a reset), but a default assignment for a combinational circuit.

WireInit is kept around as an alias to WireDefault.

Closes #959

(#987) Fix scaladoc for UInt.unary_!
Unary_- is truncating
Make combinational-multiplier warning less vague
Improve description of UInt.asSInt
Fix width-inference description of Bits.<<

(#988) Generate better code for UInt.andR

(#991) Purge bin
Purge bin/ directory which doesn't seem to be used by anything anymore.

(#992) Remove ghpages
Removed sbt dependency on GhpagesPlugin.

(#994) Unify internal (chisel3.core) and external (chisel3 / chisel3.experimental) Module class names

(#997) Bump copyright year
Bump the copyright year.

(#998) Import aliases for chisel3.core
Don't import from chisel3.core. It's not part of the public API. You'll have a bad day when we muck with the internals, because you'll need to update your code. Unless that's your thing, or you're doing some kind of bleeding edge stuff and are OK with breakages. In which case, carry on.

(#1000) Fork all sbt tasks
(No release notes as this is a testing-only change and we don't publish tests.)

(#1002) Queue Tests
Tests for Queues.

(#1004) Chisel stage

• Adds ChiselStage, a the Chisel Driver as a firrtl.options.Stage
• The original Chisel Driver is converted to a compatibility layer around ChiselStage

(#1008) move doNotDedup to experimental
doNotDedup has be implemented in firrtl/src/main/scala/firrtl/transforms/Dedup.scala, and tested in chisel3/src/test/scala/chiselTests/AnnotationNoDedup.scala. This commit move it to experimental as an API.
and maybe we need to fit the dontTouch name, rename this API to dontDedup?

(#1011) Add support for asynchronous reset

(#1013) Mainline Chisel multi-clock functionality

(#1014) ScalaDoc for Mux (examples added)

(#1015) Added documentation to Decoupled, Conditionals, Counter
Open to feedback about this ScalaDoc.

(#1016) ScalaDoc for OneHot

(#1017) Add Scaladoc for chisel3.util.TransitName

• Update documentation for util.TransitName

(#1018) Documentation for Reg utilities

(#1019) ScalaDocs improvement for utils Math, MixedVec
Scaladocs for Math (log2*, isPow2) and MixedVec.

(#1021) Util doc lsfr

(#1022) Miscellaneous Scaladoc Cleanup

• Add GitHub source links to Scaladoc
• Fix missing links in Scaladoc

(#1023) Valid/Pipe Improvements: Scaladoc, latency requirement

• Add Scaladoc for chisel3.util.{Pipe, Valid}
• Add requirement that Pipe latency is >= 0

(#1024) Generate better names for Pipe via TransitName

• Generate better names Pipe registers

(#1025) Update README to reference the bootcamp

(#1026) Update templates to include documentation.

(#1028) Docs for ListLookup
Scaladoc for ListLookup / Lookup.

(#1032) Update recommended verilator version to 4.006
Update recommended Verilator version to 4.006 in README

(#1033) Tighten inferred width for PopCount
Reduce width of PopCount output to minimal possible value.

(#1034) Decouple implementation details from LoadMemoryAnnotation.
Don't assume that the hexOrBinary field has a .toString method that returns "h" or "b".

(#1035) Mill support for Chisel3

(#1037) Split #974 into two PRs - scalastyle updates
Add scalastyle comments and reformat some code to address potential scalastyle complaints.

(#1040) Aggregate coverage - aggregate tests but not publishing
Support aggregation for the purposes of generating test coverage reports and Scala style checks.

(#1043) Replace textual release version with Shields SemVer badge.

(#1044) Change == to reference equality (eq) in Data print

(#1045) Remove @chiselName from MixedVec

(#1047) Check field referential equality in autoclonetype

(#1048) Undeprecate isLit
Undeprecate Data.isLit

(#1050) Detect bundle aliasing

(#1051) Allow naming annotation to work outside builder context
style

(#1052) Implement connectFromBits in ChiselEnum
Fix bugs in casting to ChiselEnums

(#1053) Try to eliminate JVM hang due to static initialization deadlock
When running multiple tests in parallel, we occasionally experience JVM hangs which appear to be due to static initialization deadlock when Builder initialization collides with chisel3.package initialization of the DontCare value.

Let the initialization in chisel3.package take responsibility, and assume this will happen before any user code creates (and owns) the DontCare element.

See:

• http://ternarysearch.blogspot.com/2013/07/static-initialization-deadlock.html
• https://bugs.openjdk.java.net/browse/JDK-8037567
• https://stackoverflow.com/questions/28631656/runnable-thread-state-but-in-object-wait

(#1054) Make core.DontCare private to chisel3
chisel3.core.DontCare should have been private to chisel3 to prevent client code from referencing it directly and creating the object. This corrects that short-coming.

(#1056) Support Analog DontCare bulk-connect
Allow Analog <> DontCare, DontCare <> Analog

(#1057) [proposal] Bundle literals implementation
Bundle literals implementation

(#1066) Avoid silently truncating BigInt to Int

(#1068) Style nitpick

(#1076) Change size of memories from Int to BigInt
Support memories larger than 2^(31)-1 (not supported by most simulators)

(#1077) Aspect-Oriented Programming for Chisel

(#1078) Repackagecore rebase
This moves most code from the chisel3.core package directly to chisel3. This requires updating most imports and consolidating references to be more consistent. It provides aliases (deprecated) for types and objects that no longer exist in core, so existing user code should work un-modified.

(#1079) Make asTypeOf work for bundles with zero-width fields.

(#1082) Add back Int forms of Mem do_apply methods

(#1086) Expand upon ScalaDoc in Driver

(#1088) PRNG and LFSR Utils

• Add chisel3.util.random package with Galois and Fibonacci LFSRs
• Add maximal period LFSR generation and maximal period taps
• Deprecate chisel3.util.LFSR16 in favor of chisel3.util.random.LFSR(16)

(#1092) LFSR/PRNG Asynchronous Safety, Use Vec[Bool] to store internal state

• Use Vec[Bool] for internal LFSR/PRNG state

(#1093) Fix LFSR regression
Augment LFSR16 test to test the enable as well

(#1094) Change LFSR16 deprecation from 3.3 -> 3.2

(#1096) Include snapshots by default in mill

(#1099) Minor Scaladoc update

(#1104) Fixes @chiselName issue for modules with nested ChiselEnum
This pull request removes the use of the deprecated enclosingClass function in ChiselEnum's Value macro. Coincidentally, this also fixes #1100, where modules with a nested ChiselEnum would not work when the @chiselName macro was applied to them.

(#1106) First crack at updating the readme
Update the readme to provide simpler and quicker access to primary resources

(#1116) Use Verilator 4.016
Now that ucbbar/chisel3-tools has Verilator 4.016, use that for tests.

(#1123) fix typo in README.md
Fix typo in README.md

(#1129) Fix Num.+ Scaladoc

(#1138) Core deprecation "since" should be "3.2" not "3.3"
Change core deprecation "since" from 3.3 -> 3.2

(#1139) Remove Deprecations since before 3.2

• Remove most deprecated items since before 3.2

(#1141) Fix shift register in README

(#1142) Fixup and enable Dummy CompatibilitySpec test

(#1143) Improve compatibility mode testing
Add SInt deprecated compatibility tests
Add UInt deprecated compatibility tests
Add Bits deprecated compatibility tests
Add VecLike deprecated compatibility tests
Add Wire deprecated compatibility tests
Add Data deprecated compatibility tests
Add debug deprecated compatibility tests
Add Mem/SeqMem deprecated compatibility tests
Add LFSR16 deprecated compatibility tests
Add Queue deprecated compatibility tests
Add Enum deprecated compatibility tests
Add BitPat deprecated compatibility tests

(#1147) Avoid when(reset) construct in LFSR

(#1148) Require target is hardware for Vec.apply(a: UInt)

• Improved error message if doing UInt indexing on a Chisel Vec

(#1149) Update website references to the new website

(#1151) java.lang.NullPointerException instead of scala.UnitializedFieldE?
Use java.lang.NullPointerException other than scala.UnitializedFieldError

(#1152) Refactor: remove redundant code

(#1155) Dependency API (take 2)
Use a PhaseManager for Driver internals
Migrate ChiselStage to use the DependencyAPI
Add Dependencies for Chisel Phases

(#1156) Bump Scala to 2.12.9
Bump Scala in build.sc

(#1158) Bump dependency versions
Bump external library dependency versions.

(#1160) Fix Stack Trace Trimming in Driver

• Bug fixes related to stack trace trimming
• Adds chisel3.stage.ChiselMain

(#1165) Refactor of Bits.scala

• Refactor Element, Num, and Analog classes to their own files.
• Remove unused imports, redundant abstract for Num trait, redundant final for methods of final class.

(#1173) Add Chisel Cheatsheet Latest Release Link

(#1174) Switch to new API links