diff options
Diffstat (limited to 'docs/reference/class/network.rst')
| -rw-r--r-- | docs/reference/class/network.rst | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/docs/reference/class/network.rst b/docs/reference/class/network.rst new file mode 100644 index 000000000..b0f8c8b46 --- /dev/null +++ b/docs/reference/class/network.rst @@ -0,0 +1,121 @@ +*********** +USB Network +*********** + +Role: device only. TinyUSB can present an Ethernet-style interface using +CDC-ECM, RNDIS, or CDC-NCM. The application connects Ethernet frames to a +network stack such as lwIP. + +Choose one driver +================= + +``CFG_TUD_ECM_RNDIS`` and ``CFG_TUD_NCM`` are mutually exclusive. + +* The ECM/RNDIS driver can expose separate configurations so Windows selects + RNDIS and macOS selects ECM; Linux can use either. +* NCM aggregates Ethernet datagrams into Network Transfer Blocks and is the + preferred starting point for current, higher-throughput designs. Windows + binding may require the Microsoft OS 2.0 descriptors shown by the example. + +Use the matching descriptor macro: ``TUD_CDC_ECM_DESCRIPTOR``, +``TUD_RNDIS_DESCRIPTOR``, or ``TUD_CDC_NCM_DESCRIPTOR``. Provide a unique +48-bit ``tud_network_mac_address`` and return the same address as a 12-digit +hexadecimal USB string descriptor where the class descriptor references it. + +Configuration options +===================== + +.. list-table:: + :header-rows: 1 + :widths: 42 16 42 + + * - Option + - Default + - What it controls + * - ``CFG_TUD_ECM_RNDIS`` / ``CFG_TUD_NCM`` + - ``0`` + - Selects one network class implementation. Enabling both is a build + error. + * - ``CFG_TUD_NET_MTU`` + - ``1514`` bytes + - Maximum Ethernet frame including its 14-byte Ethernet header. + * - ``CFG_TUD_NCM_OUT_NTB_MAX_SIZE`` + - ``3200`` bytes + - Largest host-to-device NTB received. Linux expects at least 2048 bytes. + * - ``CFG_TUD_NCM_IN_NTB_MAX_SIZE`` + - ``3200`` bytes + - Largest device-to-host NTB assembled for transmission. + * - ``CFG_TUD_NCM_OUT_NTB_N`` / ``CFG_TUD_NCM_IN_NTB_N`` + - ``1`` each + - Number of receive/transmit NTB buffers. Increasing these can reduce + stalls at a proportional RAM cost; benchmark before changing them. + * - ``CFG_TUD_NCM_IN_MAX_DATAGRAMS_PER_NTB`` + - ``8`` + - Maximum Ethernet frames TinyUSB aggregates into a transmit NTB. + * - ``CFG_TUD_NCM_OUT_MAX_DATAGRAMS_PER_NTB`` + - ``6`` + - Maximum frames the device tells the host to place in one receive NTB. + +Frame flow +========== + +For host-to-device frames, TinyUSB calls +``tud_network_recv_cb(src, size)``. Copy or pass the frame to the network stack +and call ``tud_network_recv_renew()`` when the supplied packet storage is no +longer needed. Return ``false`` if the frame cannot be accepted. + +For device-to-host frames: + +1. Call ``tud_network_can_xmit(size)``. +2. If it returns true, call ``tud_network_xmit(ref, arg)`` once. +3. TinyUSB calls ``tud_network_xmit_cb(dst, ref, arg)``; copy the complete + Ethernet frame into ``dst`` and return its length. + +Use ``tud_network_link_state()`` to notify the host when the logical or physical +link changes. A mounted USB device is not necessarily a link-up network +interface. + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - API or callback + - What it does + * - ``tud_network_recv_cb()`` + - Offers one received Ethernet frame. Return ``true`` only if the + application accepted the buffer or copied the frame. + * - ``tud_network_recv_renew()`` + - Releases the offered receive storage and permits the next host packet. + * - ``tud_network_can_xmit()`` / ``tud_network_xmit()`` + - Reserves room and requests one device-to-host frame. Call ``xmit`` only + once after a successful capacity check. + * - ``tud_network_xmit_cb()`` + - Copies the complete frame into TinyUSB's destination and returns its + actual byte length. + * - ``tud_network_init_cb()`` + - Resets the application network state when the ECM/RNDIS driver is + initialized or reset. + * - ``tud_network_set_packet_filter_cb()`` + - Reports NCM host filter bits so the application can adjust multicast or + promiscuous delivery. + * - ``tud_network_default_link_state_cb()`` / + ``tud_network_link_state()`` + - Supplies the initial NCM link state and later sends link up/down changes + to the host. + +NCM sizing +========== + +NCM buffer sizes have a direct RAM/throughput tradeoff. The class requires an +OUT NTB size of at least 2048 bytes. Begin with one IN and one OUT NTB, then +measure before increasing ``CFG_TUD_NCM_IN_NTB_MAX_SIZE``, +``CFG_TUD_NCM_OUT_NTB_MAX_SIZE``, or their ``*_NTB_N`` counts. Keep descriptor +capabilities and runtime responses consistent with the enabled NCM features. + +The :doc:`../../examples/device/net_lwip_webserver` example includes NCM and +ECM/RNDIS descriptor sets, lwIP integration, DHCP, DNS, link-state changes, and +host setup notes. + +Specifications used: *CDC Ethernet Control Model*, Revision 1.2, and *CDC +Network Control Model*, Revision 1.0 (Errata 1). RNDIS is a vendor protocol, +not a USB-IF CDC subclass. |