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

components/aic8800/src/fdrv/thread/rx.rs

@@ -24,7 +24,7 @@ pub static RX_WAKE_COUNT: AtomicU64 = AtomicU64::new(0);
 /// AIC8800 是 SDIO WiFi,RX 走自己的线程并独占 SDIO CARD_INT (IRQ#38),
 /// 不经过 ax_net 的以太网 IRQ 框架。因此数据帧入队后,需主动通知网络栈
 /// 来驱动一轮 poll(否则进来的 ARP/ICMP/数据包无人处理)。上层把此回调
-/// 设为 `ax_net::poll_interfaces`,反转依赖,避免本 crate 直接依赖网络栈。
+/// 设为 `ax_net::wake_net_task_irq`,反转依赖,避免本 crate 直接依赖网络栈。
 static RX_DATA_CALLBACK: AtomicUsize = AtomicUsize::new(0);
 
 /// 本批 RX 是否有数据帧入队(由 `build_and_enqueue_eth_frame` 置位,

docs/docs/architecture/net/api.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 8
 sidebar_label: "对外接口"
 ---
 
@@ -131,7 +131,6 @@ pub fn init_network(net_devs: EthernetDeviceList, config: NetworkConfig);
 
 ```rust
 pub fn request_poll();
-pub fn poll_interfaces();
 ```
 
 `request_poll()` 是 socket、设备和控制路径使用的轻量进度请求入口：
@@ -143,8 +142,6 @@ pub fn request_poll() {
 }
 ```
 
-`poll_interfaces()` 保留为 public trigger/debug API，内部只转调 `request_poll()`，不会在调用者线程中同步执行完整 `Service::poll()`。
-
 ### Vsock 初始化
 
 ```rust
