/* * 模块名称：UDP 数据面执行器与挂起槽（netTask 串行化） * 文件说明：UDP 三个碰芯片的动作（bind 打开、sendto、recvfrom）在 netTask 上下文 * 里的实际执行体，加上 per-fd 的"一次接收请求"槽位（载荷缓冲 + 源地址 * 出参 + 等待预算）。公开 API（net_sendto / net_recvfrom / * net_recvfrom_to / net_udp_set_peer / net_udp_get_mode）住在 * net_socket.h，那边只负责参数校验、装消息入队、等通知值回结果。 * 为什么单独成模块：源地址（src_addr/addrlen）是**出参指针**，不能塞进按值拷入 * 队列的 net_msg_t（AGENTS 明文「勿给 net_msg_t 加回传用字段」； * 指针过 int 桥在 64 位主机单测构建还会被截断）。所以出参走本模块的 * per-fd 槽：调用方入队前登记自己的指针，netTask 结算时把源地址写进 * 调用方内存、错误码/字节数搭任务通知值回去——与 TCP 挂起 recv 把数据 * 直接写进调用方 buf 是同一个模型（docs/网络/Net层阻塞模型架构设计.md）。 * 依赖：net_types.h（net_sock_t / NET_UDP_MODE_*）、ch395f.h（芯片事务）、 * net_socket.c（net_get_sock / net_poll / 消息分派 / 钩子调用点） * 限定条件：除 net_udp_outparam_arm / net_udp_outparam_disarm / net_udp_clear（ * 纯 RAM，任意上下文）外，全部函数须 netTask 上下文 * 关联文档：docs/网络/BSD_Socket_API_使用指南.md §6（UDP 两种芯片模式与队列化） * 作者：super_agent_bot * 创建日期：2026-11-03 * 修改记录： * 2026-11-03 super_agent_bot 创建：UDP 队列化改造（工单前置 = SNTP 客户端） */ #ifndef NET_UDP_H #define NET_UDP_H #include #include "FreeRTOS.h" #include "task.h" #include "net_types.h" /* * 函数功能：登记本次接收的源地址出参（调用方上下文，入队**前**调用） * 入口参数：sockfd - Socket 描述符 (0~7) int * src_addr - 源地址出参指针（可为 NULL = 不关心来源） struct net_sockaddr * * addrlen - 出参长度指针（可为 NULL） int * * 出口参数：无 * 返回值：0 - 登记成功 int * -1 - 失败（NET_ERR_BADF / NET_ERR_BUSY：本 fd 已有在途接收） * 限定条件：任意上下文（临界区内检查并占位，与 netTask 的读改不竞态） * 函数说明：占位成功后本 fd 的第二次接收请求会被拒（BUSY）——同一 fd 并发 * recvfrom 在数据报语义上无法区分归属，拒绝比交错投递安全。 * 调用方若入队失败必须 net_udp_outparam_disarm 归还槽位。 */ int net_udp_outparam_arm(int sockfd, struct net_sockaddr *src_addr, int *addrlen); /* * 函数功能：归还源地址出参槽（调用方上下文，入队失败/取消后的清理） * 入口参数：sockfd - Socket 描述符 (0~7) int * 出口参数：无 * 返回值：无（越界或空槽静默返回） * 限定条件：任意上下文；仅在**未收到 netTask 回执**的失败路径调用 * 函数说明：netTask 结算路径自己清槽（幂等），本函数只服务调用方侧的 * "消息没投递出去"这一条出口，防槽位泄漏导致该 fd 永久 BUSY。 */ void net_udp_outparam_disarm(int sockfd); /* * 函数功能：UDP 绑定/打开芯片侧 Socket（netTask 上下文执行体，恒服务器模式） * 入口参数：sockfd - Socket 描述符 (0~7) int * local_port - 本地（源）端口，主机序；0 = 由本函数分配动态端口 uint16_t * 出口参数：无 * 返回值：0 - 成功 int * -1 - 失败（NET_ERR_BADF 描述符非法 / NET_ERR_INVAL 非 DGRAM / * NET_ERR_BUSY 芯片 open 被拒；errno 已记） * 限定条件：netTask 上下文；sockfd 对应控制块在用且为 DGRAM * 函数说明：1. 序列按手册 §9.2.4：Socket 4~7 兜底重设收发缓冲 → SET_PROTO_TYPE(UDP) * → SET_SOUR_PORT → SET_DES_IP(0xFFFFFFFF) → SET_DES_PORT(0) → OPEN_SOCKET。 * 2. open 之后写端口/IP 会被 open 复位，故目的地址必须在 open 前下发 * （docs/网络/BSD_Socket_API_函数调用关系.md §4 调用链表）。 * 3. DesIP 恒取 0xFFFFFFFF = **服务器模式**：BSD 的 bind 只表达本地地址、 * 不选对端，客户端模式由 net_udp_set_peer_exec / sendto(带目的地址) 进入。 * 4. 动态端口分配在本函数内做（原在调用方上下文的 net_bind 里写 * s_dynamic_port——芯片事务既然挪进 netTask，端口簿记一并挪， * 避免两个上下文改同一个静态量；取号游标经 net_dynamic_port_next 共用）。 * 5. 顺带本 fd 生命周期收口：清挂起接收槽、udp_mode 置 SERVER、清对端 * 簿记、清 readable（重开不得继承上一条连接的残留电平）。 */ int net_udp_bind_exec(int sockfd, uint16_t local_port); /* * 函数功能：设置芯片 DesIP/DesPort 并切换 UDP 模式（不重开 Socket，netTask 执行体） * 入口参数：sockfd - Socket 描述符 (0~7) int * peer - 非 NULL = 客户端模式（对端）；NULL = 服务器模式 const struct net_sockaddr_in * * 出口参数：无 * 返回值：0 - 成功 int * -1 - 失败（NET_ERR_BADF / NET_ERR_INVAL，errno 已记） * 限定条件：netTask 上下文；控制块在用、type == DGRAM、芯片侧 Socket 已打开 * 函数说明：公开语义见 net_socket.h net_udp_set_peer。只写两个寄存器 * （SET_DES_IP + SET_DES_PORT，约数十微秒），不 CLOSE/OPEN， * 故接收缓冲里已到的数据不丢。 */ int net_udp_set_peer_exec(int sockfd, const struct net_sockaddr_in *peer); /* * 函数功能：UDP 发送执行体（netTask 上下文，分块 + 有界自旋 + 挂起续传） * 入口参数：sockfd - Socket 描述符 (0~7) int * buf - 载荷（调用方内存，须有效至完成） const void * * len - 载荷长度（>0） int * dest - 本包目的地址；NULL = 不改 DesIP const struct net_sockaddr_in * * caller - 调用方任务句柄（挂起 send 的完成通知目标） TaskHandle_t * 出口参数：无 * 返回值：实际发送字节数（>= 0）；NET_PENDING_REGISTERED = 已登记挂起 send； * -1 - 失败（NET_ERR_INVAL / NET_ERR_BADF，errno 已记） int * 限定条件：netTask 上下文 * 函数说明：1. dest 非 NULL → 先 SET_DES_IP/SET_DES_PORT，并把 udp_mode 置 * CLIENT、对端簿记写入 remote_ip_arr/remote_port（芯片静默进 * 客户端模式是硬件事实，本层必须如实记账，否则收包剥头判错）。 * 2. 分块与等待语义与 net_send_locked 完全同源（NET_SEND_CHUNK_MAX / * NET_SEND_SPIN_MS / NET_SEND_TIMEOUT_MS / 末块不等 SENBUF_FREE / * 短写留痕），复用挂起 send 表推进——**不复制一份 UDP 专用自旋**， * 两条路径分块粒度漂移就是 TRAP-NET-16 的复发形态。 * 3. 载荷指针在挂起期间由调用方持有（调用方阻塞在 net_wait_result， * 栈与静态缓冲均有效），与 TCP 挂起 send 同一条铁律。 */ int net_udp_sendto_exec(int sockfd, const void *buf, int len, const struct net_sockaddr_in *dest, TaskHandle_t caller); /* * 函数功能：UDP 接收执行体（netTask 上下文：即时读 / 登记挂起 / 立即拒） * 入口参数：sockfd - Socket 描述符 (0~7) int * buf - 调用方缓冲 void * * len - 缓冲容量（>0） int * flags - NET_MSG_DONTWAIT = 单次非阻塞 int * to_ms - 等待预算（0 = 无限等待，须 blocking 属性） uint32_t * caller - 调用方任务句柄（挂起完成通知目标） TaskHandle_t * 出口参数：无（源地址经 net_udp_outparam_arm 登记的指针直接写回调用方内存） * 返回值：实际接收字节数（> 0）；NET_ERR_RETURN_1(WOULDBLOCK) = 非阻塞无数据； * NET_PENDING_REGISTERED = 已登记挂起；-1 = 失败 int * 限定条件：netTask 上下文；控制块在用且为 DGRAM * 函数说明：1. 判据 = ch395f_get_recv_len()（芯片事实），readable 仅作省 SPI 的 * 门（同 net_pending_tick：事件未收到时 net_poll 每轮重读电平型 SINT * 会重新置位，U15 探针同源结论）。 * 2. 服务器模式（udp_mode == SERVER）且本包 >= 8 字节 → 先读 8 字节 * 信息头解析源地址再读载荷；客户端模式 → 整包都是载荷，源地址 = * 本 Socket 固定对端（remote_ip_arr/remote_port）。 * 3. **一个数据报一次读完**：可用字节 > len 时读满 len 后把剩余部分 * 读空丢弃（BSD 截断语义；手册 §9.2.4 对服务器模式要求一次性全部 * 读出）。旧实现只读 min(可用, len) 把半包留在芯片缓冲里，下一次 * 收包会把上一包的尾巴当成新包头的起点——整条链路的源地址从此错位。 * 4. 读空后清 readable（旧实现从不清，net_select 会永久报可读）。 * 5. 无数据 + 阻塞 → 登记挂起（同 fd 已有挂起 / 执行任务自身 → 拒绝， * BUSY），netTask 零占用返回；完成条件由 net_udp_tick 判定。 */ int net_udp_recvfrom_exec(int sockfd, void *buf, int len, int flags, uint32_t to_ms, TaskHandle_t caller); /* * 函数功能：挂起 UDP 接收完成检查（netTask 每轮 net_process_messages 调用一次，非阻塞） * 入口参数：p_socks - Socket 控制块表首指针（net_socket.c 的 s_net_socks） net_sock_t * * 出口参数：无 * 返回值：无 * 限定条件：netTask 上下文 * 函数说明：逐 fd 按序判定：①fd 已关闭/已非 UDP → 以 NET_ERR_CONNRESET 结束（必通知） * ②数据到达 → 读包（含剥头/截断/清 readable）+ 回填源地址 + 以字节数结束 * ③到点（仅显式预算）→ 以 NET_ERR_TIMEDOUT 结束（调用方 net_recvfrom_to * 映射为对外 -2）。三条出口都必须经统一出口通知，漏通知 = 调用方永久挂死。 */ void net_udp_tick(net_sock_t *p_socks); /* * 函数功能：清除本 fd 的 UDP 接收槽（不通知；"新 fd 不得继承"与 close 后幂等清理） * 入口参数：sockfd - Socket 描述符 (0~7) int * 出口参数：无 * 返回值：无（越界静默返回） * 限定条件：任意上下文（netTask 的 close/socket 分配路径调用） */ void net_udp_clear(int sockfd); /* * 函数功能：取消全部挂起 UDP 接收并逐一通知（网络重建/复位路径） * 入口参数：err - 通知的错误码 int * 出口参数：无 * 返回值：无 * 限定条件：netTask 上下文；须在控制块清零与芯片复位之前调用 */ void net_udp_cancel_all(int err); /* * 函数功能：关闭前结算本 fd 的挂起 UDP 接收（有数据先送达，无数据则取消） * 入口参数：sockfd - 将被关闭的描述符 (0~7) int * p_sock - 将被关闭的控制块指针（与 sockfd 对应） net_sock_t * * 出口参数：无 * 返回值：无（无在位挂起时静默返回） * 限定条件：netTask 上下文；须在 ch395f 关闭/复位该 Socket 之前调用 * 函数说明：与 net_pending_settle_close 同一契约——关闭不丢已到达数据 */ void net_udp_settle_close(int sockfd, net_sock_t *p_sock); #endif /* NET_UDP_H */