Merge pull request #924 from Cyan4973/xxh64_noVector

disable XXH64 autovectorization

Author: Cyan4973

README.md

@@ -95,13 +95,15 @@ A more detailed analysis is documented [in the wiki](https://github.com/Cyan4973
 
 The following macros can be set at compilation time to modify libxxhash's behavior. They are generally disabled by default.
 
-- `XXH_INLINE_ALL`: Make all functions `inline`, with implementations being directly included within `xxhash.h`.
+- `XXH_INLINE_ALL`: Make all functions `inline`, implementations is directly included from within `xxhash.h`.
                     Inlining functions is beneficial for speed on small keys.
                     It's _extremely effective_ when key length is expressed as _a compile time constant_,
                     with performance improvements observed in the +200% range .
                     See [this article](https://fastcompression.blogspot.com/2018/03/xxhash-for-small-keys-impressive-power.html) for details.
 - `XXH_PRIVATE_API`: same outcome as `XXH_INLINE_ALL`. Still available for legacy support.
                      The name underlines that `XXH_*` symbol names will not be exported.
+- `XXH_STATIC_LINKING_ONLY`: gives access to internal state declaration, required for static allocation.
+                             Incompatible with dynamic linking, due to risks of ABI changes.
 - `XXH_NAMESPACE`: Prefixes all symbols with the value of `XXH_NAMESPACE`.
                    This macro can only use compilable character set.
                    Useful to evade symbol naming collisions,
@@ -117,40 +119,50 @@ The following macros can be set at compilation time to modify libxxhash's behavi
                              Method `1` uses a gcc-specific `packed` attribute, which can provide better performance for some targets.
                              Method `2` forces unaligned reads, which is not standard compliant, but might sometimes be the only way to extract better read performance.
                              Method `3` uses a byteshift operation, which is best for old compilers which don't inline `memcpy()` or big-endian systems without a byteswap instruction.
-- `XXH_VECTOR` : manually select a vector instruction set (default: auto-selected at compilation time). Available instruction sets are `XXH_SCALAR`, `XXH_SSE2`, `XXH_AVX2`, `XXH_AVX512`, `XXH_NEON` and `XXH_VSX`. Compiler may require additional flags to ensure proper support (for example, `gcc` on linux will require `-mavx2` for `AVX2`, and `-mavx512f` for `AVX512`).
-- `XXH_NO_PREFETCH` : disable prefetching. Some platforms or situations may perform better without prefetching. XXH3 only.
-- `XXH_PREFETCH_DIST` : select prefetching distance. For close-to-metal adaptation to specific hardware platforms. XXH3 only.
+- `XXH_CPU_LITTLE_ENDIAN`: By default, endianness is determined by a runtime test resolved at compile time.
+                           If, for some reason, the compiler cannot simplify the runtime test, it can cost performance.
+                           It's possible to skip auto-detection and simply state that the architecture is little-endian by setting this macro to 1.
+                           Setting it to 0 states big-endian.
+- `XXH_NO_STDLIB`: Disable invocation of `<stdlib.h>` functions, notably `malloc()` and `free()`.
+                   `libxxhash`'s `XXH*_createState()` will always fail and return `NULL`.
+                   But one-shot hashing (like `XXH32()`) or streaming using statically allocated states
+                   still work as expected.
+                   This build flag is useful for embedded environments without dynamic allocation.
 - `XXH_NO_STREAM`: Disables the streaming API, limiting it to single shot variants only.
-- `XXH_SIZE_OPT`: `0`: default, optimize for speed
-                  `1`: default for `-Os` and `-Oz`: disables some speed hacks for size optimization
-                  `2`: makes code as small as possible, performance may cry
 - `XXH_NO_INLINE_HINTS`: By default, xxHash uses `__attribute__((always_inline))` and `__forceinline` to improve performance at the cost of code size.
                          Defining this macro to 1 will mark all internal functions as `static`, allowing the compiler to decide whether to inline a function or not.
                          This is very useful when optimizing for smallest binary size,
                          and is automatically defined when compiling with `-O0`, `-Os`, `-Oz`, or `-fno-inline` on GCC and Clang.
-                         This may also increase performance depending on compiler and architecture.
+                         This might also increase performance depending on compiler and architecture.
+- `XXH_SIZE_OPT`: `0`: default, optimize for speed
+                  `1`: default for `-Os` and `-Oz`: disables some speed hacks for size optimization
+                  `2`: makes code as small as possible, performance may cry
+- `XXH_DEBUGLEVEL` : When set to any value >= 1, enables `assert()` statements.
+                     This (slightly) slows down execution, but may help finding bugs during debugging sessions.
+- `XXH_ENABLE_AUTOVECTORIZE`: Auto-vectorization may be triggered for XXH32 and XXH64, depending on cpu vector capabilities and compiler version.
+                              Note: auto-vectorization tends to be triggered more easily with recent versions of `clang`.
+                              For XXH32, SSE4.1 or equivalent (NEON) is enough, while XXH64 requires AVX512.
+                              Unfortunately, auto-vectorization is not always a good idea, and often degrades performance.
+                              For this reason, the xxhash source code tries to prevent auto-vectorization by default.
+                              That being said, systems evolve, and this conclusion is not forthcoming.
+                              For example, it has been reported that recent Zen4 cpus are more likely to improve performance with vectorization.
+                              Therefore, should you prefer or want to test vectorized code, just enable this flag:
+                              it will remove the no-vectorization protection code, thus making it more likely for XXH32 and XXH64 to be auto-vectorized.
 - `XXH32_ENDJMP`: Switch multi-branch finalization stage of XXH32 by a single jump.
                   This is generally undesirable for performance, especially when hashing inputs of random sizes.
                   But depending on exact architecture and compiler, a jump might provide slightly better performance on small inputs. Disabled by default.
-- `XXH_NO_STDLIB`: Disable invocation of `<stdlib.h>` functions, notably `malloc()` and `free()`.
-                   `libxxhash`'s `XXH*_createState()` will always fail and return `NULL`.
-                   But one-shot hashing (like `XXH32()`) or streaming using statically allocated states
-                   still work as expected.
-                   This build flag is useful for embedded environments without dynamic allocation.
-- `XXH_STATIC_LINKING_ONLY`: gives access to internal state declaration, required for static allocation.
-                             Incompatible with dynamic linking, due to risks of ABI changes.
+- `XXH_IMPORT`: MSVC specific: should only be defined for dynamic linking, as it prevents linkage errors.
+
+#### Build modifiers specific for XXH3
+- `XXH_VECTOR` : manually select a vector instruction set (default: auto-selected at compilation time). Available instruction sets are `XXH_SCALAR`, `XXH_SSE2`, `XXH_AVX2`, `XXH_AVX512`, `XXH_NEON` and `XXH_VSX`. Compiler may require additional flags to ensure proper support (for example, `gcc` on x86_64 requires `-mavx2` for `AVX2`, or `-mavx512f` for `AVX512`).
+- `XXH_PREFETCH_DIST` : select prefetching distance. For close-to-metal adaptation to specific hardware platforms. XXH3 only.
+- `XXH_NO_PREFETCH` : disable prefetching. Some platforms or situations may perform better without prefetching. XXH3 only.
 - `XXH_NO_XXH3` : removes symbols related to `XXH3` (both 64 & 128 bits) from generated binary.
                   Useful to reduce binary size, notably for applications which do not employ `XXH3`.
 - `XXH_NO_LONG_LONG`: removes compilation of algorithms relying on 64-bit types (`XXH3` and `XXH64`). Only `XXH32` will be compiled.
                       Useful for targets (architectures and compilers) without 64-bit support.
-- `XXH_IMPORT`: MSVC specific: should only be defined for dynamic linking, as it prevents linkage errors.
-- `XXH_CPU_LITTLE_ENDIAN`: By default, endianness is determined by a runtime test resolved at compile time.
-                           If, for some reason, the compiler cannot simplify the runtime test, it can cost performance.
-                           It's possible to skip auto-detection and simply state that the architecture is little-endian by setting this macro to 1.
-                           Setting it to 0 states big-endian.
-- `XXH_DEBUGLEVEL` : When set to any value >= 1, enables `assert()` statements.
-                     This (slightly) slows down execution, but may help finding bugs during debugging sessions.
 
+#### Makefile variables
 When compiling the Command Line Interface `xxhsum` using `make`, the following environment variables can also be set :
 - `DISPATCH=1` : use `xxh_x86dispatch.c`, to automatically select between `scalar`, `sse2`, `avx2` or `avx512` instruction set at runtime, depending on local host. This option is only valid for `x86`/`x64` systems.
 - `XXH_1ST_SPEED_TARGET` : select an initial speed target, expressed in MB/s, for the first speed test in benchmark mode. Benchmark will adjust the target at subsequent iterations, but the first test is made "blindly" by targeting this speed. Currently conservatively set to 10 MB/s, to support very slow (emulated) platforms.

xxhash.h

@@ -2863,7 +2863,7 @@ static xxh_u32 XXH32_round(xxh_u32 acc, xxh_u32 input)
 #if (defined(__SSE4_1__) || defined(__aarch64__) || defined(__wasm_simd128__)) && !defined(XXH_ENABLE_AUTOVECTORIZE)
     /*
      * UGLY HACK:
-     * A compiler fence is the only thing that prevents GCC and Clang from
+     * A compiler fence is used to prevent GCC and Clang from
      * autovectorizing the XXH32 loop (pragmas and attributes don't work for some
      * reason) without globally disabling SSE4.1.
      *
@@ -3370,6 +3370,23 @@ static xxh_u64 XXH64_round(xxh_u64 acc, xxh_u64 input)
     acc += input * XXH_PRIME64_2;
     acc  = XXH_rotl64(acc, 31);
     acc *= XXH_PRIME64_1;
+#if (defined(__AVX512F__)) && !defined(XXH_ENABLE_AUTOVECTORIZE)
+    /*
+     * DISABLE AUTOVECTORIZATION:
+     * A compiler fence is used to prevent GCC and Clang from
+     * autovectorizing the XXH64 loop (pragmas and attributes don't work for some
+     * reason) without globally disabling AVX512.
+     *
+     * Autovectorization of XXH64 tends to be detrimental,
+     * though the exact outcome may change depending on exact cpu and compiler version.
+     * For information, it has been reported as detrimental for Skylake-X,
+     * but possibly beneficial for Zen4.
+     *
+     * The default is to disable auto-vectorization,
+     * but you can select to enable it instead using `XXH_ENABLE_AUTOVECTORIZE` build variable.
+     */
+    XXH_COMPILER_GUARD(acc);
+#endif
     return acc;
 }