# Intel® Integrated Performance Primitives Examples

# Disclaimer

## Legal Information

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.
A "Mission Critical Application" is any application in which failure of the Intel Product could result, directly or indirectly, in personal injury or death. SHOULD YOU PURCHASE OR USE INTEL'S PRODUCTS FOR ANY SUCH MISSION CRITICAL APPLICATION, YOU SHALL INDEMNIFY AND HOLD INTEL AND ITS SUBSIDIARIES, SUBCONTRACTORS AND AFFILIATES, AND THE DIRECTORS, OFFICERS, AND EMPLOYEES OF EACH, HARMLESS AGAINST ALL CLAIMS COSTS, DAMAGES, AND EXPENSES AND REASONABLE ATTORNEYS' FEES ARISING OUT OF, DIRECTLY OR INDIRECTLY, ANY CLAIM OF PRODUCT LIABILITY, PERSONAL INJURY, OR DEATH ARISING IN ANY WAY OUT OF SUCH MISSION CRITICAL APPLICATION, WHETHER OR NOT INTEL OR ITS SUBCONTRACTOR WAS NEGLIGENT IN THE DESIGN, MANUFACTURE, OR WARNING OF THE INTEL PRODUCT OR ANY OF ITS PARTS.

Intel may make changes to specifications and product descriptions at any time, without notice. Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined." Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. The information here is subject to change without notice. Do not finalize a design with this information.
The products described in this document may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request.
Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order.
Copies of documents which have an order number and are referenced in this document, or other Intel literature, may be obtained by calling 1-800-548-4725, or go to: http://www.intel.com/design/literature.htm

Intel processor numbers are not a measure of performance. Processor numbers differentiate features within each processor family, not across different processor families. Go to: http://www.intel.com/products/processor_number/

BlueMoon, BunnyPeople, Celeron, Celeron Inside, Centrino, Centrino Inside, Core Inside, i960, Intel, the Intel logo, Intel Atom, Intel Atom Inside, Intel Core, Intel Inside, Intel Inside logo, Intel NetBurst, Intel NetMerge, Intel NetStructure, Intel SingleDriver, Intel SpeedStep, Intel Sponsors of Tomorrow., the Intel Sponsors of Tomorrow. logo, Intel StrataFlash, Intel Viiv, Intel vPro, Intel XScale, InTru, the InTru logo, InTru soundmark, Itanium, Itanium Inside, MCS, MMX, Moblin, Pentium, Pentium Inside, skoool, the skoool logo, Sound Mark, The Journey Inside, vPro Inside, VTune, Xeon, and Xeon Inside are trademarks of Intel Corporation in the U.S. and other countries.
* Other names and brands may be claimed as the property of others.

Microsoft, Windows, Visual Studio, Visual C++, and the Windows logo are trademarks, or registered trademarks of Microsoft Corporation in the United States and/or other countries.

Java is a registered trademark of Oracle and/or its affiliates.

©Intel Corporation. All rights reserved.

Optimization Notice
Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice. Notice revision #20110804

# License Definitions

By downloading and installing this product, you hereby agree that the accompanying materials are being provided to you under the terms and conditions of the End User License Agreement for the Intel® Integrated Performance Primitives (Intel® IPP) product previously accepted by you.

# System Requirements

Recommended hardware:

- A system based on 4th Generation Intel® Core™ i3, i5, i7 or newer processor

Hardware requirements:

- A system based on Intel® Pentium® processor, Intel® Xeon® processor, or subsequent IA-32 architecture based system;

- A system based on a processor with Intel® 64 architecture.

Software requirements:

- For the basic system requirements on operating system, Intel® IPP library, IDE and compiler, refer to the corresponding Release Notes document.

For more information please see Intel® IPP System Requirements.

# How to Build Bzip2 with Intel® Integrated Performance Primitives Library

