feat(net/udp): UDP 数据面并入 netMsgQueue 串行执行（#73）

前置来自 #57 SNTP 调研：旧 net_sendto / net_recvfrom 由调用方直调 SPI 且无限自旋收包，既违约「netTask 是芯片唯一访问者」，又把 IWDG 预算吃在自旋里。改造面 - 新增 Drivers/BSP/NET/net_udp.c/.h（真机专属，模拟器不编译）： bind/set_peer/sendto/recvfrom 四条执行体 + 挂起收包表 + tick； net_msg_type_t 加四型，公开 API 一律「入队 → 睡在通知上」。 - 源地址出参不搭 net_msg_t（按值拷贝，AGENTS 禁加回传字段）：改住 net_udp.c 的 per-fd 槽，netTask 就地写回调用方内存，通知值只带结果码；每条出口都清槽，泄漏 = 该 fd 永久 BUSY。 - 发送复用 net_send_locked，不写第二份分块逻辑；「会话是否已死」收成一条判据 net_send_state_down()（TCP 看 ESTABLISHED、UDP 看 UDP_OPEN），原先 4 处各写一遍。 - 顺带修掉真缺陷（新条 TRAP-NET-22）：旧 sendto 把 DesIP 写成具体 IP，芯片静默切 UDP Client，而旧 recvfrom 无条件剥 8 字节 → SNTP 这类 48 B 应答丢载荷前 8 字节并交出垃圾源地址。加 udp_mode（塞进原有 padding，sizeof 不变）、bind 恒 SERVER、显式对端 sendto 切 CLIENT、set_peer(fd, NULL) 轻量回 SERVER，仅 SERVER 且 avail >= 8 才剥头。 - 截断定案：一次调用交付一个数据报，buf 装不下的尾巴用 64 B 栈上 scratch 排空（不用 clear_recv_buf——它连后面已到达的包一起丢）。 - 取消点接齐：net_init 重建 cancel_all、net_socket 分配 fd clear、 net_close settle_close + clear、重 bind 前先结算等包者， net_process_messages 第 5 个 tick 位挂 net_udp_tick。 - 收紧两处契约（原实现无生产调用者）：UDP 未 bind 一律 -5； net_recv / _nb / _to 拒 DGRAM（绕过剥头就是静默吃 8 字节）； NET_ERR_NOT_IN_NETTASK(-12) 退役为历史常量并写明原因。验证 - 主机单测 test/host/net_socket 全套 616/616 绿（改造前 470）：新分片 ns_s7_udp.c 20 组，改写 440 / 555 / 560 组；覆盖率 net_udp.c 234/236（99.2%）、net_socket.c 956/969（98.7%）， scripts/test_coverage_baseline.json 随本提交登记新文件。 - 测试抓到 4 个被测码真 bug：自等守卫误用调用侧谓词、芯片长度被读两次、槽指针取在 fd 合法性检查之前、重 bind 静默作废等待者。 - Keil ARMCC 0 Error(s) 0 Warning(s)；net_udp.o Code 1,358 / ZI 224 （8 fd × 28 B，其余模块零增长），全仓 RW_IRAM1 72.2%；内存台账受管区按门禁提示用 --write / --update 机器回填，未手改数字。 - pre-commit 全量钩子（含 doc-links、coding-standard、mem-budget、 generated-fresh、bsp-err、registration、nested-comment）全绿。限度 - 本轮无板子：真机回归 5 条（两端互通、set_peer(NULL) 能否恢复收广播、截断排空后下一包完整性、挂起 recv 期间 IWDG 余量、bind 写 DesIP 与 open 先后的真芯片效果）已写进覆盖率口径「台架必验」。 - scripts/stack_report.py 退出码 1 是 10-26 起挂在账上的 iec104Task 栈债（margin 1,016 < 1,024，见 docs/代码规范/pre-commit使用说明.md: 122）；本轮只让 net_bind 的 UDP 分支多一层静态帧（1,544 → 1,600）， netTask margin 1,888 与 timeSyncTask 1,152 不受影响。抬栈要过 mem-budget 台账，不在本分支自行处理。 - 登记簿销项按仓库约定留给主工作树，本分支不动 docs/任务规划/**。
2026-11-03 18:08:27 +08:00
parent 2b5eb1c0db
commit fff961d803
26 changed files with 3550 additions and 557 deletions
@@ -194,7 +194,21 @@ void ch395f_read_recv_buf(uint8_t sock, uint8_t *p_data, uint16_t len)
    g_chip.last_read_len = len;
    fake_log('r');
    if ((p_data != NULL) && (len > 0U)) {
-        if (g_fx.recv_bytes_n > 0U) {
+        if ((g_fx.recv_bytes_n > 0U) && (g_fx.recv_stream_en != 0U)) {
+            /* 流式读：从游标处继续交（UDP 一个数据报 = 头 + 载荷两次读，
+             * 每次都从第 0 字节重交的话，"剥头"与"把包头当载荷"断言不出差别）。
+             * 游标越过预置内容后补零：截断排空要的就是"读空了这个包"这一事实。 */
+            uint16_t left = (g_fx.recv_pos < g_fx.recv_bytes_n)
+                                ? (uint16_t)(g_fx.recv_bytes_n - g_fx.recv_pos)
+                                : 0U;
+            uint16_t n = (len < left) ? len : left;
+
+            (void)memcpy(p_data, &g_fx.recv_bytes[g_fx.recv_pos], n);
+            g_fx.recv_pos = (uint16_t)(g_fx.recv_pos + n);
+            if (n < len) {
+                (void)memset((uint8_t *)p_data + n, 0, (size_t)(len - n));
+            }
+        } else if (g_fx.recv_bytes_n > 0U) {
            /* 已预置内容：按预置交付，不足部分补零（默认分支行为不变） */
            uint16_t n = (len < g_fx.recv_bytes_n) ? len : g_fx.recv_bytes_n;

@@ -219,15 +233,46 @@ void ch395f_fake_set_recv_bytes(const uint8_t *p, uint16_t n)
        g_fx.recv_bytes[i] = (p != NULL) ? p[i] : (uint8_t)0xA5U;
    }
    g_fx.recv_bytes_n = n;
+    /* 既有语义：内容预置不带动游标（默认关，逐字节行为与 2026-10-24 一致） */
+    g_fx.recv_stream_en = 0U;
+    g_fx.recv_pos = 0U;
+}
+
+/* 内容预置 + 开流式读 + 游标归零：一次调用 = 芯片缓冲里躺着这么多字节 */
+void ch395f_fake_set_recv_stream(const uint8_t *p, uint16_t n)
+{
+    ch395f_fake_set_recv_bytes(p, n);
+    g_fx.recv_stream_en = (n > 0U) ? 1U : 0U;
+    g_fx.recv_pos = 0U;
+}
+
+/* 打开 WRITE_SEND_BUF 内容捕获（默认关：既有假件"内容不可断言"的行为不变） */
+void ch395f_fake_enable_write_capture(void)
+{
+    g_fx.write_cap_en = 1U;
+    g_fx.write_cap_n = 0U;
+    g_fx.write_bytes = 0U;
 }

 void ch395f_write_send_buf(uint8_t sock, uint8_t *p_data, uint16_t len)
 {
-    (void)p_data;
    g_chip.write_calls++;
    g_chip.last_sock = sock;
    g_chip.last_read_len = len;
    fake_log('w');
+    if (g_fx.write_cap_en != 0U) {
+        /* 按写入顺序拼接（分块发送时能看出第二块是不是接着第一块的尾巴）；
+         * 越界部分只计数，避免为长报文再开一份大缓冲。 */
+        uint16_t space = (uint16_t)(CH395F_FAKE_WRITE_CAP - g_fx.write_cap_n);
+        uint16_t n = (len < space) ? len : space;
+
+        if ((p_data != NULL) && (n > 0U)) {
+            (void)memcpy(&g_fx.write_cap[g_fx.write_cap_n], p_data, n);
+            g_fx.write_cap_n = (uint16_t)(g_fx.write_cap_n + n);
+        }
+        g_fx.write_bytes += (uint32_t)len;
+    }
+    (void)p_data;
 }

 uint8_t ch395f_open_socket(uint8_t sock)
@@ -67,6 +67,9 @@
 #define CH395F_FAKE_QUEUE_LEN     24
 #define CH395F_FAKE_LOG_LEN       96
 #define CH395F_FAKE_GLOB_QUEUE    24
+/* 写内容捕获容量（测试自用，真实头无此宏 → 不参与假芯片常量对齐门）：
+ * 256 够覆盖"一个小数据报全文"与"分块发送首块的前 256 字节"两类断言。 */
+#define CH395F_FAKE_WRITE_CAP     256

 /* ===== 扩展区（2026-10-24，net_socket 主机单测批次；**纯新增**，上面既有宏/字段/函数
 *       一字未动，net_listener / net_events / net_pending 三套的语义不受影响）=====
@@ -266,6 +269,20 @@ typedef struct {
     * 就还会再报一次。net_socket.c 的多块发送要的就是这个稳态，没有它就只能
     * 造"写完一块就再也等不到空闲"的假死形态。 */
    uint8_t  sint_sticky[CH395F_FAKE_SOCK_MAX];
+    /* —— 2026-11-03 UDP 队列化改造追加（默认全 0 → 既有行为逐字不变）—— */
+    /* GET_RECV_BUF 的**流式读**开关：UDP 一个数据报 = 8 字节信息头 + 载荷，
+     * 生产代码是**两次**读（先剥头再读载荷），而 set_recv_bytes 每次都从预置
+     * 内容第 0 字节交付——那样"剥掉头"与"把包头当载荷"在断言里长得一样。
+     * 本开关让交付内容带游标：第二次读拿到的是第 8 字节往后的载荷。 */
+    uint8_t  recv_stream_en;
+    uint16_t recv_pos;                 /* 游标：已交付字节数（截断排空要断言它） */
+    /* WRITE_SEND_BUF 的**内容捕获**开关：假芯片原本忽略 p_data（既有用例只数次数），
+     * 但 UDP 发送要钉"写进芯片的是不是调用方那份字节、分块边界对不对"。
+     * 默认 0 → 既有"内容不可断言"的行为一字不变。 */
+    uint8_t  write_cap_en;
+    uint8_t  write_cap[CH395F_FAKE_WRITE_CAP];   /* 按写入顺序拼接的字节（够 2 块 1KB 的前 256B） */
+    uint16_t write_cap_n;              /* 已捕获字节数（超出容量后只计数不存） */
+    uint32_t write_bytes;              /* 芯片收到的总字节数（含未捕获部分） */
 } ch395f_fake_ext_t;

 typedef struct {
@@ -310,6 +327,12 @@ void ch395f_fake_push_glob(uint16_t v);   /* 预置全局中断返回序列 */
 void ch395f_fake_set_sint_sticky(uint8_t sock, uint8_t mask);
 /* 预置 GET_RECV_BUF 交付的字节（n=0 撤销预置）；p 可为 NULL（表示填 n 个 0xA5） */
 void ch395f_fake_set_recv_bytes(const uint8_t *p, uint16_t n);
+/* 同上并**开启流式读**（游标归零）：UDP 用例要的是"头 8 字节 + 载荷"两次读
+ * 各自拿到正确片段，而不是每次都从第 0 字节重交。 */
+void ch395f_fake_set_recv_stream(const uint8_t *p, uint16_t n);
+/* 开启 WRITE_SEND_BUF 内容捕获（g_fx.write_cap / write_cap_n / write_bytes）：
+ * 默认关 → 既有"内容不可断言"的行为一字不变。 */
+void ch395f_fake_enable_write_capture(void);
 /* 顺序断言辅助：清空调用日志 / 找某个短名第一次出现的位置（-1=没调过）。
 * 刻意提供"清零日志"，否则一次长轮询（如 sock_reset 的几十轮 'x'）会把 96 格
 * 环形外的顺序信息挤掉，让后续场景的顺序断言失真。 */
@@ -50,6 +50,10 @@ int g_ns_debug_count;

 /* —— 被测生产源 —— */
 #include "net_socket.c"
+/* UDP 数据面模块（2026-11-03 队列化改造）：与 net_socket.c 同一 TU ——
+ * 它调 net_send_locked / net_get_sock / net_poll / net_dynamic_port_next 等
+ * net_socket.c 内部符号，分开编译会撞链接面（本套既有做法） */
+#include "net_udp.c"

 /* ===================== 断言框架 ===================== */

@@ -90,6 +94,8 @@ static int ns_slot_index_of(TaskHandle_t h)
 /* 生产模块的 static 在场景之间会残留，每个场景开头必须显式清干净（漏一次红一片） */
 static void reset_all(void)
 {
+    int i;
+
    (void)memset(s_net_socks, 0, sizeof(s_net_socks));
    (void)memset(s_net_errno_slots, 0, sizeof(s_net_errno_slots));
    (void)memset(s_local_ip, 0, sizeof(s_local_ip));
@@ -100,6 +106,11 @@ static void reset_all(void)
    /* UDP 上下文守卫的判据也是生产 static：不清就会把上一场景的"执行任务"带进本场景
     * （表现为守卫判错上下文，且与任务句柄复用后的地址撞车） */
    s_net_owner_task = NULL;
+    /* net_udp.c 的 per-fd 槽（挂起接收 + 源地址出参指针 + 武装态）同为生产 static：
+     * 残留一个 armed 槽，下一场景就会把源地址写进上一场景的栈内存 */
+    for (i = 0; i < NET_MAX_SOCKETS; i++) {
+        net_udp_clear(i);
+    }
    g_ns_info_count = 0;
    g_ns_error_count = 0;
    g_ns_debug_count = 0;
@@ -137,6 +148,25 @@ static void bring_up_netctx(void)
    g_ns_cur_task = (TaskHandle_t)&g_ns_task_net;
 }

+/* UDP 场景前置：DGRAM + bind（2026-11-03 队列化改造后，UDP 两个数据面接口都要求
+ * 芯片侧 Socket 已打开，未 bind 一律 NOTCONN——所以"先 bind"从可选项变成每个
+ * UDP 场景的第一行）。**不在这里 bring_up**：当前上下文（netTask 还是 caller）
+ * 决定 bind 走直接执行还是入队，由场景自己选，本函数只做 socket + bind。
+ * 返回 fd，失败返回 -1（bind 失败=假芯片 open 被拒，场景必须显式失败而不是继续跑）。 */
+static int udp_bind_ctx(int port_host)
+{
+    struct net_sockaddr_in in;
+    int fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM);
+
+    (void)memset(&in, 0, sizeof(in));
+    in.sin_family = NET_AF_INET;
+    in.sin_port = net_htons((uint16_t)port_host);
+    if (net_bind(fd, (const struct net_sockaddr *)&in, (int)sizeof(in)) != 0) {
+        return -1;
+    }
+    return fd;
+}
+
 /* 直接造一个在用的控制块（多数场景不需要走完整的 socket()/bind()） */
 static int mk_sock(int type, net_sock_state_t state)
 {
@@ -155,6 +185,8 @@ static int mk_sock(int type, net_sock_state_t state)
 #include "ns_s4_state.c"
 #include "ns_s5_io.c"
 #include "ns_s6_edges.c"
+/* 2026-11-03 UDP 队列化改造：数据面（模式/剥头/单包交付）+ 串行化 + 挂起收包 */
+#include "ns_s7_udp.c"

 /* = 分片 1 纯函数面与 fd 表 ===================== */

@@ -706,6 +738,9 @@ int main(void)
    printf("[shard6] edge branches and remaining exits\n");
    ns_run_s6();

+    printf("[shard7] UDP datagram plane: serialised chip work, modes, pending receive\n");
+    ns_run_s7();
+
    printf("=== NET Socket Tests: %d/%d PASSED (failed=%d) ===\n",
           s_passed, s_total, s_failed);
    return (s_failed == 0) ? 0 : 1;
@@ -230,6 +230,21 @@ int net_pending_active(int sockfd)

 /* ================= net_pending.h（send 侧） ================= */

+/* 会话是否已断（net_send_locked / net_send_pending 的共用判据，真实实现按 type 分流）。
+ * 桩**必须复刻分流**：写死 TCP 语义的话，UDP 挂起 send 的"会话断了要中止"分支
+ * 在本套里永远测不到（2026-11-03 UDP 队列化改造新增边界）。 */
+int net_send_state_down(const net_sock_t *p_sock)
+{
+    g_peers.state_down_calls++;
+    if (p_sock == NULL) {
+        return 1;
+    }
+    if (p_sock->type == NET_SOCK_DGRAM) {
+        return (p_sock->state != NET_SOCK_STATE_UDP_OPEN) ? 1 : 0;
+    }
+    return (p_sock->state != NET_SOCK_STATE_ESTABLISHED) ? 1 : 0;
+}
+
 int net_send_pending_register(int sockfd, const void *buf, int len, int sent,
                              TaskHandle_t caller)
 {
@@ -57,6 +57,8 @@ typedef struct {
    int   send_cancel_all_calls;
    int   last_snd_cancel_err;
    int   send_notified;
+    /* 会话断开判据被问次数（2026-11-03 起该判据按 type 分流，TCP/UDP 共用一份） */
+    int   state_down_calls;

    /* —— net_events —— */
    int evt_connect_calls;
@@ -425,7 +425,10 @@ static void tc_430_connect(void)
    reset_all();
 }

-/* TC-NETSOCK-440 UDP 数据报：sendto 分块 / recvfrom 剥 8 字节报文头 */
+/* TC-NETSOCK-440 UDP 数据报（2026-11-03 队列化改造后）：
+ * 三条硬前提写进每一段——UDP 必须**先 net_bind**（芯片侧 Socket 没打开就发/收，
+ * 是 NOTCONN 而不是"看起来能用"），执行任务（netTask）上下文走**直接执行**分支，
+ * 别的任务走 netMsgQueue（完整队列链路由分片 7 ns_s7_udp.c 钉）。 */
 static void tc_440_udp_datagram(void)
 {
    static char big[2100];
@@ -445,62 +448,71 @@ static void tc_440_udp_datagram(void)

    fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM);
    CHECK(net_sendto(fd, NULL, 5, 0, NULL, 0) == -1 && net_get_errno() == NET_ERR_INVAL,
-          "TC-NETSOCK-440d sendto invalid arguments -> INVAL");
+          "TC-NETSOCK-440d sendto invalid arguments -> INVAL (argument checks come before the bind check)");
    CHECK(net_recvfrom(fd, NULL, 5, NET_MSG_DONTWAIT, NULL, NULL) == -1 &&
          net_get_errno() == NET_ERR_INVAL, "TC-NETSOCK-440e recvfrom with a NULL buf -> INVAL");
+    /* 参数没错但还没 bind：新收紧，明确报 NOTCONN（改造前这里会直调芯片 open 都没开的 Socket） */
+    CHECK(net_sendto(fd, "x", 1, 0, NULL, 0) == -1 && net_get_errno() == NET_ERR_NOTCONN,
+          "TC-NETSOCK-440p sendto before net_bind -> NOTCONN (the chip socket is not open yet)");

-    /* 带目的地址：先设 DesIP/DesPort 再写数据（不带上限的自旋实现，健康链路一次写完） */
+    /* 带目的地址：先设 DesIP/DesPort 再写数据（执行任务上下文=直接执行，健康链路一次写完） */
    reset_all();
    bring_up_netctx();
-    fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM);
+    fd = udp_bind_ctx(8888);
+    CHECK(fd >= 0, "TC-NETSOCK-440q bind precondition");
    (void)memset(&in, 0, sizeof(in));
    in.sin_port = net_htons(8888);
    in.sin_addr.s_addr = net_inet_addr("192.168.31.9");
