Lines Matching +full:usb +full:- +full:c
3 New USB device support
9 USB device support consists of the USB device controller (UDC) drivers
10 , :ref:`udc_api`, and USB device stack, :ref:`usbd_api`.
11 The :ref:`udc_api` provides a generic and vendor independent interface to USB
13 layers, the purpose of :ref:`udc_api` is to serve new Zephyr's USB device stack
18 high-speed device controllers are supported. It also provides support for
20 or changing the configuration later. It has built-in support for several USB
21 classes and provides an API to implement custom USB functions.
23 The new USB device support is considered experimental and will replace
29 * :zephyr:code-sample:`usb-hid-keyboard`
31 * :zephyr:code-sample:`uac2-explicit-feedback`
33 * :zephyr:code-sample:`uac2-implicit-feedback`
35 Samples ported to new USB device support
36 ----------------------------------------
38 To build a sample that supports both the old and new USB device stack, set the
39 configuration ``-DCONF_FILE=usbd_next_prj.conf`` either directly or via
42 * :zephyr:code-sample:`bluetooth_hci_usb`
44 * :zephyr:code-sample:`usb-cdc-acm`
46 * :zephyr:code-sample:`usb-cdc-acm-console`
48 * :zephyr:code-sample:`usb-mass`
50 * :zephyr:code-sample:`usb-hid-mouse`
52 * :zephyr:code-sample:`zperf` To build the sample for the new device support,
54 ``-DDEXTRA_CONF_FILE=overlay-usbd_next_ecm.conf`` and devicetree overlay file
55 ``-DDTC_OVERLAY_FILE="usbd_next_ecm.overlay`` either directly or via ``west``.
57 How to configure and enable USB device support
60 For the USB device support samples in the Zephyr project repository, we have a
62 :zephyr_file:`samples/subsys/usb/common/sample_usbd_init.c`. The following code
63 snippets from this file are used as examples. USB Samples Kconfig options used
64 in the USB samples and prefixed with ``SAMPLE_USBD_`` have default values
69 The USB device stack requires a context structure to manage its properties and
71 :c:macro:`USBD_DEVICE_DEFINE` macro. This creates a static
72 :c:struct:`usbd_context` variable with a given name. Any number of contexts may
73 be instantiated. A USB controller device can be assigned to multiple contexts,
77 .. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c
78 :language: c
80 :start-after: doc device instantiation start
81 :end-before: doc device instantiation end
83 Your USB device may have manufacturer, product, and serial number string
85 use the appropriate :c:macro:`USBD_DESC_MANUFACTURER_DEFINE`,
86 :c:macro:`USBD_DESC_PRODUCT_DEFINE`, and
87 :c:macro:`USBD_DESC_SERIAL_NUMBER_DEFINE` macros. String descriptors also
89 :c:macro:`USBD_DESC_LANG_DEFINE` macro.
91 .. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c
92 :language: c
94 :start-after: doc string instantiation start
95 :end-before: doc string instantiation end
98 initializing the USB device with :c:func:`usbd_add_descriptor`.
100 .. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c
101 :language: c
103 :start-after: doc add string descriptor start
104 :end-before: doc add string descriptor end
106 USB device requires at least one configuration instance per supported speed.
107 The application should use :c:macro:`USBD_CONFIGURATION_DEFINE` to instantiate
108 a configuration. Later, USB device functions are assigned to a configuration.
110 .. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c
111 :language: c
113 :start-after: doc configuration instantiation start
114 :end-before: doc configuration instantiation end
117 context at runtime before the USB device is initialized using
118 :c:func:`usbd_add_configuration`. Note :c:enumerator:`USBD_SPEED_FS` and
119 :c:enumerator:`USBD_SPEED_HS`. The first full-speed or high-speed
122 .. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c
123 :language: c
125 :start-after: doc configuration register start
126 :end-before: doc configuration register end
129 Although we have already done a lot, this USB device has no function. A device
131 speeds. A function or class can be registered on a USB device before
132 it is initialized using :c:func:`usbd_register_class`. The desired
133 configuration is specified using :c:enumerator:`USBD_SPEED_FS` or
134 :c:enumerator:`USBD_SPEED_HS` and the configuration number. For simple cases,
135 :c:func:`usbd_register_all_classes` can be used to register all available
138 .. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c
139 :language: c
141 :start-after: doc functions register start
142 :end-before: doc functions register end
145 :c:func:`usbd_init`. After this, the configuration of the device cannot be
146 changed. A device can be deinitialized with :c:func:`usbd_shutdown` and all
149 function, and initialize it again. At the USB controller level,
150 :c:func:`usbd_init` does only what is necessary to detect VBUS changes. There
155 steps, which should be performed prior to initializing the USB device.
157 .. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c
158 :language: c
160 :start-after: doc device init start
161 :end-before: doc device init end
163 The final step to enable the USB device is :c:func:`usbd_enable`, after that,
164 if the USB device is connected to a USB host controller, the host can start
165 enumerating the device. The application can disable the USB device using
166 :c:func:`usbd_disable`.
168 .. literalinclude:: ../../../../samples/subsys/usb/hid-keyboard/src/main.c
169 :language: c
171 :start-after: doc device enable start
172 :end-before: doc device enable end
174 USB Message notifications
177 The application can register a callback using :c:func:`usbd_msg_register_cb` to
178 receive message notification from the USB device support subsystem. The
180 types from the USB CDC ACM implementation.
182 .. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c
183 :language: c
185 :start-after: doc device init-and-msg start
186 :end-before: doc device init-and-msg end
188 The helper function :c:func:`usbd_msg_type_string()` can be used to convert
189 :c:enumerator:`usbd_msg_type` to a human readable form for logging.
191 If the controller supports VBUS state change detection, the battery-powered
192 application may want to enable the USB device only when it is connected to a
193 host. A generic application should use :c:func:`usbd_can_detect_vbus` to check
196 .. literalinclude:: ../../../../samples/subsys/usb/hid-keyboard/src/main.c
197 :language: c
199 :start-after: doc device msg-cb start
200 :end-before: doc device msg-cb end
202 Built-in functions
205 The USB device stack has built-in USB functions. Some can be used directly in
209 instance (``n``) and is used as an argument to the :c:func:`usbd_register_class`.
211 +-----------------------------------+-------------------------+-------------------------+
214 | USB Audio 2 class | :ref:`uac2_device` | :samp:`uac2_{n}` |
215 +-----------------------------------+-------------------------+-------------------------+
216 | USB CDC ACM class | :ref:`uart_api` | :samp:`cdc_acm_{n}` |
217 +-----------------------------------+-------------------------+-------------------------+
218 | USB CDC ECM class | Ethernet device | :samp:`cdc_ecm_{n}` |
219 +-----------------------------------+-------------------------+-------------------------+
220 | USB Mass Storage Class (MSC) | :ref:`usbd_msc_device` | :samp:`msc_{n}` |
221 +-----------------------------------+-------------------------+-------------------------+
222 | USB Human Interface Devices (HID) | :ref:`usbd_hid_device` | :samp:`hid_{n}` |
223 +-----------------------------------+-------------------------+-------------------------+
224 | Bluetooth HCI USB transport layer | :ref:`bt_hci_raw` | :samp:`bt_hci_{n}` |
225 +-----------------------------------+-------------------------+-------------------------+
230 CDC ACM implements a virtual UART controller and provides Interrupt-driven UART
233 Interrupt-driven UART API
234 -------------------------
240 :c:func:`uart_irq_update()`, :c:func:`uart_irq_is_pending`,
241 :c:func:`uart_irq_rx_ready()`, :c:func:`uart_irq_tx_ready()`
242 :c:func:`uart_fifo_read()`, and :c:func:`uart_fifo_fill()`
244 :c:func:`uart_irq_callback_user_data_set()`. To prevent undefined behaviour,
248 Also, as described in the UART API, :c:func:`uart_irq_is_pending`
249 :c:func:`uart_irq_rx_ready()`, and :c:func:`uart_irq_tx_ready()`
250 can only be called after :c:func:`uart_irq_update()`.
254 .. code-block:: c
278 All these functions are not directly dependent on the status of the USB device.
282 is enabled, :c:func:`uart_irq_tx_ready()` will succeed. If there is data in the
283 RX FIFO, and the RX interrupt is enabled, :c:func:`uart_irq_rx_ready()` will
284 succeed. Function :c:func:`uart_irq_tx_complete()` is not implemented yet.
287 ----------------
290 blocks when the TX FIFO is full only if the hw-flow-control property is enabled
291 and called from a non-ISR context.