/* readme.txt */

/**************************************************************************+
*
*  PANAMA high-performance reference C-code, based on the description in 
*  the paper 'Fast Hashing and Stream Encryption with PANAMA', presented 
*  at the Fast Software Encryption Workshop, Paris, 1998, see "Fast 
*  Software Encryption - 5th International Workshop, FSE'98", edited by 
*  Serge Vaudenay, LNCS-1372, Springer-Verlag, 1998, pp 60-74, also 
*  available on-line at http://standard.pictel.com/ftp/research/security
*
*  Algorithm design by Joan Daemen and Craig Clapp
*
*  readme.txt  -  Explanatory file for Panama source code and other files
*
*
*  History:
*
*  29-Oct-98  Craig Clapp  Implemention for Dr. Dobbs, Dec. 1998 issue, 
*                          based on earlier performance-benchmark code.
*
*
*  Notes:  This code is supplied for the purposes of evaluating the 
*          performance of the Panama stream/hash module and as a 
*          reference implementation for generating test vectors for 
*          compatibility / interoperability verification.
*
*
+**************************************************************************/

/**************************************************************************+
*
*  Command-line options for invoking panatest:
*  ------------------------------------------
*
*  The main routine can be called with up to three command-line arguments:
*
*  The first (optional) argument specifies the number of times to perform 
*  encryption and hashing  over the test array. For performance measurements 
*  this number should be chosen large enough to swamp the granularity of the 
*  real-time clock. (e.g. a PC's real-time clock has a granularity of >50ms 
*  so each test case should run for around 5 secs. to get reasonable 
*  accuracy). Setting this argument to 0 (zero) causes this part of the 
*  program to be  skipped.
*
*  The second (optional) argument gives a text string to be hashed. Use 
*  the target platform's standard command-line conventions if spaces or 
*  control characters are to be included (e.g. enclose the string in double 
*  quotes for MS-DOS command line).
*
*  The third (optional) argument specifies the length (in bits) that the 
*  text string is to be truncated to before the hash is generated. This 
*  number cannot be longer than the actual length of the string in bits.
*
*  If all arguments are omitted the program will generate performance 
*  figures for it's default number of passes, and will generate a reference 
*  set of test vectors. To generate test vectors only, invoke panatest 
*  with a single argument of 0 (zero).
*
*  Examples:
*
*   panatest        - Print performance figures and reference test vectors
*   panatest 0      - Print reference test vectors only
*   panatest 2500   - Print performance figures for 2500 runs of the 
*                     performance test
*
*   panatest 0 "Hello world"       - Print the hash for Hello world
*   panatest 100 "Hello world" 39  - Run 100 passes of the performance test 
*                                    and print the hash for the 39-bit 
*                                    string had by truncating Hello world.
*
+**************************************************************************/


/**************************************************************************+
*
*  The following files are supplied:
*
*  readme.txt   -  This file.
*
*  panatest.c   -  Test harness for Panama stream/hash module, consistent 
*                  with exportable version - panama_x.c
*
*  panama_x.c   -  Core routines for the Panama stream/hash module, this 
*                  exportable version excludes an encryption routine.
*
*  panama.h     -  Header file for Panama C-code implementation.
*
*  panatest.exe -  MS-DOS 32-bit executable for panatest. Compiled by 
*                  MS Visual C++ Release 5.0, with compiler switches set 
*                  to maximize speed with Pentium Pro (Pentium II) as 
*                  target.
*
*  panavecs.txt -  Reference set of hash test vectors. Produced by running 
*                  panatest 0.
*                  
*  panaperf.txt -  Performance report for Panama running on a 200 MHz 
*                  Pentium Pro. Produced by running panatest 1000.
*
*  panpush5.pdf -  Example instruction schedule for the inner loop of 
*                  pan_push() on a VLIW CPU with 5 issue slots per cycle, 
*                  as produced by the TriMedia C compiler / scheduler.
*                  Bold arcs indicate instruction dependencies on the 
*                  critical path. Light arcs indicate instruction 
*                  dependencies that have a single cycle of slack. All 
*                  other instruction dependencies have two or more cycles 
*                  of slack.
*
*  panpull5.pdf -  Example instruction schedule for the inner loop of 
*                  pan_pull() on a VLIW CPU with 5 issue slots per cycle.
*                  as produced by the TriMedia C compiler / scheduler.
*
+**************************************************************************/
