Add ElaboratedCircuit and deprecate use of internal ir Circuit (backport #4683)

[chiselbot]

When I tried out #4643 internally at SiFive, I realized that despite chisel3.internal.firrtl.ir being a package private object, ir.Circuit still leaks out via ChiselCircuitAnnotation and it can be used freely. This leaks full access to the Chisel internal IR in a way that makes it really hard to change things.

This is my attempt to "spackle" that leak by providing the new ElaboratedCircuit API as the intended public interface to give to users to let them do what they want to do, while letting us muck with the internals. I think we should feel free to add and deprecate then remove APIs from ElaboratedCircuit as long as we take care to keep the actual internals private.

Before merging this, I intend to test it internally and redo #4643 on top of it because I still want to backport the annotation deprecations as well. Technically #4643 does not need this, but I think this makes the story of what changes I want to make in 7.0 a lot cleaner without having to worry about changes to ir.Circuit accidentally breaking user code.

Contributor Checklist

• Did you add Scaladoc to every public function/method?
• Did you add at least one test demonstrating the PR?
• Did you delete any extraneous printlns/debugging code?
• Did you specify the type of improvement?
• Did you add appropriate documentation in docs/src?
• Did you request a desired merge strategy?
• Did you add text to be included in the Release Notes for this change?

Type of Improvement

• API deprecation

Desired Merge Strategy

• Squash

Release Notes

Change ChiselCircuitAnnotation and CircuitSerializationAnnotation to no longer be case classes to help with the transition to ElaboratedCircuit.

Reviewer Checklist (only modified by reviewer)

• Did you add the appropriate labels? (Select the most appropriate one based on the "Type of Improvement")
• Did you mark the proper milestone (Bug fix: 3.6.x, 5.x, or 6.x depending on impact, API modification or big change: 7.0)?
• Did you review?
• Did you check whether all relevant Contributor checkboxes have been checked?
• Did you do one of the following when ready to merge:
  • Squash: You/ the contributor Enable auto-merge (squash) and clean up the commit message.
  • Merge: Ensure that contributor has cleaned up their commit history, then merge with Create a merge commit.

---

This is an automatic backport of pull request #4683 done by [Mergify](https://mergify.com).

[mergify]

Cherry-pick of 4d75573 has failed:

On branch mergify/bp/6.x/pr-4683
Your branch is up to date with 'origin/6.x'.

You are currently cherry-picking commit 4d755737.
  (fix conflicts and run "git cherry-pick --continue")
  (use "git cherry-pick --skip" to skip this patch)
  (use "git cherry-pick --abort" to cancel the cherry-pick operation)

Changes to be committed:
	new file:   core/src/main/scala/chisel3/ElaboratedCircuit.scala
	modified:   docs/src/cookbooks/hierarchy.md
	modified:   docs/src/explanations/chisel-type-vs-scala-type.md
	modified:   src/main/scala/chisel3/stage/ChiselAnnotations.scala
	modified:   src/main/scala/chisel3/stage/package.scala
	modified:   src/main/scala/chisel3/stage/phases/AddDedupGroupAnnotations.scala
	modified:   src/main/scala/chisel3/stage/phases/AddSerializationAnnotations.scala
	modified:   src/main/scala/chisel3/stage/phases/Emitter.scala
	modified:   src/main/scala/chisel3/testers/TesterDriver.scala
	modified:   src/main/scala/circt/stage/ChiselStage.scala
	modified:   src/test/scala/chisel3/stage/ChiselOptionsViewSpec.scala
	modified:   src/test/scala/chiselTests/experimental/hierarchy/SeparateElaborationSpec.scala
	modified:   src/test/scala/chiselTests/stage/phases/AddSerializationAnnotationsSpec.scala
	modified:   src/test/scala/chiselTests/stage/phases/ElaborateSpec.scala

Unmerged paths:
  (use "git add <file>..." to mark resolution)
	both modified:   core/src/main/scala/chisel3/experimental/hierarchy/core/Definition.scala
	both modified:   core/src/main/scala/chisel3/internal/Builder.scala
	both modified:   src/main/scala/chisel3/stage/ChiselOptions.scala
	both modified:   src/main/scala/chisel3/stage/phases/AddImplicitOutputAnnotationFile.scala
	both modified:   src/main/scala/chisel3/stage/phases/AddImplicitOutputFile.scala
	both modified:   src/main/scala/chisel3/stage/phases/Convert.scala
	both modified:   src/main/scala/chisel3/stage/phases/Elaborate.scala
	both modified:   src/test/scala/circtTests/stage/ChiselStageSpec.scala

To fix up this pull request, you can check it out locally. See documentation: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally