USB cherry pick series for NCS 2.7.99-CS2

doc/connectivity/usb/device_next/api/udc.rst

@@ -16,3 +16,5 @@ API reference
 *************
 
 .. doxygengroup:: udc_api
+
+.. doxygengroup:: udc_buf

doc/connectivity/usb/device_next/usb_device.rst

@@ -1,57 +1,215 @@
 .. _usb_device_stack_next:
 
-New experimental USB device support
-###################################
+New USB device support
+######################
 
 Overview
 ********
 
-The new USB device support is experimental. It consists of :ref:`udc_api`
-and :ref:`usbd_api`. The new device stack brings support for multiple device
-controllers, support for multiple configurations, and dynamic registration of
-class instances to a configuration at runtime. The stack also provides a specific
-class API that should be used to implement the functions (classes).
-It will replace :ref:`usb_device_stack`.
+USB device support consists of the USB device controller (UDC) drivers
+, :ref:`udc_api`, and USB device stack, :ref:`usbd_api`.
+The :ref:`udc_api` provides a generic and vendor independent interface to USB
+device controllers, and although, there a is clear separation between these
+layers, the purpose of :ref:`udc_api` is to serve new Zephyr's USB device stack
+exclusively.
 
-If you would like to play around with the new device support, or the new USB
-support in general, please try :zephyr:code-sample:`usb-shell` sample. The sample is mainly to help
-test the capabilities of the stack and correct implementation of the USB controller
-drivers.
+The new device stack supports multiple device controllers, meaning that if a
+SoC has multiple controllers, they can be used simultaneously. Full and
+high-speed device controllers are supported. It also provides support for
+registering multiple function or class instances to a configuration at runtime,
+or changing the configuration later. It has built-in support for several USB
+classes and provides an API to implement custom USB functions.
 
-Supported USB classes
-*********************
+The new USB device support is considered experimental and will replace
+:ref:`usb_device_stack`.
 
-Bluetooth HCI USB transport layer
-=================================
+Built-in functions
+==================
+
+The USB device stack has built-in USB functions. Some can be used directly in
+the user application through a special API, such as HID or Audio class devices,
+while others use a general Zephyr RTOS driver API, such as MSC and CDC class
+implementations. The *Identification string* identifies a class or function
+instance (n) and is used as an argument to the :c:func:`usbd_register_class`.
 
-See :ref:`bluetooth-hci-usb-sample` sample for reference.
-To build the sample for the new device support, set the configuration
-``-DCONF_FILE=usbd_next_prj.conf`` either directly or via ``west``.
++-----------------------------------+-------------------------+-------------------------+
+| Class or function                 | User API (if any)       | Identification string   |
++===================================+=========================+=========================+
+| USB Audio 2 class                 | :ref:`uac2_device`      | uac2_(n)                |
++-----------------------------------+-------------------------+-------------------------+
+| USB CDC ACM class                 | :ref:`uart_api`         | cdc_acm_(n)             |
++-----------------------------------+-------------------------+-------------------------+
+| USB CDC ECM class                 | Ethernet device         | cdc_ecm_(n)             |
++-----------------------------------+-------------------------+-------------------------+
+| USB Mass Storage Class (MSC)      | :ref:`disk_access_api`  | msc_(n)                 |
++-----------------------------------+-------------------------+-------------------------+
+| USB Human Interface Devices (HID) | :ref:`usbd_hid_device`  | hid_(n)                 |
++-----------------------------------+-------------------------+-------------------------+
+| Bluetooth HCI USB transport layer | :ref:`bt_hci_raw`       | bt_hci_(n)              |
++-----------------------------------+-------------------------+-------------------------+
 
-CDC ACM
+Samples
 =======
 
-CDC ACM implementation has support for multiple instances.
-Description from :ref:`usb_device_cdc_acm` also applies to the new implementation.
-See :zephyr:code-sample:`usb-cdc-acm` sample for reference.
-To build the sample for the new device support, set the configuration
-``-DCONF_FILE=usbd_next_prj.conf`` either directly or via ``west``.
+* :zephyr:code-sample:`usb-hid-keyboard`
 