+    ch395f_fake_enable_write_capture();
    CHECK(net_sendto(fd, "hello", 5, 0, sa, (int)sizeof(in)) == 5,
          "TC-NETSOCK-440f sendto returns the number of bytes sent");
    CHECK(g_fx.des_ip[fd][3] == 9U && g_fx.des_port[fd] == 8888U,
          "TC-NETSOCK-440g the destination address travels with this send (UDP is connectionless, address is per packet)");
    CHECK(g_chip.write_calls == 1 && s_net_socks[fd].send_bytes == 5U,
          "TC-NETSOCK-440h small packet written in one go plus statistics");
+    CHECK(g_fx.write_cap_n == 5U && memcmp(g_fx.write_cap, "hello", 5) == 0,
+          "TC-NETSOCK-440r the chip received exactly the caller's five bytes (the queue carries a pointer, not a copy of the payload)");
+    CHECK(s_net_socks[fd].udp_mode == NET_UDP_MODE_CLIENT,
+          "TC-NETSOCK-440s an explicit destination puts the chip in client mode and the software books it");

-    /* 大报分块（仍受 NET_SEND_CHUNK_MAX 上界约束） */
+    /* 大报分块（仍受 NET_SEND_CHUNK_MAX 上界约束，与 TCP 同一份实现） */
    reset_all();
    bring_up_netctx();
