github.com/cilium/cilium@v1.16.2/bpf/lib/ghash.h (about)

     1  /* SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) */
     2  /* Copyright Authors of Cilium */
     3  
     4  #pragma once
     5  
     6  #define U32MAX_DIV_GOLDEN_RATIO 0x9e3779b9
     7  
     8  /* Calculate the Fibonacci hash of @key and return the @bits-wide value.
     9   *
    10   * h(k, n) is defined as n fractional bits of k / phi, where phi is the golden
    11   * ratio: phi = (sqrt(5) + 1) / 2
    12   *
    13   * It can be calculated as h(k, n) = [ {k / phi} * 2^n ], where square brackets
    14   * denote the integer part, and curly braces denote the fractional part. In
    15   * order to calculate it using integer arithmetic and to avoid an expensive
    16   * division, the formula can be multiplied and divided by 2^32, and 2^32 / phi
    17   * can be precalculated:
    18   *
    19   * h(k, n) = ((k * (2^32/phi)) % 2^32) / 2^(32-n)
    20   *         = ((k * A) % 2^32) / 2^(32-n)                                     (1)
    21   * (modulo 2^32 is implicit, and division by a power of two is a bit shift)
    22   *
    23   * Uniformity of the output values follows from theorem [1]. If we take the
    24   * interval [0, 1] and start adding points {1 / phi}, {2 / phi}, {3 / phi}, ...
    25   * (where curly braces denote the fractional part) into this interval, each new
    26   * point will split some subinterval of [0, 1] into two new subintervals. The
    27   * theorem claims that each new point splits the largest subinterval, and the
    28   * ratio between the new parts is not bigger than 2:1 (larger to smaller). This
    29   * means that the above sequence has low discrepancy, and the points are spread
    30   * uniformly enough over [0, 1]. Scaling up the interval [0, 1] to [0, 2^n] and
    31   * throwing away the fractional part, we get a hash function that spreads output
    32   * values uniformly for consecutive inputs.
    33   *
    34   * The completeness of the output range is guaranteed because in the actual
    35   * integer calculation GCD(A, 2^32) = 1, meaning that there is an inverse
    36   * element A^-1, such that (A * A^-1) mod 2^32 = 1, so for any value v of the
    37   * hash function there is a key k = (v * A^-1) mod 2^32, such that h(k) = v.
    38   *
    39   * Even though formula (1) resembles the formula for a multiplicative hash:
    40   * h(k) = (k * A) % m, where GCD(A, m) = 1,                                  (2)
    41   * formula (1) has an important difference. Instead of taking the least
    42   * significant bits of (k * A), it takes the most significant bits, hence it
    43   * doesn't discard the MSBs of the key, unlike formula (2). Such a modification
    44   * provides better distribution for keys with common lower bits, but it poses
    45   * more restrictions on A. Even some prime values of A become problematic, for
    46   * example, when A = 2576980349, 4 MSBs of (k * A) loop over 0x9, 0x3, 0xc, 0x6,
    47   * 0xf for k = 1 .. 1877171. Applicability of A = (2^32 / phi) is proven above
    48   * using theorem [1].
    49   *
    50   * [1]: Knuth. The Art of Computer Programming (2nd edition), vol. 3, sec. 6.4,
    51   * ex. 9 (page 550, solution on page 729).
    52   */
    53  static __always_inline __u32 hash_32(__u32 key, __u32 bits)
    54  {
    55  	return (key * U32MAX_DIV_GOLDEN_RATIO) >> (32 - bits);
    56  }