NetHubVirtualChannel - 版本历史

张良：Reduce overlap between NetHubArchitecture and NetHubVirtualChannel (2026-04-25)

2026-04-24T17:13:00Z

Reduce overlap between NetHubArchitecture and NetHubVirtualChannel (2026-04-25)

←上一版本		2026年4月24日 (五) 17:13的版本
第2行：		第2行：

	This document describes the current NetHub USER virtual channel support.		This document describes the current NetHub USER virtual channel support.

			It focuses on USER virtual channel usage, prerequisites, APIs, and limits. For the full NetHub architecture and the broader interface support matrix, read [[NetHubArchitecture\|NetHubArchitecture.md]].

	== 1. Concept ==		== 1. Concept ==
第22行：		第24行：
	\|}		\|}

	== 2. Current ~~Support Status~~ ==		== 2. Current Scope ==

	~~{\| class="wikitable"~~		Current implementation summary:
	\|-
	~~! Area !!~~ Current ~~status~~		* the public API is transport-neutral by design
	\|-		* the current in-tree end-to-end USER virtual channel path follows the default <code>SDIO</code> interface
	~~\| Device~~ API ~~surface \|\|~~ transport-neutral by design		* the device-side implementation is currently in <code>backend/host/sdio/virtualchan.c</code>
	\|-		* the host userspace library is currently aligned with <code>mr_sdio.ko + netlink</code>
	~~\| Device in~~-~~tree~~ implementation \|\| currently in <code>backend/host/sdio/virtualchan.c</code>		* USB device-side ACM transport exists, but in-tree host <code>nethub_vchan</code> alignment is not finished
	\|-		* SPI is not supported
	~~\| Host~~ userspace library \|\| currently aligned with <code>mr_sdio.ko + netlink</code>
	\|-
	~~\| Default interface for the current in-tree USER virtual channel path \|\| <code>SDIO</code>~~
	\|-
	\| USB \|\| device-side ACM transport exists, but in-tree host <code>nethub_vchan</code> alignment is not finished
	\|-
	\| SPI \|\| not supported
	\|}

	== 3. Prerequisites ==		== 3. Prerequisites ==

张良：Unify tone and terminology across NetHub docs (2026-04-24)

2026-04-24T14:27:37Z

Unify tone and terminology across NetHub docs (2026-04-24)

张良：Sync NetHub docs from local Markdown (2026-04-24 wording update)

2026-04-24T14:20:29Z

Sync NetHub docs from local Markdown (2026-04-24 wording update)

显示更改

张良：Sync NetHub docs from local Markdown (2026-04-24)

2026-04-24T13:48:39Z

Sync NetHub docs from local Markdown (2026-04-24)

显示更改

张良：Sync NetHub docs from local Markdown

2026-03-17T05:33:51Z

Sync NetHub docs from local Markdown

显示更改

张良：创建页面，内容为“= NetHub USER Virtual Channel = 本文档描述 NetHub 的 `USER virtual channel` 用法。 == 1. 概念 == `USER virtual channel` 是承载在当前 host link 上的逻辑消息通道。它不是独立物理接口，而是复用当前的 `SDIO / USB / SPI` 链路，把不同类型的数据拆分到不同逻辑通道中。当前常用类型： * `USER` ** 客户或应用层私有数据 * `AT` ** hos…”

2026-03-13T09:17:57Z

创建页面，内容为“= NetHub USER Virtual Channel = 本文档描述 NetHub 的 <code>USER virtual channel</code> 用法。 == 1. 概念 == <code>USER virtual channel</code> 是承载在当前 host link 上的逻辑消息通道。它不是独立物理接口，而是复用当前的 <code>SDIO / USB / SPI</code> 链路，把不同类型的数据拆分到不同逻辑通道中。当前常用类型： * <code>USER</code> ** 客户或应用层私有数据 * <code>AT</code> ** hos…”

新页面

= NetHub USER Virtual Channel =

本文档描述 NetHub 的 <code>USER virtual channel</code> 用法。

== 1. 概念 ==

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

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

当前常用类型：

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

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

== 2. bringup 前提 ==

使用前建议确认：

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

补充说明：

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

== 3. Device 侧接口 ==

头文件：

* <code>components/net/nethub/include/nethub_vchan.h</code>

常用接口：

<syntaxhighlight lang="c">
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);
</syntaxhighlight>

== 4. Host 侧接口 ==

头文件：

* <code>bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan.h</code>

=== 4.1 初始化与清理 ===

<syntaxhighlight lang="c">
int nethub_vchan_init(void);
int nethub_vchan_deinit(void);
</syntaxhighlight>

=== 4.2 USER 通道 ===

<syntaxhighlight lang="c">
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);
</syntaxhighlight>

=== 4.3 可选状态查询 ===

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

<syntaxhighlight lang="c">
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);
</syntaxhighlight>

常用判断：

* <code>link_state == NETHUB_VCHAN_LINK_UP</code>
** 表示链路已可收发
* <code>host_state == NETHUB_VCHAN_HOST_STATE_DEVICE_RUN</code>
** 表示 host 侧已经和 device 完成握手

