Introduce RVV (#5156)

Summary:
I've verified the successful compilation via docker + qemu combination.

Also, this PR introduces all the needed overrides, which rely on default implementation, but later can be populated with the vectorized code.
Also, fixes a typo in SQ4U.

algoriddle I would appreciate if you could take a look whenever you have time. Thanks!

Pull Request resolved: #5156

Reviewed By: mdouze

Differential Revision: D102911491

Pulled By: mnorris11

fbshipit-source-id: f3555987cdbf8d32a4fbc9d07ec2307f0f8a112a

Author: alexanderguzhva

faiss/CMakeLists.txt

@@ -51,7 +51,12 @@ set(FAISS_SIMD_SVE_SRC
   utils/simd_impl/distances_arm_sve.cpp
 )
 set(FAISS_SIMD_RVV_SRC
+  impl/pq_code_distance/rvv.cpp
   impl/scalar_quantizer/sq-rvv.cpp
+  impl/binary_hamming/rvv.cpp
+  utils/simd_impl/distances_rvv.cpp
+  utils/hamming_distance/hamming_rvv.cpp
+  utils/simd_impl/rabitq_rvv.cpp
 )
 # Select SIMD sources based on target architecture
 if(CMAKE_SYSTEM_PROCESSOR MATCHES "(x86_64|amd64|AMD64)")
@@ -370,6 +375,7 @@ set(FAISS_HEADERS
   utils/hamming_distance/hamming_computer-avx512.h
   utils/hamming_distance/hamming_computer-generic.h
   utils/hamming_distance/hamming_computer-neon.h
+  utils/hamming_distance/hamming_computer-rvv.h
   utils/simd_impl/distances_autovec-inl.h
   utils/simd_impl/distances_simdlib256.h
   utils/hamming_distance/hamming_impl.h

faiss/docs/simd_dynamic_dispatch_migration.md

@@ -4,10 +4,10 @@
 
 Single Instruction, Multiple Data (SIMD) is used heavily in Faiss to speed up
 many types of operations. This includes AVX2, AVX512 (various flavors) for
-x86_64 CPUs and NEON, SVE for ARM CPUs. SIMD code that is run on a machine
-that does not support it will crash with SIGILL (illegal instruction signal),
-therefore it is important to select the right implementation for the current
-machine.
+x86_64 CPUs, NEON and SVE for ARM CPUs, and RVV for RISC-V CPUs. SIMD code
+that is run on a machine that does not support it will crash with SIGILL
+(illegal instruction signal), therefore it is important to select the right
+implementation for the current machine.
 
 Faiss is transitioning from a **monolithic SIMD** model to a **dynamic
 dispatch** model. New code should be written with dynamic dispatch in mind.
@@ -211,12 +211,13 @@ FlatCodesDistanceComputer* get_distance_computer() {
 ```
 
 **Dispatch masks:** `with_simd_level` assumes NONE + AVX2 + AVX512 +
-ARM_NEON implementations exist. If your function has another subset of available
-implementations, it can be passed with
+ARM_NEON + RISCV_RVV implementations exist. If your function has another subset
+of available implementations, it can be passed with
 `with_selected_simd_levels<mask>` with a bitmask of available levels. Missing
 levels in the mask cause the dispatch to **fall through** to the next lower
 level in the same architecture family (x86: AVX512_SPR → AVX512 → AVX2 →
-NONE; ARM: ARM_SVE → ARM_NEON → NONE — x86 and ARM chains are independent):
+NONE; ARM: ARM_SVE → ARM_NEON → NONE; RISC-V: RISCV_RVV → NONE —
+architecture chains are independent):
 
 ```cpp
 // Only NONE, AVX2, and ARM_SVE implementations exist.
@@ -237,7 +238,7 @@ your own with `(1 << int(SIMDLevel::X)) | ...`):
 |------|--------|---------|
 | `AVAILABLE_SIMD_LEVELS_NONE` | NONE only | Scalar-only functions |
 | `AVAILABLE_SIMD_LEVELS_AVX2_NEON` | NONE, AVX2, ARM_NEON | 256-bit `simdlib` ops (`with_simd_level_256bit`) |
-| `AVAILABLE_SIMD_LEVELS_A0` | NONE, AVX2, AVX512, ARM_NEON | Default (`with_simd_level`) |
+| `AVAILABLE_SIMD_LEVELS_A0` | NONE, AVX2, AVX512, ARM_NEON, RISCV_RVV | Default (`with_simd_level`) |
 | `AVAILABLE_SIMD_LEVELS_A1` | A0 + ARM_SVE | Functions with dedicated SVE implementations |
 | `AVAILABLE_SIMD_LEVELS_ALL` | All levels | Identity / diagnostic functions |
 
@@ -265,6 +266,10 @@ set(FAISS_SIMD_SVE_SRC
   # ... existing entries ...
   path/to/functions_sve.cpp         # <-- add (if SVE implementation exists)
 )
+set(FAISS_SIMD_RVV_SRC
+  # ... existing entries ...
+  path/to/functions_rvv.cpp         # <-- add (if RVV implementation exists)
+)
 # Also add any new headers to FAISS_HEADERS
 ```
 
@@ -289,6 +294,7 @@ SIMD_FILES = {
     "path/to/functions_avx2.cpp": (X86_64, AVX2),
     "path/to/functions_avx512.cpp": (X86_64, AVX512),
     "path/to/functions_neon.cpp": (AARCH64, ARM_NEON),
+    "path/to/functions_rvv.cpp": (RISCV64, RISCV_RVV),
 }
 # Also add headers to header_files()
 ```
@@ -377,9 +383,9 @@ The `simdlib` wrappers (`simd8float32_tpl`,
 `simd8uint32_tpl`) provide portable 256-bit and 512-bit operations
 across AVX2, AVX512 and NEON (two 128 bit NEON registers are clumped
 together in 256 bits)
-There is **no simdlib for SVE** (`simdlib_sve.h` does not exist).
-Use raw intrinsics when you need SVE
-(variable-length vectors via `svcntw()`).
+There is **no simdlib for SVE or RVV** (`simdlib_sve.h` and `simdlib_rvv.h`
+do not exist). Use raw intrinsics when you need SVE (variable-length vectors
+via `svcntw()`) or RVV (variable-length vectors via `__riscv_vsetvl*`).
 An example of usage is with `-inl.h` files
 
 **The include order matters** —
@@ -423,11 +429,17 @@ void my_kernel(...) {
    factory/constructor boundary. The constructed object carries its
    `SIMDLevel` as a compile-time template parameter.
 
-5. **Private dispatch machinery.** `simd_dispatch.h` is internal — do not
+5. **Variable-width SIMD is not fixed-width simdlib.** SVE and RVV are
+   variable-width architectures. Do not route them through fixed-width helpers
+   such as `with_simd_level_256bit`, `with_simd_level_512bit`, or
+   `simd8float32_tpl` unless an explicit selector maps them to a supported
+   fixed-width fallback.
+
+6. **Private dispatch machinery.** `simd_dispatch.h` is internal — do not
    include in public headers. The public API is `SIMDConfig` and `SIMDLevel`
    in `utils/simd_levels.h`.
 
-6. **Build system parity.** Every change must be reflected in both
+7. **Build system parity.** Every change must be reflected in both
    CMakeLists.txt and Buck's xplat.bzl.
 
 ## Conversion approach
@@ -470,12 +482,17 @@ cd build_dd && ctest --output-on-failure
 # Verify dispatch at different levels (DD mode only)
 FAISS_SIMD_LEVEL=NONE ctest --output-on-failure
 FAISS_SIMD_LEVEL=AVX2 ctest --output-on-failure
+FAISS_SIMD_LEVEL=RISCV_RVV ctest --output-on-failure
 
 # Also build/test static modes for comparison
 cmake -B build_avx2 -DFAISS_OPT_LEVEL=avx2 -DBUILD_TESTING=ON .
 cmake --build build_avx2 -j$(nproc) && cd build_avx2 && ctest --output-on-failure
 ```
 
+For RVV, build on `riscv64` or cross-build with RISC-V flags and run the
+resulting tests under hardware or QEMU with vector support enabled, for example
+`QEMU_CPU=rv64,v=true`.
+
 ### Buck (internal)
 
 ```bash
@@ -503,3 +520,6 @@ buck2 test -c faiss.dynamic_dispatch=true fbcode//faiss/tests:test_your_module
 - Building with CMake's default `FAISS_OPT_LEVEL=generic` and thinking DD is
   enabled — generic mode has no SIMD and no dispatch. Use
   `FAISS_OPT_LEVEL=dd` explicitly.
+- Treating SVE or RVV as fixed-width `simdlib` backends — they are
+  variable-width ISAs and need raw-intrinsic implementations or explicit scalar
+  fallbacks for fixed-width helper paths.

faiss/impl/binary_hamming/rvv.cpp

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#ifdef COMPILE_SIMD_RISCV_RVV
+
+#define THE_SIMD_LEVEL SIMDLevel::RISCV_RVV
+
+// NOLINTNEXTLINE(facebook-hte-InlineHeader)
+#include <faiss/utils/hamming_distance/hamming_computer-rvv.h>
+
+// NOLINTNEXTLINE(facebook-hte-InlineHeader)
+#include <faiss/impl/binary_hamming/IndexBinaryHNSW_impl.h>
+// NOLINTNEXTLINE(facebook-hte-InlineHeader)
+#include <faiss/impl/binary_hamming/IndexBinaryHash_impl.h>
+// NOLINTNEXTLINE(facebook-hte-InlineHeader)
+#include <faiss/impl/binary_hamming/IndexBinaryIVF_impl.h>
+// NOLINTNEXTLINE(facebook-hte-InlineHeader)
+#include <faiss/impl/binary_hamming/IndexIVFSpectralHash_impl.h>
+// NOLINTNEXTLINE(facebook-hte-InlineHeader)
+#include <faiss/impl/binary_hamming/IndexPQ_impl.h>
+
+#endif // COMPILE_SIMD_RISCV_RVV

faiss/impl/fast_scan/fast_scan.cpp

@@ -416,6 +416,82 @@ void accumulate_to_mem(
 
 namespace faiss {
 
+#ifdef COMPILE_SIMD_RISCV_RVV
+template <>
+std::unique_ptr<FastScanCodeScanner> make_fast_scan_scanner_impl<
+        SIMDLevel::RISCV_RVV>(
+        bool is_max,
+        int impl,
+        size_t nq,
+        size_t ntotal,
+        int64_t k,
+        float* distances,
+        int64_t* ids,
+        const IDSelector* sel,
+        bool with_id_map) {
+    return make_fast_scan_scanner_impl<SIMDLevel::NONE>(
+            is_max, impl, nq, ntotal, k, distances, ids, sel, with_id_map);
+}
+
+template <>
+std::unique_ptr<FastScanCodeScanner> make_range_scanner_impl<
+        SIMDLevel::RISCV_RVV>(
+        bool is_max,
+        RangeSearchResult& rres,
+        float radius,
+        size_t ntotal,
+        const IDSelector* sel) {
+    return make_range_scanner_impl<SIMDLevel::NONE>(
+            is_max, rres, radius, ntotal, sel);
+}
+
+template <>
+std::unique_ptr<FastScanCodeScanner> make_partial_range_scanner_impl<
+        SIMDLevel::RISCV_RVV>(
+        bool is_max,
+        RangeSearchPartialResult& pres,
+        float radius,
+        size_t ntotal,
+        size_t q0,
+        size_t q1,
+        const IDSelector* sel) {
+    return make_partial_range_scanner_impl<SIMDLevel::NONE>(
+            is_max, pres, radius, ntotal, q0, q1, sel);
+}
+
+template <>
+std::unique_ptr<FastScanCodeScanner> rabitq_make_knn_scanner_impl<
+        SIMDLevel::RISCV_RVV>(
+        const IndexRaBitQFastScan* index,
+        bool is_max,
+        size_t nq,
+        int64_t k,
+        float* distances,
+        int64_t* ids,
+        const IDSelector* sel,
+        const FastScanDistancePostProcessing& context,
+        bool is_multi_bit) {
+    return rabitq_make_knn_scanner_impl<SIMDLevel::NONE>(
+            index, is_max, nq, k, distances, ids, sel, context, is_multi_bit);
+}
+
+template <>
+std::unique_ptr<FastScanCodeScanner> rabitq_ivf_make_knn_scanner_impl<
+        SIMDLevel::RISCV_RVV>(
+        bool is_max,
+        const IndexIVFRaBitQFastScan* index,
+        size_t nq,
+        size_t k,
+        float* distances,
+        int64_t* ids,
+        const IDSelector* sel,
+        const FastScanDistancePostProcessing* context,
+        bool multi_bit) {
+    return rabitq_ivf_make_knn_scanner_impl<SIMDLevel::NONE>(
+            is_max, index, nq, k, distances, ids, sel, context, multi_bit);
+}
+#endif // COMPILE_SIMD_RISCV_RVV
+
 std::unique_ptr<FastScanCodeScanner> make_fast_scan_knn_scanner(
         bool is_max,
         int impl,

faiss/impl/pq_code_distance/rvv.cpp

@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#ifdef COMPILE_SIMD_RISCV_RVV
+
+#include <faiss/impl/pq_code_distance/pq_code_distance-inl.h>
+
+namespace faiss {
+namespace pq_code_distance {
+
+// RISCV_RVV: no RVV-optimized PQ code distance exists yet. Use scalar.
+
+// NOLINTNEXTLINE(facebook-hte-MisplacedTemplateSpecialization)
+template <>
+float pq_code_distance_8bit_single_impl<SIMDLevel::RISCV_RVV>(
+        size_t M,
+        const float* sim_table,
+        const uint8_t* code) {
+    return PQCodeDistanceScalar<PQDecoder8>::distance_single_code(
+            M, 8, sim_table, code);
+}
+
+// NOLINTNEXTLINE(facebook-hte-MisplacedTemplateSpecialization)
+template <>
+void pq_code_distance_8bit_four_impl<SIMDLevel::RISCV_RVV>(
+        size_t M,
+        const float* sim_table,
+        const uint8_t* __restrict code0,
+        const uint8_t* __restrict code1,
+        const uint8_t* __restrict code2,
+        const uint8_t* __restrict code3,
+        float& result0,
+        float& result1,
+        float& result2,
+        float& result3) {
+    PQCodeDistanceScalar<PQDecoder8>::distance_four_codes(
+            M,
+            8,
+            sim_table,
+            code0,
+            code1,
+            code2,
+            code3,
+            result0,
+            result1,
+            result2,
+            result3);
+}
+
+} // namespace pq_code_distance
+} // namespace faiss
+
+#define THE_SIMD_LEVEL SIMDLevel::RISCV_RVV
+
+// NOLINTNEXTLINE(facebook-hte-InlineHeader)
+#include <faiss/utils/hamming_distance/hamming_computer-rvv.h>
+// NOLINTNEXTLINE(facebook-hte-InlineHeader)
+#include <faiss/impl/pq_code_distance/PQDistanceComputer_impl.h>
+// NOLINTNEXTLINE(facebook-hte-InlineHeader)
+#include <faiss/impl/pq_code_distance/IVFPQScanner_impl.h>
+
+#undef THE_SIMD_LEVEL
+
+#endif // COMPILE_SIMD_RISCV_RVV

faiss/impl/scalar_quantizer/sq-rvv.cpp

@@ -186,7 +186,7 @@ struct DCTemplate<
         const float inv_scale = (vdiff == 0.0f) ? 0.0f : 15.0f / vdiff;
         for (size_t i = 0; i < d; i++) {
             float val = (x[i] - vmin) * inv_scale;
-            int code = static_cast<int>(std::floor(val + 0.5f));
+            int code = static_cast<int>(val);
             if (code < 0) {
                 code = 0;
             }

faiss/impl/simd_dispatch.h

@@ -32,9 +32,9 @@ constexpr int AVAILABLE_SIMD_LEVELS_NONE = (1 << int(SIMDLevel::NONE));
 constexpr int AVAILABLE_SIMD_LEVELS_AVX2_NEON = AVAILABLE_SIMD_LEVELS_NONE |
         (1 << int(SIMDLevel::AVX2)) | (1 << int(SIMDLevel::ARM_NEON));
 
-// A0: same + AVX512
-constexpr int AVAILABLE_SIMD_LEVELS_A0 =
-        AVAILABLE_SIMD_LEVELS_AVX2_NEON | (1 << int(SIMDLevel::AVX512));
+// A0: same + AVX512 + RISCV_RVV
+constexpr int AVAILABLE_SIMD_LEVELS_A0 = AVAILABLE_SIMD_LEVELS_AVX2_NEON |
+        (1 << int(SIMDLevel::AVX512)) | (1 << int(SIMDLevel::RISCV_RVV));
 
 // A1: same + ARM_SVE (for functions with dedicated SVE implementations)
 constexpr int AVAILABLE_SIMD_LEVELS_A1 =
@@ -147,8 +147,8 @@ inline auto with_selected_simd_levels(LambdaType&& action) {
  *   });
  *
  * The lambda must be a generic lambda with a SIMDLevel template parameter.
- * By default, the lambda uses levels AVX2 + AVX512 + NEON, since these are the
- * most common cases.
+ * By default, the lambda uses levels AVX2 + AVX512 + NEON + RVV, since these
+ * are the most common cases.
  *
  * @param action A generic lambda with signature `template<SIMDLevel> T
  * operator()()`

faiss/utils/distances_fused/distances_fused.cpp

@@ -24,6 +24,20 @@ bool exhaustive_L2sqr_fused_cmax<SIMDLevel::NONE>(
     return false;
 }
 
+#ifdef COMPILE_SIMD_RISCV_RVV
+template <>
+bool exhaustive_L2sqr_fused_cmax<SIMDLevel::RISCV_RVV>(
+        const float*,
+        const float*,
+        size_t,
+        size_t,
+        size_t,
+        Top1BlockResultHandler<CMax<float, int64_t>>&,
+        const float*) {
+    return false;
+}
+#endif // COMPILE_SIMD_RISCV_RVV
+
 bool exhaustive_L2sqr_fused_cmax(
         const float* x,
         const float* y,