Update CRC RFC with latest design

Author: adamgreig

text/0006-stdlib-crc.md

@@ -24,76 +24,161 @@ See the [Wikipedia page on CRCs] for more background and use cases.
 # Guide-level explanation
 [guide-level-explanation]: #guide-level-explanation
 
-The standard library includes a generator for a cyclic redundancy check (CRC)
-module, which can be used to compute and/or validate most common CRCs used by
-transmission and storage protocols.
-
-There are many variations on CRCs in use, but they can almost all be described
-by the following parameters:
-
-* The bit width of the checksum, commonly (but not always) a power of 2
-* The generator polynomial
-* The initial value of the CRC register
-* Whether to process input words least- or most-significant-bit first
+The Amaranth standard library includes a generator for a cyclic redundancy
+check (CRC) module, which can be used to compute and/or validate most common
+CRCs used by transmission and storage protocols.
+
+There are many different CRC algorithms in use, but they can almost all be
+described by the following parameters:
+
+* The bit width of the CRC, commonly (but not always) a power of 2,
+* The generator polynomial, represented as an integer where each bit is a 0 or
+  1 term in a binary-valued polynomial with as many terms as the CRC width,
+* The initial value of the CRC register, commonly non-zero to allow detection
+  of additional 0-valued data words at the start of a message,
+* Whether to process input words least- or most-significant-bit first,
+  allowing the CRC processing order to match the transmission or storage order
+  of the data bits,
 * Whether to flip the final output so that its least-significant-bit becomes
-    the most-significant bit
-* What value, if any, to XOR the output bits with before using the CRC value
+  the most-significant bit, set for the same reason as reflecting the input
+  when the CRC value will also be transmitted or stored with a certain bit
+  order,
+* What value, if any, to XOR the output bits with before using the CRC value,
+  often used to invert all bits of the output.
 
 This set of parameters is commonly known as the Williams or Rocksoft model. For
 more information, refer to ["A Painless Guide to CRC Error Detection Algorithms"].
 
 ["A Painless Guide to CRC Error Detection Algorithms"]: http://www.ross.net/crc/download/crc_v3.txt
 
-The generator in the Amaranth standard library computes CRCs from an input
-data stream of configurable width, and can therefore be use for both validating
-existing CRCs and creating new ones. It can handle any CRC parameterised by
-the Williams model above.
-
 For a list of parameters to use for standard CRCs, refer to:
 
 * [reveng]'s catalogue, which uses the same parameterisation
-* [crcmod]'s predefined list, but removing the leading `1` from the
-    polynomials, and where `Reversed` is `True`, set both `ref_in` **and**
+* [crcmod]'s predefined list, but remove the leading `1` from the
+    polynomials, XOR the "Init-value" with "XOR-out" to obtain `initial_crc`,
+    and where `Reversed` is `True`, set both `ref_in` **and**
     `ref_out` to `True`.
 * [CRC Zoo], which only lists polynomials; use the "explicit +1" form but
   remove the leading `1`.
 
+The CRC algorithms described in the [reveng] catalogue are also available
+in the Amaranth standard library in the `crc.Catalog` class.
+
 [reveng]: https://reveng.sourceforge.io/crc-catalogue/all.htm
 [crcmod]: http://crcmod.sourceforge.net/crcmod.predefined.html
 [CRC Zoo]: https://users.ece.cmu.edu/~koopman/crc/
 
-The computed CRC value is updated on any clock cycle where the `valid` input
-is asserted, with the updated value available on the `crc` output on the
-subsequent clock cycle. The latency is one cycle, and the throughput is
-one data word per clock cycle.
+In Amaranth, the `crc.Parameters` class holds the parameters that describe a
+CRC algorithm:
+
+* `crc_width`: the bit width of the CRC
+* `data_width`: the width of the input data words the CRC is computed over;
+  commonly 8 for processing byte-wise data but can be any length greater than 0
+* `polynomial`: the generator polynomial of the CRC, excluding an implicit
+  leading 1 for the "x^n" term
+* `initial_crc`: the initial value of the CRC, loaded when computation of a
+  new CRC begins
+* `reflect_input`: if True, input words are bit-reversed so that the least
+  significant bit is processed first
+* `reflect_output`: if True, the final output is bit-reversed so that its
+    least-significant bit becomes the most-significant bit of output
+* `xor_output`: a value to XOR the output with
+
+The `crc.Parameters` class may be constructed manually, or via a
+`crc.Predefined` entry in `crc.Catalog`, which contains many commonly
+used CRC algorithms. The data width is not part of the `crc.Predefined`
+class, so it must be specified to create a `crc.Parameters`, for example:
+
+```python
+from amaranth.lib import crc
+params1 = crc.Parameters(8, 8, 0x2f, 0xff, False, False, 0xff)
+params2 = crc.Catalog.CRC8_AUTOSAR(data_width=8)
+```
+
+If not specified, the data width defaults to 8 bits.
+
+The `crc.Parameters` class can be used to compute CRCs in software using its
+`compute()` method, which is passed an iterable of integer data words and
+returns the resulting CRC value.
+
+```python
+from amaranth.lib import crc
+params = crc.Parameters(8, 8, 0x2f, 0xff, False, False, 0xff)
+assert params.compute(b"123456789") == 0xdf
+```
+
+To generate a hardware CRC module, either call `create()` on `crc.Parameters`
+or manually construct a `crc.Processor`:
+
+```python
+from amaranth.lib import crc
+params = crc.Parameters(8, 8, 0x2f, 0xff, False, False, 0xff)
+crc1 = m.submodules.crc1 = crc.Processor(params)
+crc2 = m.submodules.crc2 = crc.Catalog.CRC8_AUTOSAR().create()
+```
+
+The `crc.Processor` module begins computation of a new CRC whenever its `first`
+input is asserted. Input on `data` is processed whenever `valid` is asserted,
+which may occur in the same clock cycle as `first`. The updated CRC value is
+available on the `crc` output on the clock cycle after `valid`.
 
 With the data width set to 1, a traditional bit-serial CRC is implemented
 for the given polynomial in a Galois-type shift register. For larger values
 of data width, a similar architecture computes every new bit of the CRC in
 parallel.
 
