stdlib API

[sequencer]

In this issue, I'll summarize key stdlib APIs for zaozi, mostly align to chisel, but should be re-implemented in Module and provides corresponding static verification APIs.

Here are some principles:

• Use DesignWare Build Block as much as possible to reduce the verification effort.

• Each stdlib should be implemented in Module, but can be used with simpler APIs.

• Arbiter

• Queue

• BinaryToGray

• FillInterleaved

• GraphToBinary

• Mux1H

• OHToUInt

• Pipe

• Popcount

• PriorityEncoder

• PriorityEncoderOH

• PriorityMux

• Pipe

• ShiftRegisters

• UIntToOH

• scanLeftOr

• scanRightOr

• decoder

• ClockGate

• AsyncQueue

• CRC

• ECC

• SRAM

• ROM

• leftOR

• rightOR

• CSA

• ffo

And many other DeisgnWare BuildBlock API should also be included in the stdlib, but provide the type for some of them in advance.

[unlsycn]

I consent to implement stdlib as modules as it leads to a clearer module hierarchy and allows each module to own its DV interface. But there are some differing views regarding the overarching API design :

1. It's true that we can expose only typed API to users and hide all implementation details inside them. However, it is often more practical to provide a concrete interface rather than just a set of methods. (e.g. a QueueIO is usually more convenient than basic enqueue and dequeue APIs). Hence, we should consider treating at least the hardware interface as a part of stdlib APIs. The verification interfaces can be reserved for implementation to define, and user who need dv interfaces should rely on a specific impl.
2. In Zaozi, dv ports are required to bind to a specific layer, and we consider layers as a module-level interface. What, then, are the layers of modules in stdlib? We may need a mechanism to alias layers during module instantiation (like a part of parameter?). This point needs further discussion.
3. According to 1), there is no point to tightly couple stdlib with DeisgnWare BuildBlock since we do not depend on concrete implementations of dwbb but only its interfaces and behavior. Doing so may hamper non-commercial use and upstreaming process. That said, we can still align the interfaces to dwbb as much as possible so that it will be quite easy to make wrappers in the design which uses dwbb actually or in a separate repo.

[unlsycn]

I consent to implement stdlib as modules as it leads to a clearer module hierarchy and allows each module to own its DV interface. But there are some differing views regarding the overarching API design :

1. It's true that we can expose only typed API to users and hide all implementation details inside them. However, it is often more practical to provide a concrete interface rather than just a set of methods. (e.g. a `QueueIO` is usually more convenient than basic `enqueue` and `dequeue` APIs). Hence, we should consider treating at least the hardware interface as a part of stdlib APIs. The verification interfaces can be reserved for implementation to define, and user who need dv interfaces should rely on a specific impl.

2. In Zaozi, dv ports are required to bind to a specific layer, and we consider layers as a module-level interface. What, then, are the layers of modules in stdlib? We may need a mechanism to alias layers during module instantiation (like a part of parameter?). This point needs further discussion.

3. According to 1), there is no point to tightly couple stdlib with DeisgnWare BuildBlock since we do not depend on concrete implementations of dwbb but only its interfaces and behavior. Doing so may hamper non-commercial use and upstreaming process. That said, we can still align the interfaces to dwbb as much as possible so that it will be quite easy to make wrappers in the design which uses dwbb actually or in a separate repo.

Additions to 1), an alternative is to provide a typed Bundle (such as QueueIO in Chisel) as part of the API, without restricting the actual hardware interface of the impl. Each impl would then provide a connection from its own interface to that of the API Bundle, which would be inlined during module instantiation.