-    fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM);
+    fd = udp_bind_ctx(8888);
    g_ns_int_pin_set = 0;
    ch395f_fake_push_glob((uint16_t)(1U << (fd + 4)));
    ch395f_fake_set_sint_sticky((uint8_t)fd, CH395F_SINT_STAT_SENBUF_FREE);
    CHECK(net_sendto(fd, big, 2100, 0, NULL, 0) == 2100, "TC-NETSOCK-440i all 2100 bytes delivered");
    CHECK(g_chip.write_calls == 3, "TC-NETSOCK-440j UDP also chunks at the 1024 bound (the FIFO overrun constraint matches TCP)");

-    /* recvfrom：前 8 字节是芯片 UDP 头（长度/srcPort/srcIP），要剥掉再交出去 */
+    /* recvfrom：服务器模式前 8 字节是芯片信息头（长度/源端口/源 IP），剥掉再交出去 */
    reset_all();
    bring_up_netctx();
-    fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM);
+    fd = udp_bind_ctx(8888);
    ch395f_fake_push_recv_len((uint8_t)fd, 8U + 20U);
    addrlen = (int)sizeof(in);
    (void)memset(&in, 0, sizeof(in));
-    CHECK(net_recvfrom(fd, buf, (int)sizeof(buf), 0, sa, &addrlen) == 20,
+    CHECK(net_recvfrom(fd, buf, (int)sizeof(buf), NET_MSG_DONTWAIT, sa, &addrlen) == 20,
          "TC-NETSOCK-440k returns 20: the 8-byte report header was stripped, the header is not handed over as data");
    CHECK(addrlen == (int)sizeof(in) && in.sin_family == NET_AF_INET,
          "TC-NETSOCK-440l fills the source address structure and length");

-    /* 无数据 + 非阻塞 → WOULDBLOCK（阻塞形态是自旋无预算，本套刻意不测，见交付说明） */
+    /* 无数据 + 非阻塞 → WOULDBLOCK */
    reset_all();
    bring_up_netctx();
-    fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM);
+    fd = udp_bind_ctx(8888);
    CHECK(net_recvfrom(fd, buf, (int)sizeof(buf), NET_MSG_DONTWAIT, NULL, NULL) == -1 &&
          net_get_errno() == NET_ERR_WOULDBLOCK, "TC-NETSOCK-440m non-blocking with no data -> WOULDBLOCK");
    s_net_socks[fd].blocking = 0U;
    CHECK(net_recvfrom(fd, buf, (int)sizeof(buf), 0, NULL, NULL) == -1 &&
          net_get_errno() == NET_ERR_WOULDBLOCK, "TC-NETSOCK-440n the non-blocking attribute follows the same decision");
