Previous incomplete fixes in #2023 and #2031.

The legality of a FIRRTL connection is determined by type and flow.
Chisel does not have access to true flow information. Previous fix
attempts tried to use ActualDirection as a stand-in for flow, but it is
incorrect in many cases. This new approach checks the flows of the
lvalue and rvalues in the connect and flips the connection if either
the lvalue cannot be a sink or the rvalue cannot be a source.

* Remove chisel3's own firrtl Emitter, use firrtl Serializer

This will be slightly slower as it involves converting from Chisel
modules to FIRRTL modules before turning them into Strings. This cost is
somewhat mitigated by doing that conversion lazily such that we never
materialize the entire firrtl Circuit in memory, only 1 module at a
time.

(cherry picked from commit 73bd4ee6)

# Conflicts:
#	src/main/scala/chisel3/internal/firrtl/Emitter.scala
#	src/test/scala/chiselTests/PrintableSpec.scala
#	src/test/scala/chiselTests/VecLiteralSpec.scala
#	src/test/scala/chiselTests/experimental/verification/VerificationSpec.scala

* Emit .fir lazily, overcomes JVM 2 GiB String limit

(cherry picked from commit d9c30ea0)

# Conflicts:
#	src/main/scala/chisel3/internal/firrtl/Emitter.scala

* Use BufferedCustomFileEmission in CircuitSerializationAnnotation

(cherry picked from commit a6eb2ad8

)

* Resolve backport conflicts

* Waive binary compatibility issues

Co-authored-by: Jack Koenig <koenig@sifive.com>

* [docs] Add example of stripping directions from type

* Apply suggestions from code review

Co-authored-by: Megan Wachs <megan@sifive.com>

* Improve := comment

Co-authored-by: Megan Wachs <megan@sifive.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
(cherry picked from commit e14bcb14

)

Co-authored-by: Jack Koenig <koenig@sifive.com>

* Small changes to memory doc
- Fixed typo "except" => "accept"
- Use `Counter` explicitly in ROM section example.

* Fix counter doc compile error

* remove invisible doc block in memory example

* more small fixes to make mem example pass doc compile

* Get rid of sine wave iterator in memory doc

* get rid of tabs on VecInit example

* get rid of tabs on VecInit example

(cherry picked from commit 75c00606

)

Co-authored-by: Chick Markley <chick@qrhino.com>

The example in the README is a sum, not an average.

(cherry picked from commit 3f007bec

)

Co-authored-by: Jack Koenig <koenig@sifive.com>

Co-authored-by: Jack Koenig <koenig@sifive.com>
(cherry picked from commit e6c902ea

)

Co-authored-by: Leway Colin <colin4124@gmail.com>

