refactor(ax-net): add locking and concurrency documentation and remove deprecated interfaces

[ZCShou]

针对 #1244 的完善

文档

• 新增 docs/docs/architecture/net/locks.md，说明 ax-net 的锁层级、worker 模型、waker 协调、Router/设备队列边界和禁止的反向锁路径。
• 更新网络架构文档，补充锁与并发文档链接，并同步 request_poll()、wake_net_task_irq() 等当前接口名称。

Public API 与调用点

• 移除旧的 poll_interfaces() 同步 poll 入口，统一通过 request_poll() 唤醒 net-poll worker。
• 移除旧的 eth0_ipv4_config() helper，改用按接口名查询的配置接口。
• 更新 ArceOS、StarryOS、poll/select/epoll、axruntime 和 AIC8800 相关调用点。

ax-net 结构整理

• 新增 net/ax-net/src/addr.rs，集中放置地址冲突检查、临时端口分配、前缀 mask 等共享 helper。
• 拆分 init_network()，提取配置校验、loopback 注册、未匹配配置检查和默认 DNS 初始化 helper。
• 使用 enum_dispatch 简化 Socket facade，减少手写转发代码。
• 简化 vsock stream transport 和连接管理路径。
• 抽取 DHCP packet 解析 helper，并整理 DHCP server/client 相关逻辑。

poll / waker

• 将 deferred poll wake 改为结构化 DeferPollWake，统一 TCP/UDP/raw 的延迟唤醒路径。
• request_poll() 改为只在 pending 状态从 false 变 true 时通知 wait queue。
• deferred poll wake pending 状态同样做通知去抖。
• Service::register_waker() 改为保存多个 timeout registration，避免不同 socket 的定时唤醒互相覆盖。

Router 与设备路径

• Router/device worker 时间源统一为 monotonic。
• 设备 RX worker 内部 buffer 从 1 个槽扩展到 16 个槽。
• snoop_tcp_packet() 对非 TCP packet 提前返回，减少 RX 热路径解析。
• 拆分 Router dispatch 辅助函数，包括 link-local fanout、unicast dispatch 和 loopback direct inject。

TCP / UDP / raw

• ListenTable 从 65536 个预分配 bucket 改为按端口懒创建 HashMap。
• TCP public bind 表从 Vec 改为 HashSet。
• 内联并简化 PendingTcp 相关结构。
• raw socket 引入结构化 IP header 解析辅助，减少重复 packet 字段处理。

Wi-Fi / OOB RX

• OOB RX 唤醒入口统一为 wake_net_task_irq()。
• WifiControlHandle 增加 Clone。
• reconfigure_wifi() 改为锁内 clone handle，锁外执行 connect/start_ap_open。

[ZR233]

Request changes。

这个 PR 主要做两件事：清理 ax-net 的废弃接口（例如 poll_interfaces、eth0_ipv4_config、旧的 vsock/UDP/raw helper 等），并补充网络栈锁与并发语义文档。代码方向整体是清楚的：socket 热路径只请求 poll，net-poll worker 负责推进 smoltcp；TCP/UDP 的 side table 与 socket 本体状态保持分离；下游 StarryOS、ArceOS 调用点也已经同步到新的 request_poll / VsockSocket::new() 形式。

阻塞点是新增/更新的文档还在描述已经不存在的 poll_once() 入口。当前代码里 poll_until_idle() 已直接调用 get_service().poll(&mut SOCKET_SET.inner.lock())，但 docs/docs/architecture/net/locks.md 仍把 poll_once() 当成完整 poll 的唯一入口，并且 docs/docs/architecture/net/devices.md、docs/docs/architecture/net/flows.md 也还保留 while poll_once() {} 的流程说明；另外 components/aic8800/src/fdrv/thread/rx.rs:27 的注释还提到旧的 ax_net::poll_interfaces。这个 PR 的标题和主体范围包括锁/并发文档，如果文档入口与实际代码不一致，后续按文档检查锁顺序或驱动回调时会得到错误结论。请把这些引用同步到当前实现，或恢复一个真实的 helper 后再让文档引用它。

