1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
***************
Vendor-specific
***************
The device driver provides bulk, and optionally interrupt or isochronous,
transfers for a vendor-defined interface. There is no generic vendor protocol:
the device descriptors, request semantics, framing, and host software are part
of the product's protocol.
Device
======
Enable ``CFG_TUD_VENDOR`` and add ``TUD_VENDOR_DESCRIPTOR`` for the usual pair
of bulk endpoints. Buffered mode is the practical default.
.. list-table::
:header-rows: 1
:widths: 43 17 40
* - Option
- Default
- What it controls
* - ``CFG_TUD_VENDOR_RX_BUFSIZE`` /
``CFG_TUD_VENDOR_TX_BUFSIZE``
- Device bulk maximum
- Software FIFO bytes. Setting either to zero selects direct mode for
both directions.
* - ``CFG_TUD_VENDOR_RX_EPSIZE`` /
``CFG_TUD_VENDOR_TX_EPSIZE``
- Device bulk maximum
- Bulk endpoint transfer buffers and descriptor packet sizes.
* - ``CFG_TUD_VENDOR_RX_MANUAL_XFER``
- ``0``
- Requires the application to call ``tud_vendor_n_read_xfer()`` to arm
each buffered bulk OUT transfer.
* - ``CFG_TUD_VENDOR_RX_NEED_ZLP``
- ``0``
- Allows multi-packet receive termination by a zero-length packet; enable
only when the custom host protocol sends that terminator.
* - ``CFG_TUD_VENDOR_EP_INT_OUT`` /
``CFG_TUD_VENDOR_EP_INT_IN``
- ``0``
- Enables optional direct interrupt endpoints. Their buffer-size options
default to 64 bytes.
* - ``CFG_TUD_VENDOR_EP_ISO_OUT`` /
``CFG_TUD_VENDOR_EP_ISO_IN``
- ``0``
- Enables optional direct isochronous endpoints. They require alternate
settings; their buffers default to 64 bytes.
* - ``CFG_TUD_VENDOR_ALT_SETTINGS``
- ``0``
- Enables alternate-setting tracking. It requires direct mode and is
required by the optional isochronous endpoints.
Use ``tud_vendor_available()``/``tud_vendor_read()`` for OUT data and
``tud_vendor_write()``/``tud_vendor_write_flush()`` for IN data. In buffered
mode, ``tud_vendor_rx_cb()`` is only a notification; read the FIFO rather than
using its null buffer argument.
For direct transfers, configure zero RX/TX FIFO sizes and follow the ownership
rules in ``vendor_device.h``. Optional interrupt, isochronous, and alternate
setting support is controlled by ``CFG_TUD_VENDOR_EP_*`` and
``CFG_TUD_VENDOR_ALT_SETTINGS``. Interrupt and isochronous OUT endpoints must
be explicitly re-armed after their receive callbacks.
.. list-table::
:header-rows: 1
:widths: 43 57
* - API or callback
- What it does
* - ``tud_vendor_n_mounted()``
- Tests whether an instance has any configured bulk, interrupt, or
isochronous endpoint open.
* - ``tud_vendor_n_available()`` / ``tud_vendor_n_read()``
- Reports and removes bulk OUT FIFO bytes in buffered mode.
* - ``tud_vendor_n_write_available()`` /
``tud_vendor_n_write()``
- Reports room and copies as many bulk IN bytes as fit. In direct mode the
copy is limited to one endpoint buffer.
* - ``tud_vendor_n_write_flush()``
- Starts a short buffered IN transfer and returns the number of bytes
submitted.
* - ``tud_vendor_rx_cb()`` / ``tud_vendor_tx_cb()``
- Announces received data or completed output. In direct mode, consume or
copy the receive pointer before returning from the callback.
* - ``tud_vendor_n_int_read_xfer()`` /
``tud_vendor_n_iso_read_xfer()``
- Arms one optional OUT transfer; re-arm after each receive callback.
* - ``tud_vendor_n_int_write()`` /
``tud_vendor_n_iso_write()``
- Copies and queues at most one optional endpoint buffer and returns the
accepted byte count.
* - ``tud_vendor_n_alt()``
- Returns the host-selected alternate setting when support is enabled.
Handle vendor control requests in ``tud_vendor_control_xfer_cb()`` and perform
the data/status stage with ``tud_control_xfer()`` or
``tud_control_status()``. Validate ``bmRequestType``, ``bRequest``,
``wIndex``, ``wValue``, and ``wLength`` before accepting a request.
The :doc:`../../examples/device/webusb_serial` example combines a vendor bulk
interface with WebUSB and Microsoft OS 2.0 descriptors.
Host
====
A host cannot interpret an arbitrary vendor interface from its class code.
TinyUSB does not currently offer a supported, protocol-neutral
``tuh_vendor_*`` application API. For a simple fixed device, enable
``CFG_TUH_API_EDPT_XFER`` and use the descriptor/endpoint APIs demonstrated by
:doc:`../../examples/host/bare_api`. For a reusable protocol, implement a
custom host class driver that matches devices by descriptors and VID/PID and
owns their enumeration and transfer state.
Define framing, version negotiation, maximum message lengths, timeouts, and
error recovery before deploying a vendor protocol. Never cast unvalidated
wire data directly to an application structure.
|
