Deploying applications with Intel® IPP DLLs

Deploying applications with Intel® IPP DLLs



Step 1 – Overview

When deploying an application built with Intel® Integrated Performance Primitives (Intel® IPP) dynamic-link libraries (DLLs), it is important to understand processor detection and library dispatching, so that software redistribution is problem free. Additionally, two key factors to consider are:

  • Selection of an appropriate DLL linking model
  • The location for the DLLs on the target system

This document explains how the Intel IPP dynamic libraries work and discusses these important considerations.

For information on all Intel IPP linking models, please refer to the document Intel IPP Linkage Models – Quick Reference Guide.

Version Information
This document applies to Intel IPP 6.x for Windows* running 32-bit and Intel® 64 applications.


Note: Please verify that your license permits redistribution before distributing the Intel IPP DLLs. C

For new IPP version, please see New Directory Structure and Library Naming Scheme for Intel® IPP 7.0 Library. and IPP is key component of Intel Parallel Studio. The IPP libraries of Parallel Studio are in redist directory

heck the Intel IPP website for information on obtaining a commercial license.



Step 2 – Key Concepts

Library Dispatcher
Every Intel IPP function has many binary implementations, each performance-optimized for a specific target CPU. These processor-specific functions are contained in separate DLLs. The name of each DLL has a prefix identification code that denotes its target processor and the Intel IPP version. For example, the 32-bit Intel® Core™2 signal processing library is named ippsv8-6.x.dll, where v8 is the CPU identification code and 6.x refers to Intel IPP version 6.x.

Table 1: CPU Identification Codes Associated with Processor-Specific Libraries

32-bit ID 64-bit ID Meaning
px mx C-optimized for 32-bit and Intel® 64 based processors respectively
w7 - Optimized for Pentium® 4 processors
t7 m7 Optimized for Pentium® 4 processors with Streaming SIMD Extensions 3
v8 u8 Optimized for Intel® Core™2 and Intel® Xeon® 5100 processors
p8 y8 Optimized for 45nm Intel® Core™2 Duo (Penryn) family processors


When the first Intel IPP function call occurs in the application, the application searches the system path for an Intel IPP dispatcher library. The dispatcher library identifies the system processor and invokes the function version that has the best performance on the target CPU. This process does not add overhead because the dispatcher connects to an entry point of an optimized function only once during application initialization. This allows your code to call optimized functions without worrying about the processor on which the code will execute.

Dynamic Linking
Dynamic-link libraries are loaded when an application runs. Simply link the application to the Intel IPP libraries located in the stublib folder, which load the dispatcher libraries and link to the correct entry points. Ensure that the dispatcher DLLs and the processor-specific DLLs are on the system path. In the diagram below, the application links to stublib\ipps.lib and ipps.dll automatically loads ippsv8-6.x.dll at runtime.

Processor-Specific Dispatching

diag1.bmp

Dynamic linking is useful if many Intel IPP functions are called in the application. Most applications are good candidates for this model.

Building a Custom DLL
In addition to dynamic linking, the Intel IPP provides a tool for developers to create their own DLL. This tool links selected Intel IPP functions into a new separate DLL and generates an import library to which the application can link. A custom DLL is useful if the application uses a limited set of functions. The custom DLL must be distributed with the application.

Threading and Multi-core Support
Intel IPP supports multi-threading in the dynamic libraries, which gives significant performance gain on multi-processor and multi-core systems. Threading is implemented with OpenMP* and requires libiomp5md.dll. For version 5.3 and later, a list of threaded functions is provided in the file doc\ThreadedFunctionsList.txt. For versions 5.0, 5.1 and 5.2, the threaded function lists are available online. All functions are thread-safe.

Choosing a Linking Model
Intel IPP supports two dynamic linking options. Refer to Table 2 below to choose which dynamic linking model best suits the application.

Table 2: Dynamic Linking Models