-    /* 短于 8 字节的残包：不剥头，整包交出去（钉当前实现的边界，不猜"应该怎么算"） */
+    /* 服务器模式短于 8 字节的残包：无从判头，整包按载荷交付（440o 的既有定案保留） */
    reset_all();
    bring_up_netctx();
-    fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM);
+    fd = udp_bind_ctx(8888);
    ch395f_fake_push_recv_len((uint8_t)fd, 5U);
-    CHECK(net_recvfrom(fd, buf, (int)sizeof(buf), 0, NULL, NULL) == 5,
-          "TC-NETSOCK-440o with recv_len<8 no header is stripped, the whole packet is returned (current implementation)");
+    CHECK(net_recvfrom(fd, buf, (int)sizeof(buf), NET_MSG_DONTWAIT, NULL, NULL) == 5,
+          "TC-NETSOCK-440o with recv_len<8 no header is stripped, the whole packet is delivered");
    reset_all();
 }

@@ -179,37 +179,51 @@ static void tc_505_inner_wait_and_last_chunk(void)
    reset_all();
 }

-/* TC-NETSOCK-506 UDP sendto：等待腾出与短写留痕（与 TCP 同一套语义的另一份实现） */
+/* TC-NETSOCK-506 UDP 发送卡住：两条出口都要留痕（2026-11-03 队列化改造后重写）
+ * 改造前这里钉的是"netTask 内自旋到 1s 停滞超时后短写"——那 1 秒全部花在 netTask
+ * 里，正是本次要消掉的形态。改造后 UDP 与 TCP 共用 net_send_locked 的预算机：
+ *   ① 执行任务上下文：无人能完成挂起 → 拒绝自等 → -1(BUSY)，且不写忙缓冲；
+ *   ② 调用方上下文：超预算转挂起（登记进 net_send_pending，与 TCP 同一张表），
+ *      登记里带的是**已写进芯片的字节数**——续传从断点起，已交付的字节绝不重发
+ *      （重发半截数据报 = 对端收到两个包，比丢包更难查）。
+ */
 static void tc_506_sendto_stall_and_short(void)
 {
    static char big[2100];
    int fd;
    int rc;

+    /* ① 执行任务上下文、发送缓冲一开始就不空闲 */
    bring_up_netctx();
-    fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM);
+    fd = udp_bind_ctx(8888);
    s_net_socks[fd].send_ready = 0U;
    g_ns_int_pin_set = 0;
    ch395f_fake_push_glob((uint16_t)(1U << (fd + 4)));