本地验证结果：git diff --check origin/dev...HEAD 通过；未发现新增 [patch.crates-io]；cargo xtask clippy --package ax-net 通过（base/vsock 两组）；cargo test -p ax-net --lib 通过（20 tests）；cargo xtask clippy --package ax-api、cargo xtask clippy --package ax-posix-api、cargo xtask clippy --package ax-runtime、cargo xtask clippy --package starry-kernel 均通过。rg 没有发现 Rust 代码里还调用已删除的 poll_interfaces、eth0_ipv4_config、VsockTransport 等接口。

CI 方面，当前 head 31bb77c1a3448529795a77a98fdf8c7038da636a 上已看到 format、sync-lint、std、ArceOS/Axvisor/Starry 多个 run_host/run_container job 通过；review 时 Run clippy / run_host 和 Test starry riscv64 qemu / run_container 仍处于 pending，暂未看到与本 PR 相关的失败项。

重复/重叠检查：检查了 base 分支现有 ax-net 接口和相关开放 PR（包括当前打开的 ax-net 相关项），没有发现同一清理/文档工作的重复实现；与 #1339 属于不同 CI/self-host 方向。PR body 目前为空，后续也建议补上变更摘要和上述或等价的验证命令，方便后续 reviewer 确认这个公共 API/文档清理的安全性。

[mai-team-app]

Review Summary

PR 目标：清理 ax-net 废弃接口（poll_interfaces、eth0_ipv4_config、旧 VsockTransport 等），新增 871 行锁与并发文档 locks.md，并同步更新所有文档中的 API 引用。

代码质量：Rust 代码改动方向正确——废弃接口已从 lib.rs 公共 API 中移除，下游调用点（starry-kernel、arceos_api、epoll/poll/select）已同步迁移到 request_poll() / VsockSocket::new() 形式。cargo fmt --check -p ax-net 通过。前一位 reviewer 已验证 cargo clippy 和 cargo test -p ax-net --lib 通过。

CI 状态：当前 head 31bb77c1 上所有可见 CI check run 均为 skipped 状态（path-filtered CI 对 doc/ax-net-only 变更正常跳过外围测试），未观察到 failure。

阻塞问题（与前一位 reviewer ZR233 的结论一致）：

新增/更新的文档仍然引用已被删除的 poll_once() 入口。当前代码中 poll_until_idle() 直接内联调用 get_service().poll(&mut SOCKET_SET.inner.lock())，不再有独立的 poll_once() helper。以下文件均保留了过时引用：

1. locks.md L83/L87/L166/L737 — 引用 poll_once() 作为 poll 入口和代码片段
2. flows.md L149 — 流程图使用 while poll_once() {}
3. flows.md L159 — 锁顺序描述引用 poll_once()
4. devices.md L625 — 设备 RX readiness 流程使用 while poll_once() {}
5. components/aic8800/src/fdrv/thread/rx.rs L27 — 注释仍引用已废弃的 ax_net::poll_interfaces

locks.md 是本 PR 的主要交付物，文档入口与代码不一致会导致后续按文档审计锁顺序时得到错误结论。请将这些引用同步到当前实现（poll_until_idle() + 内联 get_service().poll()），或恢复一个真实的 helper 后再让文档引用它。

重复/重叠检查：base 分支和其他开放 PR 未发现同范围的 ax-net 文档/清理工作重复。

总结：代码重构方向正确，锁文档质量优秀，但文档准确性需要修复后再合并。

Powered by mimo-v2.5-pro

[mai-team-app]

Review 总结

PR 范围：清理 ax-net 废弃接口并新增锁/并发文档（871 行 locks.md），重构 socket 枚举分发、地址 helper、DHCP 解析等内部结构。

代码质量：改动方向正确且有系统性——

