===========================================================================
Libvecpf
The "Vector Printf Library" User & Developer Guide
For the GNU/Linux OS and GLIBC 2.10
Contributed by IBM Corporation
Copyright (C) 2011-2013 IBM Corporation
===========================================================================
NOTE:Eight space tabs are the optimum editor setting for reading this file.
===========================================================================
Author(s) : Ryan S. Arnold <rsa@linux.vnet.ibm.com>
Date Created: July 12, 2011
Last Updated: August 09, 2013
===========================================================================
Table of Contents:
1. Introduction
1.1. Rationale
2. License
3. Supported Platforms
4. Dependencies
4.1 GNU/Linux OS
4.2 GLIBC Minimum Version
5. Configuration
6. Make Rules
7. Use
8. Contributing
A. History
---------------------------------------------------------------------------
1. Introduction
---------------------------------------------------------------------------
1.1. Rationale
The functionality in Libvecpf was originally suggested for GLIBC but was
rejected. The GLIBC printf-hooks were created to enable specialized
libraries, like this one, to register printf callback hooks for
specialized data types.
---------------------------------------------------------------------------
2. License
Libvecpf is released under the "LGPL v2.1" License as indicated by the file
"LICENSE".
---------------------------------------------------------------------------
3. Supported Platforms
Currently Libvecpf has only been tested on the Power Architecture POWER
platforms to support the following Vector datatypes:
Altivec/VMX Data Types:
vector unsigned int
vector signed int
vector unsigned short
vector signed short
vector unsigned char
vector signed char
vector float
VSX Data Types:
vector double
vector unsigned long
vector signed long
vector unsigned long long
vector signed long long
This library could be extended to provide printf support for the following
Vector data types:
SPE Data Types:
(Note: SPE is mutually exclusive with Altivec/VMX and VSX):
__ev64_u16__
__ev64_s16__
__ev64_u32__
__ev64_s32__
__ev64_fs__
__ev64_u64__
__ev64_s64__
__ev64_opaque__
AVX Data Types
__m256
__m256d
__m256i
SSE2 Data Types
__m128
__m128d
__m128i
---------------------------------------------------------------------------
4. Dependencies
---------------------------------------------------------------------------
4.1 GNU/Linux OS
Only GLIBC supports the printf-hooks mechanism and therefore libvecpf is a
GNU/Linux OS only library.
---------------------------------------------------------------------------
4.2 GLIBC Minimum Version
Libvecpf version 1.0.0 relies upon a minimum GLIBC 2.10 for printf-hooks
support. The libvecpf configure stage will check the libc that it is
linked against for the printf-hook support and will warn if it is not
found.
---------------------------------------------------------------------------
5. Configuration
Libvecpf must be built in a directory that is not the base level source
directory.
Libvecpf may be built as a static library, a shared library, or both. The
configuration defaults to building the shared library and not building the
static library.
In order to NOT build the shared library pass the following flag:
--enable-shared=""
In order to build the static library pass the following flag:
--enable-static
You may also explicitly pass the 'enable' switch for both, e.g.:
CFLAGS="-m32 -g -O2" ../libvecpf/configure \
--build=powerpc-linux --host=powerpc-linux --enable-shared \
--enable-static 2>&1 | tee _configure32
CFLAGS="-m64 -g -O2" ../libvecpf/configure \
--build=powerpc64-linux --host=powerpc64-linux --enable-shared \
--enable-static 2>&1 | tee _configure32
The library also support VSX 'vector double', which is enabled by default.
However, tests will be only run by make check if compiler defines __VSX__
(which is a builtin for -mcpu=power7 or -mvsx).
---------------------------------------------------------------------------
6. Make Rules
make all:
Build libvecpf-X.Y.Z.so, libvecpf.so, libvecpf.so.1, and libvecpf.a.
make check:
The libvecpf test suite will execute upon either/both libvecpf.so (the
shared library) or/and libvecpf.a (the static library) of the Vector
Printf Library depending on which --enable switches were passed.
It will only execute VSX data-type tests if the library has been built
on a system which support the VSX instruction sets (i.e. power7 and
later POWER processors).
make install:
Results in the installation of libvecpf-X.Y.Z.so, libvecpf.so,
libvecpf.so.1 into @libdir@ as specified by configure.
install_root=<new_top_level>
This causes the aforementioned libraries, applications, and header
files to be installed into <new_top_level>/@libdir@
<new_top_level>/@bindir@, <new_top_level>/@includedir@, and
<new_top_level>/@mandir@.
make uninstall:
Results in all installed files being removed.
---------------------------------------------------------------------------
7. Use
Compiling an application and linking it against the static library
libvecpf.a will expose a default feature of the link editor which purges
unused symbols. This will prevent the registration of the printf-hook
callback mechanism because the link editor thinks that the library
constructor is unused and purges it from the final link.
In order to prevent the link editor from purging the libvecpf constructor
on the final link explicitly tell it to not purge the constructor by
passing "-Wl,-u,__libvecpf_init" as in the following example:
gcc -m32 -maltivec -O3 -g -fpic -static -Wall \
-o ./test_vecpf_static \
../libvecpf/test_vecpf.c \
-Wl,-u,__libvecpf_init ./libvecpf.a
Using the additional printf length modifiers defined by this library in a
program will cause the GCC compiler to complain in the following manner
when compiled with -Wall:
warning: unknown conversion type character ‘v’ in format
This warning can be supressed with -Wno-format. Only suppress warnings
with care.
For further information on how to use the facilities provided by Libvecpf
please read the man page, libvecpf.3.
---------------------------------------------------------------------------
8. Contributing
We ask that you contribute modifications back to the community as a
gesture of goodwill under the specifics of the LGPL v2.1 license.
In order to contribute as an individual please fill out the ICLA.txt file,
sign, date, scan, and email to the maintainer.
In order to contribute as a corporate entity please fill out the CCLA.txt
file, sign, date, scan, and email to the maintainer.
Individual contributions should use the signed-off method as indicated in
the CONTRIBUTORS file.
---------------------------------------------------------------------------
A. History
- Libvecpf was originally written and packaged by Michael Brutman
<brutman@us.ibm.com>
- It was updated for breadth and packaged for community consumption by
Ryan S. Arnold <rsa@linux.vnet.ibm.com>