relax codes%8 condition on Hamming distance

Summary:
`faiss::hammings()` used to `FAISS_THROW_IF_NOT(ncodes % 8 == 0)`, even though the other Hamming entry points (`hammings_knn_hc`, `hamming_range_search`) have always accepted code sizes that are not a whole number of 64-bit words. This lifts that restriction so `hammings()` matches the rest of the API.

Ragged sizes are routed to a new out-of-line helper, `hammings_ragged()`, built on the existing `HammingComputer` family (which already carries a byte tail). Multiples of 8 keep taking the word-level kernels exactly as before, so there is no behavior change for existing callers.

Also adds a `FAISS_NOINLINE` macro to `platform_macros.h` (MSVC `__declspec(noinline)` / GCC-Clang `__attribute__((noinline))`), used to keep `hammings_ragged()` out of line.

## Why FAISS_NOINLINE

Letting the compiler inline `hammings_ragged()` into `hammings_fixSL()` instantiates the whole `HammingComputer` family into that function and roughly doubles its size (3,597 -> 7,565 bytes at the AVX2 level). That measurably slows the word-level code sizes that share the runtime-nwords loop.

Benchmarked on a Xeon 8339HC (Cooper Lake, AVX-512), `mode/opt`, na=256 x nb=4096 = 1M pairs per call, one code size per process, A/B interleaved with order flipping, 300-400 samples per cell, replicated on two cores. Positive = inlining is slower, i.e. `noinline` wins.

| ncodes | static AVX2 | dynamic dispatch (AVX512) |
| --- | --- | --- |
| 8, 16, 32, 64, 128 | ~0% | ~0% |
| 24 | +3.4% | +53% |
| 40 | +5.0% | +22% |
| 48 | ~0% | +28% |
| 56 | +4.4% | +35% |
| 12, 20, 33 (ragged) | -5% | -5% to -12% |

Two distinct mechanisms, both confirmed in the disassembly:

- **Static AVX2** - the inlined version has higher register pressure and spills, adding exactly one reload per pair in the shared outer loop. Retired instruction counts (noise-free) show +1.00 instr/pair at ncodes 24/40/48/56 and 0.00 at 8/16/32/64/128.
- **Dynamic dispatch** - the popcount inner loop is a byte-identical 24-byte sequence in both builds, but out of line it starts at `%32 == 0` (one 32-byte fetch window) and inlined at `%32 == 16` (straddles two). IPC drops 3.02 -> 2.36 at identical clock. This one is a code-placement effect: it is real today but is not something `noinline` reliably controls, and it could invert on a compiler upgrade.

Note that the dedicated `ncodes` 8/16/32/64 kernels are unaffected either way - they have their own specialized `hammings_impl<nbits>` blocks that the ragged inline never touches.

The trade: the ragged path itself is ~5% slower for being out of line. That is accepted here because the word-level sizes are the common case and are the ones that were already supported.

Differential Revision: D115982541

Author: Michael Norris

faiss/impl/platform_macros.h

