NetHubArchitecture - 版本历史

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

2026-04-24T17:12:58Z

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

←上一版本		2026年4月24日 (五) 17:12的版本
第119行：		第119行：
	== 6. Virtual Channel ==		== 6. Virtual Channel ==

	NetHub also exposes a logical virtual channel ~~API:~~		NetHub also exposes a logical virtual channel layer for message-style traffic such as <code>USER</code>, <code>AT</code>, and internal coordination payloads.

	~~<syntaxhighlight lang="c">~~		Architecture role:
	~~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>~~

	API ~~intent:~~		* device side uses <code>components/net/nethub/include/nethub_vchan.h</code>
			* host side uses <code>bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan.h</code>
			* the API is intentionally transport-neutral across host interfaces

	* stable logical message API across host interfaces		Current implementation boundary:

	~~Current~~ implementation:		* the current in-tree end-to-end USER virtual channel path follows the default <code>SDIO</code> interface
			* the device-side implementation is still centered on the SDIO backend
			* the host userspace <code>nethub_vchan</code> library is also SDIO-based today
			* USB device-side ACM transport exists, but the host-side wrapper is not yet aligned as a finished end-to-end virtual channel path

	* the in-tree implementation is still SDIO-backed		For prerequisites, detailed APIs, usage order, and limits, read [[NetHubVirtualChannel\|NetHubVirtualChannel.md]].
	* the host userspace <code>nethub_vchan</code> library is also SDIO-based today
	* therefore the current end-to-end USER virtual channel path follows the default <code>SDIO</code> interface

	== 7. Host-Side Optional Stack ==		== 7. Host-Side Optional Stack ==

张良：Add NetHub architecture diagram to docs (2026-04-25)

2026-04-24T17:07:50Z

Add NetHub architecture diagram to docs (2026-04-25)

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

	NetHub runs on the device and bridges already-available Wi-Fi capability onto one selected host interface.		NetHub runs on the device and bridges already-available Wi-Fi capability onto one selected host interface.

			[[文件:Nethub_arch.gif \| NetHub Architecture Overview]]

	<syntaxhighlight lang="text">		<syntaxhighlight lang="text">

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

2026-04-24T14:27:34Z

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

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

	This document summarizes the current NetHub architecture across the device-side module, the optional host control stack, and the current support ~~limits~~.		This document summarizes the current NetHub architecture across the device-side module, the optional host control stack, and the current support boundaries.

	== 1. High-Level Model ==		== 1. High-Level Model ==

	NetHub runs on the device and bridges already-available Wi-Fi capability onto one selected host~~-link profile~~.		NetHub runs on the device and bridges already-available Wi-Fi capability onto one selected host interface.

	<syntaxhighlight lang="text">		<syntaxhighlight lang="text">
第20行：		第20行：
	\|		\|
	v		v
	host~~-link profile~~		host interface
	(SDIO / USB / SPI)		(SDIO / USB / SPI)
	</syntaxhighlight>		</syntaxhighlight>
第35行：		第35行：
	! Area !! SDIO !! USB !! SPI		! Area !! SDIO !! USB !! SPI
	\|-		\|-
	\| Device-side ~~profile~~ \|\| yes \|\| yes \|\| yes		\| Device-side interface backend \|\| yes \|\| yes \|\| yes
	\|-		\|-
	\| Device-side data-path \|\| yes \|\| yes, through <code>USB ECM</code> \|\| no		\| Device-side data-path \|\| yes \|\| yes, through <code>USB ECM</code> \|\| no
第41行：		第41行：
	\| Device-side control transport plumbing \|\| yes \|\| yes, through <code>USB ACM</code> \|\| no		\| Device-side control transport plumbing \|\| yes \|\| yes, through <code>USB ACM</code> \|\| no
	\|-		\|-
	\| Current in-tree host Linux ~~reference path~~ \|\| yes \|\| not yet the main ~~reference~~ path \|\| no		\| Current in-tree host Linux stack \|\| yes \|\| not yet the main host path \|\| no
	\|-		\|-
	\| End-to-end USER virtual channel \|\| yes \|\| not yet aligned in-tree \|\| no		\| End-to-end USER virtual channel \|\| yes \|\| not yet aligned in-tree \|\| no
	\|-		\|-
	\| ~~Current default~~ interface \|\| yes \|\| no \|\| no		\| Default interface today \|\| yes \|\| no \|\| no
	\|}		\|}