-    /* 每轮只走 1ms：先命中 NET_SEND_TIMEOUT_MS(1s) 之前不会有别出口 → 短写 */
+    /* 每轮 500ms：停在自旋预算(2ms)与停滞超时(1000ms)之间 → 走"转挂起被拒"这条口 */
    g_ns_poll_tick_inc = 500U;
    rc = net_sendto(fd, big, 2100, 0, NULL, 0);
-    CHECK(rc < 2100 && rc >= 0,
-          "TC-NETSOCK-506a sendto stalled returns only what went out (short-write semantics match TCP)");
-    CHECK(g_ns_error_count >= 2,
-          "TC-NETSOCK-506b both the stall [ERR] and the short-write [ERR] must be there (missing one degrades into a silent truncation)");
+    CHECK(rc == -1 && net_get_errno() == NET_ERR_BUSY,
+          "TC-NETSOCK-506a a stall inside netTask now gives up with BUSY instead of spinning a full second and short-writing");
+    CHECK(g_chip.write_calls == 0,
+          "TC-NETSOCK-506b it never wrote into a busy buffer (no half datagram left in the chip FIFO)");
+    CHECK(g_peers.send_reg_calls == 1,
+          "TC-NETSOCK-506c the hand-over was really attempted (the refusal comes from the register side, not from us not trying to hand over)");
    reset_all();

