查看“︁NetHubVirtualChannel”︁的源代码

= NetHub USER Virtual Channel =

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

== 1. Concept ==

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

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.

Common logical types:

{| class="wikitable"
|-
! Type !! Meaning
|-
| <code>USER</code> || private customer or application data
|-
| <code>AT</code> || control payloads
|-
| <code>SYSTEM</code> || internal coordination messages
|}

== 2. Current Support Status ==

{| class="wikitable"
|-
! Area !! Current status
|-
| Device API surface || transport-neutral by design
|-
| Device in-tree implementation || currently in <code>backend/host/sdio/virtualchan.c</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>
|-
| USB || device-side ACM transport exists, but in-tree host <code>nethub_vchan</code> alignment is not finished
|-
| SPI || not supported
|}

== 3. Prerequisites ==

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

* device side is built with <code>CONFIG_NETHUB=y</code>
* device side enables <code>CONFIG_MR_VIRTUALCHAN=y</code>
* the selected bring-up path is the current SDIO reference flow
* host side has loaded <code>mr_sdio.ko</code>
* the host-device link is already working

Notes:

* USER and AT are parallel logical channels
* 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

== 4. Device-Side API ==

Header:

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

Common APIs:

<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>

== 5. Host-Side API ==

Header:

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

Initialization and cleanup:

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

USER channel:

<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>

Optional state query:

<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>

Optional link event callback:

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

== 6. Typical Usage Order ==

# <code>nethub_vchan_init()</code>
# <code>nethub_vchan_user_register_callback()</code>
# <code>nethub_vchan_user_send()</code>
# <code>nethub_vchan_deinit()</code> when finished

Example:

<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>

== 7. Limits and Notes ==

* maximum payload length per message is <code>1500</code> bytes
* USER virtual channel is packet-oriented, not a byte stream
* 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 control traffic and USER traffic coexist, keep private application traffic on <code>USER</code> and do not reuse the <code>AT</code> type

== 8. Related Pages ==

* [[NetHub|NetHub.md]]
* [[NetHubQuickBringup|NetHubQuickBringup.md]]
* [[NetHubArchitecture|NetHubArchitecture.md]]