doc(arch): sync L1/L2 architecture docs with adapter/syscall LD_PRELOAD changes

Update the Layer 1 (System Overview) and Layer 2 (Interface Spec) docs,
in both English (docs/) and Simplified Chinese (docs/zh_cn/), so they
match the current state of adapter/syscall/ described in
adapter/syscall/README.md.

L1 changes
  - docs/01-LAYER1-ARCHITECTURE.md, docs/zh_cn/01-LAYER1-ARCHITECTURE.md:
    expand the source-tree comment for adapter/syscall/ to spell out
    that it builds libff_syscall.so + a standalone fstack instance and
    communicates over Hugepage shared memory (sem path or
    FF_USE_RING_IPC lock-free ring path).
  - docs/F-Stack_Architecture_Layer1_System_Overview.md and the zh_cn
    counterpart: rewrite Section 7.1 'Method 2: LD_PRELOAD Interception'
    to describe the two-process model (the fstack instance must be
    started before the preloaded application), enumerate the full set
    of hooked POSIX entries (socket/bind/connect/accept/accept4/listen/
    close/read/write/send*/recv*/__read_chk/__recv_chk/__recvfrom_chk/
    ioctl/epoll_*/fork) and the FF_KERNEL_EVENT / FF_MULTI_SC /
    FF_USE_RING_IPC switches.

L2 changes
  - docs/F-Stack_Architecture_Layer2_Interface_Specification.md and the
    zh_cn counterpart: fix the library-name error in Section 6.2 (was
    'LD_PRELOAD=libfstack.so', now 'libff_syscall.so'), describe the
    two-process model, list the hooked POSIX entries and the three
    runtime/compile switches in a small table.

All cross references point to adapter/syscall/README.md as the
single source of truth. Line endings normalized to LF.

Author: jfb8856606

docs/01-LAYER1-ARCHITECTURE.md

@@ -92,7 +92,11 @@ NIC Hardware
 ├── tools/                        # Tool scripts
 ├── adapter/                      # Network adapters
 │   ├── micro_thread/             # Micro-thread interface for stateful applications using F-Stack
-│   └── syscall/                  # Intercept Linux syscalls as F-Stack APIs via LD_PRELOAD
+│   └── syscall/                  # Builds libff_syscall.so + an fstack instance binary; intercepts
+│                                  # Linux syscalls (socket/bind/connect/read/write/send/recv/
+│                                  # epoll/accept4/__recv_chk/fork/ioctl ...) via LD_PRELOAD and
+│                                  # forwards them to the fstack instance through Hugepage-backed
+│                                  # shared memory (sem path or FF_USE_RING_IPC lock-free ring path)
 ├── doc/                          # Original English documentation
 ├── docs/                         # Three-layer architecture knowledge base docs
 └── config.ini                    # Default configuration file

docs/F-Stack_Architecture_Layer1_System_Overview.md

@@ -140,7 +140,10 @@ Actual data on 10GbE link:
 │
 ├── adapter/                                # Network adapters
 │   ├── micro_thread/             # Micro-thread interface for stateful applications using F-Stack
-│   └── syscall/                  # Intercept Linux syscalls as F-Stack APIs via LD_PRELOAD
+│   └── syscall/                  # Builds libff_syscall.so + fstack instance binary; intercepts
+│                                  # Linux syscalls via LD_PRELOAD and forwards them to the fstack
+│                                  # instance through Hugepage shared memory (sem path or
+│                                  # FF_USE_RING_IPC lock-free ring path). See adapter/syscall/README.md
 ├── doc/                                    # Original English documentation
 ├── docs/                                   # Three-layer architecture knowledge base docs
 ├── config.ini                # Default configuration file
