Chisel Standard Library

[ducky64]

So the standard library we currently have (chisel3.utils) is kind of haphazard, incomplete, and in some cases, inelegant and confusing (I'm looking at you, Counter...)

This issue is just to start the conversation on what we want in a standard library. Ideally, these should be highly-reusable parts, and kind of following in Python's philosophy of "batteries included".

Some may already exist elsewhere (most notably, in rocket-chip's various utilities), the goal here would be to make it easy to use those bits without importing the monster that is rocket. A standard library would also carry the expectation of stability.

Standard library thoughts

I'll start off a list here. It's not complete or exhaustive, just a starting point for discussion. Please add more suggestions in the comments!

Async utils

• Clock crossing FIFOs
• Clock dividers
• PLL templates, generating into FPGA blocks or blackboxes

Communications utils

• Digital CDR blocks
• Encoders / decoders: 8b/10b, 64b/66b, NRZ, ...
• Standardized interfaces: JTAG, boundary scan, ...
• Standardized communication protocols: USB (2.0 | 3.0), SD card, Ethernet, PCIe, ...
• Standardized inter-chip protocols: I2C, SPI, UART, ...
• On-chip busses: TileLink, AXI, ...
• CRC generator

Processing

• All the DSP stuff, with a standardized interface

Physical interfaces

• FPGA blocks, including output drivers, input buffers, tristate drivers, and associated bundles (like a Tristate bundle)
• DDR/DDR2/etc interfaces

Other

• Most of the stuff we have in the current chisel3.utils package, but probably cleaning up the interface a bit. API breakages can be avoided by deprecating what we have right now in favor of a different package, like chisel3.stdlib (or something)
• Efficient SRAM versions of things like registers and queues

Issue Data

Type of issue: feature request

Impact: API addition (no impact on existing code)

Development Phase: request

Other information

[seldridge]

I've got a small number of things that I can see about re-licensing (highlighted below).

Some ideas:

• PRNGs
  • A better LFSR
• Checksums (you've got CRC, but others may be useful)
  • Fletcher
  • MD5?
  • SHA
• Other Encryption (SHA, AES)

[chick]

I don't know if this fits in the same utilities but there should be a standard library of testing tools, there's a vast number of different techniques for implementing unit tests throughout the chisel suite.
Tools for generating input vectors, conversions that make it easier to generate test numbers that reflect the quantization that occurs in the dut.

It's a bit pedestrian but I also think simple and clearly named (aka longly named) bit and width related functions would reduce errors (what exactly does log2Ceil do) instead things like howManyBitsDoesAUIntHaveToBeToContainThenNumber(x: BigInt) and
val (lo, hi) = extremaOfAnSIntOfWidth(width: Int). Names like that could be bit shorter but I continue to see errors in code that simple functions like this would reduce.

[ucbjrl]

We've encountered several scenarios where relatively veteran Chisel users introduce bugs using bare log2Ceil() to calculate widths. The solution isn't to re-define log2Ceil() to match incorrect usage, but rather to introduce utility functions that help express designer intent.

#819 is an attempt to help deal with this.

[hcook]

I added some specific suggestions on the rocket-chip issue. I think there are some clear candidates, mostly utility functions for converting between simple types and doing bitwise manipulations, or better muxing.

The hard part about more complicated protocols is that pretty much all of them are parameterized. In my experience, the hard part of implementing them in a generator is deciding how that parameterization is going to occur. Who decides on the parameter bindings, and when and how? Chisel doesn't help matters by attempting to force elaboration to occur in a single pass of hierarchically invoked constructors. For us, allowing protocol parameters to be pre-calculated involved escaping Chisel back into pure Scala-land. But once you've done that, what's the argument for such an implementation to be included in Chisel itself?

I continue to advocate for Chisel to be the thinest possible layer between Scala and FIRRTL.

[sequencer]

sifive-blocks has implemented a lot of standard utils, is possible to merge it in to chisel?
And I do think there is many utils containing in rocket-chip and riscv-boom, which could be include into chisel as a standard library.

[edcote]

I posted this quick reply a while back. I would love to see Diplomacy (aka. LazyModule, LazyModuleImp) added to some-version-of a shared library. @hcook mentions a thin layer. That's fine. But it'd be great to somehow decouple Diplomacy for use as a generic way to configure a non-Rocket design.