# CPU Feature Targeting

The compiler provides a CPU-dispatching feature that enables users to provide different implementations of their functionality. The CPU-dispatching mechanism checks the target architecture and then selects the best implementation at runtime. However, the mechanism has two related potential limitations:

- Users cannot control the selected code path when they have a particular reason to do so; this can be decided only by the CPU-dispatching mechanism at runtime according to the target platform.
- Users cannot test their different implementations on the same machine.

CPU feature targeting addresses these limitations.

## Usage

CPU feature targeting does not add any command-line options. Instead, the user must set a new environment variable, `INTEL_ISA_DISABLE`, before running their application.

The user can set the environment variable as follows (Linux example):

    export INTEL_ISA_DISABLE=features

where features is a comma-separated list of features such as `sse2,avx`.

### Note

The feature names are those used with the -m option.

Setting the environment variable causes the named features not to be visible on the host even if the `CPUID` reports that it has them onboard. This has the following implications:

- If the user disables a CPU feature (for example, `_FEATURE_SSE2`) using `export INTEL_ISA_DISABLE=sse2`, then `_may_i_use_cpu_feature(_FEATURE_SSE2)` will return false; however, there will be no impact on other features for `_may_i_use_cpu_feature`.
- The CPU-dispatching mechanism will be affected; that is, dispatching will not take paths that require features disabled via `INTEL_ISA_DISABLE`.
- Libraries that use `libirc` for their CPU dispatching (such as `mkl` and `libimf`/`libsvml`) will be affected by `INTEL_ISA_DISABLE` in the same way.

## Additional Information

- CPU feature targeting has no architecture restrictions. Users can set the environment variable effectively on all our current architectures.
- CPU feature targeting has no default setting (such as OFF or ON). The feature is triggered by the `INTEL_ISA_DISABLE` environment variable, so if users do not set that variable before running their application, everything works normally (with no CPU feature targeting). Also, if users specify invalid feature names within the environment variable's value, those names will be ignored.
- There is no IDE equivalent for the CPU feature targeting feature.

### Important points to remember

- The value of environment variable `INTEL_ISA_DISABLE` is a feature list string comprising feature names separated by commas. The feature names are those used with the `-m` option.
- Users must set `INTEL_ISA_DISABLE` before running their application.
- Users must not disable any feature that is requested by the `-x target` option. For example, if you compile with `-xcore-avx2` and then disable `fma` (which is required by avx2) via the `INTEL_ISA_DISABLE` environment variable, a runtime error will occur indicating that the CPU is not supported.

## Example

hide_avx.c:

    #include "immintrin.h"
    #define CHECK(feature) \
    printf("%3s: %s\n", _may_i_use_cpu_feature(feature) ? "yes" : "no", #feature);

    int main() {
        CHECK(_FEATURE_GENERIC_IA32);
        CHECK(_FEATURE_SSE4_2);
        CHECK(_FEATURE_AVX);
        CHECK(_FEATURE_AVX2);
        return 0;
    }

Build hide_avx.c using `icc`:

    icc hide_avx.c –o hide_avx.exe

Run hide_avx.exe on a machine with avx2, producing the following output:

    yes: _FEATURE_GENERIC_IA32
    yes: _FEATURE_SSE4_2
    yes: _FEATURE_AVX
    yes: _FEATURE_AVX2

Then set the environment variable on the command line:

    export INTEL_ISA_DISABLE=avx2,avx

And then run hide_avx.exe again, producing the following output:

    yes: _FEATURE_GENERIC_IA32
    yes: _FEATURE_SSE4_2
    no: _FEATURE_AVX
    no: _FEATURE_AVX2

Parent topic: Processor Targeting

## See Also

cpu_dispatch, cpu_specific