1. 废弃接口移除：poll_interfaces()、eth0_ipv4_config()、notify_oob_rx()、prefix_to_mask()、endpoint_from_ip_endpoint() 已从公共 API 中清除；下游 StarryOS socket.rs、ArceOS arceos_api/epoll/poll/select、axruntime 已同步迁移到 request_poll() / wake_net_task_irq()。
2. Socket 枚举分发：Socket::Configurable 和 Socket::SocketOps 的手动 match 体被 enum_dispatch 替代，~136 行重复 match arm 消除。
3. vsock 简化：移除 VsockTransport 枚举和 VsockTransportOps trait，VsockSocket 直接持有 VsockStreamTransport，减少间接层。VsockSocket::new() 签名从 new(transport: impl Into<VsockTransport>) 简化为 new()。
4. 内部提取：validate_config、register_loopback、ensure_all_interface_configs_used、add_default_dns_servers 从 init_network 拆分；addr.rs 模块集中 allocate_ephemeral_port、listen_addrs_conflict、mask_from_prefix；DHCP packet parsing 提取为 parse_dhcp_packet；RawIpHeader 枚举统一 IPv4/IPv6 header 构造。
5. 锁文档：locks.md 按层级说明 SERVICE、SOCKET_SET、NetControl.state、SharedRouteTable、BoundedPacketQueue、DeviceHandle、spin locks 的持锁范围和锁顺序，配 mermaid 流程图，质量优秀。所有文档中的 poll_once() 引用已同步为 poll_until_idle() + 内联 get_service().poll()。

之前 review 阻塞问题：poll_once() 过时引用已在后续 commit 中修复。当前 HEAD 无任何废弃 API 引用残留（rg 验证通过）。

CI 状态：当前 head 7ce66af9e 上 path-filtered CI（format、sync-lint）通过；其余 jobs 因 doc/ax-net-only 变更被 skipped。无 failure。

本地验证（在 reviewer clone /workspace/repo 上）：

• cargo fmt --check -p ax-net ✅
• cargo xtask clippy --package ax-net（base + vsock 两组）✅
• cargo test -p ax-net --lib（20 tests）✅
• git diff --check ✅
• rg poll_once / poll_interfaces / eth0_ipv4_config / notify_oob_rx / VsockTransport（docs + rs）无残留 ✅

重复/重叠检查：搜索 open PR（ax-net 关键字），未发现同范围清理/文档工作。#1319 为 QoS socket option，属不同方向。

建议（非阻塞）：

• locks.md 中源码行号引用（如 lib.rs#L429、service.rs#L737）在最新 commit 中有几处偏移（实际 poll_until_idle 在 L448，Service::poll 在 L715）。建议后续统一刷新，或改为按函数名链接以减少维护负担。
• PR body 为空，建议补上变更摘要和验证命令列表。

Powered by mimo-v2.5-pro

[ZR233]

Request changes。

这个 PR 当前 head 7ce66af9ecdc13f435bb0a8241ea253ebc3a3bef 的主方向是清理 ax-net 废弃入口、把 socket/poll/listen side table 的实现继续收敛，并补充网络栈锁与并发文档。上一轮 poll_once() 过时引用已经修掉，旧 thread 现在是 resolved/outdated；代码层面本地窄验证也通过。

仍有一个阻塞点：最新文档又和最新实现发生了漂移。当前代码里 TCP_BOUND_PORTS 已是 HashMap<u16, HashSet<Option<IpAddress>>>，register_tcp_bound() 用 insert()；ListenTable 也已改成 Mutex<HashMap<u16, ListenTableEntry>>，不再是 65536 个固定 bucket 的 Box<[ListenTableEntry]>。但新增的 docs/docs/architecture/net/locks.md 以及同步修改的 docs/docs/architecture/net/sockets.md 仍在展示旧的 Vec/push/Box<[ListenTableEntry]> 结构，并说明“tcp 是 65536 个端口 bucket”。这个 PR 的主要范围包括锁/并发文档，如果文档里的核心 side table 结构和代码不一致，后续按文档检查锁顺序、端口占用语义或 listen bucket 粒度时会得出错误结论。请把这些片段同步到当前实现后再合入。

本地验证：cargo fmt --check 通过；git diff --check origin/dev...HEAD 通过；未发现新增 [patch.crates-io]；cargo xtask clippy --package ax-net 通过（base 和 vsock 两组）；cargo test -p ax-net --lib 通过，20 个单测包括 listen table wildcard/specific 规则测试。

