README file for 'crcmodel'.

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 <http://www.ross.net>
=======================================================================

Unpack this archive using the following command:
              tar -xjvf crcmodel-x.x.xx.tar.bz2

  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
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 below).

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. It is a simple tool for software 
development. The user interface is quite basic and the documentation (this 
file) is useful, but simple.

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

   b) '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.

   c) 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!"

   d) 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!

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

   f) 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 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 optional parameters are 
      ignored for the algorithm-validation test.)
      All CRC processing parameters have default values that correspond to the 
      generic 32-bit algorithm.

      See the HelpMe() function for a complete list of command-line options.

   g) There is no formal documentation for this application because this is a 
      reference algorithm and not a commercial product.

      The HTML version of this README file is posted on our website and 
      provides somewhat more detail than this document.

      Ross's original article describing the theory and 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, 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

   h) Note that we have made some rather unkind remarks about Ross Williams' 
      coding style. Sorry about that, but keep in mind that at the time his 
      paper was published, (1993) he had only recently earned his PhD, and 
      that he is an algorithm guy and not a software engineer.

  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
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 =
-- ==========================================

-- This application was designed under Fedora Linux and is built using 
   the GNU C compiler, version 4.8.3.
   -- The -std=gnu11 switch is required for a successful build.
      See the Makefile for details.

-- Current Release v:1.5.02
   -- Correct several typographical errors, and improve formatting.
   -- Add additional explanations of the algorithm.
   -- Note that this may be the final version of 'crcmodel'. A much improved 
      implementation of the algorithm is now available:
      'crcPlus', a C++ port (and enhancement) of the reference model.

-- v:1.5.01
   -- Based on Ross Williams' original work and enhanced for student use.
   -- Convert most hard-coded #define's to variables and implement command-line 
      switches for dynamic configuration of the algorithm.
   -- Implementation of a _very basic_ user interface.
   -- Additions to and/or modification of source code notes.
   -- Programmers always believe that our work is totally bug-free, and we 
      are always wrong. Please report all bugs or suspected bugs via the 
      website.
   -- This application was written in four(4) days, most of which time was spent 
      in research. It has not yet been seen by our beta-test volunteers. We 
      apologize for any errors, all of which are entirely our own responsibility.
         -- Software Sam

-- Original Release v:1.0 was written by Ross Williams and is in the public domain.

-- ======================================
-- Building the 'crcmodel' application: =
-- ======================================

   1) Open a terminal window.

   2) Navigate to the directory where you want to unpack the archive.
            (See tree structure of the archive above.)

   3) Copy the compressed archive to the target directory.
            Example: cp ~/Downloads/crcmodel-1.5.01.tar.bz2

   4) Unpack the archive:
      a) If your target directory already contains an 'crcmodel' directory, 
         then rename it before unpacking the new archive.
            Example:  mv crcmodel crcmodel_OLD
      b) All contents of the compressed archive will be unpacked into a tree 
         whose base directory is 'crcmodel'. 
      c) Unpack the archive.
            tar -xjvf crcmodel-x.x.xx.tar.bz2

   5) Navigate to the directory which contains the source code.
            cd crcmodel

   6) Build the 'crcmodel' application.
      a) Be sure that your compiler version is 4.8.0 or greater.
            gcc --version
      b) Build the application.
            gmake
      c) The build should be clean with no errors and no warnings.
         If there are errors, then the most likely cause would be that the 
         compiler cannot find a necessary header file or library.
         Check your LIB_PATH and other environment variables.

   7) Once you have a clean build, invoke the application with a request for help:
            ./crcmodel --help
      a) If the application successfully displays the command-line options, 
         then the application has been built correctly.
      b) If the application does not run, then verify that all necessary libraries 
         are installed on your system. Run the 'ldd' command to list the 
         necessary libraries. The needed libraries should look something like 
         the following. These are all standard libraries which should be 
         installed on your system by default.

         [crcmodel]$ ldd crcmodel
         linux-vdso.so.1 =>  (0x00007fff4ad71000)
         libc.so.6 => /lib64/libc.so.6 (0x0000003a19000000)
         /lib64/ld-linux-x86-64.so.2 (0x0000003a18c00000)

   8) Note for users of Microsoft Windows(tm), we strongly recommend 
      that you immediately wipe your system and install Ubuntu 16 LTS.
                      <http://releases.ubuntu.com/>


-- ============================
-- Known bugs and other issues:
-- ============================
   -- The direct-calculation algorithm and the table-driven algorithm are
      not fully symmetrical for all parameter combinations. The direct 
      algorithm should be used for verifications. Repairing the table-driven
      algorithm can be done; however, it does not seem worthwhile at this time.
      See the crcPlus (C++) implementation of the table-driven CRC generator.
      

