doc: usb: refactor USB device support documentation structure (31dbdca2) · Commits · Wenxi XU / zephyr

doc/reference/usb/hid.rst

0 → 100644

+61 −0

Original line number	Diff line number	Diff line
		.. _usb_device_hid:

		USB Human Interface Devices (HID) support
		#########################################

		Since the USB HID specification is not only used by the USB subsystem, the USB HID API
		is split into two header files :zephyr_file:`include/usb/class/hid.h`
		and :zephyr_file:`include/usb/class/usb_hid.h`. The second includes a specific
		part for HID support in the USB device stack.

		HID Item helpers
		****************

		HID item helper macros can be used to compose a HID Report Descriptor.
		The names correspond to those used in the USB HID Specification.

		Example of a HID Report Descriptor:

		.. code-block:: c

		static const uint8_t hid_report_desc[] = {
		HID_USAGE_PAGE(HID_USAGE_GEN_DESKTOP),
		HID_USAGE(HID_USAGE_GEN_DESKTOP_UNDEFINED),
		HID_COLLECTION(HID_COLLECTION_APPLICATION),
		HID_LOGICAL_MIN8(0),
		/* logical maximum 255 */
		HID_LOGICAL_MAX16(0xFF, 0x00),
		HID_REPORT_ID(1),
		HID_REPORT_SIZE(8),
		HID_REPORT_COUNT(1),
		HID_USAGE(HID_USAGE_GEN_DESKTOP_UNDEFINED),
		/* HID_INPUT (Data, Variable, Absolute) */
		HID_INPUT(0x02),
		HID_END_COLLECTION,
		};


		HID items reference
		*******************

		.. doxygengroup:: usb_hid_items

		HID types reference
		*******************

		.. doxygengroup:: usb_hid_types

		HID Mouse and Keyboard report descriptors
		*****************************************

		The pre-defined Mouse and Keyboard report descriptors can be used by
		a HID device implementation or simply as examples.

		.. doxygengroup:: usb_hid_mk_report_desc

		HID Class Device API reference
		******************************

		USB HID devices like mouse, keyboard, or any other specific device use this API.

		.. doxygengroup:: usb_hid_device_api

doc/reference/usb/index.rst

+8 −248

