CRC Model - Release Notes


Copyright 2017 by The Software Samurai.
On the web: http://www.SoftwareSam.us/
Software released under GNU GPL3, and documentation released under FDL1.3

Original algorithm and notes (1993) were written and placed in the public domain by:
Ross Williams:   www.ross.net

This package contains source code and basic documentation for the 'crcmodel' application.

You will need to build the application binary for your target system (see README file).

The 'crcmodel' utility is a GNU/Linux console (command-line) utility which provides a reference model for implementing CRC (Cyclic Redundancy Check) “checksum” generation.

This is not a commercial-quality product. The user interface is quite basic and the documentation is useful but simple.

  1. This application is intended as a reference for students and others who are implementing CRC checksums in their own work.

  2. 'crcmodel' provides a simple, accurate model for CRC generation based on a set of flexible setup parameters. If, for a given source data stream and setup parameters, your CRC implementation generates the same CRC value as 'crcmodel' then you can be relatively certain that your implementation is correct.

    The reference model checksum generator does not use a table lookup. Instead it directly calculates the CRC byte-by-byte. This is a simple and reliable model for algorithm verification tests, but it is comparatively slow.

  3. For high-speed commercial-grade applications such as assembling Ethernet packets, the CRC algorithm can be enhanced by using a pre-generated lookup table to reduce the number of necessary runtime calculations. The 'crcmodel' application is able to flexibly generate such a lookup table to match your exact specifications. However, as Ross says in his notes:   “If you don't care much about speed, just use the reference model code!”

  4. We have enhanced Ross's original code to include an example implementation of the table-lookup speed enhancement. For this example we dynamically build a lookup table according to the setup parameters provided and then process the input stream using that table.

    Note that to properly evaluate the difference in processing performance between the direct calculation method and the table lookup method, we would need a much larger data set than our simple test data provides. We leave that evaluation as an exercise.

    While our simple lookup-table implementation is certainly faster, it is also potentially less robust. However, for all the likely combinations of setup parameters, the faster algorithm produces exactly the same results as the reference model. (See the GenRamTable() and FileChecksumT() functions for details of the lookup-table implementation.) We hope that your hot implementation will be even faster, and every bit as stable. Good luck!

  5. 'crcmodel' supports both 16-bit and 32-bit CRC generation using the following parameters:
    1. width of the CRC register (and table entries)
    2. “polynomial” value, i.e. the hexidecimal value which is the divisor for CRC division.
    3. initial register value
    4. reflection of the input, that is reversing the bits of each byte of the input stream.
    5. reflection of the final CRC value, that is reversing the bits of the final register value before returning from the algorithm.
    6. XOR value to be applied to the final CRC value.

  6. User Interface and command-line options. There are three operating mode options. One of these options must be the first option specified.

    1. ––test
      Perform an internal test of the algorithm using a known parameter setup and a simple input stream: “123456789”.
    2. ––file
      Specify a source binary file as the input stream and apply the reference model code to it.
    3. ––table
      Generate and export a lookup table based on the optional parameters described below.

    Optional Parameters

    These options allow optional specification of all setup parameters for CRC checksum and table generation. All CRC processing parameters have default values that correspond to a generic 32-bit algorithm. (All optional parameters are ignored for the internal algorithm-validation test. '––test')

    • ––poly=POLY
      This is the so-called “generator polynomial” or hexadecimal XOR value.
      Default: 04C11DB7h This is the value used in many popular algorithms including the one
      of particular interest to us, which is the CRC checksum used by OGG/Vorbis audio tag data.
      Any hexadecimal value will work, so long as it is the same width as the register; however,
      some values work better than others.
      Register width is specified by the '––regbits' option below.
    • ––reflect=[true | false]
      Direction of bit processing for input bytes.
      'true'  for algorithms which shift bits right (default)
      'false' for algorithms which shift bits left
    • ––reflout=[true | false]
      Reverse the order of bits for the final CRC checksum value before returning it.
      'true'  Reverse the bit order. (default)
      'false' Do not reverse the bit order.
    • ––regbits=[16 | 32]
      Number of bits in the accumulator register.
      16 == 16-bit calculations
      32 == 32-bit calculations (default)
    • ––regfinal=HEXVALUE
      Post-calculation XOR value (in hexadecimal). default: FFFFFFFFh
      Perform an XOR operation on the final CRC checksum value before returning it.
    • ––reginit=HEXVALUE
      Initial register value (in hexadecimal). This will be the register value when
      processing begins. default: FFFFFFFFh
    • ––oggvorbis
      Special Case: Set up processing parameters for OGG/Vorbis metadata (tag data)
      checksum generation.
    • ––help
      Display a list of command-line options (this list)

  7. There is no formal documentation for this application because this is a reference algorithm and not a commercial product. Ross's original article describing the theory and the practical mathematics of CRC generation can be found at:

                “A Painless Guide To CRC Error Detection Algorithms,”
                      http://www.ross.net/crc/download/crc_v3.txt

    For the current release, at least, in addition to our own implementation notes in the source code, most of Ross's explanations and source-code notes have been retained.

    Application usage is described by the list of command-line options:  crcmodel --help  (see above)

  8. Since this package was originally posted, we have completed an implementation of the CRC model in C++. We believe it to be a much cleaner implementation with enhanced source code readability and easy portability for integration into other applications. Please see the crcPlus package, available as a separate download.

  9. As a final note, in the classroom, we live by Abelson & Sussman's postulate that “Programs must be written for people to read, and only incidentally for machines to execute.” In that spirit, we have made some rather unkind remarks in the source code about Ross Williams' coding style. Sorry about that, but keep in mind that Ross is a pioneer in algorithms, and that pioneers are messy by nature in ways that software designers cannot afford to be.


The files included in this release.

crcmodel/          // Source code directory
   crcmodel.c      // Startup code, user interface and basic functionality
   crcmodel.h      // Definitions and constant data
   crctable.c      // Code for generating a CRC lookup table
   Makefile        // Build the 'crcmodel' application
   README          // Package description, release notes (this file)

Notes on the current release of 'crcmodel'



  These notes are adapted from the “README” file included with the application archive.
  Thank you and have fun with CRC!  — Software Sam