pveclib

Power Vector Library

Header files that contain useful functions leveraging the PowerISA Vector Facilities: Vector Multimedia Extension (VMX AKA Altivec) and Vector Scalar Extension (VSX). Larger functions like quadword multiply and multiple quadword multiply and madd are large enough to justify CPU specific and tuned run-time libraries. The user can choose to bind to platform specific static archives or dynamic shared object libraries which automatically (dynamic linking with IFUNC resolves) select the correct implementation for the CPU it is running on.

The goal of this project to provide well crafted implementations of useful vector and large number operations:

• Provide equivalent functions across versions of the PowerISA. For example the Vector Multiply-by-10 Unsigned Quadword operations introduced in PowerISA 3.0 (POWER9) can be implement in a few vector instructions on earlier PowerISA versions.
• Provide equivalent functions across versions of the compiler. For example builtins provided in later versions of the compiler can be implemented as inline functions with inline asm in earlier compiler versions.
• Provide higher order functions not provided directly by the PowerISA. For example vector SIMD implementation for ASCII __isalpha, etc. Another example full __int128 implementations of Count Leading Zeros, Population Count, and Multiply.
• Provide optimized run-time libraries for quadword integer multiply and multi-quadword integer multiply and add.

Build

PVECLIB now supports CPU tuned run-time libraries, both static archives and dynamic (IFUNC selected) shared objects. This complicates the build process as it now has to build the same source code, multiple times, with different compile targets (-mcpu=). Another complication comes from compiling for big endian systems where the compiler default target may not include the vector facilities (VMX and VSX).

Configure and option flags

The project can use configure test to define options like AM_CPPFLAGS and AM_CFLAGS but the user command line options (CPPFLAGS and CFLAGS) are always applied last and take precedent. See: Automake "Flag Variables Ordering" https://www.gnu.org/software/automake/manual/html_node/Flag-Variables-Ordering.html

So a configure flag like CFLAGS='-O3 -mcpu=power7' would be OK for functional verification tests of the POWER7 specific implementations of PVECLIB operations. But this would interfere with building the POWER8 and POWER9 specific objects for the production version of libpvec.so. So builds for production level PVECLIB should never specify -mcpu= in CFLAGS.

On the other hand if the user does not specify any CFLAGS, autoconf will fill in a default value of '-O2 -g'. This is bad! PVECLIB needs the global common subexpression, loop, and vector cost model optimizations enabled by '-O3'. Also '-g' will generate huge debug tables for the vector int512 run-time and slow down the build. If you need to profile or debug with basic back-trace information, use '-g1'.

So unless you are involved in the functional testing of new PVECLIB operations, the safe options are:

CFLAGS='-m64 -g1 -O3'

The PVECLIB Makefile.am files include special macros for CPU specific run-time compiles. These macros exclude the user CFLAGS from those compile commands.

On the other hand, if the compiler default target does not support PowerISA vector facilities and an appropriate '-mcpu=' option is not supplied, the compile will fail. So the PVECLIB configure.ac includes a number of configure tests that detect this and provide appropriate compile targets.

The current PVECLIB implementation assumes the target supports both VMX (Altivec) and VSX facilities. So the minimum targets are set internally (PVECLIB_DEFAULT_CFLAG) to '-mcpu=power7' for BE and '-mcpu=power8' for LE.

The PVECLIB configure.ac also includes configure tests for related PowerISA facilities that can be leveraged for PVECLIB operations but are not core functions. This includes decimal floating-point and IEEE 128-bit binary floating-point. These are both target and compiler support checks. The compiler checks are especially important for the Clang compiler as it is currently missing Decimalxx and Float128 support. Some PVECLIB operations will be disabled in this case.

The default compiler is 'gcc'. The project can be configured to use the Clang / LLVM compiler using the CC=clang flag.

Run './configure', to verify the build tools and environment.

$ ./configure CFLAGS='-O3 -g1'

On a big endian / biarch systems it is wise to explicitely specify 64-bit.

$ ./configure CFLAGS='-m64 -O3 -g1' LDFLAGS='-m64'

To use the Advance Toolchain.

$ ./configure  CC=/opt/at13.0/bin/powerpc64le-linux-gnu-gcc \
AR=/opt/at13.0/bin/powerpc64le-linux-gnu-ar \
RANLIB=/opt/at13.0/bin/powerpc64le-linux-gnu-ranlib \
CFLAGS='-m64 -O3 -g1' LDFLAGS='-m64'

Then run 'make' to perform the basic compile tests and build the run-time libraries:

$ make

and, optionally run the functional verication tests:

$ make check

and, install the headers and librarys so your programs can use them:

$ make install

If the included autotools dont match the version installed on your system, perform these step:

$ aclocal
$ autoconf
$ automake

Usage

Once pveclib is installed on the POWER or OpenPOWER system simply include the appropriate header. For example:

#include <pveclib/vec_int128_ppc.h>

The headers are organized by element type:

vec_common_ppc.h; Typedefs and helper macros
vec_f128_ppc.h; Operations on vector _Float128 values
vec_f64_ppc.h; Operations on vector double values
vec_f32_ppc.h; Operations on vector float values
vec_int512_ppc.h; Operations on Multi-quadword integer values
vec_int128_ppc.h; Operations on vector __int128 values
vec_int64_ppc.h; Operations on vector long int (64-bit) values
vec_int32_ppc.h; Operations on vector int (32-bit) values
vec_int16_ppc.h; Operations on vector short int (16-bit) values
vec_char_ppc.h; Operations on vector char (8-bit) values
vec_bcd_ppc.h; Operations on vectors of Binary Code Decimal and Zoned Decimal values

Full documentation is linked off of:

https://github.com/open-power-sdk/pveclib/wiki