diff options
Diffstat (limited to 'docs/reference/class/cdc.rst')
| -rw-r--r-- | docs/reference/class/cdc.rst | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/docs/reference/class/cdc.rst b/docs/reference/class/cdc.rst new file mode 100644 index 000000000..13f0b463d --- /dev/null +++ b/docs/reference/class/cdc.rst @@ -0,0 +1,169 @@ +********** +CDC Serial +********** + +Roles: device and host. The standard driver implements CDC ACM virtual serial +ports. The host driver can also expose FTDI, CP210x, CH34x, and PL2303 USB +serial adapters through the same ``tuh_cdc_*`` API. + +Device +====== + +Enable ``CFG_TUD_CDC`` with the required port count and add one +``TUD_CDC_DESCRIPTOR`` per port. + +.. list-table:: + :header-rows: 1 + :widths: 36 18 46 + + * - Option + - Default + - What it controls + * - ``CFG_TUD_CDC_RX_BUFSIZE`` / ``CFG_TUD_CDC_TX_BUFSIZE`` + - Device bulk maximum + - Software FIFO capacity in each direction. Larger FIFOs absorb longer + application scheduling gaps. + * - ``CFG_TUD_CDC_RX_EPSIZE`` / ``CFG_TUD_CDC_TX_EPSIZE`` + - Device bulk maximum + - Endpoint transfer buffer and descriptor packet size. Use + speed-appropriate values. + * - ``CFG_TUD_CDC_NOTIFY`` + - ``0`` + - Enables the interrupt notification endpoint and serial-state API. + * - ``CFG_TUD_CDC_RX_PERSISTENT`` / ``CFG_TUD_CDC_TX_PERSISTENT`` + - ``0`` + - Keeps the corresponding FIFO contents across disconnect/reconnect. + Enable only when stale bytes are intentional. + * - ``CFG_TUD_CDC_RX_NEED_ZLP`` + - ``0`` + - Enables multi-packet receive transfers terminated by a host-sent + zero-length packet. Enable only when the host side supports this + framing. + * - ``CFG_TUD_CDC_TX_OVERWRITABLE_IF_NOT_CONNECTED`` + - ``1`` + - Allows writes made before DTR connection to replace old queued data + rather than permanently filling the FIFO. + +Use speed-dependent values from an example when the device can enumerate at +high speed. ``CFG_TUD_CDC_NOTIFY`` enables serial-state notifications. + +The common data path is: + +.. code-block:: c + + void tud_cdc_rx_cb(uint8_t itf) { + uint8_t buf[64]; + uint32_t count = tud_cdc_n_available(itf); + uint32_t room = tud_cdc_n_write_available(itf); + if (count > sizeof(buf)) count = sizeof(buf); + if (count > room) count = room; + + count = tud_cdc_n_read(itf, buf, count); + if (count && tud_cdc_n_write(itf, buf, count) == count) { + tud_cdc_n_write_flush(itf); + } + } + +Use ``tud_cdc_n_connected()`` when transmission should depend on DTR. A port +can be mounted while a terminal has not opened it. Handle line settings in +``tud_cdc_line_state_cb()`` and ``tud_cdc_line_coding_cb()`` if they affect the +physical UART; TinyUSB does not configure that UART for you. + +.. list-table:: + :header-rows: 1 + :widths: 39 61 + + * - Device API or callback + - What it does + * - ``tud_cdc_n_connected()`` / ``tud_cdc_n_ready()`` + - Tests DTR connection, or whether the port is connected and can accept + output now. + * - ``tud_cdc_n_available()`` / ``tud_cdc_n_read()`` + - Reports and removes bytes received from the host. + * - ``tud_cdc_n_write_available()`` / ``tud_cdc_n_write()`` + - Reports TX FIFO room and copies as many bytes as fit; preserve any + unwritten remainder. + * - ``tud_cdc_n_write_flush()`` + - Starts transmission of buffered bytes without waiting for the FIFO to + fill. + * - ``tud_cdc_rx_cb()`` / ``tud_cdc_tx_complete_cb()`` + - Announces newly buffered receive data or completion of a transmit + transfer. + * - ``tud_cdc_line_state_cb()`` / ``tud_cdc_line_coding_cb()`` + - Reports host DTR/RTS and baud/data/parity/stop settings so a UART bridge + can apply them. + +See :doc:`../../examples/device/cdc_dual_ports` for multiple ports and +:doc:`../../examples/device/cdc_msc` for a composite device. + +Host +==== + +Set ``CFG_TUH_CDC`` to the required number of serial interfaces. Enable only +the adapter families needed by the product: + +.. code-block:: c + + #define CFG_TUH_CDC 1 + #define CFG_TUH_CDC_FTDI 1 + #define CFG_TUH_CDC_CP210X 1 + #define CFG_TUH_CDC_CH34X 1 + #define CFG_TUH_CDC_PL2303 1 + +The RX/TX software FIFO and endpoint buffers default to +``TUH_EPSIZE_BULK_MAX`` through ``CFG_TUH_CDC_RX_BUFSIZE``, +``CFG_TUH_CDC_TX_BUFSIZE``, ``CFG_TUH_CDC_RX_EPSIZE``, and +``CFG_TUH_CDC_TX_EPSIZE``. Increase FIFO sizes to tolerate application +latency; endpoint sizes normally stay at the host bulk maximum. Optional +``CFG_TUH_CDC_LINE_CODING_ON_ENUM`` and +``CFG_TUH_CDC_LINE_CONTROL_ON_ENUM`` values apply initial serial settings as +part of enumeration. + +``tuh_cdc_mount_cb(idx)`` reports a ready interface. Read data in +``tuh_cdc_rx_cb(idx)`` using ``tuh_cdc_read_available()`` and +``tuh_cdc_read()``. Queue output with ``tuh_cdc_write()`` and call +``tuh_cdc_write_flush()`` when it should leave promptly. + +Line-control functions such as ``tuh_cdc_set_baudrate()`` and +``tuh_cdc_set_line_coding()`` accept a completion callback. Their ``_sync`` +forms block and should only be used where the host task can continue running. +Support varies by adapter family; in particular, the combined line-coding call +is not implemented for every non-CDC adapter. + +.. list-table:: + :header-rows: 1 + :widths: 39 61 + + * - Host API or callback + - What it does + * - ``tuh_cdc_mounted()`` / ``tuh_cdc_itf_get_info()`` + - Tests an interface index and returns its address, interface descriptor, + and serial-driver type. + * - ``tuh_cdc_read_available()`` / ``tuh_cdc_read()`` + - Reports and removes bytes buffered from the serial device. + * - ``tuh_cdc_write()`` / ``tuh_cdc_write_flush()`` + - Copies output into the class FIFO and starts a USB transfer. + * - ``tuh_cdc_set_control_line_state()`` / + ``tuh_cdc_set_line_coding()`` + - Queues DTR/RTS or baud/framing changes and calls the supplied completion + callback. + * - ``tuh_cdc_mount_cb()`` / ``tuh_cdc_umount_cb()`` + - Creates or removes application state for a serial interface index. + * - ``tuh_cdc_rx_cb()`` / ``tuh_cdc_tx_complete_cb()`` + - Announces buffered input or completion of queued class output. + +The :doc:`../../examples/host/cdc_msc_hid` example shows enumeration, 115200 +8N1 setup, and bidirectional I/O. + +Practical notes +=============== + +* USB CDC transfers bytes, not UART timing. Baud rate and framing are host + requests that an application may honor, translate, or ignore. +* A write call can accept fewer bytes than requested. Preserve and retry the + remainder instead of silently dropping it. +* For interactive traffic, flush after a logical message. For throughput, + allow the FIFO to fill and flush less often. + +Specifications used: *Communications Devices Class*, Revision 1.2 (Errata 1), +and *CDC PSTN Subclass*, Revision 1.2, which defines ACM. |