* Add `isOneOf` method to `ChiselEnum` (#1966)

* Add @ekiwi's code as a starting point

* Add test for ChiselEnum isOneOf method

* Make isOneOfTester naming consistent with other testers

* Add scaladoc comments for isOneOf

* Add isOneOf tests that use the method that takes variable number of args

* Add guide level documentation example for isOneOf

(cherry picked from commit bb520b85

)

* Turn on autoclonetype2 for mdocs

Co-authored-by: Verneri Hirvonen <11316555+chiplet@users.noreply.github.com>
Co-authored-by: Jack Koenig <koenig@sifive.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

* Fix chisel3 <> for Bundles that contain compatibility Bundles (Take 2) (#2031)

PR #2023 fixed a composition issue for chisel3 biconnects delegating to
FIRRTL partial connect when compatibility mode Bundles are elements of
chisel3 Bundles. It missed an important case though that caused
previously working code to break.

The bug is fixed by doing the automatic flipping for compatibility mode
Bundles that have "Input" as a direction in addition to those that are
"Flipped".

(cherry picked from commit 5183ef88

)

# Conflicts:
#	src/test/scala/chiselTests/CompatibilityInteroperabilitySpec.scala

* Resolve backport conflicts

Co-authored-by: Jack Koenig <koenig@sifive.com>

* Make it legal for concrete resets to drive abstract reset (#2018)

This has been legal in FIRRTL since v1.2.3 (when reset inference started
using a unification-style algorithm) but was never exposed in the Chisel
API.

Also delete the overridden connects in AsyncReset and ResetType which
just duplicate logic from MonoConnect.

(cherry picked from commit 4b7b771e

)

* Fix issues with tests

Co-authored-by: Jack Koenig <koenig@sifive.com>

* Fix chisel3 <> for Bundles that contain compatibility Bundles (#2023)

BiConnect in chisel3 delegates to FIRRTL <- semantics whenever it hits a
Bundle defined in `import Chisel._`. Because chisel3 <> is commutative
it needs to be mindful of flippedness when emitting a FIRRTL <- (which
is *not* commutative).

(cherry picked from commit 16c0b53e

)

* Fix test issue in Scala 2.11

Co-authored-by: Jack Koenig <koenig@sifive.com>

Change the Scaladoc for the dontTouch utility.  Indicate that this is an
_optimization barrier_ and not just a guarantee that the signal won't be
removed.  The optimization barrier interpretation is the current
implementation in the Scala FIRRTL Compiler.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@sifive.com>

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
(cherry picked from commit f1e37900

)

Co-authored-by: Schuyler Eldridge <schuyler.eldridge@sifive.com>

Also add newline to end of `verilog` modifier code blocks so that there
is always a newline between code blocks and following material.

(cherry picked from commit 558df41d

)

Co-authored-by: Jack Koenig <koenig@sifive.com>

* Change Chisel warnings to use logger instead of println

It also uses the same logger as the Builder so that if we ever refactor
that to be passed as an argument, it will be the same logger for both
Builder and warning reporting.

(cherry picked from commit 04caf395)

* Add ChiselEnum.safe factory method and avoid warning

Previously, ChiselEnum would warn any time a UInt is converted to an
Enum. There was no way to suppress this warning. Now there is a factory
method (`.safe`) that does not warn and returns (Enum, Bool) where the
Bool is the result of calling .isValid on an Enum object. The regular
UInt cast is also now smarter and will not warn if all bitvectors of the
width of the Enum are legal states.

(cherry picked from commit 5fe539c7)

# Conflicts:
#	src/test/scala/chiselTests/ChiselSpec.scala

* Update docs for ChiselEnum

(cherry picked from commit bfb77d4c

)

* Resolve merge conflicts and waive false bincompat issue

Co-authored-by: Jack Koenig <koenig@sifive.com>

* Restore aop.Select behavior for CloneModuleAsRecord

(cherry picked from commit 0531cb53)

* Change behavior of aop.Select to not include CloneModuleAsRecord

Previously, CloneModuleAsRecord clones would result in the same
BaseModule object coming up multiple times when using APIs like
.instances, .collectDeep, and .getDeep. This was not the intended
behavior and can lead to very subtle bugs.

(cherry picked from commit 25a84b56

)

Co-authored-by: Jack Koenig <koenig@sifive.com>

* Fix CloneModuleAsRecord support for .toTarget

(cherry picked from commit d3e13ce2)

# Conflicts:
#	core/src/main/scala/chisel3/RawModule.scala

* Set refs for ModuleClone and ClonePorts in less hacky way

(cherry picked from commit b87107ad

)

* Fixup for backport

* Resolve merge conflicts
* Fix semantic meaning change of Module -> MultiIOModule on master
* Waive bincompat errors that cannot impact Scala users

Co-authored-by: Jack Koenig <koenig@sifive.com>

(cherry picked from commit 44c7fca8

)

Co-authored-by: Jack Koenig <koenig@sifive.com>

(cherry picked from commit 6a806918

)

Co-authored-by: Jiuyang Liu <liu@jiuyang.me>

(cherry picked from commit a5cfd8bf

)

Co-authored-by: Jack Koenig <koenig@sifive.com>

* Add Clock
* Add Analog
* Add Interval
* Add line from User Types (...) to Record

(cherry picked from commit 5e8ef455

)

Co-authored-by: Jack Koenig <koenig@sifive.com>

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
(cherry picked from commit 04de237e

)

Co-authored-by: Jiuyang Liu <liu@jiuyang.me>

* explain sub-projects

* Update README.md

Co-authored-by: Megan Wachs <megan@sifive.com>

Co-authored-by: Megan Wachs <megan@sifive.com>
(cherry picked from commit ea84a176

)

Co-authored-by: Deborah Soung <debs@sifive.com>

(cherry picked from commit ac31c62e

)

Co-authored-by: Jiuyang Liu <liu@jiuyang.me>

* Add test to check ShiftRegister(s) with delay is 0.

This should break ShiftRegister(x, 0) since last is not exist in a empty
Seq. Originally, test only test 1 to 4, which missed a potential bug
from #1723.

* Fix ShiftRegister with 0 delay.

if ShiftRegisters is empty, java will complain:
```
  java.util.NoSuchElementException
    scala.collection.LinearSeqOptimized.last(LinearSeqOptimized.scala:150)
```
This fix this issue and return `in` directly when ShiftRegister size is 0.

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Co-authored-by: Jiuyang Liu <liu@jiuyang.me>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

* Stop Emitting BlackBoxResourceAnno (#1954)

* Change HasBlackBoxResource to Resolve Resources

Change HasBlackBoxResource to resolve resources immediately and emit
BlackBoxInlineAnno instead of a BlackBoxResourceAnno.  This removes the
need for a FIRRTL compiler to grok the Java Resource API in order to
handle BlackBoxResourceAnno.

Emit BlackBoxInlineAnno from HasExtModuleResource instead of
BlackBoxResourceAnno.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@sifive.com>
(cherry picked from commit 820200b7

)

# Conflicts:
#	src/main/scala/chisel3/util/BlackBoxUtils.scala

* fixup! Stop Emitting BlackBoxResourceAnno (#1954)

Co-authored-by: Schuyler Eldridge <schuyler.eldridge@sifive.com>

(cherry picked from commit 1875d3da

)

Co-authored-by: Martin Schoeberl <martin@jopdesign.com>

* Implement PLA (#1912)

* implement pla

* implement test for pla

* implement inverter matrix of PLA generator

* fix for review.

Co-authored-by: Boyang Han <yqszxx@gmail.com>
(cherry picked from commit 1c1a4d72

)

* fix 2.11

Co-authored-by: Jiuyang Liu <liu@jiuyang.me>

* add ShiftRegisters to expose register inside ShiftRegister.

* use Seq.iter for oneline implementation.

(cherry picked from commit 361e4433

)

Co-authored-by: Jiuyang Liu <liu@jiuyang.me>

* Fix RegInit of Bundle lits (#1688)

Implemented by folding Element.ref into Data.ref. Element.ref had
special handling for literals, but because Bundles can also be literals,
there were code paths that tried to get the ref of a Bundle literal
which was non-existent. Now, all literals are handled together.

Because FIRRTL does not have support for Bundle literals, Bundle literal
refs are implemented by materializing a Wire.

(cherry picked from commit 5a6ce660

)

* Waive bincompat issue on package private method

Co-authored-by: Jack Koenig <koenig@sifive.com>

* add convert(chirrtl: cir.Circuit): fir.Circuit to convert chirrtl to firrtl.

* add scaladoc.

* add test.

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
(cherry picked from commit 7dd2d7db

)

Co-authored-by: Jiuyang Liu <liu@jiuyang.me>

(cherry picked from commit 4d8fed00

)

Co-authored-by: Kevin Laeufer <laeufer@cs.berkeley.edu>

* Cookbook: clean up desiredName example

* Update cookbook.md

(cherry picked from commit 9fdea534

)

Co-authored-by: Megan Wachs <megan@sifive.com>

* Add some error context to Converter .getRefs (#1878)

(cherry picked from commit c7142802

)

* Waive package private binary incompatibilities

Co-authored-by: Jack Koenig <koenig@sifive.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
(cherry picked from commit 23b3fe8a

)

Co-authored-by: Megan Wachs <megan@sifive.com>

(cherry picked from commit 804271ea

)

Co-authored-by: Jack Koenig <koenig@sifive.com>

* fixing context bug (#1874)

(cherry picked from commit 2c7264a6

)

# Conflicts:
#	src/main/scala/chisel3/aop/injecting/InjectingAspect.scala
#	src/test/scala/chiselTests/aop/InjectionSpec.scala

* Resolve conflicts

Co-authored-by: Deborah Soung <debs@sifive.com>

(cherry picked from commit da5e5cb5

)

Co-authored-by: Martin Schoeberl <martin@jopdesign.com>

nitpick

(cherry picked from commit 83eeda2e

)

Co-authored-by: Fabien Marteau <fabien.marteau@armadeus.com>

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
(cherry picked from commit 0cc35a26

)

Co-authored-by: Jiuyang Liu <liu@jiuyang.me>

* Remove space between backticks and language
* Make code examples in memories explanation work

Co-authored-by: Jack Koenig <koenig@sifive.com>
(cherry picked from commit f39ec2ef

)

Co-authored-by: Carlos Eduardo <me@carlosedp.com>

(cherry picked from commit 6e22d91e

)

Co-authored-by: Megan Wachs <megan@sifive.com>