Add LFSR generator to standard library

[adamgreig]

This is my first draft of an LFSR generator for the standard library, following in the general design of the existing CRC generator. There are a few unresolved details and some remaining questions on exactly how the implementation will work, but I am working on a first pass at that too.

Rendered

[adamgreig]

We discussed this RFC in today's meeting.

On alternatives:

We could simplify the implementation and API by only supporting Galois or only Fibonacci implementations, with the downside of potentially less efficient implementations on some platforms. I haven't researched how serious an impact this would be.

Keep both for now. We could deprecate one later if needed without changing the interface.

We could not support multi-bit generation, but this is a useful feature for many applications.

Keep it as it's vital functionality for planned use cases.

The split between Algorithm and Parameters mirrors that in lib.crc, but with fewer parameters we could consider merging them or making the Parameters settings be part of the Processor creation.

Keep them, the utility seems worth the minimal complexity.

On the unresolved questions:

Not sure if we should add explicit ready/valid signals or a reset signal, or leave those to EnableInserter/ResetInserter.

Swap to using streams for ready/valid, and keep ResetInserter for resetting.

Should we support internally-inverted LFSRs using XNOR operations, permitting a valid all-0s internal state to make initialisation easier e.g. on ASICs?

Requiring all-0s initial values can be left to synthesis tools. No need to include here.

Future work

Add some way to load a specific new state. The proposed option after discussion is a state_init input (which defaults to 1), and whenever the internal state is 0, state_init is used instead. This way the default behaviour is sensible, a ResetInserter can be used to either reset to the normal starting state or to reload a specific new state, and the initial state can be either a fixed constant or changed at runtime. This may increase resource usage compared to a hardcoded initial state or a runtime-reloadable state without the all-0s check, however.

Other points

• Clarify that the "infinite iterator" returned by Parameters.compute() is a generator
• Some applications may want to use the state as the multi-bit output, but it's awkward to have this alongside the normal output in the stream. Instead, add an option to Parameters to allow the stream payload to be either the normal output or the internal state.
  • As an alternative, state could remain an output and be used alongside the stream, but this might also be confusing when the multi-bit generation is used.
• Use an enum to select between Galois and Fibb rather than raw strings

[whitequark]

@adamgreig Do you think you could update the RFC with the conclusions from the meeting?

[whitequark]

🎉

[adamgreig]

I've updated with the feedback from the review meeting, with one variation:

Some applications may want to use the state as the multi-bit output, but it's awkward to have this alongside the normal output in the stream. Instead, add an option to Parameters to allow the stream payload to be either the normal output or the internal state.

I considered this but it also means the output_width parameter ends up changing the nominal output width and thus the progression of output states, but doesn't affect the actual width of the output stream, which instead becomes "either parameters.output_width when parameters.output_type is normal or otherwise algorithm.width if parameters.output_type is state". I think it makes more sense to use the existing state output and the stream's ready input to advance it if you want to use the internal state.