=== 4.4 可选链路事件回调 ===

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

<syntaxhighlight lang="c">
int nethub_vchan_register_link_event_callback(
nethub_vchan_link_event_callback_t callback,
void *user_data);
</syntaxhighlight>

== 5. 典型使用顺序 ==

# <code>nethub_vchan_init()</code>
# <code>nethub_vchan_user_register_callback()</code>
# <code>nethub_vchan_user_send()</code>
# 使用完成后调用 <code>nethub_vchan_deinit()</code>

示例：

<syntaxhighlight lang="c">
#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;
}
</syntaxhighlight>

== 6. 限制与注意事项 ==

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

== 7. 相关页面 ==

* [[NetHubQuickBringup|NetHub 快速上手]]
* [[NetHubArchitecture|NetHub 架构说明]]

←上一版本		2026年4月24日 (五) 14:27的版本
第1行：		第1行：
	= NetHub USER Virtual Channel =		= NetHub USER Virtual Channel =

	This document describes the current NetHub USER virtual-channel support.		This document describes the current NetHub USER virtual channel support.

	== 1. Concept ==		== 1. Concept ==

	USER virtual channel is a logical message channel carried on the active host ~~link~~.		USER virtual channel is a logical message channel carried on the active host interface.

	It is not a separate physical interface. The public API is ~~designed to be~~ transport-neutral, while the current in-tree implementation is still centered on the SDIO ~~reference path~~.		It is not a separate physical interface. The public API is transport-neutral, while the current in-tree implementation is still centered on the default <code>SDIO</code> interface.

	Common logical types:		Common logical types:
第34行：		第34行：
	\| Host userspace library \|\| currently aligned with <code>mr_sdio.ko + netlink</code>		\| Host userspace library \|\| currently aligned with <code>mr_sdio.ko + netlink</code>
	\|-		\|-
	\| Default interface for the current in-tree USER ~~vchan~~ path \|\| <code>SDIO</code>		\| Default interface for the current in-tree USER virtual channel path \|\| <code>SDIO</code>
	\|-		\|-
	\| USB \|\| device-side ACM transport exists, but in-tree host <code>nethub_vchan</code> alignment is not finished		\| USB \|\| device-side ACM transport exists, but in-tree host <code>nethub_vchan</code> alignment is not finished
第43行：		第43行：
	== 3. Prerequisites ==		== 3. Prerequisites ==

	Before using the current in-tree USER virtual-channel path, confirm:		Before using the current in-tree USER virtual channel path, confirm:

	* device side is built with <code>CONFIG_NETHUB=y</code>		* device side is built with <code>CONFIG_NETHUB=y</code>
	* device side enables <code>CONFIG_MR_VIRTUALCHAN=y</code>		* device side enables <code>CONFIG_MR_VIRTUALCHAN=y</code>
	* the selected bring-up path is the ~~current~~ SDIO ~~reference flow~~		* the selected bring-up path uses the default <code>SDIO</code> interface
	* host side has loaded <code>mr_sdio.ko</code>		* host side has loaded <code>mr_sdio.ko</code>
	* the host-device link is already working		* the host-device link is already working
第55行：		第55行：
	* USER and AT are parallel logical channels		* USER and AT are parallel logical channels
	* customer private data should stay on the <code>USER</code> type		* customer private data should stay on the <code>USER</code> type
	* documentation should not ~~claim that~~ USB and SPI already share ~~the same~~ finished end-to-end virtual-channel stack		* documentation should not describe USB and SPI as if they already share a finished end-to-end virtual channel stack

	== 4. Device-Side API ==		== 4. Device-Side API ==
第152行：		第152行：
	* USER virtual channel is packet-oriented, not a byte stream		* USER virtual channel is packet-oriented, not a byte stream
	* the current in-tree end-to-end path is SDIO-based		* the current in-tree end-to-end path is SDIO-based
	* if the device side does not enable <code>CONFIG_MR_VIRTUALCHAN</code>, the current in-tree USER virtual-channel path will not work		* if the device side does not enable <code>CONFIG_MR_VIRTUALCHAN</code>, the current in-tree USER virtual channel path will not work
	* if control traffic and USER traffic coexist, keep private application traffic on <code>USER</code> and do not reuse the <code>AT</code> type		* if control traffic and USER traffic coexist, keep private application traffic on <code>USER</code> and do not reuse the <code>AT</code> type

NetHubVirtualChannel - 版本历史

张良：​Reduce overlap between NetHubArchitecture and NetHubVirtualChannel (2026-04-25)

张良：​Unify tone and terminology across NetHub docs (2026-04-24)

张良：​Sync NetHub docs from local Markdown (2026-04-24 wording update)

张良：​Sync NetHub docs from local Markdown (2026-04-24)

张良：​Sync NetHub docs from local Markdown

张良：Reduce overlap between NetHubArchitecture and NetHubVirtualChannel (2026-04-25)

张良：Unify tone and terminology across NetHub docs (2026-04-24)

张良：Sync NetHub docs from local Markdown (2026-04-24 wording update)

张良：Sync NetHub docs from local Markdown (2026-04-24)

张良：Sync NetHub docs from local Markdown