Corrade::Cpu namespace new in Git master

Usage

The Cpu namespace contains tags such as Cpu::Avx2, Cpu::Sse2, Cpu::Neon or Cpu::Simd128. These tags behave similarly to enum values and their combination result in Cpu::Features, which is similar to the Containers::EnumSet class — they support the same bitwise operations, can be tested for subsets and supersets, and are printable with Utility::Debug.

The most advanced base CPU instruction set enabled at compile time is then exposed through the Cpu::DefaultBase variable, which is an alias to one of those tags, and it matches the architecture-specific CORRADE_TARGET_SSE2 etc. macros. Since it's a constexpr variable, it's usable in a compile-time context. The most straightforward use is shown in the following C++17 snippet:

Utility::Debug{} << "Base compiled instruction set:" << Cpu::DefaultBase;

if constexpr(Cpu::DefaultBase >= Cpu::Avx2) {
    // AVX2 code
} else {
    // scalar code
}

void transform(Cpu::ScalarT, Containers::ArrayView<float> data);
void transform(Cpu::Sse42T, Containers::ArrayView<float> data);
void transform(Cpu::Avx2T, Containers::ArrayView<float> data);

transform(Cpu::DefaultBase, data);

Cpu::Features features = Cpu::runtimeFeatures();
Utility::Debug{} << "Instruction set available at runtime:" << features;

if(features & Cpu::Avx2)
    transform(Cpu::Avx2, data);
else if(features & Cpu::Sse41)
    transform(Cpu::Sse41, data);
else
    transform(Cpu::Scalar, data);

Usage with extra instruction sets

Besides the base instruction set, which on x86 is Sse2 through Avx512f, with each tag being a superset of the previous one, there are extra instruction sets such as Popcnt or AvxFma. Basic compile-time detection for these is still straightforward, only now using Default instead of DefaultBase:

Utility::Debug{} << "Base and extra instruction sets:" << Cpu::Default;

if constexpr(Cpu::Default >= (Cpu::Avx2|Cpu::AvxFma)) {
    // AVX2+FMA code
} else {
    // scalar code
}

The process of defining and dispatching to function variants that include extra instruction sets gets moderately more complex, however. As shown on the diagram below, those are instruction sets that neither fit into the hierarchy nor are unambiguously included in a later instruction set. For example, some CPUs are known to have Avx and just AvxFma, some Avx and just AvxF16c and there are even CPUs with Avx2 but no AvxFma.

While there's no possibility of having a total ordering between all possible combinations for dispatching, the following approach is chosen:

1. The base instruction set has the main priority. For example, if both an Avx2 and a Sse2 variant are viable candidates, the Avx2 variant gets picked, even if the Sse2 variant uses extra instruction sets that the Avx2 doesn't.
2. After that, the variant with the most extra instruction sets is chosen. For example, an Avx + AvxFma variant is chosen over plain Avx.

On the declaration side, the desired base instruction set gets ORed with as many extra instruction sets as needed, and then wrapped in a CORRADE_CPU_DECLARE() macro. For example, a lookup algorithm may have a Sse41 implementation which however also relies on Popcnt and Lzcnt, and a fallback Sse2 implementation that uses neither:

int lookup(CORRADE_CPU_DECLARE(Cpu::Sse2), …);
int lookup(CORRADE_CPU_DECLARE(Cpu::Sse41|Cpu::Popcnt|Cpu::Lzcnt), …);

And a concrete overload gets picked at compile-time by passing a desired combination of CPU tags as well — or Default for the set of features enabled at compile time — this time wrapped in a CORRADE_CPU_SELECT():

int found = lookup(CORRADE_CPU_SELECT(Cpu::Default), …);

Enabling instruction sets for particular functions

On GCC and Clang, a machine target has to be enabled in order to use a particular CPU instruction set or its intrinsics. While it's possible to do that for the whole compilation unit by passing for example -mavx2 to the compiler, it would force you to create dedicated files for every architecture variant you want to support. Instead, it's possible to equip particular functions with target attributes defined by CORRADE_ENABLE_SSE2 and related macros, which then makes a particular instruction set enabled for given function.

In contrast, MSVC doesn't restrict intrinsics usage in any way, so you can freely call e.g. AVX2 intrinsics even if the whole file is compiled with just SSE2 enabled. The CORRADE_ENABLE_SSE2 and related macros are thus defined to be empty on this compiler.

For developer convenience, the CORRADE_ENABLE_SSE2 etc. macros are defined only on matching architectures, and generally only if the compiler itself has given feature set implemented and usable. Which means you can easily use them to #ifdef your variants to be compiled only where it makes sense, or even guard intrinsics includes with them to avoid including potentially heavy headers you won't use anyway. In comparison, using the CORRADE_TARGET_SSE2 etc. macros would only make the variant available if the whole compilation unit has a corresponding -m or /arch: option passed to the compiler.