第83行：		第83行：

	<syntaxhighlight lang="text">		<syntaxhighlight lang="text">
	host payload -> host~~-link~~ backend -> nethub -> active Wi-Fi endpoint		host payload -> host interface backend -> nethub -> active Wi-Fi endpoint
	Wi-Fi RX -> nethub filter -> local / host / both		Wi-Fi RX -> nethub filter -> local / host / both
	</syntaxhighlight>		</syntaxhighlight>

	Device-side Wi-Fi is already owned by the Wi-Fi backend. NetHub mainly wires the host~~-link side~~ to that Wi-Fi backend.		Device-side Wi-Fi is already owned by the Wi-Fi backend. NetHub mainly wires the selected host interface to that Wi-Fi backend.

	== 5. Control Path ==		== 5. Control Path ==

	NetHub exposes a stable control-path facade:		NetHub exposes a stable control path facade:

	<syntaxhighlight lang="c">		<syntaxhighlight lang="c">
第98行：		第98行：
	</syntaxhighlight>		</syntaxhighlight>

	That facade is implemented per ~~profile~~.		That facade is implemented per interface.

	Current interpretation:		Current interpretation:
第113行：		第113行：
	** <code>ATModule</code> does not participate in the build		** <code>ATModule</code> does not participate in the build

	<code>CONFIG_NETHUB_AT_USE_VCHAN</code> should be documented carefully as an example or legacy SDIO control-path convention, not as a finished transport-wide selector.		<code>CONFIG_NETHUB_AT_USE_VCHAN</code> should be documented carefully as an example or legacy SDIO-specific control path convention, not as a finished transport-wide selector.

	== 6. Virtual Channel ==		== 6. Virtual Channel ==

	NetHub also exposes a logical virtual-channel API:		NetHub also exposes a logical virtual channel API:

	<syntaxhighlight lang="c">		<syntaxhighlight lang="c">
第126行：		第126行：
	API intent:		API intent:

	* stable logical message API across host~~-link types~~		* stable logical message API across host interfaces

	Current ~~backend reality~~:		Current implementation:

	* the in-tree implementation is still SDIO-backed		* the in-tree implementation is still SDIO-backed
	* the host userspace <code>nethub_vchan</code> library is also SDIO-based today		* the host userspace <code>nethub_vchan</code> library is also SDIO-based today
	* therefore the current end-to-end USER virtual-channel ~~story~~ follows the default <code>SDIO</code> interface		* therefore the current end-to-end USER virtual channel path follows the default <code>SDIO</code> interface

	== 7. Host-Side Optional Stack ==		== 7. Host-Side Optional Stack ==
第144行：		第144行：
	Notes:		Notes:

	* this stack is not ~~required~~ for NetHub data-path-only products		* this stack is not mandatory for NetHub data-path-only products
	* the in-tree host Linux ~~reference~~ stack is still centered on the SDIO path		* the in-tree host Linux stack is still centered on the SDIO path

	== 8. Low-Power Scope ==		== 8. Low-Power Scope ==

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

2026-04-24T14:20:27Z

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

←上一版本		2026年4月24日 (五) 14:20的版本
第13行：		第13行：
	nethub		nethub
	+-----------+		+-----------+
	\| data path \|		\| data-path \|
	\| filter \|		\| filter \|
	\| ctrlpath \|		\| ctrlpath \|
第37行：		第37行：
	\| Device-side profile \|\| yes \|\| yes \|\| yes		\| Device-side profile \|\| yes \|\| yes \|\| yes
	\|-		\|-
	\| Device-side data path \|\| yes \|\| yes, through <code>USB ECM</code> \|\| no		\| Device-side data-path \|\| yes \|\| yes, through <code>USB ECM</code> \|\| no
	\|-		\|-
	\| Device-side control transport plumbing \|\| yes \|\| yes, through <code>USB ACM</code> \|\| no		\| Device-side control transport plumbing \|\| yes \|\| yes, through <code>USB ACM</code> \|\| no
第45行：		第45行：
	\| End-to-end USER virtual channel \|\| yes \|\| not yet aligned in-tree \|\| no		\| End-to-end USER virtual channel \|\| yes \|\| not yet aligned in-tree \|\| no
	\|-		\|-
	\| ~~Recommended today~~ \|\| yes \|\| ~~evaluation only~~ \|\| no		\| Current default interface \|\| yes \|\| no \|\| no
	\|}		\|}

第78行：		第78行：
	* <code>nethub_set_wifi_rx_filter()</code>		* <code>nethub_set_wifi_rx_filter()</code>

	== 4. Data ~~Plane~~ ==		== 4. Data-Path ==

	The data ~~plane~~ is the main NetHub function.		The data-path is the main NetHub function.

	<syntaxhighlight lang="text">		<syntaxhighlight lang="text">
