Merge pull request #237 from a6d9a6m/new-main

fix：重构网络模块并补上文档

Author: a6d9a6m

.gitignore

@@ -39,3 +39,9 @@ os/loongarch.log
 
 # Local notes
 os/可能的改进.md
+
+# Local agent guidance
+**/AGENTS.md
+
+# Local planning/refactor notes
+docs/

document/SUMMARY.md

@@ -24,7 +24,14 @@
 
 # 网络
 
-- [网络实现指南](net/network_implementation_guide.md)
+- [网络模块概览](net/README.md)
+  - [整体架构](net/architecture.md)
+  - [设备与接口](net/device_and_interface.md)
+  - [协议栈运行时](net/stack_runtime.md)
+  - [Socket 与 syscall](net/socket_syscall.md)
+  - [Loopback 与 poll](net/loopback_poll.md)
+  - [测试与排查](net/testing.md)
+  - [网络实现指南](net/network_implementation_guide.md)
   - [netperf / netserver 测试说明](net/netperf.md)
 
 # 同步原语

document/net/README.md

@@ -0,0 +1,21 @@
+# 网络模块概览
+
+网络模块负责把内核网卡设备、接口配置、smoltcp 协议栈、VFS socket 文件和网络 syscall 连接起来。
+
+## 源码入口
+
+- `os/src/device/net/`：网卡设备抽象和 VirtIO/loopback/null 设备。
+- `os/src/net/interface.rs`：接口注册表、接口配置和 smoltcp interface 兼容工厂。
+- `os/src/net/stack.rs`：`NetworkStack` 状态对象和协议栈运行时实现。
+- `os/src/net/socket.rs`：`SocketFile`、fd/socket 映射、UDP per-fd 队列和公开 socket 包装 API。
+- `os/src/kernel/syscall/network.rs`：网络 syscall ABI 层。
+
+## 文档导航
+
+- `architecture.md`：整体分层和依赖方向。
+- `device_and_interface.md`：设备注册、接口对象和中断兼容桥。
+- `stack_runtime.md`：smoltcp runtime、poll、socket set 和 loopback link。
+- `socket_syscall.md`：SocketFile、fd 映射、syscall errno 边界。
+- `loopback_poll.md`：显式 loopback 和 poll/select 唤醒。
+- `testing.md`：验证矩阵和常见排查。
+- `network_implementation_guide.md`：维护指南。

document/net/architecture.md

@@ -0,0 +1,34 @@
+# 网络架构
+
+## 目标模型
+
+```text
+device/net NetDevice
+        |
+        v
+net::register_net_device()
+        |
+        v
+NetworkInterface registry
+        |
+        v
+NetworkStack runtime
+        |
+        v
+SocketFile / syscall ABI
+```
+
+依赖方向只能自上而下或通过明确门面调用。设备层不理解 socket，syscall 层不理解 smoltcp 的内部 socket set。
+
+## 当前边界
+
+- `NetworkStack` 是协议栈状态宿主，持有 smoltcp socket set、active interface runtime、loopback link，并提供 TCP/UDP/socket 文件级 API。
+- `NetworkInterface` 是控制面接口对象，保存名称、MAC、IP 地址、网关和兼容中断状态。
+- `SocketFile` 是 VFS 文件对象，保存 fd 相关逻辑状态，如 local/remote endpoint、flags、shutdown 状态、UDP per-fd 接收队列。
+- `kernel::syscall::network` 只负责用户参数、fd table、sockaddr 编解码和 errno。
+
+## 兼容点
+
+- 当前仍是单 active smoltcp runtime，多接口 runtime 需要后续引入真正的 `StackSocketId` 和接口路由。
+- `SocketHandle` 仍包装 smoltcp handle，作为旧路径兼容类型。
+- `NetworkInterface::create_smoltcp_interface()` 暂时保留为 runtime 初始化工厂。

document/net/device_and_interface.md

@@ -0,0 +1,43 @@
+# 设备与接口
+
+## 设备层
+
+`os/src/device/net/` 只负责网卡数据面：
+
+- `net_device.rs` 定义 `NetDevice`、`NetDeviceError` 和 VirtIO net 设备实现。
+- `virtio_net.rs` 初始化 VirtIO net 设备，并调用网络子系统注册入口。
+- `loopback.rs` 提供显式 loopback 设备。
+- `null_net.rs` 仅作为空设备/占位实现，不表示 loopback。
+
+设备层不得直接依赖 IP、网关、socket、syscall 或 smoltcp socket set。
+
+## 注册路径
+
+真实网卡初始化后调用：
+
+```rust
+crate::net::register_net_device(device)
+```
+
+该入口负责：
+
+- 注册底层 `NetDevice`。
+- 创建 `NetworkInterface`。
+- 把接口加入 `NETWORK_INTERFACE_MANAGER`。
+- 通过 `NetDriverHandle` 注册中断兼容桥。
+
+## 接口层
+
+`NetworkInterface` 保存控制面状态：
+
+- interface name，如 `eth0`、`lo`。
+- MAC address。
+- IP CIDR 列表。
+- IPv4 gateway。
+- 兼容中断开关和最后中断时间。
+
+`NetworkInterface` 不应直接实现 `Driver`。中断体系仍需要 `Driver` 时，使用 `NetDriverHandle`。
+
+## Loopback
+
+默认网络初始化会确保 `lo` 存在。无真实 NIC 时，`lo` 作为 active runtime 接口，配置 `127.0.0.1/8` 且不配置默认网关。

document/net/loopback_poll.md

@@ -0,0 +1,23 @@
+# Loopback 与 poll
+
+## Loopback 模型
+
+`lo` 是显式接口，不再由 `NullNetDevice` 隐式承担。无真实 NIC 时，默认配置创建 `LoopbackNetDevice`，接口名为 `lo`，地址为 `127.0.0.1/8`。
+
+当前仍是单 active smoltcp runtime，因此有真实 NIC 时，127/8 frame 通过 `net::stack` 内部 loopback link 消费；后续多 runtime 可以把 `lo` 升级为独立 smoltcp interface。
+
+## Poll 模型
+
+协议栈推进集中在 `NetworkStack::poll()`：
+
+- smoltcp poll。
+- loopback link bounded drain。
+- UDP per-port dispatch 到 per-fd queue。
+- TCP pending close reaping。
+- poll/select waiter wakeup。
+
+`poll_until_empty()` 仅作为 loopback/netperf 兼容包装保留，不应成为新的主路径。
+
+## 中断协作
+
+网络中断兼容桥只记录事件和唤醒 waiter，不直接维护另一份协议栈状态。需要处理收包时，由进程上下文中的 poll/read/write/connect 等路径推进 `NetworkStack`。