查看“︁NetHubVirtualChannel”︁的源代码

= NetHub USER Virtual Channel =

This document describes how to use the NetHub <code>USER virtual channel</code>.

== 1. Concept ==

<code>USER virtual channel</code> is a logical message channel carried on the current host link.

It is not a separate physical interface. It reuses the current <code>SDIO / USB / SPI</code> transport and multiplexes different payload types into separate logical channels.

Commonly used types:

* <code>USER</code>
** private customer or application data
* <code>AT</code>
** host control-plane data
* <code>SYSTEM</code>
** internal system coordination messages

For most customer integrations, only the <code>USER</code> type matters.

== 2. Bring-Up Prerequisites ==

Before using it, confirm:

* device side is built with <code>CONFIG_NETHUB=y</code>
* device side is built with <code>CONFIG_MR_VIRTUALCHAN=y</code>
* host side has already loaded <code>mr_sdio.ko</code>
* the underlying host-device link is already working

Additional notes:

* The <code>USER</code> channel and the control channel are parallel channels
* If the host control plane itself uses <code>vchan</code>, it uses the <code>AT</code> type
* Customer private messages should stay on the <code>USER</code> type

== 3. device-side Interfaces ==

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>

== 4. host-side Interfaces ==

Header:

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

=== 4.1 Initialization and Cleanup ===

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

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

=== 4.3 Optional State Query ===

If you need to know whether the virtual channel is ready, you can optionally use:

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

Typical checks:

* <code>link_state == NETHUB_VCHAN_LINK_UP</code>
** the link is ready for TX/RX
* <code>host_state == NETHUB_VCHAN_HOST_STATE_DEVICE_RUN</code>
** the host has completed the handshake with the device

=== 4.4 Optional Link Event Callback ===

If the application wants passive notification when the link goes up or down, it can optionally register:

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

== 5. Typical Usage Order ==

# <code>nethub_vchan_init()</code>
# <code>nethub_vchan_user_register_callback()</code>
# <code>nethub_vchan_user_send()</code>
# Call <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>

== 6. Limits and Notes ==

* Maximum payload length per message is <code>1500</code> bytes
* The <code>USER</code> channel is packet-oriented, not a byte stream
* The kernel module must be loaded before use
* If the device side does not enable <code>CONFIG_MR_VIRTUALCHAN</code>, the host-side <code>USER</code> channel will not work
* If host control-plane traffic and <code>USER</code> traffic coexist, do not reuse the <code>AT</code> type for customer private data

== 7. Related Pages ==

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