feat(adapter): implement lock-free rte_ring IPC for LD_PRELOAD - FF_USE_RING_IPC

Implement dual-ring SPSC IPC model to replace sem_wait/sem_post synchronization
between APP and fstack processes, controlled by FF_USE_RING_IPC compile macro.

Core changes:
- Makefile: Add FF_USE_RING_IPC macro with FF_PRELOAD_POLLING_MODE mutual exclusion
- ff_socket_ops.h: Add ff_sc_ring_zone struct (64B cache-aligned), modify ff_so_context
  (sem_t -> completion+ring_zone_id+reserved), add ring IPC function declarations
- ff_so_zone.c: Implement ff_create_sc_ring_zone/ff_attach_sc_ring_zone for Hugepage
  ring creation, conditional sem_init bypass in ring mode
- ff_socket_ops.c: Add ff_handle_socket_ops_ring callback, rewrite ff_handle_each_context
  to O(1) rte_ring_dequeue_burst, implement ff_ring_process_requests/send_response/
  dequeue_wait/alarm_wakeup helper functions
- ff_hook_syscall.c: Rewrite ACQUIRE/RELEASE_ZONE_LOCK/SYSCALL macros for ring mode,
  implement ff_ring_submit_and_wait, add ring-mode epoll_wait/kevent with rte_rdtsc
  high-precision timeout, replace alarm_event_sem with ring sentinel

Key design decisions:
- SPSC mode (RING_F_SP_ENQ|RING_F_SC_DEQ) for zero-CAS overhead
- Three configurable wait strategies: busy-poll/yield-poll/eventfd
- All changes under #ifdef FF_USE_RING_IPC, original sem path fully preserved
- Cache line alignment maintained for all modified structures

Performance targets: syscall RTT < 1us, throughput >= 10% improvement

Refs: SPEC-001 (requirements), SPEC-002 (architecture), SPEC-003 (interfaces)

Author: jfb8856606

adapter/syscall/Makefile

@@ -21,6 +21,10 @@ endif
 # If disable it, epoll use sem_wait.
 #FF_PRELOAD_POLLING_MODE=1
 
+# Lock-free ring IPC mode, replace sem_wait/sem_post with rte_ring.
+# If enable it, FF_PRELOAD_POLLING_MODE must be disabled.
+#FF_USE_RING_IPC=1
+
 # If enable FF_KERNEL_EVENT, epoll_create/epoll_clt/epoll_wait always call f-stack and system API at the same time.
 # Use for some scenarios similar to Nginx.
 #FF_KERNEL_EVENT=1
@@ -59,6 +63,13 @@ ifdef FF_PRELOAD_POLLING_MODE
 	CFLAGS+= -DFF_PRELOAD_POLLING_MODE
 endif
 
+ifdef FF_USE_RING_IPC
+ifdef FF_PRELOAD_POLLING_MODE
+$(error "FF_USE_RING_IPC and FF_PRELOAD_POLLING_MODE are mutually exclusive")
+endif
+	CFLAGS+= -DFF_USE_RING_IPC
+endif
+
 ifdef FF_USE_THREAD_STRUCT_HANDLE
 	CFLAGS+= -DFF_USE_THREAD_STRUCT_HANDLE
 endif

adapter/syscall/ff_hook_syscall.c

@@ -12,6 +12,12 @@
 
 #include <rte_malloc.h>
 #include <rte_memcpy.h>
+#ifdef FF_USE_RING_IPC
+#include <rte_ring.h>
+#include <rte_cycles.h>
+#include <sys/eventfd.h>
+#include <sched.h>
+#endif
 
 #include "ff_config.h"
 #include "ff_socket_ops.h"
@@ -111,6 +117,38 @@ static __thread int sh_iov_static_fill_idx_share = 0;
     }                                                             \
     args = name##_args;
 
