mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-10-30 08:02:30 +00:00
5d2405227a
Adds xxhash kernel module with xxh32 and xxh64 hashes. xxhash is an
extremely fast non-cryptographic hash algorithm for checksumming.
The zstd compression and decompression modules added in the next patch
require xxhash. I extracted it out from zstd since it is useful on its
own. I copied the code from the upstream XXHash source repository and
translated it into kernel style. I ran benchmarks and tests in the kernel
and tests in userland.
I benchmarked xxhash as a special character device. I ran in four modes,
no-op, xxh32, xxh64, and crc32. The no-op mode simply copies the data to
kernel space and ignores it. The xxh32, xxh64, and crc32 modes compute
hashes on the copied data. I also ran it with four different buffer sizes.
The benchmark file is located in the upstream zstd source repository under
`contrib/linux-kernel/xxhash_test.c` [1].
I ran the benchmarks on a Ubuntu 14.04 VM with 2 cores and 4 GiB of RAM.
The VM is running on a MacBook Pro with a 3.1 GHz Intel Core i7 processor,
16 GB of RAM, and a SSD. I benchmarked using the file `filesystem.squashfs`
from `ubuntu-16.10-desktop-amd64.iso`, which is 1,536,217,088 B large.
Run the following commands for the benchmark:
modprobe xxhash_test
mknod xxhash_test c 245 0
time cp filesystem.squashfs xxhash_test
The time is reported by the time of the userland `cp`.
The GB/s is computed with
1,536,217,008 B / time(buffer size, hash)
which includes the time to copy from userland.
The Normalized GB/s is computed with
1,536,217,088 B / (time(buffer size, hash) - time(buffer size, none)).
| Buffer Size (B) | Hash | Time (s) | GB/s | Adjusted GB/s |
|-----------------|-------|----------|------|---------------|
| 1024 | none | 0.408 | 3.77 | - |
| 1024 | xxh32 | 0.649 | 2.37 | 6.37 |
| 1024 | xxh64 | 0.542 | 2.83 | 11.46 |
| 1024 | crc32 | 1.290 | 1.19 | 1.74 |
| 4096 | none | 0.380 | 4.04 | - |
| 4096 | xxh32 | 0.645 | 2.38 | 5.79 |
| 4096 | xxh64 | 0.500 | 3.07 | 12.80 |
| 4096 | crc32 | 1.168 | 1.32 | 1.95 |
| 8192 | none | 0.351 | 4.38 | - |
| 8192 | xxh32 | 0.614 | 2.50 | 5.84 |
| 8192 | xxh64 | 0.464 | 3.31 | 13.60 |
| 8192 | crc32 | 1.163 | 1.32 | 1.89 |
| 16384 | none | 0.346 | 4.43 | - |
| 16384 | xxh32 | 0.590 | 2.60 | 6.30 |
| 16384 | xxh64 | 0.466 | 3.30 | 12.80 |
| 16384 | crc32 | 1.183 | 1.30 | 1.84 |
Tested in userland using the test-suite in the zstd repo under
`contrib/linux-kernel/test/XXHashUserlandTest.cpp` [2] by mocking the
kernel functions. A line in each branch of every function in `xxhash.c`
was commented out to ensure that the test-suite fails. Additionally
tested while testing zstd and with SMHasher [3].
[1] https://phabricator.intern.facebook.com/P57526246
[2] https://github.com/facebook/zstd/blob/dev/contrib/linux-kernel/test/XXHashUserlandTest.cpp
[3] https://github.com/aappleby/smhasher
zstd source repository: https://github.com/facebook/zstd
XXHash source repository: https://github.com/cyan4973/xxhash
Signed-off-by: Nick Terrell <terrelln@fb.com>
Signed-off-by: Chris Mason <clm@fb.com>
236 lines
7.6 KiB
C
236 lines
7.6 KiB
C
/*
|
|
* xxHash - Extremely Fast Hash algorithm
|
|
* Copyright (C) 2012-2016, Yann Collet.
|
|
*
|
|
* BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without
|
|
* modification, are permitted provided that the following conditions are
|
|
* met:
|
|
*
|
|
* * Redistributions of source code must retain the above copyright
|
|
* notice, this list of conditions and the following disclaimer.
|
|
* * Redistributions in binary form must reproduce the above
|
|
* copyright notice, this list of conditions and the following disclaimer
|
|
* in the documentation and/or other materials provided with the
|
|
* distribution.
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
|
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
|
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
*
|
|
* This program is free software; you can redistribute it and/or modify it under
|
|
* the terms of the GNU General Public License version 2 as published by the
|
|
* Free Software Foundation. This program is dual-licensed; you may select
|
|
* either version 2 of the GNU General Public License ("GPL") or BSD license
|
|
* ("BSD").
|
|
*
|
|
* You can contact the author at:
|
|
* - xxHash homepage: http://cyan4973.github.io/xxHash/
|
|
* - xxHash source repository: https://github.com/Cyan4973/xxHash
|
|
*/
|
|
|
|
/*
|
|
* Notice extracted from xxHash homepage:
|
|
*
|
|
* xxHash is an extremely fast Hash algorithm, running at RAM speed limits.
|
|
* It also successfully passes all tests from the SMHasher suite.
|
|
*
|
|
* Comparison (single thread, Windows Seven 32 bits, using SMHasher on a Core 2
|
|
* Duo @3GHz)
|
|
*
|
|
* Name Speed Q.Score Author
|
|
* xxHash 5.4 GB/s 10
|
|
* CrapWow 3.2 GB/s 2 Andrew
|
|
* MumurHash 3a 2.7 GB/s 10 Austin Appleby
|
|
* SpookyHash 2.0 GB/s 10 Bob Jenkins
|
|
* SBox 1.4 GB/s 9 Bret Mulvey
|
|
* Lookup3 1.2 GB/s 9 Bob Jenkins
|
|
* SuperFastHash 1.2 GB/s 1 Paul Hsieh
|
|
* CityHash64 1.05 GB/s 10 Pike & Alakuijala
|
|
* FNV 0.55 GB/s 5 Fowler, Noll, Vo
|
|
* CRC32 0.43 GB/s 9
|
|
* MD5-32 0.33 GB/s 10 Ronald L. Rivest
|
|
* SHA1-32 0.28 GB/s 10
|
|
*
|
|
* Q.Score is a measure of quality of the hash function.
|
|
* It depends on successfully passing SMHasher test set.
|
|
* 10 is a perfect score.
|
|
*
|
|
* A 64-bits version, named xxh64 offers much better speed,
|
|
* but for 64-bits applications only.
|
|
* Name Speed on 64 bits Speed on 32 bits
|
|
* xxh64 13.8 GB/s 1.9 GB/s
|
|
* xxh32 6.8 GB/s 6.0 GB/s
|
|
*/
|
|
|
|
#ifndef XXHASH_H
|
|
#define XXHASH_H
|
|
|
|
#include <linux/types.h>
|
|
|
|
/*-****************************
|
|
* Simple Hash Functions
|
|
*****************************/
|
|
|
|
/**
|
|
* xxh32() - calculate the 32-bit hash of the input with a given seed.
|
|
*
|
|
* @input: The data to hash.
|
|
* @length: The length of the data to hash.
|
|
* @seed: The seed can be used to alter the result predictably.
|
|
*
|
|
* Speed on Core 2 Duo @ 3 GHz (single thread, SMHasher benchmark) : 5.4 GB/s
|
|
*
|
|
* Return: The 32-bit hash of the data.
|
|
*/
|
|
uint32_t xxh32(const void *input, size_t length, uint32_t seed);
|
|
|
|
/**
|
|
* xxh64() - calculate the 64-bit hash of the input with a given seed.
|
|
*
|
|
* @input: The data to hash.
|
|
* @length: The length of the data to hash.
|
|
* @seed: The seed can be used to alter the result predictably.
|
|
*
|
|
* This function runs 2x faster on 64-bit systems, but slower on 32-bit systems.
|
|
*
|
|
* Return: The 64-bit hash of the data.
|
|
*/
|
|
uint64_t xxh64(const void *input, size_t length, uint64_t seed);
|
|
|
|
/*-****************************
|
|
* Streaming Hash Functions
|
|
*****************************/
|
|
|
|
/*
|
|
* These definitions are only meant to allow allocation of XXH state
|
|
* statically, on stack, or in a struct for example.
|
|
* Do not use members directly.
|
|
*/
|
|
|
|
/**
|
|
* struct xxh32_state - private xxh32 state, do not use members directly
|
|
*/
|
|
struct xxh32_state {
|
|
uint32_t total_len_32;
|
|
uint32_t large_len;
|
|
uint32_t v1;
|
|
uint32_t v2;
|
|
uint32_t v3;
|
|
uint32_t v4;
|
|
uint32_t mem32[4];
|
|
uint32_t memsize;
|
|
};
|
|
|
|
/**
|
|
* struct xxh32_state - private xxh64 state, do not use members directly
|
|
*/
|
|
struct xxh64_state {
|
|
uint64_t total_len;
|
|
uint64_t v1;
|
|
uint64_t v2;
|
|
uint64_t v3;
|
|
uint64_t v4;
|
|
uint64_t mem64[4];
|
|
uint32_t memsize;
|
|
};
|
|
|
|
/**
|
|
* xxh32_reset() - reset the xxh32 state to start a new hashing operation
|
|
*
|
|
* @state: The xxh32 state to reset.
|
|
* @seed: Initialize the hash state with this seed.
|
|
*
|
|
* Call this function on any xxh32_state to prepare for a new hashing operation.
|
|
*/
|
|
void xxh32_reset(struct xxh32_state *state, uint32_t seed);
|
|
|
|
/**
|
|
* xxh32_update() - hash the data given and update the xxh32 state
|
|
*
|
|
* @state: The xxh32 state to update.
|
|
* @input: The data to hash.
|
|
* @length: The length of the data to hash.
|
|
*
|
|
* After calling xxh32_reset() call xxh32_update() as many times as necessary.
|
|
*
|
|
* Return: Zero on success, otherwise an error code.
|
|
*/
|
|
int xxh32_update(struct xxh32_state *state, const void *input, size_t length);
|
|
|
|
/**
|
|
* xxh32_digest() - produce the current xxh32 hash
|
|
*
|
|
* @state: Produce the current xxh32 hash of this state.
|
|
*
|
|
* A hash value can be produced at any time. It is still possible to continue
|
|
* inserting input into the hash state after a call to xxh32_digest(), and
|
|
* generate new hashes later on, by calling xxh32_digest() again.
|
|
*
|
|
* Return: The xxh32 hash stored in the state.
|
|
*/
|
|
uint32_t xxh32_digest(const struct xxh32_state *state);
|
|
|
|
/**
|
|
* xxh64_reset() - reset the xxh64 state to start a new hashing operation
|
|
*
|
|
* @state: The xxh64 state to reset.
|
|
* @seed: Initialize the hash state with this seed.
|
|
*/
|
|
void xxh64_reset(struct xxh64_state *state, uint64_t seed);
|
|
|
|
/**
|
|
* xxh64_update() - hash the data given and update the xxh64 state
|
|
* @state: The xxh64 state to update.
|
|
* @input: The data to hash.
|
|
* @length: The length of the data to hash.
|
|
*
|
|
* After calling xxh64_reset() call xxh64_update() as many times as necessary.
|
|
*
|
|
* Return: Zero on success, otherwise an error code.
|
|
*/
|
|
int xxh64_update(struct xxh64_state *state, const void *input, size_t length);
|
|
|
|
/**
|
|
* xxh64_digest() - produce the current xxh64 hash
|
|
*
|
|
* @state: Produce the current xxh64 hash of this state.
|
|
*
|
|
* A hash value can be produced at any time. It is still possible to continue
|
|
* inserting input into the hash state after a call to xxh64_digest(), and
|
|
* generate new hashes later on, by calling xxh64_digest() again.
|
|
*
|
|
* Return: The xxh64 hash stored in the state.
|
|
*/
|
|
uint64_t xxh64_digest(const struct xxh64_state *state);
|
|
|
|
/*-**************************
|
|
* Utils
|
|
***************************/
|
|
|
|
/**
|
|
* xxh32_copy_state() - copy the source state into the destination state
|
|
*
|
|
* @src: The source xxh32 state.
|
|
* @dst: The destination xxh32 state.
|
|
*/
|
|
void xxh32_copy_state(struct xxh32_state *dst, const struct xxh32_state *src);
|
|
|
|
/**
|
|
* xxh64_copy_state() - copy the source state into the destination state
|
|
*
|
|
* @src: The source xxh64 state.
|
|
* @dst: The destination xxh64 state.
|
|
*/
|
|
void xxh64_copy_state(struct xxh64_state *dst, const struct xxh64_state *src);
|
|
|
|
#endif /* XXHASH_H */
|