/power-gzip

POWER NX zlib compliant library

Primary LanguageC

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.

[TOC]

How to Use

  • If want to use nxzlib to substitute zlib, following the steps as below:
  1. Build libnxz.so
make clean; make
  1. Use libnxz.so to substitute libz.so (replace 0.0 with the version being used)
cp lib/libnxz.so.0.0 /usr/lib/
mv /usr/lib/libz.so /usr/lib/libz.so.bak
ln -s /usr/lib/libnxz.so.0.0 /usr/lib/libz.so
  • If don't want to override the libz.so, use LD_PRELOAD to run. Something like:
LD_PRELOAD=./libnxz.so /home/your_program
  • If want to use nxzlib standalone, following the steps as below:
  1. Edit config.mk and remove line ZLIB = -DZLIB_API
  2. Build libnxz.so
make clean; make

How to Run Test

cd test
make clean; 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.