mosra · mosra · Aug 1, 2022 · Jul 9, 2022 · Jul 9, 2022 · Jul 9, 2022
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -60,6 +60,8 @@ project(Corrade CXX)
 # Use folders for nice tree in Visual Studio and XCode
 set_property(GLOBAL PROPERTY USE_FOLDERS ON)
 
+set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/modules/" ${CMAKE_MODULE_PATH})
+
 include(CMakeDependentOption)
 
 # Options that used to be unprefixed. New options shouldn't be added to this
@@ -187,6 +189,112 @@ if(CORRADE_TARGET_WINDOWS)
     endif()
 endif()
 
+# Check if we can use IFUNC for CPU dispatch. Linux with glibc and Android with
+# API 18+ has it, but e.g. Alpine Linux with musl doesn't, and on Android with
+# API < 30 we don't get AT_HWCAP passed into the resolver and can't call
+# getauxval() ourselves because it's too early at that point, which makes it
+# pretty useless. Plus it also needs a certain binutils version and a capable
+# compiler, so it's easiest to just verify the whole thing.
+if(CORRADE_TARGET_UNIX)
+    include(CheckCXXSourceCompiles)
+    check_cxx_source_compiles("\
+int fooImplementation() { return 42; }
+#if defined(__ANDROID_API__) && __ANDROID_API__ < 30
+#error need Android API 30+ to have AT_HWCAP passed into the resolver
+#endif
+extern \"C\" int(*fooDispatcher())() {
+    return fooImplementation;
+}
+int foo() __attribute__((ifunc(\"fooDispatcher\")));
+int main() { return foo() - 42; }\
+        " _CORRADE_CPU_CAN_USE_IFUNC)
+    # In cases where ifunc is known to be broken, disable it by default --
+    # users can still force it to be enabled, but the initial state should not
+    # cause crashes or other strange behavior.
+    if(_CORRADE_CPU_CAN_USE_IFUNC)
+        set(_CORRADE_CPU_USE_IFUNC_DEFAULT ON)
+        # On GCC 4.8, if --coverage or -fprofile-arcs is enabled, the ifunc
+        # dispatchers cause a segfault. On Ubuntu 20.04 at least. Not the case
+        # with GCC 5 there, not the case with GCC 4.8 on Arch. Can't find any
+        # upstream bug report or commit that would be related to this.
+        if(CMAKE_CXX_COMPILER_ID AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS "4.9" AND CMAKE_CXX_FLAGS MATCHES "(--coverage|-fprofile-arcs)")
+            if(NOT DEFINED CORRADE_CPU_USE_IFUNC)
+                message(WARNING "Disabling CORRADE_CPU_USE_IFUNC by default as it may crash when used together with --coverage on GCC 4.8.")
+            endif()
+            set(_CORRADE_CPU_USE_IFUNC_DEFAULT OFF)
+        endif()
+
+        # If sanitizers are enabled, call into the dispatch function crashes.
+        # Upstream bugreport https://github.com/google/sanitizers/issues/342
+        # suggests using __attribute__((no_sanitize_address)), but that doesn't
+        # work / can't be used because it would mean marking basically
+        # everything including the actual implementation that's being
+        # dispatched to.
+        #
+        # Sanitizers can be also enabled any other way such as with
+        # CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER or with per-target properties
+        # which isn't easy to detect, so as a secondary measure there's a kill
+        # switch in Corrade/configure.h that will fail with an error if a
+        # sanitizer is detected and CORRADE_CPU_USE_IFUNC is enabled.
+        #
+        # While Clang and GCC use -fsanitize=whatever, MSVC allows also
+        # /fsanitize=, so catch both.
+        if(CMAKE_CXX_FLAGS MATCHES "[-/]fsanitize=")
+            if(NOT DEFINED CORRADE_CPU_USE_IFUNC)
+                message(WARNING "Disabling CORRADE_CPU_USE_IFUNC by default as it crashes when used together with sanitizers. See https://github.com/google/sanitizers/issues/342 for more information.")
+            endif()
+            set(_CORRADE_CPU_USE_IFUNC_DEFAULT OFF)
+        endif()
+    else()
+        set(_CORRADE_CPU_USE_IFUNC_DEFAULT OFF)
+    endif()
+else()
+    set(_CORRADE_CPU_CAN_USE_IFUNC OFF)
+    set(_CORRADE_CPU_USE_IFUNC_DEFAULT OFF)
+endif()
+cmake_dependent_option(CORRADE_CPU_USE_IFUNC "Allow using GNU IFUNC for runtime CPU dispatch" ${_CORRADE_CPU_USE_IFUNC_DEFAULT} "_CORRADE_CPU_CAN_USE_IFUNC" OFF)
+
+# Runtime CPU dispatch. Because going through a function pointer may have
+# negative perf consequences, enable it by default only on platforms that have
+# IFUNC, and thus can avoid the function pointer indirection.
+option(CORRADE_BUILD_CPU_RUNTIME_DISPATCH "Build with runtime dispatch for CPU-dependent functionality" ${_CORRADE_CPU_CAN_USE_IFUNC})
+# Enabled by default and independent of CORRADE_BUILD_CPU_RUNTIME_DISPATCH as
+# correctness is important. It can however negatively affect performance
+# compared to IFUNC or compile-time dispatch, so make it possible to disable
+# this for benchmarks.
+cmake_dependent_option(CORRADE_BUILD_TESTS_FORCE_CPU_POINTER_DISPATCH "Force pointer-based dispatch for unit tests to verify all variants of CPU-dependent functionality" ON "CORRADE_BUILD_TESTS" OFF)
+
+# Pass -msimd128 to tests to make it possible to verify also the WASM SIMD
+# functionality even if the actual library is built without. I thought it would
+# be a no-brainer, however *actual* finalized SIMD128 requires final Clang 13
+# (such version is reported since emsdk 2.0.13, but the actual final version
+# containing all intrinsics is only in emsdk 2.0.18), and Node.js 15+, which
+# contains V8 8.6:
+#   https://github.com/nodejs/node/blob/main/doc/changelogs/CHANGELOG_V15.md#2020-10-20-version-1500-current-bethgriggs
+# Final bitmask instructions were added in 8.5, Node.js 14 has 8.4:
+#   https://github.com/v8/v8/commit/aa5bcc09bf7d5d77056e6033918d79c30aa3f49a
+# However, even now, in the midst of 2022 wildfires, emsdk still bundles
+# Node.js 14.18 and there's no hope of it being upgraded any time soon:
+#   https://github.com/emscripten-core/emsdk/pull/877
+#   https://github.com/emscripten-core/emsdk/issues/947
+#   https://github.com/emscripten-core/emsdk/issues/1064
+# So instead of having -msimd128 always, I only enable it implicitly if Node.js
+# 15 is found, and then CORRADE_ENABLE_SIMD128 / CORRADE_TARGET_SIMD128 gets
+# enabled only if there's Clang 13 but also Emscripten 2.0.18+. What a mess.
+if(CORRADE_TARGET_EMSCRIPTEN)
+    set(ENABLE_IF_NODEJS_15 OFF)
+    if(CORRADE_BUILD_TESTS)
+        find_package(NodeJs REQUIRED QUIET)
+        if(NOT NodeJs_VERSION VERSION_LESS 15.0)
+            set(ENABLE_IF_NODEJS_15 ON)
+        elseif(NOT DEFINED CORRADE_BUILD_TESTS_FORCE_WASM_SIMD128)
+            message(WARNING "Disabling CORRADE_BUILD_TESTS_FORCE_WASM_SIMD128 by default as finalized WebAssembly SIMD support is only since Node.js 15 but found version ${NodeJs_VERSION}")
+        endif()
+    endif()
+
+    cmake_dependent_option(CORRADE_BUILD_TESTS_FORCE_WASM_SIMD128 "Force -msimd128 for unit tests to verify also WASM SIMD variants of CPU-dependent functionality" ${ENABLE_IF_NODEJS_15} "CORRADE_BUILD_TESTS_FORCE_CPU_POINTER_DISPATCH" OFF)
+endif()
+
 # Backwards compatibility for unprefixed CMake options. If the user isn't
 # explicitly using prefixed options in the first run already, accept the
 # unprefixed options, and remember this decision for subsequent runs
@@ -256,7 +364,6 @@ if(CORRADE_BUILD_TESTS)
     enable_testing()
 endif()
 
-set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/modules/" ${CMAKE_MODULE_PATH})
 if(CMAKE_CROSSCOMPILING)
     find_program(CORRADE_RC_EXECUTABLE corrade-rc)
     if(NOT CORRADE_RC_EXECUTABLE)

diff --git a/doc/Doxyfile b/doc/Doxyfile
@@ -2280,14 +2280,14 @@ DOT_NUM_THREADS        = 0
 # The default value is: Helvetica.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_FONTNAME           = Verdana
+DOT_FONTNAME           = Source Sans Pro
 
 # The DOT_FONTSIZE tag can be used to set the size (in points) of the font of
 # dot graphs.
 # Minimum value: 4, maximum value: 24, default value: 10.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_FONTSIZE           = 8
+DOT_FONTSIZE           = 16
 
 # By default doxygen will tell dot to use the default font as specified with
 # DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set
@@ -2445,7 +2445,7 @@ DOT_PATH               =
 # command).
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOTFILE_DIRS           =
+DOTFILE_DIRS           = .
 
 # The MSCFILE_DIRS tag can be used to specify one or more directories that
 # contain msc files that are included in the documentation (see the \mscfile

diff --git a/doc/building-corrade.dox b/doc/building-corrade.dox
@@ -550,9 +550,28 @@ Options controlling the build:
     Corrade features simultaneously in multiple threads. Enabled by default,
     disable if you don't need this and don't want to pay potential performance
     penalties coming from thread-local variables.
+-   `CORRADE_BUILD_CPU_RUNTIME_DISPATCH` --- Build with performance-critical
+    code paths optimized for multiple architectures (such as SSE or AVX on
+    x86), with the best matching variant selected at runtime based on detected
+    CPU features. If not enabled, the library is built with just a single
+    variant that's picked at compile time depending on target architecture
+    flags being passed to the compiler. Enabled by default on platforms that
+    support [GNU IFUNC](https://sourceware.org/glibc/wiki/GNU_IFUNC), which is
+    currently only Linux with glibc and Android with API 30+. See also the
+    `CORRADE_CPU_USE_IFUNC` option below and
+    @ref Cpu-usage-automatic-cached-dispatch for details and information about
+    performance tradeoffs.
 
 Platform-specific options:
 
+-   `CORRADE_CPU_USE_IFUNC` --- Allow
+    [GNU IFUNC](https://sourceware.org/glibc/wiki/GNU_IFUNC) to be used for
+    runtime dispatch in the @ref Cpu library. Available only on platforms that
+    support it, which is currently only Linux with glibc and Android with API
+    30+, and there enabled by default unless a problematic case is detected
+    that may cause it to misbehave. See
+    @ref Cpu-usage-automatic-cached-dispatch for details and information about
+    performance tradeoffs.
 -   `CORRADE_UTILITY_USE_ANSI_COLORS` --- if building for Windows, this will
     use ANSI escape codes in @ref Utility::Debug instead of WINAPI functions.
     Note that you need at least Windows 10 or non-standard console emulator to
@@ -622,11 +641,31 @@ compatibility if `CORRADE_BUILD_DEPRECATED` isn't disabled.
 
 @subsection building-corrade-tests Building and running tests
 
-If you want to build also the tests (which are not built by default), enable
-`CORRADE_BUILD_TESTS` in CMake. The tests use Corrade's own
-@ref Corrade::TestSuite "TestSuite" framework and can be run either manually
-(the binaries are located in `Test/` subdirectories in the build directory) or
-using
+Building of tests is controlled by the following options:
+
+-   `CORRADE_BUILD_TESTS` --- Builds unit tests. Disabled by default.
+-   `CORRADE_BUILD_TESTS_FORCE_CPU_POINTER_DISPATCH` --- Force unit tests to be
+    built with function-pointer-based dispatch for CPU-dependent functionality,
+    independently of the `CORRADE_BUILD_CPU_RUNTIME_DISPATCH` and
+    `CORRADE_CPU_USE_IFUNC` options. This makes it possible for the tests to
+    verify all variants instead of just one, and is enabled by default. The
+    overhead from function pointers may however be significant on certain
+    platforms, skewing benchmark results. Disable it to make the tests use the
+    same dispatch method as the rest of the library.
+-   `CORRADE_BUILD_TESTS_FORCE_WASM_SIMD128` --- Force Emscripten unit tests to
+    be built with `-msimd128` independenently of `CMAKE_CXX_FLAGS`. Together
+    with `CORRADE_BUILD_TESTS_FORCE_CPU_POINTER_DISPATCH` and presence of the
+    @ref CORRADE_ENABLE_SIMD128 preprocessor variable this makes it possible
+    for the tests to verify also WebAssembly SIMD variants of CPU-dependent
+    functionality instead of just the scalar version if the rest of the library
+    is built without `-msimd128`. Enabled by default if
+    `CORRADE_BUILD_TESTS_FORCE_CPU_POINTER_DISPATCH` is set and Node.js version
+    15+ is found, which has finalized WebAssembly SIMD support. Disable to make
+    the tests use the same compilation flags as the rest of the library.
+
+The tests use Corrade's own @relativeref{Corrade,TestSuite} framework and can
+be run either manually (the binaries are located in `Test/` subdirectories in
+the build directory) or using
 
 @code{.sh}
 ctest --output-on-failure
@@ -947,8 +986,9 @@ for more information.
 @subsection building-corrade-ci-circleci CircleCI
 
 In `package/ci/` there is a `circle.yml` file with Linux GCC 4.8, Linux ARM64,
-macOS, Emscripten, AddressSanitizer, ThreadSanitizer, Android x86 and iOS
-x86_64 configuration. Online at https://circleci.com/gh/mosra/corrade.
+macOS, Emscripten (except SIMD, see the file for details), AddressSanitizer,
+ThreadSanitizer, Android x86 and iOS x86_64 configuration. Online at
+https://circleci.com/gh/mosra/corrade.
 
 @subsection building-corrade-ci-appveyor AppVeyor
 

diff --git a/doc/corrade-changelog.dox b/doc/corrade-changelog.dox
@@ -45,15 +45,18 @@ namespace Corrade {
     @ref CORRADE_TARGET_POWERPC
 -   New @ref CORRADE_TARGET_SSE3, @ref CORRADE_TARGET_SSSE3,
     @ref CORRADE_TARGET_SSE41, @ref CORRADE_TARGET_SSE42,
-    @ref CORRADE_TARGET_AVX, @ref CORRADE_TARGET_AVX_F16C,
-    @ref CORRADE_TARGET_AVX_FMA, @ref CORRADE_TARGET_AVX2,
-    @ref CORRADE_TARGET_AVX512F, @ref CORRADE_TARGET_NEON,
-    @ref CORRADE_TARGET_NEON_FP16, @ref CORRADE_TARGET_NEON_FMA and
-    @ref CORRADE_TARGET_SIMD128 preprocessor variables added to the already
-    existing @ref CORRADE_TARGET_SSE2 for detecting enabled instruction sets on
-    x86, ARM and WebAssembly
+    @ref CORRADE_TARGET_POPCNT, @ref CORRADE_TARGET_LZCNT,
+    @ref CORRADE_TARGET_BMI1, @ref CORRADE_TARGET_AVX,
+    @ref CORRADE_TARGET_AVX_F16C, @ref CORRADE_TARGET_AVX_FMA,
+    @ref CORRADE_TARGET_AVX2, @ref CORRADE_TARGET_AVX512F,
+    @ref CORRADE_TARGET_NEON, @ref CORRADE_TARGET_NEON_FMA,
+    @ref CORRADE_TARGET_NEON_FP16 and @ref CORRADE_TARGET_SIMD128 preprocessor
+    variables added to the already existing @ref CORRADE_TARGET_SSE2 for
+    detecting enabled instruction sets on x86, ARM and WebAssembly
 -   New @ref CORRADE_TARGET_32BIT preprocessor variable for cross-platform
     detection of 32-bit builds
+-   New @ref Cpu namespace that provides building blocks for compile-time and
+    runtime CPU feature detection and dispatch on x86, ARM and WebAssembly
 
 @subsubsection corrade-changelog-latest-new-containers Containers library
 
@@ -360,6 +363,13 @@ namespace Corrade {
     Windows as well instead of declaring aligned memory allocation functions on
     its own, as it's not worth the seriously-looking compiler warnings (see
     [mosra/corrade#145](https://github.com/mosra/corrade/issues/145))
+-   Platforms that support @ref CORRADE_CPU_USE_IFUNC will now build certain
+    code paths optimized for multiple architectures, with the best variant
+    selected at runtime using the @ref Cpu library based on available CPU
+    features. This behavior can be disabled with the
+    @ref CORRADE_BUILD_CPU_RUNTIME_DISPATCH CMake option. Platforms without
+    IFUNC support implement runtime dispatch using function pointers instead of
+    indirect functions and have this currently disabled by default.
 
 @subsection corrade-changelog-latest-bugfixes Bug fixes
 

diff --git a/doc/corrade-cmake.dox b/doc/corrade-cmake.dox
@@ -211,6 +211,9 @@ also available as preprocessor variables if you include
 -   `CORRADE_BUILD_MULTITHREADED` --- Defined if compiled in a way that makes
     it possible to safely use certain Corrade features simultaneously in
     multiple threads.
+-   `CORRADE_BUILD_CPU_RUNTIME_DISPATCH` --- Defined if built with code paths
+    optimized for multiple architectres with the best matching variant selected
+    at runtime based on detected CPU features
 -   `CORRADE_TARGET_UNIX` --- Defined if compiled for some Unix flavor (Linux,
     BSD, macOS, iOS, Android, ...)
 -   `CORRADE_TARGET_APPLE` --- Defined if compiled for Apple platforms
@@ -230,6 +233,9 @@ also available as preprocessor variables if you include
 -   `CORRADE_TARGET_MSVC` --- Defined if compiling with MSVC or Clang with a
     MSVC frontend
 -   `CORRADE_TARGET_MINGW` --- Defined if compiling under MinGW
+-   `CORRADE_CPU_USE_IFUNC` - Defined if
+    [GNU IFUNC](https://sourceware.org/glibc/wiki/GNU_IFUNC) is allowed to be
+    used for runtime dispatch in the @ref Cpu library
 -   `CORRADE_PLUGINMANAGER_NO_DYNAMIC_PLUGIN_SUPPORT` --- Defined if
     @ref PluginManager doesn't support dynamic plugin loading due to platform
     limitations
@@ -239,8 +245,11 @@ also available as preprocessor variables if you include
     used for colored output with @ref Utility::Debug on Windows
 
 Besides all the defines above, the @ref Corrade/Corrade.h additionally defines
-@ref CORRADE_CXX_STANDARD, @ref CORRADE_TARGET_X86, @ref CORRADE_TARGET_ARM,
-@ref CORRADE_TARGET_POWERPC, @ref CORRADE_TARGET_LIBCXX,
+@ref CORRADE_CXX_STANDARD, @ref CORRADE_TARGET_X86 and related x86-specific
+variables, @ref CORRADE_TARGET_ARM and related ARM-specific variables,
+@ref CORRADE_TARGET_POWERPC, @ref CORRADE_TARGET_WASM and related
+WebAssembly-specific variables, @ref CORRADE_TARGET_32BIT,
+@ref CORRADE_TARGET_BIG_ENDIAN, @ref CORRADE_TARGET_LIBCXX,
 @ref CORRADE_TARGET_LIBSTDCXX and @ref CORRADE_TARGET_DINKUMWARE based on
 target architecture, standard and STL used. They are not exposed in CMake
 because the meaning is unclear with projects that mix more different C++