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

• • • • • USER
          • private customer or application data
        • AT
          • control payloads
        • SYSTEM
          • internal coordination messages

2. Current Support Status

Area	Current status
Device API surface	transport-neutral by design
Device in-tree implementation	currently in backend/host/sdio/virtualchan.c
Host userspace library	currently aligned with mr_sdio.ko + netlink
End-to-end USER vchan reference path	SDIO
USB	device-side ACM transport exists, but in-tree host nethub_vchan 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 CONFIG_NETHUB=y
        • device side enables CONFIG_MR_VIRTUALCHAN=y
        • the selected bring-up path is the current SDIO reference flow
        • host side has loaded mr_sdio.ko
        • the host-device link is already working

Notes:

• • • • • USER and AT are parallel logical channels
        • customer private data should stay on the USER 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:

• • • • • components/net/nethub/include/nethub_vchan.h

Common APIs:

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

5. Host-Side API

Header:

• • • • • bsp/common/msg_router/linux_host/userspace/nethub/virtualchan/nethub_vchan.h

Initialization and cleanup:

        int nethub_vchan_init(void);
        int nethub_vchan_deinit(void);

USER channel:

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

Optional state query:

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

Optional link event callback:

        int nethub_vchan_register_link_event_callback(
            nethub_vchan_link_event_callback_t callback,
            void *user_data);

6. Typical Usage Order

1. 1. 1. 1. 1. nethub_vchan_init()
            2. nethub_vchan_user_register_callback()
            3. nethub_vchan_user_send()
            4. nethub_vchan_deinit() when finished

Example:

        #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
", (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;
        }

7. Limits and Notes

• • • • • maximum payload length per message is 1500 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 CONFIG_MR_VIRTUALCHAN, the current in-tree USER virtual-channel path will not work
        • if control traffic and USER traffic coexist, keep private application traffic on USER and do not reuse the AT type

8. Related Pages

• • • • • NetHub.md
        • NetHubQuickBringup.md
        • NetHubArchitecture.md