CI 状态：当前 head 上 format、sync-lint、std、ArceOS/Axvisor/Starry 多数相关 job 通过；Run clippy / run_host 日志里 ax-net (base) 和 ax-net (feature: vsock) 已通过，后续在 crab-usb 编译阶段被 Actions 取消，没有看到 ax-net clippy 诊断。Test axvisor self-hosted x86_64 / run_host 失败为已知 smoke-vmx timeout 类型：guest 已到 ~ # pwd && echo 'guest linux test pass!' 后 600s 超时；#1340 未修改 Axvisor x86_64/VMX/smoke-vmx 配置，已在 #1230 追加本次 run 记录（https://github.com/rcore-os/tgoskits/issues/1230#issuecomment-4766156586），按无关 CI 稳定性问题跟踪。

测试覆盖：本 PR 没有新增运行时集成测试，但新增/改动的 ax-net 单测覆盖了 listen table 关键冲突规则；对于文档同步问题，现有测试不会捕捉文档代码片段漂移，因此这次阻塞点需要人工修正文档。

重复/重叠分析：检查 base 当前 ax-net 相关实现以及 open PR 搜索结果。#1319 也修改 ax-net 的 socket/router/tcp/udp/raw 表面，但目标是 Starry socket QoS/options 与 cmsg 语义，属于同模块冲突风险/partial-overlap，不是本 PR 的废弃接口清理和锁文档重复实现；合入顺序上后合入的一方需要重跑相关 ax-net clippy/test 并处理同文件冲突。没有发现 base 或其他 open PR 已经完整替代本 PR 当前清理范围。

[ZR233]

Approve。

本轮按当前 head 5ffaa35cf894a58421ef546cb82bf95644205770 复审。最新 commit 只修改 docs/docs/architecture/net/locks.md 和 docs/docs/architecture/net/sockets.md，用于同步上一轮指出的 ListenTable / TCP_BOUND_PORTS 文档漂移。现在文档已经描述为 TCP_BOUND_PORTS: HashMap<u16, HashSet<Option<IpAddress>>>，ListenTable.tcp: HashMap<u16, ListenTableEntry>，每个端口 bucket 内部仍是 Arc<Mutex<Vec<ListenTableEntryInner>>>；这与当前 tcp.rs 和 listen_table.rs 实现一致。上一轮文档漂移 thread 已解析。

代码方向上，这个 PR 清理 ax-net::poll_interfaces()、eth0_ipv4_config()、旧 notify_oob_rx() 和旧 vsock transport 入口，并把调用方统一到 request_poll() / wake_net_task_irq() / VsockSocket::new()；同时将 socket facade、地址 helper、DHCP 解析、deferred poll wake、Router dispatch 和 listen/bind side table 做了结构化收敛。锁与并发文档现在也和实现保持一致，说明了 SERVICE -> SOCKET_SET.inner -> Service::poll()、Router/设备队列边界、TCP bind/listen side table、OOB RX wake 等关键路径。

本地验证：cargo fmt --check 通过；git diff --check origin/dev...HEAD 通过；未发现新增 [patch.crates-io]；cargo xtask clippy --package ax-net 通过（base 和 vsock 两组）；cargo test -p ax-net --lib 通过，20 个单测全部通过。rg 未发现当前文档/代码仍引用已删除的 poll_once()、ax_net::poll_interfaces()、eth0_ipv4_config()、notify_oob_rx()、VsockTransport、PendingTcp 或旧的固定 65536 listen bucket / Box<[ListenTableEntry]> 描述；剩余 ax_poll_interfaces() 是 ArceOS 对外兼容 API 名称，内部已转调 ax_net::request_poll()，历史 CHANGELOG 条目也不影响当前接口。

CI 状态：当前 head 上 format、sync-lint、std、ArceOS/Axvisor/Starry 多个 QEMU/board smoke 已有成功项；Run clippy / run_host 仍在进行中，但本地 ax-net targeted clippy 已覆盖本 PR 主要改动包，没有看到与本 PR 相关的失败。队列中的 board/HTTP smoke 不直接覆盖本次 ax-net 文档/API 清理。

