feat: 新增路由功能

2026-07-26 01:40:05 +08:00
parent 1a54aed0ee
commit 2e8e05494b
12 changed files with 1630 additions and 15 deletions
@@ -0,0 +1,162 @@
+/**
+ * @file datarouter.h
+ * @brief 数据路由库 —— 公共接口
+ *
+ * ## 概念
+ *
+ * - **通道 (Channel)**：编译期声明的报文类型（如 sensor / status / control）
+ * - **端口 (Port)**：运行期创建的连接点，绑定一个报文类型和多个外设发送 handler
+ * - **路由**：将报文类型关联到一个或多个物理外设发送函数
+ * - **多外设**：一个端口可注册多个 handler，发送时逐一调用全部 handler
+ *
+ * ## 使用流程
+ *
+ * 1. 在 datarouter_config.h 中声明报文类型
+ * 2. 调用 datarouter_init() 初始化
+ * 3. 通过 datarouter_port_create() 创建端口
+ * 4. 调用 datarouter_port_set_type() 指定端口处理的报文类型
+ * 5. 调用 datarouter_port_add_handler() 注册一个或多个外设发送函数
+ * 6. 调用 datarouter_send_<id>() 触发发送（库逐一调用所有注册的 handler）
+ * 7. 实现 datarouter_on_recv_<id>() 处理从外设收到的报文
+ * 8. datarouter_port_delete() 移除端口
+ *
+ * ## 路由规则
+ *
+ *    datarouter_send_<id>(port, data, len)
+ *      → 校验端口类型
+ *      → for each handler: handler(port, data, len)
+ *      → return 0
+ *
+ * 接收：外设收到数据 → 用户识别报文类型 → 调 datarouter_on_recv_<id>(port, data, len)
+ */
+
+#ifndef DATAROUTER_H
+#define DATAROUTER_H
+
+#include <stdint.h>
+#include <stddef.h>
+
+#include "datarouter_config.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @enum datarouter_channel
+ * @brief 报文类型枚举
+ *
+ * 由 DATAROUTER_CHANNELS 宏列表自动生成。
+ */
+enum datarouter_channel {
+#define DATAROUTER_CHANNEL(id, desc) DATAROUTER_CHANNEL_##id,
+    DATAROUTER_CHANNELS
+#undef DATAROUTER_CHANNEL
+    DATAROUTER_CHANNEL_COUNT
+};
+
+/**
+ * @brief 外设发送 handler 类型
+ *
+ * @param[in] port_id  源端口 ID
+ * @param[in] data     数据缓冲区
+ * @param[in] len      数据长度
+ */
+typedef void (*datarouter_send_handler_t)(uint32_t port_id, const void *data, size_t len);
+
+#ifndef DATAROUTER_MAX_HANDLERS_PER_PORT
+#define DATAROUTER_MAX_HANDLERS_PER_PORT 4
+#endif
+
+/**
+ * @defgroup send_functions 发送触发函数
+ *
+ * 每个报文类型生成一个发送触发函数。
+ * 内部校验端口后，逐一调用端口上注册的所有 handler。
+ * @{
+ */
+
+#define DATAROUTER_CHANNEL(id, desc) \
+    int datarouter_send_##id(uint32_t port_id, const void *data, size_t len);
+DATAROUTER_CHANNELS
+#undef DATAROUTER_CHANNEL
+
+/** @} */
+
+/**
+ * @defgroup recv_callbacks 接收回调声明
+ *
+ * 每个报文类型生成一个接收回调声明。用户实现。
+ * @{
+ */
+
+#define DATAROUTER_CHANNEL(id, desc) \
+    void datarouter_on_recv_##id(uint32_t port_id, const void *data, size_t len);
+DATAROUTER_CHANNELS
+#undef DATAROUTER_CHANNEL
+
+/** @} */
+
+/**
+ * @defgroup port_api 端口管理 API
+ *
+ * 每个端口可注册 N 个外设发送 handler（上限 DATAROUTER_MAX_HANDLERS_PER_PORT）。
+ * 发送时逐一调用全部 handler，实现一对多广播路由。
+ * @{
+ */
+
+typedef int32_t datarouter_port_t;
+#define DATAROUTER_INVALID_PORT ((datarouter_port_t)-1)
+
+void datarouter_init(void);
+void datarouter_reset(void);
+
+datarouter_port_t datarouter_port_create(void);
+void datarouter_port_delete(datarouter_port_t port);
+
+void datarouter_port_set_type(datarouter_port_t port, int channel_id);
+int  datarouter_port_get_type(datarouter_port_t port);
+
+/**
+ * @brief 为端口添加一个外设发送 handler
+ * @param[in] port     端口 ID
+ * @param[in] handler  发送函数指针（不可为 NULL）
+ * @retval 0  成功
+ * @retval -1 端口无效
+ * @retval -2 handler 列表已满
+ * @retval -3 handler 已存在（不重复添加）
+ */
+int datarouter_port_add_handler(datarouter_port_t port, datarouter_send_handler_t handler);
+
+/**
+ * @brief 从端口移除一个外设发送 handler
+ * @param[in] port     端口 ID
+ * @param[in] handler  要移除的函数指针
+ * @retval 0  成功
+ * @retval -1 端口无效
+ * @retval -2 handler 未找到
+ */
+int datarouter_port_remove_handler(datarouter_port_t port, datarouter_send_handler_t handler);
+
+/** @brief 清除端口所有 handler */
+void datarouter_port_clear_handlers(datarouter_port_t port);
+
+/** @brief 获取端口当前 handler 数量 @return handler 数量，-1 表示端口无效 */
+int datarouter_port_handler_count(datarouter_port_t port);
+
+/** @} */
+
+/**
+ * @defgroup introspection 报文类型元数据查询
+ * @{
+ */
+int         datarouter_channel_count(void);
+const char *datarouter_channel_name(int channel_id);
+const char *datarouter_channel_desc(int channel_id);
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* DATAROUTER_H */