查看“︁NetHubVirtualChannel”︁的源代码

= NetHub USER Virtual Channel =

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

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 transport-neutral, while the current in-tree implementation is still centered on the default <code>SDIO</code> interface.

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

Current implementation summary:

* 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
* 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>
* USB device-side ACM transport exists, but in-tree host <code>nethub_vchan</code> alignment is not finished
* SPI is 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 uses the default <code>SDIO</code> interface
* 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 describe USB and SPI as if they already share a 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]]