第106行：		第106行：
	* <code>SPI</code>: not implemented		* <code>SPI</code>: not implemented

	~~Optional AT solution~~:		Main build-time switches related to this area:

	* <code>CONFIG_NETHUB_CTRLCHANNEL_USE_ATMODULE=y</code>		* <code>CONFIG_NETHUB_CTRLCHANNEL_USE_ATMODULE=y</code>
	** example enables <code>ATModule</code> plus host <code>bflbwifid / bflbwifictrl</code>		** the example enables <code>ATModule</code> plus host <code>bflbwifid / bflbwifictrl</code>
	* <code>CONFIG_NETHUB_CTRLCHANNEL_USE_ATMODULE=n</code>		* <code>CONFIG_NETHUB_CTRLCHANNEL_USE_ATMODULE=n</code>
	** ~~data-plane-only products can omit~~ the ~~example control chain~~		** <code>ATModule</code> does not participate in the build

	<code>CONFIG_NETHUB_AT_USE_VCHAN</code> should be documented carefully as an example or legacy SDIO control-path convention, not as a finished transport-wide selector.		<code>CONFIG_NETHUB_AT_USE_VCHAN</code> should be documented carefully as an example or legacy SDIO control-path convention, not as a finished transport-wide selector.
第132行：		第132行：
	* the in-tree implementation is still SDIO-backed		* the in-tree implementation is still SDIO-backed
	* the host userspace <code>nethub_vchan</code> library is also SDIO-based today		* the host userspace <code>nethub_vchan</code> library is also SDIO-based today
	* therefore the current end-to-end USER virtual-channel story is the SDIO ~~reference path~~		* therefore the current end-to-end USER virtual-channel story follows the default <code>SDIO</code> interface

	== 7. Host-Side Optional Stack ==		== 7. Host-Side Optional Stack ==
第144行：		第144行：
	Notes:		Notes:

	* this is not required for NetHub data-~~plane~~-only products		* this stack is not required for NetHub data-path-only products
	* the in-tree host Linux reference stack is still centered on the SDIO path		* the in-tree host Linux reference stack is still centered on the SDIO path

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

2026-04-24T13:48:37Z

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 架构说明 = 本文档面向需要理解模块边界和 API 的开发者。 == 1. 当前架构结论 == * 当前物理主路径是 '''SDIO''' * `USB / SPI` 目前仍保留 backend 骨架，不作为当前推荐 bringup 路径 * device 侧 Wi-Fi backend 支持 `fhost / wl80211` * 控制通道和 `USER virtual channel` 都是当前 host link 上的逻辑通道，不是独立物理接口 * host 控制 backend 运行…”

2026-03-13T09:16:39Z

创建页面，内容为“= NetHub 架构说明 = 本文档面向需要理解模块边界和 API 的开发者。 == 1. 当前架构结论 == * 当前物理主路径是 '''SDIO''' * <code>USB / SPI</code> 目前仍保留 backend 骨架，不作为当前推荐 bringup 路径 * device 侧 Wi-Fi backend 支持 <code>fhost / wl80211</code> * 控制通道和 <code>USER virtual channel</code> 都是当前 host link 上的逻辑通道，不是独立物理接口 * host 控制 backend 运行…”

新页面

= NetHub 架构说明 =

本文档面向需要理解模块边界和 API 的开发者。

== 1. 当前架构结论 ==

* 当前物理主路径是 '''SDIO'''
* <code>USB / SPI</code> 目前仍保留 backend 骨架，不作为当前推荐 bringup 路径
* device 侧 Wi-Fi backend 支持 <code>fhost / wl80211</code>
* 控制通道和 <code>USER virtual channel</code> 都是当前 host link 上的逻辑通道，不是独立物理接口
* host 控制 backend 运行时二选一：<code>tty</code> 或 <code>vchan</code>

== 2. 功能视角架构图 ==

<syntaxhighlight lang="text">
Host
|
| network data / control payload / USER payload
v
Host Link (current main path: SDIO)
|
+-- Data Channel <--> nethub data bridge
+-- Control Channel <-> nethub ctrlpath <-> ATModule
+-- USER VCHAN <-> nethub vchan user path
|
v
Device
|
+-- nethub
| +-- data bridge
| +-- hard-coded Wi-Fi RX filter
| +-- active Wi-Fi selector (STA / AP)
| +-- ctrlpath
| +-- virtual channel
|
+-- Wi-Fi backend (fhost / wl80211) + lwIP
</syntaxhighlight>