-Mass Storage Class
-==================
+* :zephyr:code-sample:`uac2-explicit-feedback`
+
+Samples ported to new USB device support
+----------------------------------------
+
+To build a sample that supports both the old and new USB device stack, set the
+configuration ``-DCONF_FILE=usbd_next_prj.conf`` either directly or via
+``west``.
+
+* :ref:`bluetooth-hci-usb-sample`
+
+* :zephyr:code-sample:`usb-cdc-acm`
+
+* :zephyr:code-sample:`usb-cdc-acm-console`
+
+* :zephyr:code-sample:`usb-mass`
+
+* :zephyr:code-sample:`usb-hid-mouse`
+
+* :zephyr:code-sample:`zperf` To build the sample for the new device support,
+  set the configuration overlay file
+  ``-DDEXTRA_CONF_FILE=overlay-usbd_next_ecm.conf`` and devicetree overlay file
+  ``-DDTC_OVERLAY_FILE="usbd_next_ecm.overlay`` either directly or via ``west``.
+
+How to configure and enable USB device support
+**********************************************
+
+For the USB device support samples in the Zephyr project repository, we have a
+common file for instantiation, configuration and initialization,
+:zephyr_file:`samples/subsys/usb/common/sample_usbd_init.c`. The following code
+snippets from this file are used as examples. USB Samples Kconfig options used
+in the USB samples and prefixed with ``SAMPLE_USBD_`` have default values
+specific to the Zephyr project and the scope is limited to the project samples.
+In the examples below, you will need to replace these Kconfig options and other
+defaults with values appropriate for your application or hardware.
+
+The USB device stack requires a context structure to manage its properties and
+runtime data. The preferred way to define a device context is to use the
+:c:macro:`USBD_DEVICE_DEFINE` macro. This creates a static
+:c:struct:`usbd_context` variable with a given name. Any number of contexts may
+be instantiated. A USB controller device can be assigned to multiple contexts,
+but only one context can be initialized and used at a time. Context properties
+must not be directly accessed or manipulated by the application.
+
+.. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c
+   :language: c
+   :start-after: doc device instantiation start
+   :end-before: doc device instantiation end
+
+Your USB device may have manufacturer, product, and serial number string
+descriptors. To instantiate these string descriptors, the application should
+use the appropriate :c:macro:`USBD_DESC_MANUFACTURER_DEFINE`,
+:c:macro:`USBD_DESC_PRODUCT_DEFINE`, and
+:c:macro:`USBD_DESC_SERIAL_NUMBER_DEFINE` macros. String descriptors also
+require a single instantiation of the language descriptor using the
+:c:macro:`USBD_DESC_LANG_DEFINE` macro.
+
+.. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c
+   :language: c
+   :start-after: doc string instantiation start
+   :end-before: doc string instantiation end
+
+String descriptors must be added to the device context at runtime before
+initializing the USB device with :c:func:`usbd_add_descriptor`.
+
+.. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c
+   :language: c
+   :start-after: doc add string descriptor start
+   :end-before: doc add string descriptor end
+
+USB device requires at least one configuration instance per supported speed.
+The application should use :c:macro:`USBD_CONFIGURATION_DEFINE` to instantiate
+a configuration. Later, USB device functions are assigned to a configuration.
+
+.. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c
+   :language: c
+   :start-after: doc configuration instantiation start
+   :end-before: doc configuration instantiation end
+
+Each configuration instance for a specific speed must be added to the device
+context at runtime before the USB device is initialized using
+:c:func:`usbd_add_configuration`. Note :c:enumerator:`USBD_SPEED_FS` and
+:c:enumerator:`USBD_SPEED_HS`. The first full-speed or high-speed
+configuration will get ``bConfigurationValue`` one, and then further upward.
+
+.. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c
+   :language: c
+   :start-after: doc configuration register start
+   :end-before: doc configuration register end
+
+
+Although we have already done a lot, this USB device has no function. A device
+can have multiple configurations with different set of functions at different
+speeds. A function or class can be registered on a USB device before
+it is initialized using :c:func:`usbd_register_class`. The desired
+configuration is specified using :c:enumerator:`USBD_SPEED_FS` or
+:c:enumerator:`USBD_SPEED_HS` and the configuration number.  For simple cases,
+:c:func:`usbd_register_all_classes` can be used to register all available
+instances.
+
+.. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c
+   :language: c
+   :start-after: doc functions register start
+   :end-before: doc functions register end
+
+The last step in the preparation is to initialize the device with
+:c:func:`usbd_init`. After this, the configuration of the device cannot be
+changed. A device can be deinitialized with :c:func:`usbd_shutdown` and all
+instances can be reused, but the previous steps must be repeated. So it is
+possible to shutdown a device, register another type of configuration or
+function, and initialize it again.  At the USB controller level,
+:c:func:`usbd_init` does only what is necessary to detect VBUS changes. There
+are controller types where the next step is only possible if a VBUS signal is
+present.
+
+A function or class implementation may require its own specific configuration
+steps, which should be performed prior to initializing the USB device.
+
+.. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c
+   :language: c
+   :start-after: doc device init start
+   :end-before: doc device init end
+
+The final step to enable the USB device is :c:func:`usbd_enable`, after that,
+if the USB device is connected to a USB host controller, the host can start
+enumerating the device. The application can disable the USB device using
+:c:func:`usbd_disable`.
+
+.. literalinclude:: ../../../../samples/subsys/usb/hid-keyboard/src/main.c
+   :language: c
+   :start-after: doc device enable start
+   :end-before: doc device enable end
+
+USB Message notifications
+=========================
+
+The application can register a callback using :c:func:`usbd_msg_register_cb` to
+receive message notification from the USB device support subsystem. The
+messages are mostly about the common device state changes, and a few specific
+types from the USB CDC ACM implementation.
 