Finally, the CORRADE_ENABLE() function allows multiple instruction sets to be enabled at the same time in a more concise way and consistently on both GCC and Clang.

Definitions of the lookup() function variants from above would then look like below with the target attributes added. The extra instruction sets get explicitly enabled as well, in contrast a scalar variant would have no target-specific annotations at all.

int lookup(CORRADE_CPU_DECLARE(Cpu::Scalar), …) {
    …
}
#ifdef CORRADE_ENABLE_SSE2
CORRADE_ENABLE_SSE2 int lookup(CORRADE_CPU_DECLARE(Cpu::Sse2), …) {
    …
}
#endif
#if defined(CORRADE_ENABLE_SSE41) && \
    defined(CORRADE_ENABLE_POPCNT) && \
    defined(CORRADE_ENABLE_LZCNT)
CORRADE_ENABLE(SSE41,POPCNT,LZCNT) int lookup(
    CORRADE_CPU_DECLARE(Cpu::Sse41|Cpu::Popcnt|Cpu::Lzcnt), …)
{
    …
}
#endif

Automatic runtime dispatch

Similarly to how the best-matching function variant can be picked at compile time, there's a possibility to do the same at runtime without maintaining a custom dispatch code for each case as was shown above. To avoid having to dispatch on every call and to remove the argument passthrough overhead, all variants need to have the same function signature, separate from the CPU tags. That's achievable by putting them into lambdas with a common signature, and returning that lambda from a wrapper function that contains the CPU tag. After that, a runtime dispatcher function that is created with the CORRADE_CPU_DISPATCHER_BASE() macro. The transform() variants from above would then look like this instead:

using TransformT = void(*)(Containers::ArrayView<float>);

TransformT transformImplementation(Cpu::ScalarT) {
    return [](Containers::ArrayView<float> data) { … };
}
TransformT transformImplementation(Cpu::Sse42T) {
    return [](Containers::ArrayView<float> data) { … };
}
TransformT transformImplementation(Cpu::Avx2T) {
    return [](Containers::ArrayView<float> data) { … };
}

CORRADE_CPU_DISPATCHER_BASE(transformImplementation)

The macro creates an overload of the same name, but taking Features instead, and internally dispatches to one of the overloads using the same rules as in the compile-time dispatch. Which means you can now call it with e.g. runtimeFeatures(), get a function pointer back and then call it with the actual arguments:

/* Dispatch once and cache the function pointer */
TransformT transform = transformImplementation(Cpu::runtimeFeatures());

/* Call many times */
transform(data);

using LookupT = int(*)(…);

LookupT lookupImplementation(CORRADE_CPU_DECLARE(Cpu::Scalar)) {
    …
}
LookupT lookupImplementation(CORRADE_CPU_DECLARE(Cpu::Sse2)) {
    …
}
LookupT lookupImplementation(CORRADE_CPU_DECLARE(Cpu::Sse41|Cpu::Popcnt|Cpu::Lzcnt)) {
    …
}

CORRADE_CPU_DISPATCHER(lookupImplementation, Cpu::Popcnt, Cpu::Lzcnt)

CORRADE_CPU_DISPATCHER(lookupImplementation, Cpu::Popcnt|Cpu::Lzcnt)

Automatic cached dispatch

Ultimately, the dispatch can be performed implicitly, exposing only the final function or a function pointer, with no additional steps needed from the user side. There's three possible scenarios with varying performance tradeoffs. Continuing from the lookupImplementation() example above:

• On Linux and Android with API 30+ it's possible to use the GNU IFUNC mechanism, where the dynamic linker performs a dispatch during the early startup. This is the fastest variant of runtime dispatch, as it results in an equivalent of a regular dynamic library function call. Assuming a dispatcher was created using either CORRADE_CPU_DISPATCHER() or CORRADE_CPU_DISPATCHER_BASE(), it's implemented using the CORRADE_CPU_DISPATCHED_IFUNC() macro:

  CORRADE_CPU_DISPATCHED_IFUNC(lookupImplementation, int lookup(…))

• On platforms where IFUNC isn't available, a function pointer can be used for runtime dispatch instead. It's one additional indirection, which may have a visible effect if the dispatched-to code is relatively tiny and is called from within a tight loop. Assuming a dispatcher was created using either CORRADE_CPU_DISPATCHER() or CORRADE_CPU_DISPATCHER_BASE(), it's implemented using the CORRADE_CPU_DISPATCHED_POINTER() macro:

  CORRADE_CPU_DISPATCHED_POINTER(lookupImplementation, int(*lookup)(…))