@@ -104,6 +104,7 @@ inline int __builtin_clzll(uint64_t x) {
 #endif // _MSC_VER
 
 #define FAISS_ALWAYS_INLINE __forceinline
+#define FAISS_NOINLINE __declspec(noinline)
 
 // MSVC uses pragma pack instead of __attribute__((packed))
 // Use FAISS_PACK_STRUCTS_BEGIN/END to wrap packed structure definitions
@@ -137,6 +138,7 @@ inline int __builtin_clzll(uint64_t x) {
 #define FAISS_PACK_STRUCTS_END
 
 #define FAISS_ALWAYS_INLINE __attribute__((always_inline)) inline
+#define FAISS_NOINLINE __attribute__((noinline))
 
 #endif
 

faiss/utils/hamming.h

@@ -111,7 +111,7 @@ FAISS_API extern size_t hamming_batch_size;
  *
  * @param  a             size na * nbytespercode
  * @param  b             size nb * nbytespercode
- * @param  nbytespercode should be multiple of 8
+ * @param  nbytespercode any size; multiples of 8 take a faster kernel
  * @param  dis           output distances, size na * nb
  */
 void hammings(

faiss/utils/hamming_distance/hamming_impl.h

@@ -298,6 +298,25 @@ void generalized_hammings_knn_hc_impl(
     }
 }
 
+FAISS_NOINLINE void hammings_ragged(
+        const uint8_t* __restrict a,
+        const uint8_t* __restrict b,
+        size_t na,
+        size_t nb,
+        size_t ncodes,
+        hamdis_t* __restrict dis) {
+    with_HammingComputer<THE_SIMD_LEVEL>(ncodes, [&]<class HammingComputer>() {
+        for (size_t i = 0; i < na; i++) {
+            HammingComputer hc(a + i * ncodes, ncodes);
+            const uint8_t* bi = b;
+            for (size_t j = 0; j < nb; j++) {
+                dis[i * nb + j] = hc.hamming(bi);
+                bi += ncodes;
+            }
+        }
+    });
+}
+
 } // anonymous namespace
 
 /******************************************************************
@@ -364,7 +383,19 @@ void hammings_fixSL<THE_SIMD_LEVEL>(
         size_t nb,
         size_t ncodes,
         hamdis_t* dis) {
-    FAISS_THROW_IF_NOT(ncodes % 8 == 0);
+    // Ragged sizes take the out-of-line HammingComputer path. Keeping it out
+    // of line matters: inlining it here instantiates the whole computer family
+    // into this function (roughly doubling its size) and slows the word-level
+    // sizes that share the runtime-nwords loop below. Measured at ncodes
+    // 24/40/48/56: +3-5% under static AVX2, where the inlined version spills
+    // and reloads once more per pair, and +22-56% under dynamic dispatch, where
+    // the (byte-identical) hot loop stops landing on a 32-byte boundary. The
+    // dedicated 8/16/32/64 kernels are unaffected either way. The ragged path
+    // itself pays ~5% for being out of line, which is the trade made here.
+    if (ncodes % 8 != 0) {
+        hammings_ragged(a, b, na, nb, ncodes, dis);
+        return;
+    }
     switch (ncodes) {
         case 8:
             hammings_impl<64>(C64(a), C64(b), na, nb, dis);

tests/test_hamming.cpp

@@ -333,3 +333,44 @@ TEST(TestHamming, test_hamming_knn) {
         EXPECT_EQ(dist_gen, *true_bit_distances) << assert_str.str();
     }
 }
+
+// Code sizes that are not a whole number of 64-bit words take the byte-tail
+// kernel rather than the word-level one. The knn entry points have always
+// accepted them; hammings() used to throw instead.
+TEST(TestHamming, test_hammings_ragged_code_size) {
+    std::default_random_engine rng(123);
+    std::uniform_int_distribution<int32_t> uniform(0, 255);
+
+    const size_t na = 3;
+    const size_t nb = 7;
+
+    for (auto code_size : {1, 2, 5, 12, 20, 33}) {
+        std::vector<uint8_t> a(na * code_size);
+        std::vector<uint8_t> b(nb * code_size);
+        for (auto& v : a) {
+            v = uniform(rng);
+        }
+        for (auto& v : b) {
+            v = uniform(rng);
+        }
+
+        // Reference: byte-wise popcount of the XOR, independent of faiss.
+        std::vector<hamdis_t> expected(na * nb);
+        for (size_t i = 0; i < na; ++i) {
+            for (size_t j = 0; j < nb; ++j) {
+                int d = 0;
+                for (int c = 0; c < code_size; ++c) {
+                    d += __builtin_popcount(
+                            static_cast<unsigned>(
+                                    a[i * code_size + c] ^
+                                    b[j * code_size + c]));
+                }
+                expected[i * nb + j] = d;
+            }
+        }
+
+        std::vector<hamdis_t> dis(na * nb);
+        faiss::hammings(a.data(), b.data(), na, nb, code_size, dis.data());
+        EXPECT_EQ(dis, expected) << "code_size = " << code_size;
+    }
+}