Switch from veneers to private macro interfaces

[jackkoenig]

This is an update to the "Scala 2/3 veneer pattern" for how to deal with public methods that use macros, first described in https://github.com/chipsalliance/chisel/pull/4682/files#r1979854957.

The old pattern was as follows:

• In src/main/scala create FooImpl.scala which contains private[chisel3] trait FooImpl and/or private[chisel3] trait ObjectFooImpl (for objects).
  • FooImpl should contain all functional code and package private or protected methods to be called by the public APIs.
  • Any public APIs that don't need macros are also defined here.
• In src/main/scala-2 and src/main/scala-3, create Foo.scala which contains class Foo extends FooImpl and/or object Foo extends ObjectFooImpl.
  • Foo contains all public APIs that need macros and should contain no implementation code--it should call the private methods defined in FooImpl

The new approach is as follows:

• In src/main/scala/Foo.scala define class Foo extends FooIntf and/or object Foo extends Foo$Intf.
  • These are the actual public classes/objects.
  • This is where all implementation code must live, including implementing private or protected methods that will be called by the Intf
• In src/main/scala-2 and src/main/scala-3 define FooIntf.scala which contains private[chisel3] trait FooIntf and/or private[chisel3] trait Foo$Intf.
  • These traits should define any public methods that use macros (or in Scala 3, polyfill macro methods). The implementation of these public methods should be simply to call an _impl version of the same method (defined in the public API in src/main/scala).
  • These traits should be self-typed on the public API that extends them (e.g. { self: Foo => or { self: Foo.type => for objects). (this is a circular dependency but it enables calling implementation methods defined in the public API)

(Note: originally "new approach" included FooVirtualMethods, but this is not actually necessary due to the self typing on the Intf traits)

The new approach has some advantages over the old approach:

• The "main" file name for an API is now also where the bulk of the code lives. It was annoying going to Module.scala and that just being the public methods
• The filename and class/object/trait name where the implementation lives shows up in stack traces, so it's much better to see Module and Module.scala than ObjectModuleImpl and ModuleImpl.scala in a stack trace.
• The new naming scheme for objects (using trailing $ rather an preceding Object) is more clear IMO as it matches the desugared type name for objects.
• The self-typing enforces that Intf traits are only mixed in the right place and somewhat self-documents what the Intf traits are for.
• It avoids duplication of ScalaDoc on public classes/objects.

Draft for now since this needs to be applied to a lot more files.

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

• Internal or build-related (includes code refactoring/cleanup)

Desired Merge Strategy

• Rebase: You will rebase the PR onto master and it will be merged with a merge commit.

Release Notes

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.

[seldridge]

I glanced though all the files. I'm good with the pattern.

I'm really hoping that we can get this Scala3 migration done quickly so that all this can be cleaned up. 🙏