-    /* 写完一块后等发完的超时出口 */
-    bring_up_netctx();
-    fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM);
+    /* ② 调用方上下文：第一块写得进、之后芯片不再报空闲 → 第二块转挂起 */
+    bring_up();
+    fd = udp_bind_ctx(8888);
    g_ns_int_pin_set = 0;
    ch395f_fake_push_glob((uint16_t)(1U << (fd + 4)));
-    g_fake.int_status[fd] = CH395F_SINT_STAT_SENBUF_FREE;   /* 只给一次 */
+    g_fake.int_status[fd] = CH395F_SINT_STAT_SENBUF_FREE;   /* 只给一次空闲 */
    g_ns_poll_tick_inc = 500U;
-    rc = net_sendto(fd, big, 2100, 0, NULL, 0);
-    CHECK(rc >= 1024 && rc < 2100,
-          "TC-NETSOCK-506c first chunk delivered and the second chunk wait timed out -> a value between 1024 and 2099");
+    rc = net_send_locked(&s_net_socks[fd], big, 2100, (TaskHandle_t)&g_ns_task_caller);
+    CHECK(rc == NET_PENDING_REGISTERED,
+          "TC-NETSOCK-506d a UDP send past the spin budget converts to pending exactly like TCP (no in-place busy wait)");
+    CHECK(g_peers.send_reg_calls == 1 && g_peers.last_snd_sent == 1024,
+          "TC-NETSOCK-506e the pending entry carries the bytes already written (1024), so the resume starts at the break point");
+    CHECK(g_chip.write_calls == 1,
+          "TC-NETSOCK-506f exactly one chunk reached the chip before handing over");
    reset_all();
 }

@@ -447,7 +461,10 @@ static void tc_555_udp_src_addr(void)
    int fd;

    bring_up_netctx();
-    fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM);
+    /* 2026-11-03 队列化改造：剥头只发生在**服务器模式**，而服务器模式由 bind 建立
+     * （DesIP=0xFFFFFFFF）。改造前这段直接 net_socket 就能收，是因为它无条件剥头——
+     * 那正是本组要修的缺陷（客户端模式没有头，照剥就吃掉载荷前 8 字节）。 */
+    fd = udp_bind_ctx(8888);
    ch395f_fake_push_recv_len((uint8_t)fd, (uint16_t)(8U + 3U));
    ch395f_fake_set_recv_bytes(hdr, (uint16_t)sizeof(hdr));

@@ -467,91 +484,84 @@ static void tc_555_udp_src_addr(void)
 }