• For the least amount of overhead, the compile-time dispatch can be used, with arguments passed through by hand. Similarly to IFUNC, this will also result in a regular function, but without the indirect overhead. Furthermore, since it's a direct call to the lambda inside, compiler optimizations will fully inline its contents, removing any remaining overhead and allowing LTO and other inter-procedural optimizations that wouldn't be possible with the indirect calls. This option is best suited for scenarios where it's possible to build and optimize code for a single target platform. In this case it calls directly to the original variants, so no macro is needed and CORRADE_CPU_DISPATCHER() / CORRADE_CPU_DISPATCHER_BASE() is not needed either:

  int lookup(…) {
      return lookupImplementation(CORRADE_CPU_SELECT(Cpu::Default))(…);
  }

With all three cases, you end up with either a function or a function pointer. The macro signatures are deliberately similar to each other and to the direct function declaration to make it possible to unify them under a single wrapper macro in case a practical use case needs to handle more than one variant.

Finally, when exposed in a header as appropriate, both the function and the function pointer variant can be then called the same way:

#ifdef LOOKUP_USES_FUNCTION_POINTER
int (*lookup)(…);
#else
int lookup(…);
#endif

int found = lookup(…);

Classes

struct Avx2T

AVX2 tag type.

struct Avx512fT

AVX-512 Foundation tag type.

struct AvxF16cT

AVX F16C tag type.

struct AvxFmaT

AVX FMA tag type.

struct AvxT

AVX tag type.

struct Bmi1T

BMI1 tag type.

struct Bmi2T

BMI2 tag type.

class Features

Feature set.

struct LzcntT

LZCNT tag type.

struct NeonFmaT

NEON FMA tag type.

struct NeonFp16T

NEON FP16 tag type.

struct NeonT

NEON tag type.

struct PopcntT

POPCNT tag type.

struct ScalarT

Scalar tag type.

struct Simd128T

SIMD128 tag type.

struct Sse2T

SSE2 tag type.

struct Sse3T

SSE3 tag type.

struct Sse41T

SSE4.1 tag type.

struct Sse42T

SSE4.2 tag type.

struct Ssse3T

SSSE3 tag type.

template<class T>

struct TypeTraits

Traits class for CPU detection tag types.

Typedefs

using DefaultBaseT = ScalarT

Default base tag type.

using DefaultExtraT = Implementation::Tags<0>

Default extra tag type.

using DefaultT = Implementation::Tags<static_cast<unsigned int>TypeTraits<DefaultBaseT>::Index)|DefaultExtraT::Value>

Default tag type.

Functions

template<class T>

auto tag() -> T constexpr

Tag for a tag type.

template<class T>

auto features() -> Features constexpr

Feature set for a tag type.

auto compiledFeatures() -> Features constexpr

CPU instruction sets enabled at compile time.

auto runtimeFeatures() -> Features

Detect available CPU instruction sets at runtime.

Variables

ScalarT Scalar constexpr

Scalar tag.

Sse2T Sse2 constexpr

SSE2 tag.

Sse3T Sse3 constexpr

SSE3 tag.

Ssse3T Ssse3 constexpr

SSSE3 tag.

Sse41T Sse41 constexpr

SSE4.1 tag.

Sse42T Sse42 constexpr

SSE4.2 tag.

PopcntT Popcnt constexpr

POPCNT tag.

LzcntT Lzcnt constexpr

LZCNT tag.

Bmi1T Bmi1 constexpr

BMI1 tag.

Bmi2T Bmi2 constexpr

BMI2 tag.

AvxT Avx constexpr

AVX tag.

AvxF16cT AvxF16c constexpr

AVX F16C tag.

AvxFmaT AvxFma constexpr

AVX FMA tag.

Avx2T Avx2 constexpr

AVX2 tag.

Avx512fT Avx512f constexpr

AVX-512 Foundation tag.

NeonT Neon constexpr

NEON tag type.

NeonFmaT NeonFma constexpr

NEON FMA tag type.

NeonFp16T NeonFp16 constexpr

NEON FP16 tag type.

Simd128T Simd128 constexpr

SIMD128 tag type.

DefaultBaseT DefaultBase constexpr

Default base tag.

DefaultExtraT DefaultExtra constexpr

Default extra tags.

DefaultT Default constexpr

Default tags.

Typedef documentation

Function documentation

foo(Cpu::Avx2);
foo(Cpu::tag<Cpu::Avx2T>());

Cpu::Features a = Cpu::Avx2;
Cpu::Features b = Cpu::features<Cpu::Avx2T>();

Variable documentation