Feature Dynamic Linking Custom DLL
Processor Updates Automatic Recompile and redistribute
Optimization All processors All processors
Build Link to stub static libraries Build and link to a separate import library which dispatches a separate DLL
Function Naming Regular names Regular names
Total Binary Size Large Small
Executable Size Smallest Smallest
Kernel Mode No No
Multi-threading Yes Possible



Step 3 – Linking the Application

The Intel IPP can be compiled with Microsoft Visual C++* 2005,  Microsoft Visual C++* 2008 and Intel® C++ Compiler 10.0 or later. Instructions for configuring Microsoft Visual Studio to link to the Intel IPP libraries are below. These instructions require that you know the location of Intel IPP files on the development system. The default locations for the Intel IPP header files, dispatching stub libraries and dynamic libraries are listed in Table 3.

Table 3: Default File Locations

File Type 32-bit Default Location Intel® 64 Default Location
Header files C:\Program Files\Intel\IPP\6.x\ia32\include C:\Program Files\Intel\IPP\6.x\em64t\include
Dispatcher stub libraries C:\Program Files\Intel\IPP\6.x\ia32\stublib C:\Program Files\Intel\IPP\6.x\em64t\stublib
Dynamic libraries C:\Program Files\Intel\IPP\6.x\ia32\bin C:\Program Files\Intel\IPP\6.x\em64t\bin


Dynamic Linking

To link to the 32-bit and Intel® 64 dynamic libraries using the Microsoft* Visual Studio* 2008 environment, please refer to the document Calling Intel® IPP in Microsoft Visual C++ 2008.

To link to the 32-bit and Intel® 64 dynamic libraries using the Microsoft* Visual Studio* 2005 environment, perform the following steps:

  1. Include ipp.h in the source code.
  2. Select View » Solution Explorer and make sure this window is active.
  3. If you are using the Microsoft* compiler, Select Tools » Options » Projects and Solutions » VC++ Directories.
    • In the drop down menu titled Show directories for: select Include Files and type in the directory for the Intel IPP header files.
    • In the drop down menu titled Show directories for: select Library Files and type in the directory for the Intel IPP dispatching stub libraries.
    • In the drop down menu titled Show directories for: select Executable Files and type in the directory for the Intel IPP dynamic libraries.

    vs1.gif

  4. If you are using Intel® C++ Compiler 10.0, select Tools » Options » Intel® C++ » Directories.
    • Type in the directory for the Intel IPP header files in the Includes field.
    • Type in the directory for the Intel IPP dispatching stub libraries in the Libraries field.
    • Type in the directory for the Intel IPP dynamic libraries in the Executables field.

    vs2.gif

  5. Click OK to apply the settings and exit the window.
  6. On the main toolbar select Project » Properties » Configuration Properties » Linker » Input and in the Additional Dependencies line, add the libraries you require (e.g. ipps.lib or ippsem64t.lib). Please refer to the document Library Dependencies by Domain to determine which libraries to link to the application.
  7. Click OK to apply the settings and exit the window.

vs3.gif

Custom DLL
To build and link to a custom DLL, download and unzip the Intel IPP sample code package for Windows. Change to folder ipp-samples\advanced-usage\linkage\customdll and follow the instructions contained in the file readme.htm.


Step 4 – Deploying the Application

The Intel IPP dispatcher and processor-specific DLLs, located in ia32\bin or em64t\bin, or a custom DLL must be distributed with the application software. The Intel IPP core functions library, ippcore-6.x.dll, and the threading dynamic link library, libiomp5md.dll, must also be distributed.

When distributing a custom DLL, it is best to create a distinct naming scheme to avoid conflicts and for tracking purposes. This is also important because custom DLLs must be recompiled and redistributed to include new processor optimizations not available in previous Intel IPP versions.

On Microsoft Windows*, the system PATH variable is a list of folder locations that is searched for executable files. When the application is invoked, the Intel IPP DLLs need to be located in a folder that is listed in the PATH variable. Choose a location for the Intel IPP DLLs or custom DLL on the target system so that the application can easily detect them. Possible distribution locations include WINDOWS\system32, the application folder or any other folder on the target system. The table below compares these options.