重复/重叠分析：#1319 同样触及 ax-net socket/router/tcp/udp/raw 表面，但目标是 Starry socket QoS/options 与 cmsg 语义，属于同模块 partial-overlap/后续合并冲突风险，不是本 PR 的废弃接口清理和锁文档重复实现；后合入的一方需要重跑 ax-net clippy/test 并处理同文件冲突。未发现 base 或其他 open PR 已完整替代本 PR 当前清理范围。

[mai-team-app]

Review 总结

本轮按当前 head 5ffaa35cf894a58421ef546cb82bf95644205770 复审。

PR 范围：清理 ax-net 废弃公共接口（poll_interfaces()、eth0_ipv4_config()、notify_oob_rx()、旧 VsockTransport 等），新增 878 行锁与并发文档 locks.md，重构 socket 枚举分发、地址 helper、DHCP 解析、deferred poll wake、Router dispatch 和 listen/bind side table。

代码质量：改动方向正确且系统性——

1. 废弃接口移除：所有旧 API 已从 lib.rs 公共表面清除，下游 StarryOS socket.rs、ArceOS arceos_api、epoll/poll/select、axruntime、AIC8800 均已同步迁移到 request_poll() / wake_net_task_irq() / VsockSocket::new()。
2. ListenTable 重构：从预分配 65536 个 bucket 的 Box<[ListenTableEntry]> 改为按端口懒创建 Mutex<HashMap<u16, ListenTableEntry>>，减少固定内存占用。
3. TCP bind 表：TCP_BOUND_PORTS 改为 HashMap<u16, HashSet<Option<IpAddress>>>，public bind ownership 记录更精确。
4. PendingTcp 简化：PendingTcp wrapper 已移除，syn_queue 直接使用 AcceptedTcp。
5. enum_dispatch：Socket facade 用手写 match 替换为 enum_dispatch，消除 ~136 行重复匹配体。
6. DeferPollWake：统一 deferred poll wake 为结构化 DeferPollWake 类型，替代先前的元组和分散 waker。
7. init_network 拆分：validate_config、register_loopback、ensure_all_interface_configs_used、add_default_dns_servers 从大函数提取。
8. 锁文档：locks.md 按层级说明 SERVICE、SOCKET_SET、NetControl.state、SharedRouteTable、BoundedPacketQueue、DeviceHandle、spin locks 的持锁范围和锁顺序，配 mermaid 流程图。

文档与代码一致性：

• locks.md L305-L306 正确引用 TCP_BOUND_PORTS: HashMap<u16, HashSet<Option<IpAddress>>>
• locks.md L328-L329 正确引用 ListenTable.tcp: Mutex<HashMap<u16, ListenTableEntry>>
• 所有文档中的 poll_once() 引用已同步为 poll_until_idle() + 内联 get_service().poll()
• rg 验证无任何 poll_once、poll_interfaces、eth0_ipv4_config、notify_oob_rx、VsockTransport、PendingTcp、65536、Box<[ListenTableEntry]> 残留

CI 状态：当前 head 上可见 check run 均为 success 或 skipped（path-filtered CI 对 doc/ax-net-only 变更正常跳过外围测试），无 failure。

本地验证（在 reviewer clone /workspace/repo 上）：

• git diff --check origin/dev...HEAD ✅
• 无新增 [patch.crates-io] ✅
• cargo fmt --check -p ax-net ✅
• cargo xtask clippy --package ax-net（base + vsock 两组）✅
• cargo test -p ax-net --lib（20 tests）✅
• rg 废弃 API 引用全面扫描 ✅

重复/重叠分析：#1319 同样触及 ax-net socket/router/tcp/udp/raw 表面，但目标是 Starry socket QoS/options 与 cmsg 语义（IP_TOS、IPV6_TCLASS、SO_PRIORITY），属于同模块 partial-overlap，不是本 PR 的废弃接口清理和锁文档重复实现；后合入的一方需要重跑 ax-net clippy/test 并处理同文件冲突。

建议（非阻塞）：

• locks.md 中部分源码行号引用在最新 commit 中有少量偏移，建议后续按函数名链接以减少维护负担。
• PR body 已有详细变更摘要，但可补充验证命令列表方便后续 reviewer。

Powered by mimo-v2.5-pro