# Intel® Integrated Performance Primitives Custom Static Library Dispatcher Example

# 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 sample, 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 2nd 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

- A system equipped with Intel® Xeon Phi™ Coprocessor to run Multi-threading Example for Intel® Xeon Phi™ Coprocessor

Software requirements:

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

Product specific requirements:

- Intel® Threading Building Blocks (Intel® TBB) installed as part of Intel® Parallel Studio XE Composer Edition, or installed from Intel® TBB Open Source site

- Intel® C++ Composer XE, Intel® Parallel Studio XE and Intel® Manycore Platform Software Stack (Intel® MPSS) 3.2.3 or higher on systems equipped with Intel® Xeon Phi™ coprocessor for the manycore-specific example

- Intel® MPSS version 4.2 or higher for Intel® Xeon Phi™ processor x200 product family programming

For more information please see Intel® IPP System Requirements.

# Overview

Intel® Integrated Performance Primitives (Intel® IPP) provides the cdispatch.pl example, which demonstrates how to build the custom static library dispatcher (regardless of the operating system type).

The custom dispatcher for static libraries makes sense in case of strict requirements to the binary/application size. The table below shows the size in megabytes of each CPU-specific part of the Intel® IPP image processing (IP) merged static library. As you can see from the table, for IA-32 architecture the Intel® IPP library supports 6 different CPU generations, while for Intel® 64 architecture - 8. If your application does not need to support all CPUs listed in this table and the application size is critical, you can use the provided example and save ~10-15% of linked library size with each CPU that is removed from the dispatching path.

The size in megabytes for Intel® IPP IP domain static libraries depending on the target:

IA-32 | Size | Intel® 64 | Size | Target Instruction Set | Target CPU Model
--- | --- | --- | --- | --- | ---
W7 | 8.8 |  | 10.0 | Intel® Streaming SIMD Extensions 2 (Intel® SSE2) | Intel® Pentium® 4
|  | M7 | 11.0 | Intel® SSE3 | Intel® Pentium® 4E (Intel® microarchitecture code name Prescott)
S8 | 10.0 | N8 | 13.0 | Supplemential Streaming SIMD Extensions 3 (SSSE3) | Intel® Atom™ (Intel® microarchitecture code name Silverthorne & Intel® microarchitecture code name Merom)
P8 | 11.0 | Y8 | 13.0 | Intel® SSE4.2 | Intel® Atom™ (Intel® microarchitecture code name Silvermont & Intel® microarchitecture code name Nehalem)
G9 | 12.0 | E9 | 15.0 | Intel® Advanced Vector Extensions (Intel® AVX) | Intel® microarchitecture code name Sandy Bridge
H9 | 12.0 | L9 | 15.0 | Intel® Advanced Vector Extensions 2 (Intel® AVX2) | Intel® microarchitecture code name Haswell
|  | N0 | 16.0 | Intel® Advanced Vector Extensions 512 (Intel® AVX512) - AVX512F | Intel® Xeon® Phi™ (Intel® microarchitecture code name Knights Landing)
|  | K0 | 14.0 | Intel® AVX512 - AVX512BW | Intel® Xeon® (Intel® microarchitecture code name Skylake)

## Using Custom Static Library Dispatcher

### Prerequisites

To use the custom static library dispatcher, you need to have Perl installed on your system. There are no specific requirements to Perl version and you can use any version from https://www.perl.org/get.html.

### Example Structure

The Intel® IPP custom static library dispatcher example consists only of one Perl script cdispatch.pl.

### Building Custom Static Library Dispatcher

To build the Intel® IPP custom static library dispatcher run the cdispatch.pl script with proper command line options

    perl cdispatch.pl -L <set of x64 libs> -l <set of ia32 libs> -s <ipp header> -o <output dir> [-h]

where:

- -L <set of x64 libs> defines the exact list of Intel® 64 CPUs that must be supported by this custom dispatcher. This set of CPUs can be any combination of m7, n8, y8, e9, l9, n0, k0.

Note | Dispatching requires at least two CPUs.

- -l <set of ia32 libs> defines the exact list of IA-32 CPUs that must be supported by this custom dispatcher. This set of CPUs can be any combination of w7, s8, p8, g9, h9.

Note | Dispatching requires at least two CPUs.

- -s <ipp header> points to path to the header file of the Intel® IPP domain for which you are going to create the custom dispatching scheme

- -o <output dir> points to path to the folder, where the script should store all generated files required for the custom dispatcher

- -h provides a short help message similar to the description above

Examples:

- Generating the dispatcher (C-files with dispatcher function implementation) for 2 IA-32 CPUs (w7 and p8) for the Intel® IPP crypto domain:

    perl cdispatch.pl -l w7,p8 -s ippcp.h -o .\

- Generating the dispatcher for all optimizations for IA-32 and Intel® 64 for ippCP.h from local Intel® IPP copy into c:\tmp\dispatch folder:

    perl cdispatch.pl -L m7,n8,y8,e9,l9,n0,k0 -l w7,s8,p8,g9,h9 \
            -s C:\ipp201701gold_crypto_os\include\ippcp.h -o c:\tmp\dispatch

## Building Application with Generated Files

The script generates a number of C-files - one for each function declared in the specified header. Additionally, for the domain you use the scipt create a new header file with the d suffix at the end of file name, for example, ippcpd.h.

Before building the project you should

- Replace all #include <ippxx.h> statements in your application sources with #include <ippxxd.h>

- Add ippxxd.h and all generated C-files to your project

After your project is built, you can see that the size of your binary is decreased and you have an ability to debug custom dispatching mechanism.

# 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/.