NX GZIP compression library

libnxz implements a zlib-compatible API for Linux userspace programs that exploit the NX GZIP accelerator available on POWER9 and newer processors.

How to Use

• If want to use nxzlib to substitute zlib, following the steps as below:
  1. Build libnxz.so

     ./configure
     make

  2. Use LD_PRELOAD to preload libnxz with the specified path.

     LD_PRELOAD=./libnxz.so /home/your_program

• Alternatively, override the libz.so with libnxz.so However, this method is NOT recommended as it may break down the machine.

  cp lib/libnxz.so.0.0 /usr/lib/  #(replace 0.0 with the version being used)
  mv /usr/lib/libz.so /usr/lib/libz.so.bak
  ln -s /usr/lib/libnxz.so.0.0 /usr/lib/libz.so

How to Run Test

cd test
./configure
make
make check

How to Select NXs

By default, the NX-GZIP device with the nearest process to cpu affinity is selected. Consider using numactl -N 0 (or 8) to force your process attach to a particular device

How to enable log and trace for debug

The default log will be /tmp/nx.log. Use export NX_GZIP_LOGFILE=your.log to specify a different log. By default, only errors will be recorded in log.

Use export NX_GZIP_VERBOSE=2 to record the more information.

Use export NX_GZIP_TRACE=1 to enable logic trace.

Use export NX_GZIP_TRACE=8 to enable statistics trace.

Supported Functions List

All the zlib supported functions are listed and described at libnxz.h.

If want to use nxzlib standalone, add a prefix 'nx_' before the function. For example, use nx_compress instead of compress.

Code organization

• libnxz.h - Provides the zlib-compatible API.
• doc/ - Provides documentation about the library.
• inc_nx/ - Internal header files.
• lib/ - Implements the library functions.
• oct/ - Provide output comparison tests validating that data can be compressed and decompressed with other libraries maintaining their integrity.
• samples/ - Provide example application that use the libnxz API.
• selftest/ - Small set of tests for the NX GZIP accelerator. These tests are reused in Linux.
• test/ - Unit tests for libnxz.