Table 4: Intel IPP DLL Location

System PATH Permissions Threading Library
WINDOWS\system32 This folder is listed on the system PATH by default. Administrator permissions may be required to copy files to this folder. If other applications copy the threading library to this folder, it can cause a possible conflict.
Application Folder or Subfolder Windows will first check the application folder for the DLLs. Special permissions may be required. No conflicts.
Other Folder Add this directory to the system PATH. Special permissions may be required. Possible conflict.


In all cases, the application must be able to find the location of the Intel IPP DLLs or custom DLL in order to run properly.

The Intel IPP provides a convenient method to performance optimize a 32-bit or Intel 64 application for the latest processors. Application and DLL distribution requires developers to do the following:

  1. Choose the appropriate DLL linking model.
    • Dynamic linking – the application is linked to stub libraries. At runtime, dispatcher DLLs detect the target processor and dispatch processor-specific DLLs. Dispatcher and processor-specific DLLs are distributed with the application.
    • Custom DLL – the application is linked to a custom import library. At runtime, the custom DLL is invoked. The custom DLL is distributed with the application.
  2. Determine the best location for the Intel IPP DLLs on the end–user system.
    • WINDOWS\system32
    • Application folder or subfolder
    • Other folder


Appendix A - Verifying Correctness

Intel IPP demo software or sample code programs can be used to test DLL redistribution:

  • Two test applications are provided in the demo folder.
  • Intel IPP samples also can be used to test deployments.

Errors may occur if the DLLs are not found by the Windows* application. These errors are summarized in the table below.

Table 5: Common Error Messages

Issue Error message
The core library is not found by the application. “The application has failed to start because ippcore-6.x.dll was not found. Re-installing the application may fix this problem.”
The dispatcher DLL or custom DLL is not found by the application. “The application has failed to start because ipps-6.x.dll was not found. Re-installing the application may fix this problem.”
The threading library is not found by the application. “The application has failed to start because libiomp5md.dll was not found. Re-installing the application may fix this problem.”
No processor-specific DLLs were found by the application. “No DLLs were found in the Waterfall procedure”



Appendix B - Known Issues and Limitations

  • Intel IPP DLL names changed since version 5.1 to include the Intel IPP version e.g. ippst7-5.1.dll.
  • When faced with multiple versions of the threading library from different Intel® Software Development products, choose the most recent version to redistribute with the application.
  • The use of the Intel IPP Runtime Installer (RTI) is deprecated. Intel IPP versions 6.x and later do not include the RTI utility.


Appendix C - References

Optimization Notice in English

For more complete information about compiler optimizations, see our Optimization Notice.

Comments

's picture

This article uses libguide40.dll as OMP library rather than libiomp5md. This seems to be inaccurate since IIPP 6.x is build with libiomp5md instead of libguide40.

More over in Intel's forum http://software.intel.com/en-us/forums/intel-integrated-performance-primitives/topic/62001/ is clearly specified that IIPP 6.x cannot be used in conjunction with another library that loads libguide40 (this case OpenCV but is the same problem with MEX libraries for Matlab 2008a).

I think a clarification about this issue would be welcome.

's picture

I want to evaluate Intel IPP v 6.1

AmandaS (Intel)'s picture

You can download a free 30 day evaluation version of any Intel® Software Development Product at:
http://software.intel.com/en-us/articles/intel-software-evaluation-center/

Allan Bennett-brown's picture

This article says "This document applies to Intel IPP 6.x for Windows* running 32-bit and Intel® 64 applications." Can you please provide a link to the corresponding or updated article that applies to IPP 7.x for Windows. Thank-you.

opavlyshak's picture

Is there an article describing this for Intel IPP 7.x and Visual Studio 2010?

suresh k.'s picture

i am getting ipps-6.1.dll error at redistribution time please let me know how can i remove it

Waiting for your valuable response

Thanks and Regards
Suresh Kansujiya