+#ifdef FF_USE_RING_IPC
+/*
+ * Ring mode macros: ACQUIRE/RELEASE_ZONE_LOCK are not used in the
+ * normal request path (SYSCALL macro is rewritten), but kept as
+ * no-ops to prevent compilation errors from any residual references.
+ */
+#define ACQUIRE_ZONE_LOCK(exp) do { (void)(exp); } while (0)
+#define ACQUIRE_ZONE_TRY_LOCK(exp) ACQUIRE_ZONE_LOCK(exp)
+#define RELEASE_ZONE_LOCK(s) do { (void)(s); } while (0)
+
+/*
+ * Ring mode SYSCALL: enqueue to req_ring, wait on rsp_ring.
+ * No spinlock, no status machine — ring operations are lock-free.
+ */
+#define SYSCALL(op, arg) do {                                     \
+    sc->ops = (op);                                               \
+    sc->args = (arg);                                             \
+    sc->result = 0;                                               \
+    sc->error = 0;                                                \
+    if (ff_ring_submit_and_wait(ff_so_zone->ring_zone, sc, -1) < 0) { \
+        errno = ETIMEDOUT;                                        \
+        ret = -1;                                                 \
+    } else {                                                      \
+        ret = sc->result;                                         \
+        if (ret < 0) {                                            \
+            errno = sc->error;                                    \
+        }                                                         \
+    }                                                             \
+} while (0)
+
+#else /* !FF_USE_RING_IPC */
+
 /* Dirty read first, and then try to lock sc and real read. */
 #define ACQUIRE_ZONE_LOCK(exp) do {                               \
     while (1) {                                                   \
@@ -159,6 +197,8 @@ static __thread int sh_iov_static_fill_idx_share = 0;
     RELEASE_ZONE_LOCK(FF_SC_IDLE);                                \
 } while (0)
 
+#endif /* FF_USE_RING_IPC */
+
 #define RETURN_NOFREE() do {                                      \
     DEBUG_LOG("RETURN_NOFREE ret:%d, errno:%d\n", ret, errno);    \
     return ret;                                                   \
@@ -245,7 +285,9 @@ static int ff_kernel_max_fd = FF_KERNEL_MAX_FD_DEFAULT;
 #endif
 
 /* not support thread socket now */
+#ifndef FF_USE_RING_IPC
 static int need_alarm_sem = 0;
+#endif
 
 #define count_trailing_zeros(x) __builtin_ctzll(x)
 