-/* TC-NETSOCK-560 UDP 上下文守卫：非执行任务不得直调芯片
- * 三条一起才成立，缺一条都不算把危险面关掉：
- *   ① 执行任务内照常成功（守卫不是"把 UDP 判死"）
- *   ② 非执行任务被拒且**一次芯片事务都没有**（拒了却已经抢过 SPI = 白拒）
- *   ③ 正常错误路径不被守卫吞掉，且**走消息队列的接口完全不受影响**
- *      （那些接口生来就是给非 netTask 用的，误伤它们才是大事故）
+/* TC-NETSOCK-560 UDP 上下文契约（2026-11-03 队列化改造**反转**了本组的原命题）
+ * 改造前：非执行任务调用 net_sendto / net_recvfrom 一律 NET_ERR_NOT_IN_NETTASK(-12)
+ *         ——那是 2026-10-24"先把危险面关掉"的临时守卫（SPI 竞争 TRAP-NET-14）。
+ * 改造后：任意任务都能调，芯片事务全部串行到 netTask 执行；守卫随之退役。
+ * 三条一起才成立，缺一条都不算把改造钉住：
+ *   ① 非执行任务调用**成功**，且芯片事务发生在泵（=netTask 上下文）里，不在调用方
+ *   ② 执行任务内直接执行，不投自己（板级用例照旧可在自己任务里裸调）
+ *   ③ 参数/状态错误优先于上下文；-12 这个码在 UDP 路径上不再出现
 */
 static void tc_560_udp_context_guard(void)
 {
    char buf[8];
    int fd;

-    /* ① 执行任务上下文：与修复前逐字相同 */
-    bring_up_netctx();
-    fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM);
-    CHECK(net_sendto(fd, "abc", 3, 0, NULL, 0) == 3,
-          "TC-NETSOCK-560a net_sendto unchanged inside the executing task");
-    reset_all();
-
-    /* ② 非执行任务：拒绝 + 零芯片事务（bring_up 里 net_init 是以 netTask 身份跑的，
-     *    此刻 g_ns_cur_task 已还原成 caller，正是"别的任务"） */
+    /* ① 非执行任务（bring_up 已把身份还原成 caller）：改造前被拒，改造后必须成 */
    bring_up();
-    fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM);
+    fd = udp_bind_ctx(8888);
+    CHECK(fd >= 0, "UDP-560a0 bind from a caller task succeeds (queue path, no direct SPI)");
    g_chip.write_calls = 0;
    g_chip.read_calls = 0;
    g_fxchip.set_des_ip_calls = 0;
-    g_fxchip.glob_calls = 0;
-    g_ns_poll_calls = 0;
-    g_ns_error_count = 0;
+    g_ns_put_calls = 0;
+    g_ns_notify_calls = 0;
+    CHECK(net_sendto(fd, "abc", 3, 0, NULL, 0) == 3,
+          "UDP-560a non-executing task's sendto now succeeds (it used to be refused with -12)");
+    CHECK(g_chip.write_calls == 1 && g_ns_put_calls >= 1 && g_ns_notify_calls >= 1,
+          "UDP-560b the write happened while the pump ran as netTask: the caller enqueued, blocked, and was notified (serialised, not forbidden)");
+    CHECK(net_get_errno() != NET_ERR_NOT_IN_NETTASK,
+          "UDP-560c the retired guard does not come back: -12 is never returned on a success path");

-    CHECK(net_sendto(fd, "abc", 3, 0, NULL, 0) == -1 &&
-          net_get_errno() == NET_ERR_NOT_IN_NETTASK,
-          "TC-NETSOCK-560b non-executing task gets NET_ERR_NOT_IN_NETTASK (exact code, not -1)");
-    CHECK(g_chip.write_calls == 0 && g_fxchip.set_des_ip_calls == 0 &&
-          g_ns_poll_calls == 0,
-          "TC-NETSOCK-560c clean refusal: zero writes, zero set_des_ip, zero net_poll rounds");
-    CHECK(net_recvfrom(fd, buf, (int)sizeof(buf), NET_MSG_DONTWAIT, NULL, NULL) == -1 &&
-          net_get_errno() == NET_ERR_NOT_IN_NETTASK,
-          "TC-NETSOCK-560d net_recvfrom guarded the same way");
-    CHECK(g_chip.read_calls == 0 && g_fxchip.glob_calls == 0 && g_ns_poll_calls == 0,
-          "TC-NETSOCK-560e recvfrom touched no chip and no global interrupt register either");
-    CHECK(g_ns_error_count == 2,
-          "TC-NETSOCK-560f each refusal logs one ERR line (silence hides the wrong task)");
+    ch395f_fake_push_recv_len((uint8_t)fd, 8U + 3U);
+    s_net_socks[fd].readable = 1U;
+    CHECK(net_recvfrom(fd, buf, (int)sizeof(buf), NET_MSG_DONTWAIT, NULL, NULL) == 3,
+          "UDP-560d non-executing task's recvfrom goes the same route and returns the payload");
+    CHECK(g_chip.read_calls >= 2 && g_ns_block_waits >= 1,
+          "UDP-560e the caller slept on its own notification while netTask did the SPI reads (the old spin-in-caller shape is gone)");