@@ -775,25 +778,43 @@ int main() {
 ```
 
 **Method 2: LD_PRELOAD Interception (e.g., Nginx)**
+
+In LD_PRELOAD mode the application runs in two separate processes: a standalone `fstack`
+instance (links libfstack.a, polls DPDK) plus the user application (e.g. nginx) preloaded
+with `libff_syscall.so`. The two processes communicate over Hugepage shared memory — the
+default is a semaphore-based path; setting `FF_USE_RING_IPC=1` switches the data plane to
+a lock-free DPDK SPSC `rte_ring`. The `fstack` instance must be started before the
+LD_PRELOAD application.
+
 ```bash
-# Enable F-Stack support for Nginx
-LD_PRELOAD=libff_syscall.so nginx
-
-# LD_PRELOAD hooks intercept:
-  socket() → ff_socket()
-  bind() → ff_bind()
-  connect() → ff_connect()
-  read() → ff_read()
-  write() → ff_write()
-  send() → ff_send()
-  sendto() → ff_sendto()
-  sendmsg() → ff_sendmsg()
-  recv() → ff_recv()
-  recvfrom() → ff_recvfrom()
-  recvmsg() → ff_recvmsg()
+# 1) Start the fstack instance first (one or more instances)
+./fstack --conf config.ini --proc-type=primary --proc-id=0 &
+
+# 2) Then enable F-Stack support for Nginx via LD_PRELOAD
+LD_PRELOAD=/path/to/libff_syscall.so nginx
+
+# Hooked POSIX entries forwarded to ff_* / kqueue:
+  socket()     → ff_socket()                 accept()     → ff_accept()
+  bind()       → ff_bind()                   accept4()    → ff_accept() + SOCK_CLOEXEC/NONBLOCK
+  connect()    → ff_connect()                listen()     → ff_listen()
+  read()       → ff_read()                   close()      → ff_close()
+  write()      → ff_write()                  ioctl()      → ff_ioctl()
+  send/sendto/sendmsg() → ff_send/sendto/sendmsg()
+  recv/recvfrom/recvmsg() → ff_recv/recvfrom/recvmsg()
+  __read_chk / __recv_chk / __recvfrom_chk   (glibc _FORTIFY_SOURCE wrappers)
+  epoll_create/ctl/wait() → kqueue-backed events (optional polling mode)
+  fork()       → per-process FreeBSD struct thread (Linux-kernel-like semantics)
   ...
+
+# Key environment variables / compile switches:
+#   FF_KERNEL_EVENT=1   Forward kernel-only fds to host epoll in parallel
+#   FF_MULTI_SC=1       SO_REUSEPORT-style multi-sc, one sc per worker fd
+#   FF_USE_RING_IPC=1   Switch IPC to lock-free DPDK SPSC ring (default v3.4 opts)
 ```
 
+See `adapter/syscall/README.md` for the full feature list, compile flags, known
+limitations, and acknowledgements.
+
 ### 7.2 Tool Support
 
 Operations tools communicate with F-Stack processes via IPC:

docs/F-Stack_Architecture_Layer2_Interface_Specification.md

@@ -1026,21 +1026,43 @@ symmetric_rss = 1  # Bidirectional connections to same queue
 
 ### 6.2 Application Integration Interfaces
 
-**Direct Call Mode**: Application directly links `libfstack.a` and calls `ff_*` APIs
+**Direct Call Mode**: Application directly links `libfstack.a` and calls `ff_*` APIs.
 
-**LD_PRELOAD Mode**: Use `LD_PRELOAD=libfstack.so` to intercept system calls
+**LD_PRELOAD Mode**: Application is preloaded with `libff_syscall.so` (built from
+`adapter/syscall/`); it runs as a **separate process** from the `fstack` instance
+binary and the two communicate over Hugepage shared memory. The default IPC path is
+semaphore-based; setting `FF_USE_RING_IPC=1` switches to a lock-free DPDK SPSC ring.
+The `fstack` instance must be started before the LD_PRELOAD application.
 
 ```bash
+# Start the fstack instance(s) first
+./fstack --conf config.ini --proc-type=primary --proc-id=0 &
+
 # Nginx integration
-LD_PRELOAD=/path/to/libfstack.so /usr/sbin/nginx -g "daemon off;"
+LD_PRELOAD=/path/to/libff_syscall.so /usr/sbin/nginx -g "daemon off;"
 
 # Redis integration
-LD_PRELOAD=/path/to/libfstack.so /usr/bin/redis-server /etc/redis.conf
+LD_PRELOAD=/path/to/libff_syscall.so /usr/bin/redis-server /etc/redis.conf
 
 # Custom application
-LD_PRELOAD=/path/to/libfstack.so ./my_app
+LD_PRELOAD=/path/to/libff_syscall.so ./my_app
 ```
 
+Hooked POSIX entries include `socket / bind / connect / accept / accept4 / listen /
+close / read / write / send / sendto / sendmsg / recv / recvfrom / recvmsg /
+__read_chk / __recv_chk / __recvfrom_chk / ioctl / epoll_create|ctl|wait / fork`.
+
+Common runtime / compile switches:
+
+| Switch | Default | Effect |
+|---|---|---|
+| `FF_KERNEL_EVENT` | off | Forward kernel-only fds to host epoll in parallel |
+| `FF_MULTI_SC` | off | SO_REUSEPORT-style multi-sc, one sc per worker fd |
+| `FF_USE_RING_IPC` | off | Switch IPC to lock-free DPDK SPSC ring (v3.4 opts on by default) |
+
+For the full design, supported modes, environment variables, performance notes and
+known limitations, see `adapter/syscall/README.md`.
+
 ---
 
 ## Summary

docs/zh_cn/01-LAYER1-ARCHITECTURE.md

@@ -92,7 +92,11 @@ NIC 驱动 (igb_uio / vfio-pci)
 ├── tools/                        # 工具脚本
 ├── adapter/                      # 网络适配器
 │   ├── micro_thread/             # 微线程接口，方便有状态应用使用 F-Stack
-│   └── syscall/                  # 通过 LD_PRELOAD 劫持 Linux syscall 为 F-Stack API
+│   └── syscall/                  # 编译产物为 libff_syscall.so 与独立 fstack 实例二进制；通过
+│                                  # LD_PRELOAD 劫持 Linux syscall（socket/bind/connect/read/write/
+│                                  # send/recv/epoll/accept4/__recv_chk/fork/ioctl 等）转发给
+│                                  # fstack 实例，IPC 走 Hugepage 共享内存（sem 路径或开关
+│                                  # FF_USE_RING_IPC 后的 lock-free ring 路径）
 ├── doc/                          # 原始英文文档
 ├── docs/                         # 三层架构知识库文档
 └── config.ini                    # 默认配置文件

docs/zh_cn/F-Stack_Architecture_Layer1_System_Overview.md

@@ -138,7 +138,10 @@ F-Stack 模式 (用户态网络)
 │
 ├── adapter/                                # 网络适配器
 │   ├── micro_thread/             # 微线程接口，方便有状态应用使用 F-Stack
-│   └── syscall/                  # 通过 LD_PRELOAD 劫持 Linux syscall 为 F-Stack API
+│   └── syscall/                  # 编译产物为 libff_syscall.so 与独立 fstack 实例二进制；通过
+│                                  # LD_PRELOAD 劫持 Linux syscall 转发给 fstack 实例，IPC 走
+│                                  # Hugepage 共享内存（默认 sem 路径，或开关 FF_USE_RING_IPC 后
+│                                  # 切到 lock-free ring 路径），详见 adapter/syscall/README.md
 ├── doc/                                    # 原始英文文档
 ├── docs/                                   # 三层架构知识库文档
 ├── config.ini                # 默认配置文件
@@ -770,25 +773,40 @@ int main() {
 ```
 
 **方式 2：LD_PRELOAD 拦截 (如 Nginx)**
+
+LD_PRELOAD 模式下应用以两个进程方式运行：独立的 `fstack` 实例（链接 libfstack.a，跑
+DPDK 轮询），以及预加载 `libff_syscall.so` 的用户应用（如 nginx）。两者通过 Hugepage
+共享内存通信——默认走信号量路径，置 `FF_USE_RING_IPC=1` 后切换为基于 DPDK SPSC
+`rte_ring` 的 lock-free 路径。**`fstack` 实例必须在 LD_PRELOAD 应用之前启动**。
+
 ```bash
-# Nginx 启用 F-Stack 支持
-LD_PRELOAD=libff_syscall.so nginx
-
-# LD_PRELOAD 钩子拦截：
-  socket() → ff_socket()
-  bind() → ff_bind()
-  connect() → ff_connect()
-  read() → ff_read()
-  write() → ff_write()
-  send() → ff_send()
-  sendto() → ff_sendto()
-  sendmsg() → ff_sendmsg()
-  recv() → ff_recv()
-  recvfrom() → ff_recvfrom()
-  recvmsg() → ff_recvmsg()
+# 1) 先启动 fstack 实例（可启动多个）
+./fstack --conf config.ini --proc-type=primary --proc-id=0 &
+
+# 2) 再使用 LD_PRELOAD 启用 Nginx 的 F-Stack 支持
+LD_PRELOAD=/path/to/libff_syscall.so nginx
+
+# LD_PRELOAD 钩子拦截（转发至 ff_* / kqueue）：
+  socket()     → ff_socket()                 accept()     → ff_accept()
+  bind()       → ff_bind()                   accept4()    → ff_accept() + SOCK_CLOEXEC/NONBLOCK
+  connect()    → ff_connect()                listen()     → ff_listen()
+  read()       → ff_read()                   close()      → ff_close()
+  write()      → ff_write()                  ioctl()      → ff_ioctl()
+  send/sendto/sendmsg() → ff_send/sendto/sendmsg()
+  recv/recvfrom/recvmsg() → ff_recv/recvfrom/recvmsg()
+  __read_chk / __recv_chk / __recvfrom_chk   (glibc _FORTIFY_SOURCE 包装)
+  epoll_create/ctl/wait() → kqueue 事件（可选 polling 模式）
+  fork()       → 每进程独立 FreeBSD struct thread（贴近 Linux kernel 语义）
   ...
+
+# 关键环境变量 / 编译开关：
+#   FF_KERNEL_EVENT=1   并行转发内核 fd 给宿主 epoll
+#   FF_MULTI_SC=1       SO_REUSEPORT 风格的多 sc，每 worker fd 一个 sc
+#   FF_USE_RING_IPC=1   将 IPC 切到 lock-free DPDK SPSC ring（默认含 v3.4 优化）
 ```
 
+完整功能列表、编译开关、已知限制及致谢请参考 `adapter/syscall/README.md`。
+
 ### 7.2 工具支持
 
 运维工具通过 IPC 与 F-Stack 进程通信：

docs/zh_cn/F-Stack_Architecture_Layer2_Interface_Specification.md

@@ -1181,21 +1181,41 @@ symmetric_rss = 1  # 双向连接到同一队列
 
 ### 6.2 应用集成接口
 
-**直接调用模式**：应用直接链接 libfstack.a 并调用 ff_* API
+**直接调用模式**：应用直接链接 libfstack.a 并调用 ff_* API。
 
-**LD_PRELOAD 模式**：使用 LD_PRELOAD=libfstack.so 拦截系统调用
+**LD_PRELOAD 模式**：应用预加载 `libff_syscall.so`（由 `adapter/syscall/` 构建），与
+独立的 `fstack` 实例**以两个进程方式运行**，两者通过 Hugepage 共享内存通信；默认走
+信号量路径，置 `FF_USE_RING_IPC=1` 后切换为基于 DPDK SPSC `rte_ring` 的 lock-free
+路径。**`fstack` 实例必须在 LD_PRELOAD 应用之前启动**。
 
 ```bash
+# 先启动 fstack 实例（可启动多个）
+./fstack --conf config.ini --proc-type=primary --proc-id=0 &
+
 # Nginx 集成
-LD_PRELOAD=/path/to/libfstack.so /usr/sbin/nginx -g "daemon off;"
+LD_PRELOAD=/path/to/libff_syscall.so /usr/sbin/nginx -g "daemon off;"
 
 # Redis 集成
-LD_PRELOAD=/path/to/libfstack.so /usr/bin/redis-server /etc/redis.conf
+LD_PRELOAD=/path/to/libff_syscall.so /usr/bin/redis-server /etc/redis.conf
 
 # 自定义应用
-LD_PRELOAD=/path/to/libfstack.so ./my_app
+LD_PRELOAD=/path/to/libff_syscall.so ./my_app
 ```
 
+被劫持的 POSIX 入口包括：`socket / bind / connect / accept / accept4 / listen /
+close / read / write / send / sendto / sendmsg / recv / recvfrom / recvmsg /
+__read_chk / __recv_chk / __recvfrom_chk / ioctl / epoll_create|ctl|wait / fork`。
+
+常用运行时 / 编译开关：
+
+| 开关 | 默认 | 作用 |
+|---|---|---|
+| `FF_KERNEL_EVENT` | 关 | 并行转发内核 fd 给宿主 epoll |
+| `FF_MULTI_SC` | 关 | SO_REUSEPORT 风格的多 sc，每 worker fd 一个 sc |
+| `FF_USE_RING_IPC` | 关 | 将 IPC 切到 lock-free DPDK SPSC ring（默认含 v3.4 优化） |
+
+完整设计、支持模式、环境变量、性能数据与已知限制详见 `adapter/syscall/README.md`。
+
 ---
 
 ## 总结