@@ -2152,7 +2194,9 @@ ff_hook_epoll_wait(int epfd, struct epoll_event *events,
 {
     DEBUG_LOG("ff_hook_epoll_wait, epfd:%d, maxevents:%d, timeout:%d\n", epfd, maxevents, timeout);
     int fd = epfd;
+#ifndef FF_USE_RING_IPC
     struct timespec abs_timeout;
+#endif
 
     CHECK_FD_OWNERSHIP(epoll_wait, (epfd, events, maxevents, timeout));
 
@@ -2190,6 +2234,7 @@ ff_hook_epoll_wait(int epfd, struct epoll_event *events,
         }
     }
 
+#ifndef FF_USE_RING_IPC
     if (timeout > 0) {
         clock_gettime(CLOCK_REALTIME, &abs_timeout);
         DEBUG_LOG("before wait, sec:%ld, nsec:%ld\n", abs_timeout.tv_sec, abs_timeout.tv_nsec);
@@ -2206,13 +2251,48 @@ ff_hook_epoll_wait(int epfd, struct epoll_event *events,
             RETURN_ERROR_NOFREE(EINVAL);
         }
     }
+#endif
 
     args->epfd = fd;
     args->events = sh_events;
     args->maxevents = maxevents;
     args->timeout = timeout;
 
 RETRY:
+#ifdef FF_USE_RING_IPC
+    {
+        int64_t timeout_us;
+        if (timeout < 0) {
+            timeout_us = -1;       /* block forever */
+        } else if (timeout == 0) {
+            timeout_us = 0;        /* non-blocking */
+        } else {
+            timeout_us = (int64_t)timeout * 1000;  /* ms -> us */
+        }
+
+        args->epfd = fd;
+        args->events = sh_events;
+        args->maxevents = maxevents;
+        args->timeout = timeout;
+
+        sc->ops = FF_SO_EPOLL_WAIT;
+        sc->args = args;
+        sc->result = 0;
+        sc->error = 0;
+        errno = 0;
+
+        ret = ff_ring_submit_and_wait(ff_so_zone->ring_zone, sc, timeout_us);
+
+        if (ret == -ETIMEDOUT) {
+            ret = 0;  /* timeout: 0 events */
+        } else {
+            ret = sc->result;
+            if (ret < 0) {
+                errno = sc->error;
+            }
+        }
+    }
+#else /* !FF_USE_RING_IPC */
     /* for timeout, Although not really effective in FreeBSD stack */
     //SYSCALL(FF_SO_EPOLL_WAIT, args);
     ACQUIRE_ZONE_LOCK(FF_SC_IDLE);
@@ -2296,6 +2376,7 @@ ff_hook_epoll_wait(int epfd, struct epoll_event *events,
 
     sc->status = FF_SC_IDLE;
     rte_spinlock_unlock(&sc->lock);
+#endif /* !FF_USE_RING_IPC */
 
     if (likely(ret > 0)) {
         if (unlikely(ret > maxevents)) {
@@ -2512,6 +2593,33 @@ kevent(int kq, const struct kevent *changelist, int nchanges,
     args->kq = kq;
     args->timeout = (struct timespec *)timeout;
 
+#ifdef FF_USE_RING_IPC
+    {
+        int64_t timeout_us;
+        if (timeout == NULL) {
+            timeout_us = -1;       /* block forever */
+        } else {
+            timeout_us = timeout->tv_sec * 1000000LL + timeout->tv_nsec / 1000;
+        }
+
+        sc->ops = FF_SO_KEVENT;
+        sc->args = args;
+        sc->result = 0;
+        sc->error = 0;
+        errno = 0;
+
+        ret = ff_ring_submit_and_wait(ff_so_zone->ring_zone, sc, timeout_us);
+
+        if (ret == -ETIMEDOUT) {
+            ret = 0;  /* timeout: 0 events */
+        } else {
+            ret = sc->result;
+            if (ret < 0) {
+                errno = sc->error;
+            }
+        }
+    }
+#else /* !FF_USE_RING_IPC */
     ACQUIRE_ZONE_LOCK(FF_SC_IDLE);
     //rte_spinlock_lock(&sc->lock);
 
@@ -2583,6 +2691,7 @@ kevent(int kq, const struct kevent *changelist, int nchanges,
     sc->status = FF_SC_IDLE;
 
     rte_spinlock_unlock(&sc->lock);
+#endif /* !FF_USE_RING_IPC */
 
     if (ret > 0) {
         if (eventlist && nevents) {
@@ -3236,6 +3345,12 @@ void
 alarm_event_sem()
 {
 #ifndef FF_THREAD_SOCKET
+#ifdef FF_USE_RING_IPC
+    /* Ring mode: wakeup APP via response ring sentinel */
+    if (ff_so_zone && ff_so_zone->ring_zone && sc) {
+        ff_ring_alarm_wakeup(ff_so_zone->ring_zone, sc);
+    }
+#else
     DEBUG_LOG("check whether need to alarm sem sc:%p, status:%d, ops:%d, need_alarm_sem:%d\n",
         sc, sc->status, sc->ops, need_alarm_sem);
     rte_spinlock_lock(&sc->lock);
@@ -3248,6 +3363,58 @@ alarm_event_sem()
 
     DEBUG_LOG("finish alarm sem sc:%p, status:%d, ops:%d, need_alarm_sem:%d\n",
         sc, sc->status, sc->ops, need_alarm_sem);
+#endif /* FF_USE_RING_IPC */
 #endif
 }
 
+#ifdef FF_USE_RING_IPC
+/*
+ * APP side: submit request to req_ring and wait for response on rsp_ring.
+ *
+ * @param ring_zone Ring zone pointer
+ * @param sc        so_context with ops/args already filled
+ * @param timeout_us Timeout in microseconds: -1=forever, 0=non-blocking, >0=wait
+ * @return 0 on success, -ETIMEDOUT on timeout
+ */
+int
+ff_ring_submit_and_wait(struct ff_sc_ring_zone *ring_zone,
+                        struct ff_so_context *sc,
+                        int64_t timeout_us)
+{
+    void *obj = NULL;
+
+    if (ring_zone == NULL || ring_zone->req_ring == NULL ||
+        ring_zone->rsp_ring == NULL) {
+        return -EINVAL;
+    }
+
+    /* Enqueue request — spin if ring full */
+    while (rte_ring_sp_enqueue(ring_zone->req_ring, sc) != 0) {
+        ERR_LOG("req_ring full, waiting... sc:%p, ops:%d\n", sc, sc->ops);
+        rte_pause();
+    }
+
+    /* Notify fstack via eventfd if configured */
+    if (ring_zone->wait_mode == FF_RING_WAIT_EVENTFD &&
+        ring_zone->eventfd_req >= 0) {
+        uint64_t val = 1;
+        write(ring_zone->eventfd_req, &val, sizeof(val));
+    }
+
+    /* Wait for response from rsp_ring */
+    int ret = ff_ring_dequeue_wait(ring_zone->rsp_ring, &obj,
+        timeout_us, ring_zone->wait_mode);
+
+    if (ret == -ETIMEDOUT) {
+        return -ETIMEDOUT;
+    }
+
+    /* Verify we got our own sc back (SPSC guarantees ordering) */
+    if (obj != sc) {
+        ERR_LOG("ring response mismatch: expected sc:%p, got:%p\n", sc, obj);
+    }
+
+    return 0;
+}
+#endif /* FF_USE_RING_IPC */
+