Original line number	Diff line number	Diff line
		.. _usb_api:

		USB device stack
		################
		USB device support
		##################

		.. contents::
		:depth: 2
		:local:
		:backlinks: top
		.. toctree::
		:maxdepth: 1

		USB Vendor and Product identifiers
		**********************************

		The USB Vendor ID for the Zephyr project is 0x2FE3. The default USB Product
		ID for the Zephyr project is 0x100. The USB bcdDevice Device Release Number
		represents the Zephyr kernel major and minor versions as a binary coded
		decimal value. When a vendor integrates the Zephyr USB subsystem into a
		product, the vendor must use the USB Vendor and Product ID assigned to them.
		A vendor integrating the Zephyr USB subsystem in a product must not use the
		Vendor ID of the Zephyr project.

		The USB maintainer, if one is assigned, or otherwise the Zephyr Technical
		Steering Committee, may allocate other USB Product IDs based on well-motivated
		and documented requests.

		Each USB sample has its own unique Product ID.
		When adding a new sample, add a new entry in :file:`samples/subsys/usb/usb_pid.Kconfig`
		and a Kconfig file inside your sample subdirectory.
		The following Product IDs are currently used:

		* :kconfig:`CONFIG_USB_PID_CDC_ACM_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_CDC_ACM_COMPOSITE_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_HID_CDC_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_CONSOLE_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_DFU_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_HID_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_HID_MOUSE_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_MASS_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_TESTUSB_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_WEBUSB_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_BLE_HCI_H4_SAMPLE`

		USB device controller drivers
		*****************************

		The Device Controller Driver Layer implements the low level control routines
		to deal directly with the hardware. All device controller drivers should
		implement the APIs described in file usb_dc.h. This allows the integration of
		new USB device controllers to be done without changing the upper layers.

		USB Device Controller API
		=========================

		.. doxygengroup:: _usb_device_controller_api

		USB device core layer
		*********************

		The USB Device core layer is a hardware independent interface between USB
		device controller driver and USB device class drivers or customer applications.
		It's a port of the LPCUSB device stack. It provides the following
		functionalities:

		* Responds to standard device requests and returns standard descriptors,
		essentially handling 'Chapter 9' processing, specifically the standard
		device requests in table 9-3 from the universal serial bus specification
		revision 2.0.
		* Provides a programming interface to be used by USB device classes or
		customer applications. The APIs are described in the usb_device.h file.
		* Uses the APIs provided by the device controller drivers to interact with
		the USB device controller.


		USB Device Core Layer API
		=========================

		There are two ways to transmit data, using the 'low' level read/write API or
		the 'high' level transfer API.

		Low level API
		To transmit data to the host, the class driver should call usb_write().
		Upon completion the registered endpoint callback will be called. Before
		sending another packet the class driver should wait for the completion of
		the previous write. When data is received, the registered endpoint callback
		is called. usb_read() should be used for retrieving the received data.
		For CDC ACM sample driver this happens via the OUT bulk endpoint handler
		(cdc_acm_bulk_out) mentioned in the endpoint array (cdc_acm_ep_data).

		High level API
		The usb_transfer method can be used to transfer data to/from the host. The
		transfer API will automatically split the data transmission into one or more
		USB transaction(s), depending endpoint max packet size. The class driver does
		not have to implement endpoint callback and should set this callback to the
		generic usb_transfer_ep_callback.

		.. doxygengroup:: _usb_device_core_api

		USB device class drivers
		************************

		Zephyr USB Device Stack supports many standard classes, such as HID, MSC
		Ethernet over USB, DFU, Bluetooth.

		Implementing non standard USB class
		===================================

		Configuration of USB Device is done in the stack layer.

		The following structures and callbacks need to be defined:

		* Part of USB Descriptor table
		* USB Endpoint configuration table
		* USB Device configuration structure
		* Endpoint callbacks
		* Optionally class, vendor and custom handlers

		For example, for USB loopback application:

		.. literalinclude:: ../../../subsys/usb/class/loopback.c
		:language: c
		:start-after: usb.rst config structure start
		:end-before: usb.rst config structure end
		:linenos:

		Endpoint configuration:

		.. literalinclude:: ../../../subsys/usb/class/loopback.c
		:language: c
		:start-after: usb.rst endpoint configuration start
		:end-before: usb.rst endpoint configuration end
		:linenos:

		USB Device configuration structure:

		.. literalinclude:: ../../../subsys/usb/class/loopback.c
		:language: c
		:start-after: usb.rst device config data start
		:end-before: usb.rst device config data end
		:linenos:


		The vendor device requests are forwarded by the USB stack core driver to the
		class driver through the registered vendor handler.

		For the loopback class driver, :c:func:`loopback_vendor_handler` processes
		the vendor requests:

		.. literalinclude:: ../../../subsys/usb/class/loopback.c
		:language: c
		:start-after: usb.rst vendor handler start
		:end-before: usb.rst vendor handler end
		:linenos:

		The class driver waits for the :makevar:`USB_DC_CONFIGURED` device status code
		before transmitting any data.

		.. _testing_USB_native_posix:

		Testing USB over USP/IP in native_posix
		***************************************

		Virtual USB controller implemented through USB/IP might be used to test USB
		Device stack. Follow general build procedure to build USB sample for
		the native_posix configuration.

		Run built sample with:

		.. code-block:: console

		west build -t run

		In a terminal window, run the following command to list USB devices:

		.. code-block:: console

		$ usbip list -r localhost
		Exportable USB devices
		======================
		- 127.0.0.1
		1-1: unknown vendor : unknown product (2fe3:0100)
		: /sys/devices/pci0000:00/0000:00:01.2/usb1/1-1
		: (Defined at Interface level) (00/00/00)
		: 0 - Vendor Specific Class / unknown subclass / unknown protocol (ff/00/00)

		In a terminal window, run the following command to attach USB device:

		.. code-block:: console

		$ sudo usbip attach -r localhost -b 1-1

		The USB device should be connected to your Linux host, and verified with the following commands:

		.. code-block:: console

		$ sudo usbip port
		Imported USB devices
		====================
		Port 00: <Port in Use> at Full Speed(12Mbps)
		unknown vendor : unknown product (2fe3:0100)
		7-1 -> usbip://localhost:3240/1-1
		-> remote bus/dev 001/002
		$ lsusb -d 2fe3:0100
		Bus 007 Device 004: ID 2fe3:0100

		USB Human Interface Devices (HID) support
		*****************************************

		HID Item helpers
		================

		HID item helper macros can be used to compose a HID Report Descriptor.
		The names correspond to those used in the USB HID Specification.

		Example of a HID Report Descriptor:

		.. code-block:: c

		static const uint8_t hid_report_desc[] = {
		HID_USAGE_PAGE(HID_USAGE_GEN_DESKTOP),
		HID_USAGE(HID_USAGE_GEN_DESKTOP_UNDEFINED),
		HID_COLLECTION(HID_COLLECTION_APPLICATION),
		HID_LOGICAL_MIN8(0),
		/* logical maximum 255 */
		HID_LOGICAL_MAX16(0xFF, 0x00),
		HID_REPORT_ID(1),
		HID_REPORT_SIZE(8),
		HID_REPORT_COUNT(1),
		HID_USAGE(HID_USAGE_GEN_DESKTOP_UNDEFINED),
		/* HID_INPUT (Data, Variable, Absolute) */
		HID_INPUT(0x02),
		HID_END_COLLECTION,
		};


		.. doxygengroup:: usb_hid_items

		.. doxygengroup:: usb_hid_types

		HID Mouse and Keyboard report descriptors
		=========================================

		The pre-defined Mouse and Keyboard report descriptors can be used by
		a HID device implementation or simply as examples.

		.. doxygengroup:: usb_hid_mk_report_desc

		HID Class Device API
		********************

		USB HID devices like mouse, keyboard, or any other specific device use this API.

		.. doxygengroup:: usb_hid_device_api
		udc.rst
		uds.rst
		uds_testing.rst
		hid.rst

