feat(zc_recv): M0+M1 zero-copy receive (kernel mp0 passthrough + user API)

Implements FSTACK_ZC_RECV per docs/zc_read_spec spec 12/13 (all gated by
the FSTACK_ZC_RECV macro; default build unaffected).

M0 (kernel):
- kern_zc_recvit (freebsd/kern/uipc_syscalls.c): compact recvit sibling that
  passes a non-NULL mbuf out-param into soreceive, handing back the socket
  buffer chain without uiomove. Decl in freebsd/sys/syscallsubr.h.

Switch:
- lib/Makefile: FF_ZC_RECV -> -DFSTACK_ZC_RECV (mirrors FF_ZC_SEND).

M1 (userspace, lib/):
- ff_zc_recv (ff_syscall_wrapper.c): builds uio (resid only) + calls
  kern_zc_recvit; fills struct ff_zc_mbuf.
- ff_zc_mbuf_read rewritten (ff_veth.c): real copy-out with intra-mbuf cursor
  (was empty stub; signature data const->mutable OUT).
- ff_zc_mbuf_segment / ff_zc_recv_free (ff_veth.c): zero-copy traversal + chain
  release via m_freem (returns backing DPDK seg).
- ff_api.h: declarations.

Verified: lib builds clean under -Werror both with FF_ZC_RECV=1 and default.
Runtime/integration tests (M2-M3) follow.

Author: zc-read-impl-leader

docs/zc_read_spec/zh_cn/20-impl-execution-plan.md

@@ -0,0 +1,20 @@
+# 20 · 实现执行计划（FSTACK_ZC_RECV）
+
+> 依据 spec 10-19。本阶段开始写实现代码。所有改动 `#ifdef FSTACK_ZC_RECV` 门控，默认不启用 → 现有构建零影响。
+> 铁律：每步实际编译验证；改动以 spec 为蓝本但以实际代码/编译结果为准。
+
+## 执行顺序（M0→M1→M2，M3-M5 后续）
+| 步 | 里程碑 | 改动文件 | 退出条件 |
+|---|---|---|---|
+| 1 | 构建基线 | —— | 确认 lib 当前可编译（或记录现状）|
+| 2 | M0-内核 | freebsd/kern/uipc_syscalls.c（+ 声明）| kern_zc_recvit 编译通过 |
+| 3 | 开关 | lib/Makefile | FF_ZC_RECV→FSTACK_ZC_RECV |
+| 4 | M1-API 声明 | lib/ff_api.h | ff_zc_recv/ff_zc_recv_free/ff_zc_mbuf_read 声明 |
+| 5 | M1-用户态 | lib/ff_syscall_wrapper.c（ff_zc_recv）、lib/ff_veth.c（read 重写 + free）| 编译通过 |
+| 6 | 构建验证 | —— | FSTACK_ZC_RECV=1 编译通过；默认编译不回归 |
+| 7 | M2/测试 | tests/ | 后续 |
+
+## 防回归
+- 所有新增代码 `#ifdef FSTACK_ZC_RECV`；
+- 不改 soreceive 核心、不改原 kern_recvit/soo_read；
+- 默认（不定义 FF_ZC_RECV）构建与改动前一致。

freebsd/kern/uipc_syscalls.c

@@ -1046,6 +1046,68 @@ kern_recvit(struct thread *td, int s, struct msghdr *mp, enum uio_seg fromseg,
 	return (error);
 }
 