-The `match` output signal may be used to validate data that contains a trailing
-CRC. If the most recently processed word(s) form a valid CRC for all the data
-processed since reset, the CRC register will always contain a fixed value which
-can be computed in advance, and the `match` output indicates whether the CRC
-register currently contains this value.
+The `match_detected` output signal may be used to validate data that contains a
+trailing CRC. If the most recently processed word(s) form a valid CRC for all
+the data processed since reset, the CRC register will always contain a fixed
+value which can be computed in advance, and the `match_detected` output
+indicates whether the CRC register currently contains this value.
 
 # Reference-level explanation
 [reference-level-explanation]: #reference-level-explanation
 
+The proposed new interface is:
+
+* A `crc.Parameters` class which holds the parameters for a CRC algorithm,
+  all of which are passed to the constructor:
+    * `crc_width`: bit width of the CRC register
+    * `data_width`: bit width of input data words
+    * `polynomial`: generator polynomial for CRC algorithm
+    * `initial_crc`: initial value of CRC at start of computation
+    * `reflect_input`: if True, input words are bit-reversed
+    * `reflect_output`: if True, output values are bit-reversed
+    * `xor_output`: value to XOR the CRC value with at output
+* The class has the following methods:
+    * `compute(data)` performs a software CRC computation on `data`, an
+      iterable of input data words, and returns the CRC value
+    * `create()` returns a `crc.Processor` instance preconfigured to use
+      these parameters
+    * `residue()` returns the residue value for these parameters, which is
+      the value left in the CRC register after processing an entire valid
+      codeword (data followed by its own valid CRC)
+    * `check()` returns the CRC computation of the ASCII string "123456789",
+      a defacto standard for validating CRC correctness
+* A `crc.Predefined` class which is constructed using all the parameters of
+  `crc.Parameters` except `data_width`, which is application-specific. This
+  class implements `__call__(data_width=8)` which is used to create a
+  `crc.Parameters` with the specified data width
+* A `crc.Catalog` class which contains instances of `crc.Predefined` as
+  class attributes
+* A `crc.Processor` class which inherits from `Elaboratable` and implements
+  the hardware generator
+
+The hardware implementation uses the property that CRCs are linear, and so the
+new value of any bit of the CRC register can be found as a linear combination
+of the current state and all the input bits. By expressing the CRC computation
+as a linear system like this, we can then determine the boolean equation used
+to update each bit of the CRC in parallel. A software CRC calculator is
+implemented in Python in order to find these logic equations.
+
 The proposed CRC generator is already implemented and available in [PR 681].
 The docstrings and comments in it should explain its operation to a suitably
 technical level of detail.
 
 [PR 681]: https://github.com/amaranth-lang/amaranth/pull/681
 
-The proposed implementation uses the fact that CRCs are a linear calculation,
-and so the new value of any bit of the CRC register can be found as a linear
-combination of the current state and all the input bits. By expressing the CRC
-computation as a linear system like this, we can then determine the logic
-equation used to update each bit of the CRC in parallel. A software CRC
-calculator is implemented in Python in order to find these logic equations.
-
 # Drawbacks
 [drawbacks]: #drawbacks
 
@@ -144,21 +229,18 @@ computations.
 # Unresolved questions
 [unresolved-questions]: #unresolved-questions
 
-- There is a `reset` signal to reset the CRC state to its initial value.
-  In practice, users could replace this with a `ResetInserter` wrapper.
-  Since all users will need this signal, it seems easier to include it
-  directly in the module interface.
-
-- We could include a number of standard CRC parameters directly in the standard
-  library, to make using them more convenient. I don't know what the preferred
-  interface for this would be, perhaps just a Python module with some
-  constants?
+- Currently the design uses a `first` signal to signal the beginning of a new
+  CRC computation (previously called `reset`). Requiring that it may be
+  asserted simultaneously with the first valid data word of the new CRC adds
+  muxes to the design that would not be needed if `first` and `valid` cannot
+  be asserted together. Is this a worthwhile tradeoff, or is there a way to
+  avoid the extra muxes?
 
 # Future possibilities
 [future-possibilities]: #future-possibilities
 
-- The data interface uses a `data` and `valid` signal. Eventually, this should
-  be replaced with a Stream, once they are finalised.
+- The data interface uses `first`, `data`, and `valid` signals.
+  Eventually, this should be replaced with a Stream, once they are finalised.
 
 - Currently the entire input data word must be valid together; there is no
   support for masking some bits off. In particular, such a feature could be