Intel® Integrated Performance Primitives Developer Reference

Developer Reference

  • 2021
  • 03/26/2021
  • Public Content
Contents

SetCpuFeatures

Sets the processor-specific library code for the specified processor features.

Syntax

IppStatus ippSetCpuFeatures(Ipp64u
cpuFeatures
);
Include Files
ippcore.h
Parameters
cpuFeatures
Features to be supported by the library. Refer to
ippdefs.h
 for
ippCPUID_xx
 definition.
Description
This function sets the processor-specific code of the Intel IPP library according to the processor features specified in
cpuFeatures
. You can use the following predefined sets of features (the
FM
 suffix below means
feature mask
):
32-bit code:
#define PX_FM ( ippCPUID_MMX | ippCPUID_SSE )
#define W7_FM ( PX_FM | ippCPUID_SSE2 )
#define V8_FM ( W7_FM | ippCPUID_SSE3 | ippCPUID_SSSE3 )
#define S8_FM ( V8_FM | ippCPUID_MOVBE )
#define P8_FM ( V8_FM | ippCPUID_SSE41 | ippCPUID_SSE42 )
#define G9_FM ( P8_FM | ippCPUID_AVX | ippAVX_ENABLEDBYOS | ippCPUID_F16C )
#define H9_FM ( G9_FM | ippCPUID_AVX2 | ippCPUID_MOVBE | ippCPUID_PREFETCHW )
64-bit code:
#define PX_FM ( ippCPUID_MMX | ippCPUID_SSE | ippCPUID_SSE2 )
#define M7_FM ( PX_FM | ippCPUID_SSE3 )
#define U8_FM ( M7_FM | ippCPUID_SSSE3 )
#define N8_FM ( U8_FM | ippCPUID_MOVBE )
#define Y8_FM ( U8_FM | ippCPUID_SSE41 | ippCPUID_SSE42 )
#define E9_FM ( Y8_FM | ippCPUID_AVX | ippAVX_ENABLEDBYOS | ippCPUID_F16C )
#define L9_FM ( E9_FM | ippCPUID_MOVBE | ippCPUID_AVX2 | ippCPUID_PREFETCHW )
#define N0_FM ( L9_FM | ippCPUID_AVX512F | ippCPUID_AVX512CD | ippCPUID_AVX512PF | ippCPUID_AVX512ER | ippAVX512_ENABLEDBYOS )
#define K0_FM ( L9_FM | ippCPUID_AVX512F | ippCPUID_AVX512CD | ippCPUID_AVX512VL | ippCPUID_AVX512BW | ippCPUID_AVX512DQ | ippAVX512_ENABLEDBYOS )
Do not use any other Intel IPP function while
ippSetCpuFeatures
 is executing. Otherwise, your application behavior is undefined.
To avoid initialization of internal structures for one Intel® architecture and then call of the processing function that is optimized for another architecture, do not use the
ippSetCpuFeatures
 function in chains of Intel IPP connected calls like
<processing function
GetSize
 +
<processing function
Init
 +
<processing function>
. Otherwise, Intel IPP functionality behavior is undefined.
Intel IPP library supports two internal sets of CPU features:
  • Real CPU features
    : the features that are supported by the CPU at which the library is executed. These features are read-only and can be obtained with the
    ippGetCpuFeatures
     function.
  • Enabled features
    : the features that are enabled externally to Intel IPP by the application. These features are read-write and can be obtained with ippGetEnabledCpuFeatures
    and set with
    ippSetCpuFeatures
    .
The
ippSetCpuFeatures
 function provides additional flexibility in measuring performance improvements reached by using specific CPU features. For example, the call of the
ippInit()
 (or the first call of any Intel IPP function for the library version starting with 9.0) function in an application running on the 4th Generation Intel® Core™ i7 processor with 64-bit OS installed dispatches the L9 code version optimized for Intel® Advanced Vector Extensions 2 (Intel® AVX2) with several other features like fast 16-bit floating point support. To check performance improvement for all Intel IPP functionality reached by using Intel® AVX2, you can run a benchmark for the currently dispatched version of code and then compare performance with the Intel® Advanced Vector Extensions (Intel® AVX) version of code with Intel® AVX2 disabled. To disable Intel AVX2, call
ippSetCpuFeatures(E9_FM)
. To enable Intel AVX2 back, call
ippSetCpuFeatures( L9_FM )
. Thus, you can use the
ippSetCpuFeatures
 function to dispatch any version of Intel IPP code and enable/disable specific CPU features. If you are not well familiar with the features of your CPU, use the
ippInit()
 function (or auto-initialization mechanism available starting with Intel IPP 9.0) for the default library behavior.
Product and Performance Information
Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.
Notice revision #20201201
Return Values
ippStsNoErr
Indicates that the required processor-specific code is successfully set.
ippStsCpuMismatch
Indicates that the specified processor features are not valid. Previously set code is used. If the requested feature is below the minimal supported by the
m7
 library - that is Intel® Streaming SIMD Extensions 2 (Intel® SSE2) for IA-32 - or
w7
 - that is Intel® SSE3 for Intel® 64 architecture,
m7/w7
 code is dispatched respectively.
ippStsFeatureNotSupported
Indicates that the current CPU does not support at least one of the requested features. If the
ippCPUID_NOCHECK
 bit of the
cpuFeatures
 parameter is set to 1, these not supported features are enabled, otherwise - disabled.
ippStsUnknownFeature
Indicates that at least one of the requested features is unknown. It means that the feature is not defined in the
ippdefs.h
 file. Further behavior of the library depends on known features passed to
cpuFeatures
. Unknown features are ignored.
ippStsFeaturesCombination
Indicates that the combination of features is not correct. For example,
ippSetCpuFeatures(ippCPUID_AVX2);
 will generate this warning that means that
ippCPUID_AVX2
 bit is set to 1 in
cpuFeatures
, but at least one of the
ippCPUID_MMX
,
ippCPUID_SSE
, …,
ippCPUID_AVX
 bits or all of these bits are not set. Use
ippSetCpuFeatures(H9_FM);
 or
ippSetCpuFeatures(L9_FM);
 instead to avoid this warning. All the missing bits, if supported by CPU, are set to 1. This means that if the library supports the Intel® AVX2 code, it also internally uses all known MMX™, Intel® SSE, and Intel® AVX extensions, which are below Intel® AVX2.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.