+#ifdef FSTACK_ZC_RECV
+/*
+ * FSTACK_ZC_RECV: zero-copy receive.
+ *
+ * A compact sibling of kern_recvit that passes a non-NULL mbuf out-parameter
+ * (mp0) into soreceive(). Per the FreeBSD soreceive(9) contract, when mp0 is
+ * non-NULL the socket-buffer mbuf chain is handed back to the caller without
+ * a uiomove copy (only uio_resid is consulted). The caller (ff_zc_recv) owns
+ * the returned chain and must release it via m_freem()/ff_zc_recv_free().
+ *
+ * No address/control-message handling here: ZC receive targets the bulk data
+ * fast path. Boundaries that cannot be zero-copied (split mbuf, MSG_PEEK,
+ * OOB, TLS, UDP) are handled inside soreceive by falling back to a copy
+ * (m_copym) or by the dgram path; the returned chain stays correct either way.
+ */
+int
+kern_zc_recvit(struct thread *td, int s, struct uio *uio, struct mbuf **mp0)
+{
+	struct file *fp;
+	struct socket *so;
+	struct mbuf *zc_chain = NULL;
+	ssize_t len;
+	int error, flags = 0;
+
+	if (mp0 == NULL)
+		return (EINVAL);
+	*mp0 = NULL;
+
+	AUDIT_ARG_FD(s);
+	error = getsock(td, s, &cap_recv_rights, &fp);
+	if (error != 0)
+		return (error);
+	so = fp->f_data;
+
+#ifdef MAC
+	error = mac_socket_check_receive(td->td_ucred, so);
+	if (error != 0) {
+		fdrop(fp, td);
+		return (error);
+	}
+#endif
+
+	len = uio->uio_resid;
+	error = soreceive(so, NULL, uio, &zc_chain, NULL, &flags);
+	if (error != 0) {
+		if (uio->uio_resid != len && (error == ERESTART ||
+		    error == EINTR || error == EWOULDBLOCK))
+			error = 0;
+	}
+	if (error == 0) {
+		td->td_retval[0] = len - uio->uio_resid;
+		*mp0 = zc_chain;
+	} else if (zc_chain != NULL) {
+		/* error after some mbufs were detached: free them */
+		m_freem(zc_chain);
+	}
+
+	fdrop(fp, td);
+	return (error);
+}
+#endif /* FSTACK_ZC_RECV */
+
 static int
 recvit(struct thread *td, int s, struct msghdr *mp, void *namelenp)
 {

freebsd/sys/syscallsubr.h

@@ -301,6 +301,13 @@ int	kern_readlinkat(struct thread *td, int fd, const char *path,
 int	kern_readv(struct thread *td, int fd, struct uio *auio);
 int	kern_recvit(struct thread *td, int s, struct msghdr *mp,
 	    enum uio_seg fromseg, struct mbuf **controlp);
+#ifdef FSTACK_ZC_RECV
+/* FSTACK_ZC_RECV: zero-copy receive variant — hands the socket-buffer mbuf
+ * chain back to the caller via *mp0 (soreceive's mp0 out-parameter), avoiding
+ * the soreceive->uiomove copy. Caller owns *mp0 and must m_freem() it. */
+int	kern_zc_recvit(struct thread *td, int s, struct uio *uio,
+	    struct mbuf **mp0);
+#endif
 int	kern_renameat(struct thread *td, int oldfd, const char *old, int newfd,
 	    const char *new, enum uio_seg pathseg);
 int	kern_frmdirat(struct thread *td, int dfd, const char *path, int fd,

lib/Makefile

@@ -212,6 +212,10 @@ ifdef FF_ZC_SEND
 CFLAGS+= -DFSTACK_ZC_SEND
 endif
 
+ifdef FF_ZC_RECV
+CFLAGS+= -DFSTACK_ZC_RECV
+endif
+
 # add for LVS tcp option toa, disabled by default
 # CFLAGS+= -DLVS_TCPOPT_TOA
 

lib/ff_api.h

@@ -394,10 +394,45 @@ int ff_zc_mbuf_get(struct ff_zc_mbuf *m, int len);
 int ff_zc_mbuf_write(struct ff_zc_mbuf *m, const char *data, int len);
 
 /*
- * Read data to the mbuf chain in 'sturct ff_zc_mbuf'.
- * not implemented now.
+ * Read data out of the mbuf chain in 'struct ff_zc_mbuf' into the caller's
+ * buffer, advancing the internal cursor (zm->bsd_mbuf_off / zm->off).
+ *
+ * NOTE: `data` is an OUT buffer (the chain is copied INTO it); the previous
+ * 'const char *' signature was a not-implemented placeholder.
+ *
+ * @return bytes read this call (>0), 0 when the chain is exhausted, -1 error.
+ */
+int ff_zc_mbuf_read(struct ff_zc_mbuf *m, char *data, int len);
+
+#ifdef FSTACK_ZC_RECV
+/*
+ * FSTACK_ZC_RECV: zero-copy receive entry. Retrieves the socket-buffer mbuf
+ * chain directly (data still points into the underlying DPDK mbuf), avoiding
+ * the soreceive->uiomove copy. On success zm->bsd_mbuf holds the chain head,
+ * zm->len the byte count, and the cursor is reset for ff_zc_mbuf_read /
+ * ff_zc_mbuf_segment traversal.
+ *
+ * The caller OWNS the returned chain and MUST release it via
+ * ff_zc_recv_free() once done — otherwise the backing DPDK mbufs leak.
+ *
+ * @return bytes received (>0), 0 on peer close, -1 on error (errno set).
+ */
+ssize_t ff_zc_recv(int fd, struct ff_zc_mbuf *zm, size_t nbytes);
+
+/*
+ * Zero-copy traversal: return the current segment's data pointer + length
+ * (pointing into the mbuf, no copy) and advance the cursor.
+ * @return seg bytes (>0), 0 when exhausted, -1 error.
+ */
+int ff_zc_mbuf_segment(struct ff_zc_mbuf *zm, void **seg_data, int *seg_len);
+
+/*
+ * Release a chain obtained from ff_zc_recv (m_freem the whole chain, which
+ * returns each backing DPDK mbuf segment). Idempotent; zeroes zm. Must be
+ * called exactly once per successful ff_zc_recv.
  */
-int ff_zc_mbuf_read(struct ff_zc_mbuf *m, const char *data, int len);
+void ff_zc_recv_free(struct ff_zc_mbuf *zm);
+#endif /* FSTACK_ZC_RECV */
 
 /*
  * M8: zero-copy send entry. Caller must pass the mbuf chain

lib/ff_syscall_wrapper.c

@@ -1225,6 +1225,58 @@ ff_zc_send(int fd, const void *mb, size_t nbytes)
 }
 #endif /* FSTACK_ZC_SEND */
 
+#ifdef FSTACK_ZC_RECV
+/*
+ * FSTACK_ZC_RECV: zero-copy receive entry. Builds a uio carrying only the
+ * requested byte budget (uio_resid) and calls kern_zc_recvit, which passes a
+ * non-NULL mbuf out-parameter into soreceive so the socket-buffer mbuf chain
+ * is handed back without a uiomove copy. On success zm->bsd_mbuf holds the
+ * chain head; the caller must release it via ff_zc_recv_free().
+ *
+ * `zm` must be a valid 'struct ff_zc_mbuf *'. Do NOT pass a char buffer.
+ */
+ssize_t
+ff_zc_recv(int fd, struct ff_zc_mbuf *zm, size_t nbytes)
+{
+    struct uio auio;
+    struct iovec aiov;
+    struct mbuf *chain = NULL;
+    int rc;
+
+    if (zm == NULL || nbytes == 0 || nbytes > INT_MAX) {
+        rc = EINVAL;
+        goto kern_fail;
+    }
+
+    /* uio is only consulted for uio_resid when mp0 is non-NULL (soreceive(9));
+     * iov_base is unused on the ZC path but set for completeness. */
+    aiov.iov_base = NULL;
+    aiov.iov_len = nbytes;
+    auio.uio_iov = &aiov;
+    auio.uio_iovcnt = 1;
+    auio.uio_resid = nbytes;
+    auio.uio_segflg = UIO_SYSSPACE;
+    auio.uio_rw = UIO_READ;
+    auio.uio_td = curthread;
+    auio.uio_offset = 0;
+
+    if ((rc = kern_zc_recvit(curthread, fd, &auio, &chain)))
+        goto kern_fail;
+
+    rc = curthread->td_retval[0];
+
+    zm->bsd_mbuf = chain;
+    zm->bsd_mbuf_off = chain;
+    zm->off = 0;
+    zm->len = rc;
+
+    return (rc);
+kern_fail:
+    ff_os_errno(rc);
+    return (-1);
+}
+#endif /* FSTACK_ZC_RECV */
+
 ssize_t
 ff_send(int s, const void *buf, size_t len, int flags)
 {

lib/ff_veth.c

@@ -356,11 +356,82 @@ ff_zc_mbuf_write(struct ff_zc_mbuf *zm, const char *data, int len)
 }
 
 int
-ff_zc_mbuf_read(struct ff_zc_mbuf *m, const char *data, int len)
+ff_zc_mbuf_read(struct ff_zc_mbuf *zm, char *data, int len)
 {
-    // DOTO: Support read zero copy
-    return 0;
+    struct mbuf *mb;
+    int progress = 0, length, moff;
+
+    if (zm == NULL || data == NULL || len <= 0) {
+        return -1;
+    }
+
+    /* For RECV, bsd_mbuf_off is the current mbuf cursor and `off` is the
+     * already-consumed offset WITHIN that mbuf. Copy out up to `len` bytes,
+     * spanning mbufs as needed. */
+    mb = (struct mbuf *)zm->bsd_mbuf_off;
+    moff = zm->off;
+    while (mb != NULL && progress < len) {
+        length = min(mb->m_len - moff, len - progress);
+        bcopy(mtod(mb, char *) + moff, data + progress, length);
+        progress += length;
+        moff += length;
+        if (moff >= mb->m_len) {
+            mb = mb->m_next;
+            moff = 0;
+        }
+    }
+    zm->bsd_mbuf_off = mb;
+    zm->off = moff;
+
+    return progress;
+}
+
+#ifdef FSTACK_ZC_RECV
+/*
+ * FSTACK_ZC_RECV: return the current segment's data pointer + length without
+ * copying (pointer aliases into the underlying DPDK mbuf), then advance the
+ * cursor to the next mbuf. Valid until ff_zc_recv_free() is called.
+ */
+int
+ff_zc_mbuf_segment(struct ff_zc_mbuf *zm, void **seg_data, int *seg_len)
+{
+    struct mbuf *mb;
+
+    if (zm == NULL || seg_data == NULL || seg_len == NULL) {
+        return -1;
+    }
+
+    mb = (struct mbuf *)zm->bsd_mbuf_off;
+    if (mb == NULL) {
+        return 0;   /* chain exhausted */
+    }
+
+    *seg_data = mtod(mb, void *);
+    *seg_len = mb->m_len;
+    zm->bsd_mbuf_off = mb->m_next;
+    zm->off = 0;
+
+    return mb->m_len;
+}
+
+/*
+ * FSTACK_ZC_RECV: release the whole chain obtained from ff_zc_recv. m_freem
+ * walks m_next and frees each mbuf; ext-mbuf segments trigger ff_mbuf_ext_free
+ * which returns the backing DPDK mbuf seg (see docs/zc_read_spec). Idempotent.
+ */
+void
+ff_zc_recv_free(struct ff_zc_mbuf *zm)
+{
+    if (zm == NULL || zm->bsd_mbuf == NULL) {
+        return;
+    }
+    m_freem((struct mbuf *)zm->bsd_mbuf);
+    zm->bsd_mbuf = NULL;
+    zm->bsd_mbuf_off = NULL;
+    zm->off = 0;
+    zm->len = 0;
 }
+#endif /* FSTACK_ZC_RECV */
 
 void *
 ff_mbuf_gethdr(void *pkt, uint16_t total, void *data,