-    /* ③ 正常错误路径优先：守卫排在参数校验之后 */
+    /* ③ 参数检查排在上下文与状态之前（守卫退役不许顺手把错误优先级改掉） */
    CHECK(net_sendto(-1, "abc", 3, 0, NULL, 0) == -1 &&
-          net_get_errno() == NET_ERR_BADF, "TC-NETSOCK-560g out-of-range fd still reports BADF first");
+          net_get_errno() == NET_ERR_BADF, "UDP-560f out-of-range fd still reports BADF first");
    CHECK(net_sendto(fd, NULL, 3, 0, NULL, 0) == -1 &&
-          net_get_errno() == NET_ERR_INVAL,
-          "TC-NETSOCK-560h NULL buf still reports INVAL, the guard does not swallow it");
+          net_get_errno() == NET_ERR_INVAL, "UDP-560g NULL buf still reports INVAL");
    CHECK(net_recvfrom(fd, NULL, 3, NET_MSG_DONTWAIT, NULL, NULL) == -1 &&
-          net_get_errno() == NET_ERR_INVAL, "TC-NETSOCK-560i recvfrom keeps the same precedence");
-
-    /* ④ 走消息队列的接口不受守卫影响：同一个非 netTask 上下文照常能把活干完 */
-    CHECK(net_close(fd) == 0,
-          "TC-NETSOCK-560j net_close from a non-executing task still works (queue path untouched)");
-    /* 执行完的证据用"收到回执 + 槽位释放"，不看 close_calls：芯片此刻已是
-     * CLOSED，走的是快路径（不再补发 CLOSE，见 TC-NETSOCK-320a/b），拿它当证据
-     * 会把一条正确的快路径判成失败 */
-    CHECK(s_net_socks[fd].in_use == 0U && g_ns_notify_calls >= 1,
-          "TC-NETSOCK-560k queue path really completed (receipt seen and slot released)");
+          net_get_errno() == NET_ERR_INVAL, "UDP-560h recvfrom keeps the same precedence");
    reset_all();

-    /* ⑤ 未捕获执行任务（net_init 没跑）：守卫不抢先，仍由参数/状态检查给确定错误 */
+    /* ② 执行任务上下文：直接执行，不投自己（板级 testTask 形态） */
+    bring_up_netctx();
+    fd = udp_bind_ctx(8888);
+    g_ns_put_calls = 0;
+    CHECK(net_sendto(fd, "abc", 3, 0, NULL, 0) == 3,
+          "UDP-560i netTask context sends directly");
+    CHECK(g_ns_put_calls == 0,
+          "UDP-560j the executing task never enqueues to itself (a self-post would have to wait for its own pump)");
    reset_all();
-    g_ns_pump = net_process_messages;
-    CHECK(net_sendto(0, "abc", 3, 0, NULL, 0) == -1 &&
-          net_get_errno() == NET_ERR_BADF,
-          "TC-NETSOCK-560l before net_init sendto reports BADF, no invented context error");

-    /* 未捕获执行任务、但 socket 确实在用时，守卫**选择放行**：宁可不做判定，也不给
-     * 一个无从判定的场景编造错误码。放行后走的是完全正常的执行路径（这里 DONTWAIT
-     * 无数据 → WOULDBLOCK），证明守卫不是"没初始化就一律拒绝"的粗暴实现。
-     * 刻意用 recvfrom 而不是 sendto：未初始化时 net_poll 直接短路返回、时间基准
-     * 不前进，sendto 的等待环永远等不到超时（真机上不可达：net_socket 之后还有
-     * NET_READY 屏障，但这条差异值得记一笔，见交付报告）。 */
+    /* ④ 队列未绑定（net_init 之前的早期上下文）：与其他队列化接口同一口径 NET_ERR，
+     *    不是 BADF 也不是 -12——无从投递就是无从投递 */
    reset_all();
-    g_ns_cur_task = (TaskHandle_t)&g_ns_task_caller;   /* net_init 没跑：判据恒 NULL */
+    g_ns_cur_task = (TaskHandle_t)&g_ns_task_caller;
    fd = net_socket(NET_AF_INET, NET_SOCK_DGRAM);
-    g_fxchip.glob_calls = 0;
+    CHECK(net_sendto(fd, "abc", 3, 0, NULL, 0) == NET_ERR &&
+          s_net_udp[fd].armed == 0U,
+          "UDP-560k before net_init (no queue bound) sendto returns NET_ERR and leaves no slot armed");
+    CHECK(net_recvfrom(fd, buf, (int)sizeof(buf), NET_MSG_DONTWAIT, NULL, NULL) == NET_ERR,
+          "UDP-560l the same for recvfrom (the armed out-param slot is handed back on that exit)");
+    reset_all();
+
+    /* ⑤ 执行任务内的**阻塞** UDP 收包仍被拒（改造没有打开自等死锁的门）：
+     *    完成它的 tick 就跑在同一个任务里 */
+    bring_up_netctx();
+    fd = udp_bind_ctx(8888);
+    CHECK(net_recvfrom(fd, buf, (int)sizeof(buf), 0, NULL, NULL) == -1 &&
+          net_get_errno() == NET_ERR_BUSY,
+          "UDP-560m a blocking UDP receive inside netTask is refused with BUSY (self-wait = deadlock)");
    CHECK(net_recvfrom(fd, buf, (int)sizeof(buf), NET_MSG_DONTWAIT, NULL, NULL) == -1 &&
          net_get_errno() == NET_ERR_WOULDBLOCK,
-          "TC-NETSOCK-560m guard stays open when the executing task was never captured");
-    CHECK(net_get_errno() != NET_ERR_NOT_IN_NETTASK && g_fxchip.glob_calls == 0,
-          "TC-NETSOCK-560n no context error invented and no global register read");
+          "UDP-560n the same call with NET_MSG_DONTWAIT is the legal netTask form (WOULDBLOCK, no wait)");
    reset_all();
 }