NetHubVirtualChannel

NetHub USER Virtual Channel

本文档描述 NetHub 的 USER virtual channel 用法。

1. 概念

USER virtual channel 是承载在当前 host link 上的逻辑消息通道。

它不是独立物理接口，而是复用当前的 SDIO / USB / SPI 链路，把不同类型的数据拆分到不同逻辑通道中。

当前常用类型：

• USER
  • 客户或应用层私有数据
• AT
  • host 控制面数据
• SYSTEM
  • 系统内部协调消息

客户集成时，通常只需要关注 USER 类型。

2. bringup 前提

使用前建议确认：

• device 侧已编入 CONFIG_NETHUB=y
• device 侧已编入 CONFIG_MR_VIRTUALCHAN=y
• host 侧已经加载 mr_sdio.ko
• host 与 device 的底层链路已经正常工作

补充说明：

• USER 通道和控制通道是并列关系
• 如果 host 控制面本身走 vchan，它使用的是 AT 类型
• 客户私有消息建议固定使用 USER 类型

3. Device 侧接口

头文件：

• components/net/nethub/include/nethub_vchan.h

常用接口：

int nethub_vchan_user_send(const void *data, uint16_t len);
int nethub_vchan_user_recv_register(nethub_vchan_recv_cb_t recv_cb, void *cb_arg);

4. Host 侧接口

头文件：

• bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan.h

4.1 初始化与清理

int nethub_vchan_init(void);
int nethub_vchan_deinit(void);

4.2 USER 通道

typedef void (*nethub_vchan_recv_callback_t)(const void *data, size_t len);

int nethub_vchan_user_send(const void *data, size_t len);
int nethub_vchan_user_register_callback(nethub_vchan_recv_callback_t callback);

4.3 可选状态查询

如果需要判断当前 virtual channel 是否 ready，可选使用：

typedef struct {
    nethub_vchan_link_state_t link_state;
    nethub_vchan_host_state_t host_state;
} nethub_vchan_state_snapshot_t;

int nethub_vchan_get_state_snapshot(nethub_vchan_state_snapshot_t *snapshot);

常用判断：

• link_state == NETHUB_VCHAN_LINK_UP
  • 表示链路已可收发
• host_state == NETHUB_VCHAN_HOST_STATE_DEVICE_RUN
  • 表示 host 侧已经和 device 完成握手

4.4 可选链路事件回调

如果应用希望在链路 up/down 时被动收到通知，可选注册：

int nethub_vchan_register_link_event_callback(
    nethub_vchan_link_event_callback_t callback,
    void *user_data);

5. 典型使用顺序

1. nethub_vchan_init()
2. nethub_vchan_user_register_callback()
3. nethub_vchan_user_send()
4. 使用完成后调用 nethub_vchan_deinit()

示例：

#include <stdio.h>
#include <string.h>

#include "nethub_vchan.h"

static void user_rx_cb(const void *data, size_t len)
{
    printf("recv USER data: %.*s\n", (int)len, (const char *)data);
}

int main(void)
{
    const char *msg = "hello from host";

    if (nethub_vchan_init() != 0) {
        return -1;
    }

    nethub_vchan_user_register_callback(user_rx_cb);
    nethub_vchan_user_send(msg, strlen(msg));

    nethub_vchan_deinit();
    return 0;
}

6. 限制与注意事项

• 单次消息最大长度为 1500 字节
• USER 通道是消息包语义，不是流式字节流
• 使用前必须保证内核模块已经加载
• 如果 device 侧未启用 CONFIG_MR_VIRTUALCHAN，host 侧 USER 通道无法工作
• 如果同时使用 host 控制面和 USER 通道，客户私有数据不要复用 AT 类型

7. 相关页面

• NetHub 快速上手
• NetHub 架构说明