Add NIC IRQ affinity tuning support (#528)

Summary:

Add NIC IRQ affinity configuration to ucache_bench, ported from TaoBench.
This feature distributes network interrupt processing across CPUs to prevent
IRQ handling from bottlenecking on a few cores.

New parameters:
- nic_channel_ratio: Ratio of NIC channels to logical cores (0.0 = disabled)
- interface_name: Network interface for IRQ affinity tuning (default: eth0)
- hard_binding: Hard bind NIC channels to specific CPU cores (default: 0)

Changes:
- Add affinitize_nic() function to configure NIC channels via ethtool and
  redistribute IRQ affinity using affinitize_nic.py script
- Add new CLI arguments to server: --nic-channel-ratio, --interface-name,
  --hard-binding
- Update install script to copy affinitize_nic scripts for OSS builds
- Add NIC affinity params to benchmark configs and jobs_internal.yml
- Add ucache_bench_debug_nic_affinity_configs.json for testing

Differential Revision: D96763816

Author: charles-typ

packages/ucache_bench/install_ucache_bench.sh

@@ -747,6 +747,17 @@ else
     echo "  WARNING: ucachebench_client binary not found"
 fi
 
+# Copy affinitize NIC scripts for IRQ affinity tuning
+AFFINITIZE_SRC="$BENCHPRESS_ROOT/packages/common/affinitize"
+AFFINITIZE_DST="$UCACHE_BENCH_DIR/affinitize"
+if [ -d "$AFFINITIZE_SRC" ]; then
+    echo "Copying affinitize NIC scripts..."
+    mkdir -p "$AFFINITIZE_DST"
+    cp -r "$AFFINITIZE_SRC/"* "$AFFINITIZE_DST/"
+    chmod +x "$AFFINITIZE_DST/affinitize_nic.py" 2>/dev/null || true
+    echo "  Installed: $AFFINITIZE_DST/"
+fi
+
 echo ""
 echo "=============================================="
 echo "UCacheBench Installation Complete!"

packages/ucache_bench/run.py

@@ -31,6 +31,7 @@
 
 BENCHPRESS_ROOT: pathlib.Path = pathlib.Path(os.path.abspath(__file__)).parents[2]
 UCACHE_BENCH_DIR: str = os.path.join(BENCHPRESS_ROOT, "benchmarks", "ucache_bench")
+AFFINITIZE_NIC_SYSTEM_PATH: str = "/usr/local/bin/affinitize_nic"
 
 # Constants
 MEM_USAGE_FACTOR = 0.75  # to prevent OOM
@@ -158,6 +159,78 @@ def profile_server() -> None:
     )
 
 
+def get_affinitize_nic_path() -> str:
+    """Get path to the affinitize_nic script.
+
+    Checks system path first, then common packages dir, falls back to
+    benchmark-local copy (created by install script for OSS builds).
+    """
+    if os.path.exists(AFFINITIZE_NIC_SYSTEM_PATH):
+        return AFFINITIZE_NIC_SYSTEM_PATH
+    # Internal fbpkg: shared utility in packages/common/affinitize/
+    common_path = os.path.join(
+        BENCHPRESS_ROOT, "packages", "common", "affinitize", "affinitize_nic.py"
+    )
+    if os.path.exists(common_path):
+        return common_path
+    # OSS: copied by install script to benchmark dir
+    return os.path.join(UCACHE_BENCH_DIR, "affinitize", "affinitize_nic.py")
+
+
+def affinitize_nic(args: argparse.Namespace) -> None:
+    """Configure NIC IRQ affinity to distribute interrupts across CPUs.
+
+    This prevents IRQ processing from bottlenecking on a few cores.
+    Ported from TaoBench's NIC affinity tuning.
+
+    Steps:
+    1. Set the number of NIC combined channels using ethtool
+    2. Redistribute IRQ affinity across CPUs using affinitize_nic.py
+    """
+    n_cores = len(os.sched_getaffinity(0))
+    n_channels = int(n_cores * args.nic_channel_ratio)
+
+    if n_channels <= 0:
+        print(
+            f"Skipping NIC affinity: n_channels={n_channels} "
+            f"(cores={n_cores}, ratio={args.nic_channel_ratio})"
+        )
+        return
+
+    # Step 1: Set NIC channel count
+    try:
+        cmd = ["ethtool", "-L", args.interface_name, "combined", str(n_channels)]
+        print(f"Setting NIC channels: {' '.join(cmd)}")
+        subprocess.run(cmd, check=True, capture_output=True)
+    except (subprocess.CalledProcessError, FileNotFoundError, OSError) as e:
+        print(f"Failed to set NIC channels to {n_channels}: {e}")
+
+    # Step 2: Set IRQ affinity
+    try:
+        cmd = [
+            get_affinitize_nic_path(),
+            "-f",
+            "-a",
+            "--xps",
+        ]
+        if args.hard_binding:
+            cmd += [
+                "--cpu",
+                " ".join(str(x) for x in range(n_channels)),
+            ]
+        else:
+            cmd += [
+                "-A",
+                "all-nodes",
+                "--max-cpus",
+                str(n_channels),
+            ]
+        print(f"Setting NIC IRQ affinity: {' '.join(cmd)}")
+        subprocess.run(cmd, check=True, capture_output=True)
+    except (subprocess.CalledProcessError, FileNotFoundError, OSError) as e:
+        print(f"Failed to set NIC IRQ affinity: {e}")
+
+
 def run_server(args: argparse.Namespace) -> None:
     """Run the UcacheBench server.
 
@@ -177,6 +250,10 @@ def run_server(args: argparse.Namespace) -> None:
         hash_power = calculate_hash_power(memory_mb)
         print(f"Auto-calculated hash_power={hash_power} for {memory_mb}MB memory")
 
+    # Configure NIC IRQ affinity before starting server
+    if args.interface_name != "lo" and args.nic_channel_ratio > 0:
+        affinitize_nic(args)
+
     print(
         f"Starting UcacheBench server with {args.memory_mb}MB memory on port {args.port}"
     )
@@ -522,6 +599,27 @@ def init_parser() -> argparse.ArgumentParser:
         help="Reduce IO thread count to match non-IRQ CPU count (set to non-zero to enable)",
     )
 
+    # NIC IRQ affinity configuration (ported from TaoBench)
+    server_parser.add_argument(
+        "--nic-channel-ratio",
+        type=float,
+        default=0.0,
+        help="Ratio of NIC channels to logical cores (0.0 = disabled, 0.5 = TaoBench default). "
+        "Sets ethtool combined channels and redistributes IRQ affinity.",
+    )
+    server_parser.add_argument(
+        "--interface-name",
+        type=str,
+        default="eth0",
+        help="Network interface name for NIC IRQ affinity tuning",
+    )
+    server_parser.add_argument(
+        "--hard-binding",
+        type=int,
+        default=0,
+        help="Hard bind NIC channels to specific CPU cores (set to non-zero to enable)",
+    )
+
     # Navy (hybrid mode) configuration
     server_parser.add_argument(
         "--navy-cache-path",