From 02fe5d152a3de2afcb4234e9043461f80af3e261 Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Tue, 7 May 2024 16:20:08 -0700 Subject: [PATCH 1/4] update version number to v0.8.3 reflecting the change for results produced by XXH3_128bits_withSecretandSeed() for the specific case of `seed == 0` and `len < 240`. --- cli/xxhsum.1 | 2 +- xxhash.h | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/cli/xxhsum.1 b/cli/xxhsum.1 index 1b51c016..dd5fdeb4 100644 --- a/cli/xxhsum.1 +++ b/cli/xxhsum.1 @@ -1,5 +1,5 @@ . -.TH "XXHSUM" "1" "July 2023" "xxhsum 0.8.2" "User Commands" +.TH "XXHSUM" "1" "May 2024" "xxhsum 0.8.3" "User Commands" . .SH "NAME" \fBxxhsum\fR \- print or check xxHash non\-cryptographic checksums diff --git a/xxhash.h b/xxhash.h index 2269398e..e60537d0 100644 --- a/xxhash.h +++ b/xxhash.h @@ -547,7 +547,7 @@ extern "C" { ***************************************/ #define XXH_VERSION_MAJOR 0 #define XXH_VERSION_MINOR 8 -#define XXH_VERSION_RELEASE 2 +#define XXH_VERSION_RELEASE 3 /*! @brief Version number, encoded as two digits each */ #define XXH_VERSION_NUMBER (XXH_VERSION_MAJOR *100*100 + XXH_VERSION_MINOR *100 + XXH_VERSION_RELEASE) From 92d283916d231704ced5154095b8c563ec8adbff Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Tue, 7 May 2024 16:33:33 -0700 Subject: [PATCH 2/4] update documentation of XXH3_128bits_withSecretandSeed() to reflect #894 --- xxhash.h | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/xxhash.h b/xxhash.h index e60537d0..25bd16b5 100644 --- a/xxhash.h +++ b/xxhash.h @@ -1932,9 +1932,9 @@ XXH_PUBLIC_API void XXH3_generateSecret_fromSeed(XXH_NOESCAPE void* secretBuffer * @param secretSize The length of @p secret, in bytes. * @param seed The 64-bit seed to alter the hash result predictably. * - * These variants generate hash values using either - * @p seed for "short" keys (< @ref XXH3_MIDSIZE_MAX = 240 bytes) - * or @p secret for "large" keys (>= @ref XXH3_MIDSIZE_MAX). + * These variants generate hash values using either: + * - @p seed for "short" keys (< @ref XXH3_MIDSIZE_MAX = 240 bytes) + * - @p secret for "large" keys (>= @ref XXH3_MIDSIZE_MAX). * * This generally benefits speed, compared to `_withSeed()` or `_withSecret()`. * `_withSeed()` has to generate the secret on the fly for "large" keys. @@ -1961,24 +1961,33 @@ XXH_PUBLIC_API XXH_PUREF XXH64_hash_t XXH3_64bits_withSecretandSeed(XXH_NOESCAPE const void* data, size_t len, XXH_NOESCAPE const void* secret, size_t secretSize, XXH64_hash_t seed); + /*! * @brief Calculates 128-bit seeded variant of XXH3 hash of @p data. * - * @param input The block of data to be hashed, at least @p len bytes in size. + * @param data The memory segment to be hashed, at least @p len bytes in size. * @param length The length of @p data, in bytes. - * @param secret The secret data. - * @param secretSize The length of @p secret, in bytes. + * @param secret The secret used to alter hash result predictably. + * @param secretSize The length of @p secret, in bytes (must be >= XXH3_SECRET_SIZE_MIN) * @param seed64 The 64-bit seed to alter the hash result predictably. * * @return @ref XXH_OK on success. * @return @ref XXH_ERROR on failure. * - * @see XXH3_64bits_withSecretandSeed() + * @see XXH3_64bits_withSecretandSeed(): contract is the same. + * + * Note: there was a bug in an earlier version of this function (<= v0.8.2) + * that would make it generate an incorrect hash value + * when @p seed == 0 and @p length < XXH3_MIDSIZE_MAX. + * As stated in the contract, the correct hash result must be + * the same as XXH3_128bits_withSeed() when @p length < XXH3_MIDSIZE_MAX. + * Results generated by this older version are not considered comparable. */ XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH3_128bits_withSecretandSeed(XXH_NOESCAPE const void* input, size_t length, XXH_NOESCAPE const void* secret, size_t secretSize, XXH64_hash_t seed64); + #ifndef XXH_NO_STREAM /*! * @brief Resets an @ref XXH3_state_t with secret data to begin a new hash. From 8e483e4dd273474d86e168718ea318a30f7b6312 Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Tue, 7 May 2024 16:52:49 -0700 Subject: [PATCH 3/4] update XSUM_benchMem() doc --- cli/xsum_bench.c | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/cli/xsum_bench.c b/cli/xsum_bench.c index dfea66b7..7f67969a 100644 --- a/cli/xsum_bench.c +++ b/cli/xsum_bench.c @@ -340,9 +340,13 @@ static char* XSUM_strcatDup(const char* s1, const char* s2) /*! * XSUM_benchMem(): - * buffer: Must be 16-byte aligned. - * The real allocated size of buffer is supposed to be >= (bufferSize+3). - * returns: 0 on success, 1 if error (invalid mode selected) + * Benchmark provided content up to twice per function: + * - once at provided aligned memory address (%16) + * - second time at unaligned memory address (+3) + * Enabled functions and modes are provided via @g_hashesToBench global variable. + * @buffer: Must be 16-byte aligned. + * The allocated size of underlying @buffer must be >= (@bufferSize+3). + * This function also fills @g_benchSecretBuf, to bench XXH3's _withSecret() variants. */ static void XSUM_benchMem(const void* buffer, size_t bufferSize) { From d622b4fbb1862ced14df792614bd6697eb584e27 Mon Sep 17 00:00:00 2001 From: Yann Collet Date: Tue, 7 May 2024 18:24:44 -0700 Subject: [PATCH 4/4] updated documentation of XXH3_64bits_reset_withSecretandSeed() --- xxhash.h | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/xxhash.h b/xxhash.h index 25bd16b5..834a2183 100644 --- a/xxhash.h +++ b/xxhash.h @@ -1975,13 +1975,6 @@ XXH3_64bits_withSecretandSeed(XXH_NOESCAPE const void* data, size_t len, * @return @ref XXH_ERROR on failure. * * @see XXH3_64bits_withSecretandSeed(): contract is the same. - * - * Note: there was a bug in an earlier version of this function (<= v0.8.2) - * that would make it generate an incorrect hash value - * when @p seed == 0 and @p length < XXH3_MIDSIZE_MAX. - * As stated in the contract, the correct hash result must be - * the same as XXH3_128bits_withSeed() when @p length < XXH3_MIDSIZE_MAX. - * Results generated by this older version are not considered comparable. */ XXH_PUBLIC_API XXH_PUREF XXH128_hash_t XXH3_128bits_withSecretandSeed(XXH_NOESCAPE const void* input, size_t length, @@ -2000,12 +1993,13 @@ XXH3_128bits_withSecretandSeed(XXH_NOESCAPE const void* input, size_t length, * @return @ref XXH_OK on success. * @return @ref XXH_ERROR on failure. * - * @see XXH3_64bits_withSecretandSeed() + * @see XXH3_64bits_withSecretandSeed(). Contract is identical. */ XXH_PUBLIC_API XXH_errorcode XXH3_64bits_reset_withSecretandSeed(XXH_NOESCAPE XXH3_state_t* statePtr, XXH_NOESCAPE const void* secret, size_t secretSize, XXH64_hash_t seed64); + /*! * @brief Resets an @ref XXH3_state_t with secret data to begin a new hash. * @@ -2017,12 +2011,21 @@ XXH3_64bits_reset_withSecretandSeed(XXH_NOESCAPE XXH3_state_t* statePtr, * @return @ref XXH_OK on success. * @return @ref XXH_ERROR on failure. * - * @see XXH3_64bits_withSecretandSeed() + * @see XXH3_64bits_withSecretandSeed(). Contract is identical. + * + * Note: there was a bug in an earlier version of this function (<= v0.8.2) + * that would make it generate an incorrect hash value + * when @p seed == 0 and @p length < XXH3_MIDSIZE_MAX + * and @p secret is different from XXH3_generateSecret_fromSeed(). + * As stated in the contract, the correct hash result must be + * the same as XXH3_128bits_withSeed() when @p length <= XXH3_MIDSIZE_MAX. + * Results generated by this older version are wrong, hence not comparable. */ XXH_PUBLIC_API XXH_errorcode XXH3_128bits_reset_withSecretandSeed(XXH_NOESCAPE XXH3_state_t* statePtr, XXH_NOESCAPE const void* secret, size_t secretSize, XXH64_hash_t seed64); + #endif /* !XXH_NO_STREAM */ #endif /* !XXH_NO_XXH3 */