-See :zephyr:code-sample:`usb-mass` sample for reference.
-To build the sample for the new device support, set the configuration
-``-DCONF_FILE=usbd_next_prj.conf`` either directly or via ``west``.
+.. literalinclude:: ../../../../samples/subsys/usb/common/sample_usbd_init.c
+   :language: c
+   :dedent:
+   :start-after: doc device init-and-msg start
+   :end-before: doc device init-and-msg end
 
-Networking
-==========
+The helper function :c:func:`usbd_msg_type_string()` can be used to convert
+:c:enumerator:`usbd_msg_type` to a human readable form for logging.
 
-At the moment only CDC ECM class is implemented and has support for multiple instances.
-It provides a virtual Ethernet connection between the remote (USB host) and
-Zephyr network support.
+If the controller supports VBUS state change detection, the battery-powered
+application may want to enable the USB device only when it is connected to a
+host. A generic application should use :c:func:`usbd_can_detect_vbus` to check
+for this capability.
 
-See :zephyr:code-sample:`zperf` for reference.
-To build the sample for the new device support, set the configuration overlay file
-``-DDEXTRA_CONF_FILE=overlay-usbd_next_ecm.conf`` and devicetree overlay file
-``-DDTC_OVERLAY_FILE="usbd_next_ecm.overlay`` either directly or via ``west``.
+.. literalinclude:: ../../../../samples/subsys/usb/hid-keyboard/src/main.c
+   :language: c
+   :dedent:
+   :start-after: doc device msg-cb start
+   :end-before: doc device msg-cb end

drivers/kscan/kscan_input.c

@@ -23,8 +23,9 @@ struct kscan_input_data {
 	bool pressed;
 };
 
-static void kscan_input_cb(const struct device *dev, struct input_event *evt)
+static void kscan_input_cb(struct input_event *evt, void *user_data)
 {
+	const struct device *dev = user_data;
 	struct kscan_input_data *data = dev->data;
 
 	switch (evt->code) {
@@ -100,13 +101,9 @@ static const struct kscan_driver_api kscan_input_driver_api = {
 };
 
 #define KSCAN_INPUT_INIT(index) \
-	static void kscan_input_cb_##index(struct input_event *evt)            \
-	{                                                                      \
-		kscan_input_cb(DEVICE_DT_GET(DT_INST(index, DT_DRV_COMPAT)),   \
-			       evt);                                           \
-	}                                                                      \
 	INPUT_CALLBACK_DEFINE(DEVICE_DT_GET(DT_INST_PARENT(index)),            \
-			      kscan_input_cb_##index);                         \
+			      kscan_input_cb,                                  \
+			      (void *)DEVICE_DT_INST_GET(index));              \
 	static const struct kscan_input_config kscan_input_config_##index = {  \
 		.input_dev = DEVICE_DT_GET(DT_INST_PARENT(index)),             \
 	};                                                                     \