@@ -249,14 +246,6 @@ pub struct ArpEntry {
 
 `device` 字段是真实接口名。loopback 不产生 ARP entry。
 
-### 兼容 helper
-
-```rust
-pub fn eth0_ipv4_config() -> Option<Ipv4InterfaceConfig>;
-```
-
-该函数是旧调用方的 convenience helper。新代码应优先使用 `ipv4_config(name)` 或接口 registry API，避免重新引入固定 `eth0` 假设。
-
 ## Socket Facade
 
 socket API 统一 AF_INET、AF_UNIX 和 AF_VSOCK 的公共操作形状。协议细节由具体 backend 负责。
@@ -355,7 +344,7 @@ pub enum Socket {
 | `udp::UdpSocket` | `UdpSocket::new()` | AF_INET / SOCK_DGRAM |
 | `raw::RawSocket` | `RawSocket::new(ip_version, ip_protocol)` | AF_INET / SOCK_RAW |
 | `unix::UnixSocket` | `UnixSocket::new(Transport)` | AF_UNIX / stream,dgram |
-| `vsock::VsockSocket` | `VsockSocket::new(VsockTransport)` | AF_VSOCK / stream |
+| `vsock::VsockSocket` | `VsockSocket::new()` | AF_VSOCK / stream |
 
 ### 设备绑定
 
@@ -621,7 +610,7 @@ pub struct NetConfig {
 }
 
 pub fn register_device_with_config(dev: Box<dyn EthernetDriver>, config: NetConfig);
-pub fn notify_oob_rx();
+pub fn wake_net_task_irq();
 ```
 
 `register_device_with_config()` 用于运行期加入静态 IPv4 Ethernet 设备，例如 Wi-Fi AP 模式设备。它会：
@@ -632,7 +621,7 @@ pub fn notify_oob_rx();
 - 启动该设备的 RX/TX worker。
 - 可选启用内置单客户端 DHCP server。
 
-`dedicated_poll = true` 时，设备 RX readiness 不走 Ethernet IRQ registrar，而由外部驱动线程调用 `notify_oob_rx()` 唤醒 OOB poll task。
+`dedicated_poll = true` 时，设备 RX readiness 不走 Ethernet IRQ registrar，而由外部驱动线程调用 `wake_net_task_irq()` 唤醒 OOB poll task。
 
 ## Unix Namespace API
 
@@ -677,7 +666,7 @@ TCP/UDP 在 bind port 为 `0` 时分配临时端口。临时端口范围从 `491
 
 ### API 使用建议
 
-- 新代码使用 `interfaces()`、`interface_by_name()`、`interface_by_id()` 和 `ipv4_config(name)`，不要依赖 `eth0_ipv4_config()`。
+- 使用 `interfaces()`、`interface_by_name()`、`interface_by_id()` 和 `ipv4_config(name)` 查询接口状态。
 - socket 发送路径不要直接使用 `default_routes()` 自行选路，应交给 TCP/UDP/raw backend。
 - 设备驱动只实现 `EthernetDriver`，不要直接接触 `Router` 或 `SocketSet`。
 - 需要唤醒协议栈进度时调用 `request_poll()`，不要从调用者上下文同步 poll smoltcp。

docs/docs/architecture/net/architecture.md

@@ -40,7 +40,7 @@ flowchart TB
         Query["interfaces() / default_routes() / arp_entries()"]
         DnsApi["dns_servers() / dns_query()"]
         Sockets["TcpSocket / UdpSocket / RawSocket / UnixSocket / VsockSocket"]
-        PollApi["request_poll() / poll_interfaces()"]
+        PollApi["request_poll()"]
     end
 
     subgraph Control["Control plane"]
@@ -108,6 +108,7 @@ flowchart TB
 | Single protocol core | 一个 smoltcp `Interface`、全局 `SocketSet`、socket backend、DHCP、orphan 回收、poll 调度 | [service.rs](net/ax-net/src/service.rs), [wrapper.rs](net/ax-net/src/wrapper.rs), [tcp.rs](net/ax-net/src/tcp.rs), [udp.rs](net/ax-net/src/udp.rs), [listen_table.rs](net/ax-net/src/listen_table.rs), [orphan.rs](net/ax-net/src/orphan.rs) | 本文、[Socket 系统](sockets.md) |
 | Multi-device Router | smoltcp `Device` 适配、TX 路由、RX 汇聚、loopback 快速路径 | [router.rs](net/ax-net/src/router.rs) | [多设备实现](devices.md) |
 | Device layer | Ethernet 封装/解封装、ARP、IRQ/OOB RX、rd-net 适配 | [device/](net/ax-net/src/device/) | [多设备实现](devices.md) |
+| Locking and concurrency | 全局锁顺序、设备/协议核心解耦、原子状态和 waker 协调 | [lib.rs](net/ax-net/src/lib.rs), [service.rs](net/ax-net/src/service.rs), [router.rs](net/ax-net/src/router.rs) | [锁与并发](locks.md) |
 | Configuration | 静态网络配置、DHCP、MTU、缓冲区、feature | [config.rs](net/ax-net/src/config.rs), [consts.rs](net/ax-net/src/consts.rs), `Cargo.toml` | [配置参考](configuration.md) |
 | Integration and tests | OS 集成、启动流程、测试范围 | `ax-runtime`, `starry-kernel`, `ax-api` | [集成](integration.md), [测试](testing.md) |
 
@@ -132,7 +133,7 @@ Public API 是上层 OS 模块进入 `ax-net` 的边界，主要定义在 [lib.r
 | 接口查询 | `interfaces()`、`interface_by_name()`、`ipv4_config()`、`default_routes()`、`arp_entries()` | 从控制面或设备层返回只读快照 |
 | DNS | `dns_servers()`、`dns_query()`、`dns_query_timeout()` | 读取 DNS registry，并通过临时 smoltcp DNS socket 查询 |
 | Socket facade | `TcpSocket`、`UdpSocket`、`RawSocket`、`UnixSocket`、`VsockSocket` | 为 syscall/POSIX 层提供统一 socket backend |
-| Poll 触发 | `request_poll()`、`poll_interfaces()` | 唤醒专用 net-poll worker，避免应用线程同步驱动协议栈 |
+| Poll 触发 | `request_poll()` | 唤醒专用 net-poll worker，避免应用线程同步驱动协议栈 |
 | Socket options | `GetSocketOption`、`SetSocketOption`、`Configurable` | 覆盖通用 `SO_*`、`TCP_*`、`IP_*` 选项 |
 
 Public API 的职责是做边界收敛：上层不需要知道某个 socket 是否由 smoltcp、Unix transport 或 vsock transport 实现，也不需要直接操作 `Service`、`Router` 或 `SocketSet`。具体 API 列表见 [API 参考](api.md)。

docs/docs/architecture/net/configuration.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 9
 sidebar_label: "配置参考"
 ---
 
@@ -235,7 +235,7 @@ pub struct NetConfig {
 
 ```rust
 pub fn register_device_with_config(dev: Box<dyn EthernetDriver>, config: NetConfig);
-pub fn notify_oob_rx();
+pub fn wake_net_task_irq();
 ```
 
 注册过程：
@@ -247,7 +247,7 @@ pub fn notify_oob_rx();
 - `dhcp_server_client_ip` 存在时启用内置单客户端 DHCP server。
 - 调用 `request_poll()` 让 net-poll worker 看到新状态。
 
-`dedicated_poll = true` 时，驱动侧收到 out-of-band RX 事件后调用 `notify_oob_rx()`。
+`dedicated_poll = true` 时，驱动侧收到 out-of-band RX 事件后调用 `wake_net_task_irq()`。
 
 ## 资源预算
 
@@ -414,5 +414,5 @@ let config = NetworkConfig {
 - 多网口默认路由通过 metric 控制，主出口使用较小 metric。
 - `gateway = 0.0.0.0` 用于只有直连路由的静态接口。
 - 需要稳定接口名时优先使用 `ByMac` 或 `ByDriverName`，避免依赖探测顺序。
-- 新代码通过 `ipv4_config(name)` 查询地址，不依赖 `eth0_ipv4_config()`。
+- 通过 `ipv4_config(name)` 查询指定接口地址，避免固定 `eth0` 假设。
 - 提高队列常量时应按“每 socket”或“每设备”的乘数估算内存，而不是只看单个 buffer。

docs/docs/architecture/net/devices.md

@@ -553,7 +553,7 @@ Ethernet 设备在 IP packet 与真实 Ethernet frame 之间转换，并维护 A
 Ethernet 支持两种 RX readiness 模式：
 
 - IRQ 模式：`EthernetIrqRegistrar` 注册硬件 IRQ，IRQ 到来后 `handle_ethernet_irq()` 唤醒 `poll_ready`。
-- OOB RX 模式：用于 SDIO Wi-Fi 等设备，RX 就绪由设备外部线程调用 `notify_oob_rx()`，再唤醒 `{ifname}-oob-poll` 和设备 worker。
+- OOB RX 模式：用于 SDIO Wi-Fi 等设备，RX 就绪由设备外部线程调用 `wake_net_task_irq()`，再唤醒 `{ifname}-oob-poll` 和设备 worker。
 
 `register_waker()` 只在存在 IRQ registration 或 OOB RX wake source 时注册：
 
@@ -622,7 +622,7 @@ fn poll_until_idle() {
         }
 
         while POLL_AGAIN.swap(false, Ordering::AcqRel) {
-            while poll_once() {}
+            while get_service().poll(&mut SOCKET_SET.inner.lock()) {}
         }
         POLLING_INTERFACES.store(false, Ordering::Release);
         if !POLL_AGAIN.load(Ordering::Acquire) {

docs/docs/architecture/net/flows.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 9
+sidebar_position: 10
 sidebar_label: "运行时流程"
 ---
 
@@ -146,7 +146,7 @@ fn poll_until_idle() {
         }
 
         while POLL_AGAIN.swap(false, Ordering::AcqRel) {
-            while poll_once() {}
+            while get_service().poll(&mut SOCKET_SET.inner.lock()) {}
         }
         POLLING_INTERFACES.store(false, Ordering::Release);
         if !POLL_AGAIN.load(Ordering::Acquire) {
@@ -156,7 +156,7 @@ fn poll_until_idle() {
 }
 ```
 
-`poll_once()` 的锁顺序是：
+`poll_until_idle()` 内联 poll 调用的锁顺序是：
 
 ```text
 SERVICE -> SOCKET_SET.inner -> Service::poll()
@@ -342,7 +342,7 @@ incoming SYN
   -> snoop_tcp_packet()
   -> LISTEN_TABLE.incoming_tcp_packet()
   -> create child smoltcp TCP socket
-  -> enqueue PendingTcp
+  -> enqueue AcceptedTcp
   -> smoltcp consumes SYN and advances child state
 
 TcpSocket::accept()
@@ -507,7 +507,7 @@ vsock 只在 `vsock` feature 下启用：
 
 ```text
 VsockSocket
-  -> VsockTransport::Stream
+  -> VsockStreamTransport
   -> vsock::connection_manager
   -> rdif_vsock::Interface event path
 ```

docs/docs/architecture/net/integration.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 10
+sidebar_position: 11
 sidebar_label: "系统集成"
 ---
 
@@ -114,10 +114,10 @@ ax_net::unix::register_unix_namespace(crate::unix_ns::AxFsUnixNamespace);
 
 ### 动态 Wi-Fi 与 SoftAP
 
-带 `wifi_control()` 的设备会走动态注册路径。runtime 从驱动读取 link policy，并把 OOB RX 唤醒函数设置为 `ax_net::notify_oob_rx`：
+带 `wifi_control()` 的设备会走动态注册路径。runtime 从驱动读取 link policy，并把 OOB RX 唤醒函数设置为 `ax_net::wake_net_task_irq`：
 
 ```rust
-ctrl.set_rx_wake(ax_net::notify_oob_rx);
+ctrl.set_rx_wake(ax_net::wake_net_task_irq);
 let policy = ctrl.link_policy();
 ```