src/include/xxhash.h

   1 /* SPDX-License-Identifier: BSD-2-Clause */
   2
   3 /*
   4  * xxHash - Extremely Fast Hash algorithm
   5  * Copyright (C) 2012-2016, Yann Collet.
   6  *
   7  * You can contact the author at:
   8  * - xxHash homepage: http://cyan4973.github.io/xxHash/
   9  * - xxHash source repository: https://github.com/Cyan4973/xxHash
  10  */
  11
  12 /*
  13  * Notice extracted from xxHash homepage:
  14  *
  15  * xxHash is an extremely fast Hash algorithm, running at RAM speed limits.
  16  * It also successfully passes all tests from the SMHasher suite.
  17  *
  18  * Comparison (single thread, Windows Seven 32 bits, using SMHasher on a Core 2
  19  * Duo @3GHz)
  20  *
  21  * Name            Speed       Q.Score   Author
  22  * xxHash          5.4 GB/s     10
  23  * CrapWow         3.2 GB/s      2       Andrew
  24  * MumurHash 3a    2.7 GB/s     10       Austin Appleby
  25  * SpookyHash      2.0 GB/s     10       Bob Jenkins
  26  * SBox            1.4 GB/s      9       Bret Mulvey
  27  * Lookup3         1.2 GB/s      9       Bob Jenkins
  28  * SuperFastHash   1.2 GB/s      1       Paul Hsieh
  29  * CityHash64      1.05 GB/s    10       Pike & Alakuijala
  30  * FNV             0.55 GB/s     5       Fowler, Noll, Vo
  31  * CRC32           0.43 GB/s     9
  32  * MD5-32          0.33 GB/s    10       Ronald L. Rivest
  33  * SHA1-32         0.28 GB/s    10
  34  *
  35  * Q.Score is a measure of quality of the hash function.
  36  * It depends on successfully passing SMHasher test set.
  37  * 10 is a perfect score.
  38  *
  39  * A 64-bits version, named xxh64 offers much better speed,
  40  * but for 64-bits applications only.
  41  * Name     Speed on 64 bits    Speed on 32 bits
  42  * xxh64       13.8 GB/s            1.9 GB/s
  43  * xxh32        6.8 GB/s            6.0 GB/s
  44  */
  45
  46 #ifndef XXHASH_H
  47 #define XXHASH_H
  48
  49 #include <types.h>
  50
  51 /*-****************************
  52  * Simple Hash Functions
  53  *****************************/
  54
  55 /**
  56  * xxh32() - calculate the 32-bit hash of the input with a given seed.
  57  *
  58  * @input:  The data to hash.
  59  * @length: The length of the data to hash.
  60  * @seed:   The seed can be used to alter the result predictably.
  61  *
  62  * Speed on Core 2 Duo @ 3 GHz (single thread, SMHasher benchmark) : 5.4 GB/s
  63  *
  64  * Return:  The 32-bit hash of the data.
  65  */
  66 uint32_t xxh32(const void *input, size_t length, uint32_t seed);
  67
  68 /**
  69  * xxh64() - calculate the 64-bit hash of the input with a given seed.
  70  *
  71  * @input:  The data to hash.
  72  * @length: The length of the data to hash.
  73  * @seed:   The seed can be used to alter the result predictably.
  74  *
  75  * This function runs 2x faster on 64-bit systems, but slower on 32-bit systems.
  76  *
  77  * Return:  The 64-bit hash of the data.
  78  */
  79 uint64_t xxh64(const void *input, size_t length, uint64_t seed);
  80
  81 /*-****************************
  82  * Streaming Hash Functions
  83  *****************************/
  84
  85 /*
  86  * These definitions are only meant to allow allocation of XXH state
  87  * statically, on stack, or in a struct for example.
  88  * Do not use members directly.
  89  */
  90
  91 /**
  92  * struct xxh32_state - private xxh32 state, do not use members directly
  93  */
  94 struct xxh32_state {
  95         uint32_t total_len_32;
  96         uint32_t large_len;
  97         uint32_t v1;
  98         uint32_t v2;
  99         uint32_t v3;
 100         uint32_t v4;
 101         uint32_t mem32[4];
 102         uint32_t memsize;
 103 };
 104
 105 /**
 106  * struct xxh32_state - private xxh64 state, do not use members directly
 107  */
 108 struct xxh64_state {
 109         uint64_t total_len;
 110         uint64_t v1;
 111         uint64_t v2;
 112         uint64_t v3;
 113         uint64_t v4;
 114         uint64_t mem64[4];
 115         uint32_t memsize;
 116 };
 117
 118 /**
 119  * xxh32_reset() - reset the xxh32 state to start a new hashing operation
 120  *
 121  * @state: The xxh32 state to reset.
 122  * @seed:  Initialize the hash state with this seed.
 123  *
 124  * Call this function on any xxh32_state to prepare for a new hashing operation.
 125  */
 126 void xxh32_reset(struct xxh32_state *state, uint32_t seed);
 127
 128 /**
 129  * xxh32_update() - hash the data given and update the xxh32 state
 130  *
 131  * @state:  The xxh32 state to update.
 132  * @input:  The data to hash.
 133  * @length: The length of the data to hash.
 134  *
 135  * After calling xxh32_reset() call xxh32_update() as many times as necessary.
 136  *
 137  * Return:  Zero on success, otherwise an error code.
 138  */
 139 int xxh32_update(struct xxh32_state *state, const void *input, size_t length);
 140
 141 /**
 142  * xxh32_digest() - produce the current xxh32 hash
 143  *
 144  * @state: Produce the current xxh32 hash of this state.
 145  *
 146  * A hash value can be produced at any time. It is still possible to continue
 147  * inserting input into the hash state after a call to xxh32_digest(), and
 148  * generate new hashes later on, by calling xxh32_digest() again.
 149  *
 150  * Return: The xxh32 hash stored in the state.
 151  */
 152 uint32_t xxh32_digest(const struct xxh32_state *state);
 153
 154 /**
 155  * xxh64_reset() - reset the xxh64 state to start a new hashing operation
 156  *
 157  * @state: The xxh64 state to reset.
 158  * @seed:  Initialize the hash state with this seed.
 159  */
 160 void xxh64_reset(struct xxh64_state *state, uint64_t seed);
 161
 162 /**
 163  * xxh64_update() - hash the data given and update the xxh64 state
 164  * @state:  The xxh64 state to update.
 165  * @input:  The data to hash.
 166  * @length: The length of the data to hash.
 167  *
 168  * After calling xxh64_reset() call xxh64_update() as many times as necessary.
 169  *
 170  * Return:  Zero on success, otherwise an error code.
 171  */
 172 int xxh64_update(struct xxh64_state *state, const void *input, size_t length);
 173
 174 /**
 175  * xxh64_digest() - produce the current xxh64 hash
 176  *
 177  * @state: Produce the current xxh64 hash of this state.
 178  *
 179  * A hash value can be produced at any time. It is still possible to continue
 180  * inserting input into the hash state after a call to xxh64_digest(), and
 181  * generate new hashes later on, by calling xxh64_digest() again.
 182  *
 183  * Return: The xxh64 hash stored in the state.
 184  */
 185 uint64_t xxh64_digest(const struct xxh64_state *state);
 186
 187 /*-**************************
 188  * Utils
 189  ***************************/
 190
 191 /**
 192  * xxh32_copy_state() - copy the source state into the destination state
 193  *
 194  * @src: The source xxh32 state.
 195  * @dst: The destination xxh32 state.
 196  */
 197 void xxh32_copy_state(struct xxh32_state *dst, const struct xxh32_state *src);
 198
 199 /**
 200  * xxh64_copy_state() - copy the source state into the destination state
 201  *
 202  * @src: The source xxh64 state.
 203  * @dst: The destination xxh64 state.
 204  */
 205 void xxh64_copy_state(struct xxh64_state *dst, const struct xxh64_state *src);
 206
 207 #endif /* XXHASH_H */