The data compression domain of the Intel® IPP library contains several functions that can speed up the well-known Bzip2 library (https://www.sourceware.org/bzip2) in both data compression and decompression operations. For the detailed description of these functions, refer to the Volume 1: "Signal Processing/Data Compression Functions/BWT-Based Compression Functions" section of the Intel® IPP Developer Reference.

To use these functions, before building the library you need to replace the original source code of several Bzip2 functions with Intel® IPP functions calls.

This document provides instructions on how to prepare the Bzip2 source code and build the library.

## Downloading, Patching and Build on Linux* and macOS*

### Downloading Bzip2 Source Code

Before building the library, you need to download Bzip2 source code files from the Bzip2 site (https://sourceware.org/pub/bzip2/).

Download the Bzip2 v.1.0.x tar file from the specified address to a working directory. Current supported versions are 1.0.6 (https://sourceware.org/pub/bzip2/bzip2-1.0.6.tar.gz) and 1.0.8 (https://sourceware.org/pub/bzip2/bzip2-1.0.8.tar.gz). Unpack the downloaded archive with the following command on Linux*/macOS* systems.

    $ tar xf bzip2-1.0.6.tar.gz

or

    $ tar xf bzip2-1.0.8.tar.gz

This command will create the `bzip2-1.0.6` or `bzip2-1.0.8` folder in your working directory.

### Patching the Source Code

1. Change directory to the `bzip2-1.0.6` or `bzip2-1.0.8`

2. Apply the corresponding source code patch file `bzip2-1.0.6.patch.bin` (`bzip2-1.0.8.patch.bin`) from Intel® IPP product distribution with the following command.

    $ cd bzip2-1.0.6
    $ patch -p1 < "path to corresponding patch file"

or

    $ cd bzip2-1.0.8
    $ patch -p1 < "path to corresponding patch file"

For example, if patch file is located in your working directory do the following

    $ cd bzip2-1.0.8
    $ patch -p1 < ../bzip2-1.0.8.patch.bin

If the patching process completed successfully, you will see the following messages:

    patching file bzlib.c
    patching file Makefile
    patching file Makefile-libbz2_so
    patching file makefile.msc

### Configuring and Building Bzip2 Library

After Bzip2 source code files are patched successfully, you need to build the library. Basically, you need to

- Add the `WITH_IPP` definition to compiler command line

- Add the `$IPPROOT/include` directory to the list of header files search for compiler

- Add Intel® IPP libraries to the list of `ld` input files.

#### Build Libbz2 Static Library

On Linux* OS, you can implement the above steps with the standard Bzip2 `make` command and the following (64-bit build):

    # Build static Bzip2 library with static Intel(R) IPP linkage on Linux*
    $ export CFLAGS="-m64 -DWITH_IPP -I$IPPROOT/include"
    $ export IPP_LDFLAGS="$IPPROOT/lib/intel64/libippdc.a $IPPROOT/lib/intel64/libipps.a $IPPROOT/lib/intel64/libippcore.a"
    $ make

or 32-bit build process:

    # Build static Bzip2 library with static Intel(R) IPP linkage on Linux*
    $ export CFLAGS="-m32 -DWITH_IPP -I$IPPROOT/include"
    $ export IPP_LDFLAGS="$IPPROOT/lib/ia32/libippdc.a $IPPROOT/lib/ia32/libipps.a $IPPROOT/lib/ia32/libippcore.a"
    $ make

On macOS*, there is no separation between 32- and 64-bit libraries, and you don’t need to specify different set of libraries for different architectures. Use the following commands (32-bit example):

    # Build static Bzip2 library with static Intel(R) IPP linkage on macOS*
    $ export CFLAGS="-m32 -DWITH_IPP -I$IPPROOT/include"
    $ export IPP_LDFLAGS="$IPPROOT/lib/libippdc.a $IPPROOT/lib/libipps.a $IPPROOT/lib/libippcore.a"
    $ make

Here, the `-m32` option specifies IA-32 target CPU architecture. For Intel® 64 architecture the compiler option should be `-m64`.

The above commands assume that `IPPROOT` environment variable points to head of Intel® IPP location.

The best way is to set up Intel® software tools environment using the environment setup file. You can find how to do that in Get Started with Intel® IPP document.

Note | The conditional compilation statements, used for Bzip2 source code files modification, allow to build original version of Bzip2 from the same source code files. For that, you need to build Bzip2 library without modification of `CFLAGS` and `IPP_LDFLAGS`. If `WITH_IPP` definition doesn’t exist in compiler options, Bzip2 source code files are compiled (and, then build) as unpatched.

#### Build Libbz2 Dynamic Library

In Bzip2 source code package the dynamic library is built with a separate make file `Makefile-libbz2_so`. The commands to invoke this make files are:

    $ export CFLAGS="-m32 -DWITH_IPP -I$IPPROOT/include"
    $ export IPP_LDFLAGS="$IPPROOT/lib/ia32/libippdc.a $IPPROOT/lib/ia32/libipps.a $IPPROOT/lib/ia32/libippcore.a"
    $ make -f Makefile-libbz2_so

Note | This makefile is Linux*-specific and doesn’t work for macOS*

### Static and Dynamic Linking to Intel® IPP Libraries

When building the `libbz2` dynamic shared object, you can use either static or dynamic linking to Intel® IPP libraries. Different linking modes have their advantages and disadvantages. For example, static linking to Intel® IPP provides target object (`libbz2.so`, or `libbz2.dylib` in our case) independence from environment, easy transfer from one computer to another. On the other hand, statically linked object has bigger size and can’t benefit from newer (updated) version of Intel® IPP without re-linking.

The `libbz2` dynamic libraries, linked statically with Intel® IPP, are self-sufficient. It means that when you build an application using these libraries, you don’t need to add Intel® IPP libraries to the linker command line (unless your application uses Intel® IPP apart from `libbz2`). All references to Intel® IPP functions are already resolved within Bzip2 dynamic library, and this library doesn’t need anything extra from Intel® IPP.

#### Build Bzip2 with Static Linking to Intel® IPP

On Linux* OS, when the below linker flags are specified by the `IPP_LDFLAGS` environment variable, Bzip2 is linked to Intel® IPP libraries (.a files) statically:

    $ export IPP_LDFLAGS="$IPPROOT/lib/intel64/libippdc.a $IPPROOT/lib/intel64/libipps.a \
                      $IPPROOT/lib/intel64/libippcore.a"

You can check the independence of the resulting dynamic library `libbz2.so` from Intel® IPP libraries with the "ldd" tool.

For example,

    $ ldd libbz2.so
            linux-vdso.so.1 =>  (0x00007fffa8491000)
            libc.so.6 => /lib64/libc.so.6 (0x00007f081b2d3000)
            /lib64/ld-linux-x86-64.so.2 (0x00007f081b958000)

You can see that the `libbz2.so` dynamic library depends on system dynamic libraries only. The size of the resulting `libbz2` library in this case will be more than 800 KBytes because it contains optimizations for all CPUs supported by Intel® IPP.

You can use the following command to build an application with such kind of library:

    $ cc -o bzip2_test -Ibzip2/include bzip2_test.c -L. -lbz2

Here, `bzip2/include` is a directory where Bzip2 header files reside. "-L." means that Linux* linker will be searching next libraries in the current directory, "-lbz2" means that the linker will look for the `libbz2.so` file (shared linking is default method on most Linux* systems).

To run built application on Linux* system, you need to modify the `LD_LIBRARY_PATH` environment variable, which describes the search path for dynamic libraries:

    $ export LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH
    $ ./bzip2_test

There is no written method to build Bzip2 dynamic library on macOS*, but the basic rules are the same:

- Compile library source code files for position-independent code;

- Link library dynamic object file to either static or dynamic Intel® IPP library files.

#### Building Bzip2 with Dynamic Linking to Intel® IPP

Sometimes, you may want to build `libbz2` dynamic library linked dynamically to Intel® IPP libraries. This is, for example, if you know that `libbz2` will be used on a computer with pre-installed and properly set dynamic Intel® IPP libraries. Or, you may want to minimize file size of `libbz2` dynamic library, or, to decrease the total amount of RAM size required for several application(s) which use `libbz2`.

In this case, the following set of commands will build the `libbz2.so` library with dynamic linking to the Intel® IPP libraries (64-bit example).

    $ <configure Intel(R) IPP environment>
    $ export CFLAGS="-m64 -DWITH_IPP -I$IPPROOT/include"
    $ export IPP_LDFLAGS="-L$IPPROOT/lib/intel64 -lippdc -lipps -lippcore"
    $ make -f Makefile-libbz2_so

To check how `libbz2.so` is built:

    -bash-4.2$ ldd libbz2.so.1.0
            linux-vdso.so.1 =>  (0x00007fffad90f000)
            libippdc.so => $IPPROOT/lib/intel64/libippdc.so (0x00007f6f95b33000)
            libipps.so => $IPPROOT/lib/intel64/libipps.so (0x00007f6f958ed000)
            libippcore.so => $IPPROOT/lib/intel64/libippcore.so (0x00007f6f956e1000)
            libc.so.6 => /lib64/libc.so.6 (0x00007f6f952f4000)
            libdl.so.2 => /lib64/libdl.so.2 (0x00007f6f950f0000)
            libm.so.6 => /lib64/libm.so.6 (0x00007f6f94dee000)
            /lib64/ld-linux-x86-64.so.2 (0x00007f6f95f4c000)

On your computer, the actual library name and address can be different. The above "ldd" output shows that the `libbz2.so` shared object is built dynamically with Intel® IPP `libippdc.so`, `libipps.so` and `libippcore.so` dynamic libraries.

On a target computer, before the `libbz2` library is used, you need to properly set paths to Intel® IPP dynamic libraries. On Linux* OS, do this by modifying the `LD_LIBRARY_PATH` environment variable. On macOS*, modify `DYLD_LIBRARY_PATH`. If you set up your Intel® IPP working environment according to Get Started with Intel® IPP document, these environment variables are set automatically.

## Downloading, Patching, and Build on Windows*

To download Bzip2 source code files for Windows*, you can use the same URL addresses as for Linux*. However, the patching and building processes on Windows* are different.

### Unpacking Zlib Tarball

To get the Bzip2 source code files on Windows* computer, you need to:

- Download the `.tar.gz` file from https://sourceforge.net/projects/bzip2.

- Unpack the archive using any of available tar tools for Windows*. For example

  - `7-zip` from http://www.7-zip.org/.

### Patching Original Bzip2 Files

There are no standard system tools for patching on Windows*, so you need to use 3-rd party tools. For example, http://gnuwin32.sourceforge.net/packages/patch.htm from Free Software Foundation.

With this tool you need to use the following command line options:

    > patch.exe -p1 --binary < <patch file location>\bzip2-1.0.6.patch.bin

or

    > patch.exe -p1 --binary < <patch file location>\bzip2-1.0.8.patch.bin

Example of output is below:

    > 7z.exe x bzip2-latest.tar.gz
    > 7z.exe x bzip2-1.0.8.tar
    > cd bzip2-1.0.8
    > patch.exe -p1 --binary < ..\bzip2-1.0.8.patch.bin
    patching file bzlib.c
    patching file Makefile
    patching file Makefile-libbz2_so
    patching file makefile.msc

### Building Bzip2 With Intel® IPP on Windows*

To build Bzip2 on Windows*, use the "nmake" file `makefile.msc` from `bzip2-1.0.6` or `bzip2-1.0.6` directory. To do that, start Microsoft* Visual Studio* command-line window that corresponds to a target application architecture (IA-32 or Intel® 64) and execute the following command from the root of Bzip2 source code tree (below are 64-bit examples).

Static linking:

    <configure Intel(R) IPP environment>
    set LIBP=%IPPROOT%\lib\intel64
    nmake -f makefile.msc CC="cl -DWITH_IPP -I""%IPPROOT%\include"""^
     IPP_LDFLAGS="/link /libpath:""%LIBP%"" ippdcmt.lib ippsmt.lib ippcoremt.lib"

Dynamic linking:

    <configure Intel(R) IPP environment>
    set LIBP=%IPPROOT%\lib\intel64
    nmake -f makefile.msc CC="cl -DWITH_IPP -I""%IPPROOT%\include"""^
     IPP_LDFLAGS="/link /libpath:""%LIBP%"" ippdc.lib ipps.lib ippcore.lib"

In the first case the "nmake" creates the `libbz2.lib`, `bzip2.exe` and `bzip2recover.exe` not depending on dynamic Intel® IPP libraries. In the second, `bzip2.exe` and `bzip2recover.exe` executable files depend on `ippdc.dll`, `ipps.dll` and `ippcore.dll` from Intel® IPP distribution package.

### Testing of Bzip2 with Intel® IPP

The final part of all make files in Bzip2 is the corresponding binary files testing. The testing is based on execution of `bzip2.exe` tool with different compression options to generate compressed files, decompress them with different file names and to compare compressed and decompressed data.

In modified `makefile.msc` the comparison of compressed data `bz2` and `rb2` files disabled because Bzip2 library with Intel® IPP functions generate different compressed data. It is fully compatible with Bzip2 format, but is not "bit-by-bit" equal to original library. Thus, this method of comparison won’t work.

The remaining comparison of reference data (`ref` files) and decompressed data (`tst` files) should show no differences.

# Technical Support

If you did not register your Intel® software product during installation, please do so now at the Intel® Software Development Products Registration Center. Registration entitles you to free technical support, product updates and upgrades for the duration of the support term.

For general information about Intel technical support, product updates, user forums, FAQs, tips and tricks, and other support questions, please visit (http://www.intel.com/software/products/support).

Note | If your distributor provides technical support for this product, please contact them rather than Intel.

For technical information about the Intel® IPP library, including FAQ’s, tips and tricks, and other support information, please visit the Intel® IPP forum: (http://software.intel.com/en-us/forums/intel-integrated-performance-primitives) and browse the Intel® IPP support page: https://software.intel.com/en-us/intel-ipp-support/.