doc/reference/usb/udc.rst

0 → 100644

+17 −0

Original line number	Diff line number	Diff line
		.. _udc_api:

		USB device controller driver API
		################################

		The USB Device Controller Driver Layer implements the low level control routines
		to deal directly with the hardware. All device controller drivers should
		implement the APIs described in :zephyr_file:`include/drivers/usb/usb_dc.h`.
		This allows the integration of new USB device controllers to be done without
		changing the upper layers.
		With this API it is not possible to support more than one controller
		instance at runtime.

		API reference
		*************

		.. doxygengroup:: _usb_device_controller_api

doc/reference/usb/uds.rst

0 → 100644

+148 −0

Original line number	Diff line number	Diff line
		.. _usb_device_stack:

		USB device stack
		################

		The USB device stack is a hardware independent interface between USB
		device controller driver and USB device class drivers or customer applications.
		It is a port of the LPCUSB device stack and has been modified and expanded
		over time. It provides the following functionalities:

		* Uses the APIs provided by the device controller drivers to interact with
		the USB device controller.
		* Responds to standard device requests and returns standard descriptors,
		essentially handling 'Chapter 9' processing, specifically the standard
		device requests in table 9-3 from the universal serial bus specification
		revision 2.0.
		* Provides a programming interface to be used by USB device classes or
		customer applications. The APIs is described in
		:zephyr_file:`include/usb/usb_device.h`

		The device stack has few limitations with which it is not possible to support
		more than one controller instance at runtime, and only one USB device
		configuration is supported.

		Supported USB classes:

		* USB Audio (experimental)
		* USB CDC ACM
		* USB CDC ECM
		* USB CDC EEM
		* RNDIS
		* USB MSC
		* USB DFU
		* Bluetooth HCI over USB
		* USB HID class

		:ref:`List<usb-samples>` of samples for different purposes.
		CDC ACM and HID samples have configuration overlays for composite configuration.

		Implementing a non-standard USB class
		*************************************

		The configuration of USB Device is done in the stack layer.

		The following structures and callbacks need to be defined:

		* Part of USB Descriptor table
		* USB Endpoint configuration table
		* USB Device configuration structure
		* Endpoint callbacks
		* Optionally class, vendor and custom handlers

		For example, for the USB loopback application:

		.. literalinclude:: ../../../subsys/usb/class/loopback.c
		:language: c
		:start-after: usb.rst config structure start
		:end-before: usb.rst config structure end
		:linenos:

		Endpoint configuration:

		.. literalinclude:: ../../../subsys/usb/class/loopback.c
		:language: c
		:start-after: usb.rst endpoint configuration start
		:end-before: usb.rst endpoint configuration end
		:linenos:

		USB Device configuration structure:

		.. literalinclude:: ../../../subsys/usb/class/loopback.c
		:language: c
		:start-after: usb.rst device config data start
		:end-before: usb.rst device config data end
		:linenos:


		The vendor device requests are forwarded by the USB stack core driver to the
		class driver through the registered vendor handler.

		For the loopback class driver, :c:func:`loopback_vendor_handler` processes
		the vendor requests:

		.. literalinclude:: ../../../subsys/usb/class/loopback.c
		:language: c
		:start-after: usb.rst vendor handler start
		:end-before: usb.rst vendor handler end
		:linenos:

		The class driver waits for the :makevar:`USB_DC_CONFIGURED` device status code
		before transmitting any data.

		.. _testing_USB_native_posix:

		USB Vendor and Product identifiers
		**********************************

		The USB Vendor ID for the Zephyr project is ``0x2FE3``.
		This USB Vendor ID must not be used when a vendor
		integrates Zephyr USB device support into its own product.

		Each USB sample has its own unique Product ID.
		The USB maintainer, if one is assigned, or otherwise the Zephyr Technical
		Steering Committee, may allocate other USB Product IDs based on well-motivated
		and documented requests.

		When adding a new sample, add a new entry in :file:`samples/subsys/usb/usb_pid.Kconfig`
		and a Kconfig file inside your sample subdirectory.
		The following Product IDs are currently used:

		* :kconfig:`CONFIG_USB_PID_CDC_ACM_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_CDC_ACM_COMPOSITE_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_HID_CDC_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_CONSOLE_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_DFU_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_HID_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_HID_MOUSE_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_MASS_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_TESTUSB_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_WEBUSB_SAMPLE`
		* :kconfig:`CONFIG_USB_PID_BLE_HCI_H4_SAMPLE`

		The USB device descriptor field ``bcdDevice`` (Device Release Number) represents
		the Zephyr kernel major and minor versions as a binary coded decimal value.

		API reference
		*************

		There are two ways to transmit data, using the 'low' level read/write API or
		the 'high' level transfer API.

		Low level API
		To transmit data to the host, the class driver should call usb_write().
		Upon completion the registered endpoint callback will be called. Before
		sending another packet the class driver should wait for the completion of
		the previous write. When data is received, the registered endpoint callback
		is called. usb_read() should be used for retrieving the received data.
		For CDC ACM sample driver this happens via the OUT bulk endpoint handler
		(cdc_acm_bulk_out) mentioned in the endpoint array (cdc_acm_ep_data).

		High level API
		The usb_transfer method can be used to transfer data to/from the host. The
		transfer API will automatically split the data transmission into one or more
		USB transaction(s), depending endpoint max packet size. The class driver does
		not have to implement endpoint callback and should set this callback to the
		generic usb_transfer_ep_callback.

		.. doxygengroup:: _usb_device_core_api

