From c00ec58e13ff989b858258c59fdcc8b3f02ddc6a Mon Sep 17 00:00:00 2001 From: ypc <15051963820@163.com> Date: Tue, 7 Jul 2026 14:35:56 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20SPEC=20v1.2=20=E2=80=94=20=E5=8C=BA?= =?UTF-8?q?=E5=88=86=E8=87=AA=E7=A0=94/=E5=BC=80=E6=BA=90=E5=BA=93=20+=20?= =?UTF-8?q?=E8=A1=A5=E5=85=A8=205=20=E4=B8=AA=E8=87=AA=E7=A0=94=E6=A8=A1?= =?UTF-8?q?=E5=9D=97=E8=AF=A6=E7=BB=86=20API=20=E5=88=86=E6=9E=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 自研(需实现): libmd5/libtask/libdatacenter/libcmd/libcomm 开源(直接用): cJSON/xxhash/tinyxml2/mosquitto/mongoose/libmodbus/lib60870 新增: 定时器/事件/消息队列/命令框架/通讯抽象层/数据中心 完整API规范 --- SPEC.md | 233 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) diff --git a/SPEC.md b/SPEC.md index 405a7f9..9af038d 100644 --- a/SPEC.md +++ b/SPEC.md @@ -221,3 +221,236 @@ release/ - `CROSS=arm` 切换 ARM 交叉编译 - `ROOT_DIR`/`SRC_ROOT_DIR`/`REL_INC`/`LIB_REL`/`EXE_REL` — 路径 - `C_FLAGS`/`CXX_FLAGS` — 编译选项（.c 用 gcc，.cpp 用 g++） + +--- + +## 6. 模块分类：自研 vs 开源/项目库 + +> **重要**：以下分类决定模块是"自主从零实现"还是"直接使用现有开源库" + +### 6.1 自研模块（需要从零实现） + +| 模块 | 位置 | 语言 | 说明 | +|------|------|------|------| +| `libmd5` | public/ | 纯C | RFC 1321 MD5 摘要，需自主实现 | +| `libtask` | public/ | C/C++ | 事件/定时器/消息队列综合调度框架 | +| `libdatacenter` | public/ | C++ | 信号数据中心，signal_in/out/ao/yk/param | +| `libcmd` | public/ | C++ | 命令注册/分发/linenoise交互框架 | +| `libcomm` | public/ | C++ | TCP/UDP/UART 通讯抽象层 | + +### 6.2 开源/项目库（不需要重写，直接使用） + +| 模块 | 位置 | 来源 | 说明 | +|------|------|------|------| +| `libcJSON` | public/ | cJSON | JSON 解析/生成，开源 MIT 许可证 | +| `libmy_xxhash` | public/ | xxHash | 极速哈希，BSD 2-Clause 许可证 | +| `libxml` | public/ | tinyxml2 | XML 解析，Zlib 许可证 | +| `libmy_mosquitto` | public/ | mosquitto | MQTT 客户端 | +| `libmongoose` | protocol/ | mongoose | 嵌入式 HTTP/WebSocket | +| `libmodbus` | protocol/ | libmodbus | Modbus RTU/TCP 协议栈 | +| `lib60870` | protocol/ | lib60870 | IEC 60870-5-101/103/104 协议栈 | + +--- + +## 7. libmd5 自研模块详细功能 + +### 功能点（来自 RTU 原工程 `md5.c` 分析） +| 序号 | 函数 | 说明 | +|------|------|------| +| M01 | `StartMD5(ctx)` | 初始化上下文：设置魔数 A=0x67452301 等 | +| M02 | `EncodeMD5(ctx, input, len)` | 输入待计算数据，分块处理 64 字节块 | +| M03 | `GetMD5(ctx, result)` | 获取 16 字节 MD5 摘要 | +| M04 | `GetMD5String(ctx, output, mode)` | 格式化 hex 字符串（mode=0 大写, 1 小写） | +| M05 | `MD5Transform`(内部) | 4 轮 × 16 步的 MD5 核心变换 | +| M06 | `Encode`(内部) | uint32 数组 → LE 字节序列 | +| M07 | `Decode`(内部) | LE 字节序列 → uint32 数组 | + +### 数据结构 +```c +typedef struct { + uint32_t state[4]; /* A, B, C, D */ + uint32_t count[2]; /* 位计数 (low, high) */ + unsigned char buffer[64]; /* 待处理数据缓冲 */ +} MD5_CTX; +``` + +--- + +## 8. libtask 自研模块详细功能 + +### 功能点（来自 RTU 原工程 `myTask.c` + `myTask.h` 分析） + +#### 8.1 定时器子系统 +| 序号 | 函数 | 说明 | +|------|------|------| +| T01 | `task_timer_create(name, cb, arg, timeout_ms, flags)` | 创建定时器, flags=单次/周期 | +| T02 | `task_timer_start(ptimer)` | 启动定时器 | +| T03 | `task_timer_stop(ptimer)` | 停止定时器 | +| T04 | `task_timer_restart(ptimer, timeout_ms)` | 重启定时器(修改周期) | +| T05 | `task_timer_destroy(ptimer)` | 销毁定时器 | +| T06 | `task_timer_is_active(ptimer)` | 查询是否运行中 | +| T07 | `timer_manager_thread`(内部) | 独立线程轮询所有定时器到期 | + +#### 8.2 事件子系统 +| 序号 | 函数 | 说明 | +|------|------|------| +| T08 | `task_event_create(name)` | 创建事件对象 | +| T09 | `task_event_destroy(pevent)` | 销毁事件对象 | +| T10 | `task_event_send(pevent, event)` | 发送事件位 | +| T11 | `task_event_recv(pevent, set, opt, timeout_ms, recved)` | 等待事件, opt=AND/OR | +| T12 | `task_event_clear(pevent, event)` | 清除事件位 | +| T13 | `task_event_query(pevent)` | 查询当前事件位 | + +#### 8.3 消息队列子系统 +| 序号 | 函数 | 说明 | +|------|------|------| +| T14 | `task_msg_queue_create(name, msg_size, msg_num)` | 创建定长消息队列 | +| T15 | `task_msg_queue_destroy(pqueue)` | 销毁消息队列 | +| T16 | `task_msg_queue_send(pqueue, msg, size)` | 发送消息(阻塞) | +| T17 | `task_msg_queue_send_timeout(pqueue, msg, size, timeout_ms)` | 发送消息(超时) | +| T18 | `task_msg_queue_recv(pqueue, msg, size, timeout_ms)` | 接收消息(超时) | +| T19 | `task_msg_queue_try_recv(pqueue, msg, size)` | 尝试接收(非阻塞) | +| T20 | `task_msg_queue_get_count(pqueue)` | 获取队列当前消息数 | +| T21 | `task_msg_queue_space(pqueue)` | 获取队列剩余空间 | + +#### 8.4 程序运行流程 +``` +定时器: timer_manager_thread 每 10ms 轮询所有活跃定时器 → 到期则回调 +事件: 内部位图 + pthread_cond, send 置位+唤醒, recv 等待+清零 +消息队列: 环形缓冲区 + pthread_mutex + pthread_cond +``` + +--- + +## 9. libcmd 自研模块详细功能 + +### 功能点（来自 RTU 原工程 `myCmd.h` + `my_cmd.cpp` 分析） +| 序号 | 函数/宏 | 说明 | +|------|---------|------| +| C01 | `cmd_manager_add_command(name, func, desc, complete)` | 注册命令 | +| C02 | `cmd_manager_get_commands(out_count)` | 获取所有已注册命令列表 | +| C03 | `cmd_help(argc, argv)` | 打印帮助信息 | +| C04 | `cmd_find(name)` | 按名称查找命令 | +| C05 | `cmd_complete(buf, completions, ncomp)` | Tab 自动补全回调 | +| C06 | `cmd_sub_complete(buf, completions, ncomp, subs, sub_count)` | 子命令补全 | +| C07 | `linenoise(prompt)` | 行编辑+历史交互式输入 | +| C08 | `linenoiseFree(ptr)` | 释放 linenoise 返回的内存 | +| C09 | `linenoiseHistoryAdd(line)` | 添加历史记录 | +| C10 | `linenoiseHistoryFree()` | 释放历史 | +| C11 | `CMD_REGISTER(name, func, desc)` | 宏：注册无补全的命令 | +| C12 | `CMD_REGISTER_C(name, func, desc, complete)` | 宏：注册带补全的命令 | + +### 数据结构 +```c +typedef struct { + const char *name; /* 命令名 */ + void (*func)(int argc, char *argv[]); /* 回调 */ + const char *desc; /* 描述 */ + void (*complete)(...); /* 补全回调 */ +} stru_cmd; +``` + +### 程序运行流程 +``` +命令注册 → cmd_manager_add_command → 存入全局命令哈希表 +交互式Shell → linenoise(提示符) → 用户输入 → 查找命令 → 回调执行 +Tab补全 → cmd_complete/cmd_sub_complete → linenoiseSetCompletionCallback +``` + +--- + +## 10. libcomm 自研模块详细功能 + +### 功能点（来自 RTU 原工程 myComm.h + comm/*.cpp 分析） +| 序号 | 函数 | 说明 | +|------|------|------| +| N01 | `comm_create(type, debug, para)` | 创建通讯实例(TCP/UDP/UART) | +| N02 | `comm_connect(id)` | 建立连接 | +| N03 | `comm_disconnect(id)` | 断开连接 | +| N04 | `comm_send(id, fd, data, len)` | 发送数据 | +| N05 | `comm_recv_register(id, cb)` | 注册接收回调 | +| N06 | `comm_state_register(id, cb)` | 注册状态变化回调 | +| N07 | `comm_destroy(id)` | 销毁实例 | + +### 通讯类型枚举 +```c +COMM_TYPE_TCP_SERVER, COMM_TYPE_TCP_CLIENT, +COMM_TYPE_UDP_SERVER, COMM_TYPE_UDP_CLIENT, +COMM_TYPE_UART +``` + +### 参数结构体 +```c +stru_tcp_para { local_ip, local_port, remote_ip, remote_port } +stru_udp_para { local_ip, local_port, remote_ip, remote_port } +stru_uart_para { device, baudrate, data_bits, stop_bits, parity } +``` + +### 程序运行流程 +``` +comm_create → 按类型创建 TCP/UDP/UART 实例 → 返回 id +comm_connect → TCP 三次握手 / UDP bind / UART open +comm_send → 投递到对应 fd +接收线程 → 读 fd → 调用 comm_recv_cb 回调 +状态变化 → 调用 comm_state_cb 回调(CONNECTED/DISCONNECTED) +``` + +--- + +## 11. libdatacenter 自研模块详细功能 + +### 功能点（来自 RTU 原工程 myDatacenter.h + datacenter/*.cpp 分析） + +#### 11.1 信号注册（5 种信号类型） +| 序号 | 函数 | 说明 | +|------|------|------| +| D01 | `dc_signal_out(saddr, desc, data_type, p_data)` | 注册输出信号(遥测/遥信) | +| D02 | `dc_signal_out_with_callback(...)` | 输出信号+变化回调 | +| D03 | `dc_signal_in(saddr, desc, link_saddr, p_data)` | 注册输入信号(关联输出信号) | +| D04 | `dc_signal_in_with_callback(...)` | 输入信号+变化回调 | +| D05 | `dc_signal_ao(saddr, desc, data_type, ctrl_type, p_data, cb, mod)` | 注册模拟输出(遥控) | +| D06 | `dc_signal_param(saddr, desc, data_type, ctrl_type, p_data, num, cb, mod)` | 注册参数(定值) | +| D07 | `dc_signal_yk(saddr, desc, data_type, ctrl_type, p_data, cb, mod)` | 注册遥控信号 | + +#### 11.2 信号控制 +| 序号 | 函数 | 说明 | +|------|------|------| +| D08 | `dc_signal_ao_set_val(saddr, step, ctrl, p_data, mod)` | 设置 AO 值(SBO/直接) | +| D09 | `dc_signal_param_set_val(saddr, step, ctrl, zone, p_data, mod)` | 设置定值(带区号) | +| D10 | `dc_signal_yk_set_status(saddr, step, ctrl, p_data, mod)` | 设置遥控状态 | + +#### 11.3 信号查询 +| 序号 | 函数 | 说明 | +|------|------|------| +| D11 | `dc_get_out_signal_info(saddr, desc, data_type, p_data)` | 查询输出信号信息 | +| D12 | `dc_get_in_signal_info(...)` | 查询输入信号 | +| D13 | `dc_get_ao_signal_info(...)` | 查询 AO 信号 | +| D14 | `dc_get_param_signal_info(...)` | 查询参数信号 | +| D15 | `dc_get_yk_signal_info(...)` | 查询遥控信号 | +| D16 | `dc_get_signal_val(p_data, data_type)` | 信号值转字符串 | +| D17 | `dc_set_out_signal_val(saddr, set_data, mod)` | 设置输出信号值 | +| D18 | `dc_get_signal_count(type)` | 按类型统计信号数 | + +#### 11.4 事件/扰动/故障队列 +| 序号 | 函数 | 说明 | +|------|------|------| +| D19 | `dc_event_queue_push(soe)` | SOE 事件入队 | +| D20 | `dc_event_register_queue_pop(cb)` | 注册事件消费回调 | +| D21 | `dc_disturb_dd_queue_push(dd)` | 扰动数据入队 | +| D22 | `dc_disturb_dd_register_queue_pop(cb)` | 注册扰动消费回调 | +| D23 | `dc_fault_queue_push(fault)` | 故障数据入队 | +| D24 | `dc_fault_register_queue_pop(cb)` | 注册故障消费回调 | + +#### 11.5 控制步骤枚举 +```c +SIGNAL_CTRL_STEP { READY, SELECT, DIRECT, CANCEL } // SBO 控制步骤 +SIGNAL_CTRL_TYPE { NONE, DIRECT_NORMAL, SBO_NORMAL } // 控制类型 +``` + +### 源文件组成（15 个 .cpp 文件） +``` +datacenter.cpp dc_cfg_check.cpp dc_event.cpp +dc_param.cpp dc_signal.cpp dc_signal_compare.cpp +dc_signal_core.cpp dc_signal_ctrl.cpp dc_signal_find.cpp +dc_signal_query.cpp dc_signal_show.cpp dc_signal_util.cpp +```