README file for 'crcPlus'.

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

Derived from the author's earlier 'crcmodel' C-language hack.

Original reference 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 crcPlus-x.x.xx.tar.bz2

  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
This package contains source code and documentation for the 'crcPlus' 
application. You will need to build the application binary for your target 
system (see below).

The 'crcPlus' utility is a GNU/Linux console (command-line) utility, written 
in C++, and which provides a fully-configurable reference model for implementing 
a CRC (Cyclic Redundancy Check) generator in your own projects.

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

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

      The reference model is implemented in two flavours:
      1) A direct-calculation reference model which calculates the CRC of
         an incomming data stream byte-by-byte. This is a simple and reliable 
         model for algorithm verification tests, but it is comparatively slow.
      2) A table-driven reference model for high-speed commercial-grade 
         applications. The table-driven CRC algorithm uses a dynamically 
         generated hash table to significantly reduce the number of necessary 
         runtime calculations.

   c) The 'crcPlus' application is able to generate a hash table (lookup table) 
      to match your exact CRC specifications, so that you can drop it directly 
      into your own project.

   d) While our hash table implementation is certainly faster than the direct 
      calculation algorithm, it is also potentially less robust. However, for 
      all the likely combinations of configuration parameters and for _all_ 
      supported register widths, the faster algorithm produces exactly the same 
      results as the direct-calculation model.

   e) User Interface and command-line options.
      There are three operating mode options. One of these options must be the 
      first option specified.
      1) --file
         Specify a source binary file as the input stream and apply the 
         reference model code to it.
      2) --table
         Generate and export a lookup table based on the specified configuration 
         parameters 
      3) --test
         Perform an internal test of the algorithm using known parameter setup 
         and a simple input stream: "123456789".

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

      -- 'crcPlus' supports CRC generation any size accumulator register between 
         8 bits and 32 bits, inclusive. In addition to register width, the 
         following configuration parameters may be specified:
      -- "polynomial" value, i.e. the hexidecimal value which is the divisor 
         for CRC division. 
      -- initial register value
      -- XOR value to be applied to the final CRC 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.

   g) Documentation.

      The documentation for crcPlus is provided in both 'info' (Texinfo) and 
      HTML format.

      This application is not intended as a tutorial on CRC. Instead, it simply 
      describes how the CRC_Gen algorithm works and shows examples of how it may 
      be integrated into a software project.

      Ross Williams' 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

      Application usage is described by the list of command-line options:
          crcplus --help


  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
The files included in this release.

crcPlus/                // Source code directory
   crcPlus.cpp          // Application-level source code
   crcPlus.hpp          // Application-class definition and general definitions
   CRC_Gen.hpp          // Definition and implementation of the CRC Generator class
   Makefile             // Build the 'crcPlus' application
   OggSamp1_01.bin      // Test data taken from an OGG/Vorbis sample file (Xiph.org)
   numbers.bin          // Additional test data
   README               // Package description, release notes (this file)
   Texinfo/             // Documentation directory
     crcplus.info       // Documentation in 'info' format
     crcplus.html       // Documentation in 'HTML' format
     Makefile           // Build the info/HTML documentation
     applycss           // Apply CSS style to the HTML document
     applycss_response.txt  // Note that the HTML post-processor 'idpp' 
                            // is available as a separate download
     crcPlus.texi       // Documentation source markup
     texiMacros.texi
     same_author.texi
     gpl-3.0.texi
     fdl-1.3.texi
     infodoc_styles.css // CSS3 style definitions for the HTML-format documentation

  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -

-- =========================================
-- NOTES on the current release of crcPlus =
-- =========================================

-- This application was designed under Fedora Linux and is built using 
   the GNU C compiler, version 4.8.3 or higher.
   -- See the Makefile for compile switches.

-- Current Release v:0.1.00
   -- This is the C++ port (with significant enhancements) of our earlier
      'crcmodel' reference model written in C.
      'crcmodel' was based on Ross Williams' original work, and was enhanced 
      for student use. Ross's article (with code examples) was written in 1993
      and is in the public domain.

-- ======================================
-- Building the 'crcPlus' 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/crcplus-0.1.00.tar.bz2

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

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

   6) Build the 'crcPlus' 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.
         
         If the application fails to build or 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.

         [crcPlus]$ ldd crcplus
         linux-vdso.so.1 =>  (0x00007ffe9abad000)
         libstdc++.so.6 => /lib64/libstdc++.so.6 (0x0000003a28000000)
         libm.so.6 => /lib64/libm.so.6 (0x0000003a1a000000)
         libgcc_s.so.1 => /lib64/libgcc_s.so.1 (0x0000003a1bc00000)
         libc.so.6 => /lib64/libc.so.6 (0x0000003a19000000)
         /lib64/ld-linux-x86-64.so.2 (0x0000003a18c00000)

   7) Once you have a clean build, invoke the application with a request 
      for the version:
            ./crcplus --version
      a) If the application successfully displays the version number and 
         copyright information, then the application has been built correctly.

   8) Note to those who are developing CRC support under 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:
-- ============================
   -- No outstanding bug reports, but be aware that this is the first 
      _public_ release, so keep your eyes open.

