README.CMPSC

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


        Hercules CMPSC "Compression Call" instruction support


The z/Architecture Compression Call instruction (CMPSC opcode B263) has
two different implementations within Hercules 4.0 Hyperion.

The original (legacy) cmpsc implementation does not currently support the
z/Architecture CMPSC-enhancement facility, fails to pass certain cmpsctst
testing tool(*) architecural compliance tests, and is not as fast.

The newer cmpsc_2012 implementation not only passes all cmpsctst testing
tool architectural compliance tests, but also supports the z/Architecture
CMPSC-enhancement facility, and is about 10% faster as well. As a result,
the new 2012 implementation is now the default implementation in Hercules
4.0 Hyperion.

The original legacy implementation still exists and can still be used if
desired, but you will need to specifically request it by adding a "LDMOD"
(load module) statement to your configuration file to request the module
"altcmpsc.dll" be loaded (or by manually entering the ldmod panel command
after Hercules has been started).

The CMPSC Compression Call instruction is fully described in painstaking
detail in publication "ESA/390 Data Compression" (SA22-7208) as well as
in the z/Architecture Principles of Operation manual too (SA22-7832).

The original legacy cmpsc implementation logic is contained in a single
'C' source file called "cmpsc.c".

The newer default cmpsc_2012 implementation logic is spread across several
different source files, each handling just one aspect of the instruction's
overall functionality, and closely follows IBM's flow charts published in
each of those manuals:


      cmpsc_2012.c        Primary implementation functions
      cmpsc.h             Implementation-wide common header
      cmpscbit.h          Bit Extraction Helper Macros
      cmpscget.h          Get Next Index Functions
      cmpscget.c          Get Next Index Functions
      cmpscput.h          Put Next Index Functions
      cmpscput.c          Put Next Index Functions
      cmpscdct.h          Get Dictionary Entry Functions
      cmpscdct.c          Get Dictionary Entry Functions
      cmpscmem.h          Memory Access Functions
      cmpscmem.c          Memory Access Functions
      cmpscdbg.h          Debugging Functions (not implemented)
      cmpscdbg.c          Debugging Functions (not implemented)


The original legacy cmpsc implementation was written by Bernard van der
Helm of Noordwijkerhout, The Netherlands. The cmpsc_2012 implementation
was written by Fish (David B. Trout) of the United States of America.

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

(*) The CMPSCTST instruction testing tool is maintained separately from
    Hercules in its own source code repository on GitHub, ships with a
    pre-built set of ready-to-run binaries (executable files and scripts)
    for both Windows and Linux (CentOS 6.4 with gcc 4.4), a default set
    of test files, and contains a detailed README explaining how to not
    only build the tool for yourself but also how to run its many tests.
    The URL of the repository is:  https://github.com/Fish-Git/cmpsctst

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