从功能上看，<code>nethub</code> 主要做 4 件事：

* 维护 <code>Wi-Fi <-> HostLink</code> 的数据桥接
* 用硬编码 filter 决定报文是 <code>local</code>、<code>host</code>、还是 <code>both</code>
* 维护当前生效的 Wi-Fi 通道选择 <code>STA / AP</code>
* 在同一 host link 上提供控制通道和可选的 <code>USER virtual channel</code>

== 3. 技术/API 视角架构图 ==

<syntaxhighlight lang="text">
Application
|
+-- device public API
| +-- nethub.h
| +-- nethub_vchan.h
| +-- nethub_filter.h
|
+-- host public API
+-- bflbwifi.h
+-- virtualchan/nethub_vchan.h

device side
nethub_bootstrap()
-> profile select
-> endpoint register
-> hub lifecycle
-> Wi-Fi bridge
-> host backend (current main path: sdio)

host side
bflbwifictrl
-> IPC
-> bflbwifid
-> libbflbwifi
-> channel facade
+-- tty backend
+-- vchan backend
-> mr_sdio.ko + msg_router
</syntaxhighlight>

== 4. Device 侧公共接口 ==

头文件：

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

核心 API：

* <code>nethub_bootstrap()</code>
* <code>nethub_shutdown()</code>
* <code>nethub_get_status()</code>
* <code>nethub_set_active_wifi_channel()</code>
* <code>nethub_ctrl_upld_send()</code>
* <code>nethub_ctrl_dnld_register()</code>
* <code>nethub_vchan_user_send()</code>
* <code>nethub_vchan_user_recv_register()</code>
* <code>nethub_set_wifi_rx_filter()</code>

边界说明：

* <code>nethub_ctrl_*</code> 对应 host link 上的逻辑控制通道
* <code>nethub_vchan_user_*</code> 对应 host link 上的逻辑 <code>USER</code> 通道
* <code>nethub_set_wifi_rx_filter()</code> 用于完全替换内建 Wi-Fi RX filter，必须在 <code>nethub_bootstrap()</code> 前调用

== 5. Host 侧公共接口 ==

头文件：

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

控制面能力：

* <code>bflbwifi_ctrl_config_init()</code>
* <code>bflbwifi_ctrl_config_use_tty()</code>
* <code>bflbwifi_ctrl_config_use_vchan()</code>
* <code>bflbwifi_init_ex()</code>
* <code>bflbwifi_get_ctrl_status()</code>
* <code>bflbwifi_sta_connect()</code>
* <code>bflbwifi_sta_disconnect()</code>
* <code>bflbwifi_sta_get_state()</code>
* <code>bflbwifi_scan()</code>
* <code>bflbwifi_get_version()</code>
* <code>bflbwifi_restart()</code>
* <code>bflbwifi_ota_upgrade()</code>
* <code>bflbwifi_ap_start()</code>
* <code>bflbwifi_ap_stop()</code>

USER virtual channel 能力：

* <code>nethub_vchan_init()</code>
* <code>nethub_vchan_deinit()</code>
* <code>nethub_vchan_user_send()</code>
* <code>nethub_vchan_user_register_callback()</code>
* <code>nethub_vchan_get_state_snapshot()</code>
* <code>nethub_vchan_register_link_event_callback()</code>

== 6. 关键数据流 ==

=== 6.1 connect_ap ===

# 用户执行 <code>bflbwifictrl connect_ap <ssid> <password></code>
# CLI 通过本地 IPC 把命令发给 <code>bflbwifid</code>
# daemon 调用 <code>libbflbwifi</code>
# <code>libbflbwifi</code> 通过 <code>tty</code> 或 <code>vchan</code> backend 下发控制消息
# device 侧 <code>ATModule</code> 执行 Wi-Fi 控制
# device 侧上报响应和状态，host 侧刷新状态并返回结果

=== 6.2 数据面 ===

# host 网络流量进入 <code>mr_eth0</code>
# kernel/msg_router 通过 SDIO 与 device 通信
# device 侧 <code>nethub</code> 把 host data 转给当前 active Wi-Fi
# Wi-Fi RX 包经过 <code>nethub</code> filter 判断后，决定是本地处理、发给 host，还是两边都处理

== 7. 推荐阅读顺序 ==

* 首次 bringup：[[NetHubQuickBringup|NetHub 快速上手]]
* 理解 <code>USER</code> 通道：[[NetHubVirtualChannel|NetHub USER Virtual Channel]]

NetHubArchitecture - 版本历史

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

张良：​Add NetHub architecture diagram to docs (2026-04-25)

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

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