doc/reference/usb/uds_testing.rst

0 → 100644

+50 −0

Original line number	Diff line number	Diff line
		.. _usb_device_testing:

		Testing USB device support
		##########################

		Testing over USPIP in native_posix
		***********************************

		A virtual USB controller implemented through USBIP might be used to test the USB
		Device stack. Follow the general build procedure to build the USB sample for
		the native_posix configuration.

		Run built sample with:

		.. code-block:: console

		west build -t run

		In a terminal window, run the following command to list USB devices:

		.. code-block:: console

		$ usbip list -r localhost
		Exportable USB devices
		======================
		- 127.0.0.1
		1-1: unknown vendor : unknown product (2fe3:0100)
		: /sys/devices/pci0000:00/0000:00:01.2/usb1/1-1
		: (Defined at Interface level) (00/00/00)
		: 0 - Vendor Specific Class / unknown subclass / unknown protocol (ff/00/00)

		In a terminal window, run the following command to attach the USB device:

		.. code-block:: console

		$ sudo usbip attach -r localhost -b 1-1

		The USB device should be connected to your Linux host, and verified with the following commands:

		.. code-block:: console

		$ sudo usbip port
		Imported USB devices
		====================
		Port 00: <Port in Use> at Full Speed(12Mbps)
		unknown vendor : unknown product (2fe3:0100)
		7-1 -> usbip://localhost:3240/1-1
		-> remote bus/dev 001/002
		$ lsusb -d 2fe3:0100
		Bus 007 Device 004: ID 2fe3:0100

Admin message