1/*
2 * Copyright 2013-present Facebook, Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#pragma once
18
19#include <stdint.h>
20#include <cstddef>
21
22/*
23 * Checksum functions
24 */
25
26namespace folly {
27
28/**
29 * Compute the CRC-32C checksum of a buffer, using a hardware-accelerated
30 * implementation if available or a portable software implementation as
31 * a default.
32 *
33 * @note CRC-32C is different from CRC-32; CRC-32C starts with a different
34 * polynomial and thus yields different results for the same input
35 * than a traditional CRC-32.
36 */
37uint32_t
38crc32c(const uint8_t* data, size_t nbytes, uint32_t startingChecksum = ~0U);
39
40/**
41 * Compute the CRC-32 checksum of a buffer, using a hardware-accelerated
42 * implementation if available or a portable software implementation as
43 * a default.
44 */
45uint32_t
46crc32(const uint8_t* data, size_t nbytes, uint32_t startingChecksum = ~0U);
47
48/**
49 * Compute the CRC-32 checksum of a buffer, using a hardware-accelerated
50 * implementation if available or a portable software implementation as
51 * a default.
52 *
53 * @note compared to crc32(), crc32_type() uses a different set of default
54 * parameters to match the results returned by boost::crc_32_type and
55 * php's built-in crc32 implementation
56 */
57uint32_t
58crc32_type(const uint8_t* data, size_t nbytes, uint32_t startingChecksum = ~0U);
59
60/**
61 * Given two checksums, combine them in to one checksum.
62 *
63 * Example:
64 * len1 len2
65 * Given a buffer [ checksum 1 | checksum 2 ]
66 * such that the first buffer's crc is checksum1 and has length len1,
67 * and the remainder of the buffer's crc is checksum2 and len 2,
68 * a total checksum over the whole buffer can be made by:
69 *
70 * crc32_combine(checksum1, checksum 2, len2); // len1 not needed.
71 *
72 * Note that this is equivalent to:
73 *
74 * crc32(buffer2, len2, crc32(buffer1, len1));
75 *
76 * However, this allows calculating the checksums in parallel
77 * or calculating checksum 2 before checksum 1.
78 *
79 * Additionally, this is also equivalent, but much slower:
80 * crc2 = crc32(buffer2, len2, 0);
81 * crc1 = crc32(buffer1, len1, 0);
82 * combined = crc2 ^ crc32(buffer_of_all_zeros, len2, crc1);
83 *
84 * crc32[c]_combine is roughly ~10x faster than either of the other
85 * above two examples.
86 */
87uint32_t crc32_combine(uint32_t crc1, uint32_t crc2, size_t crc2len);
88
89/* crc32c_combine is the same as crc32_combine, but uses the crc32c
90 polynomial */
91uint32_t crc32c_combine(uint32_t crc1, uint32_t crc2, size_t crc2len);
92
93} // namespace folly
94