doc: move USB documentation to connectivity

Mostly moved and reorganised content to the Connectivity chapter, separated API references. Fill in some gaps in the USB device documentation. Signed-off-by: Johann Fischer <johann.fischer@nordicsemi.no>
Willmish · Jun 15, 2023 · b335c19 · b335c19
1 parent 09a9a7e
commit b335c19
Show file tree

Hide file tree

Showing 24 changed files with 748 additions and 473 deletions.
diff --git a/MAINTAINERS.yml b/MAINTAINERS.yml
@@ -2619,7 +2619,7 @@ USB:
     - subsys/usb/
     - tests/subsys/usb/
     - tests/drivers/udc/
-    - doc/services/usb/
+    - doc/connectivity/usb/
   labels:
     - "area: USB"
 

diff --git a/doc/connectivity/index.rst b/doc/connectivity/index.rst
@@ -9,4 +9,5 @@ Connectivity
    bluetooth/index.rst
    networking/index.rst
    lora_lorawan/index.rst
+   usb/index.rst
    usb_c/index.rst
diff --git a/doc/connectivity/usb/api/hid.rst b/doc/connectivity/usb/api/hid.rst
@@ -0,0 +1,25 @@
+.. _usb_hid_common:
+
+Human Interface Devices (HID)
+#############################
+
+Common USB HID part that can be used outside of USB support, defined in
+header file :zephyr_file:`include/zephyr/usb/class/hid.h`.
+
+HID types reference
+*******************
+
+.. doxygengroup:: usb_hid_definitions
+
+HID items reference
+*******************
+
+.. doxygengroup:: usb_hid_items
+
+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
diff --git a/doc/connectivity/usb/device/api/index.rst b/doc/connectivity/usb/device/api/index.rst
@@ -0,0 +1,11 @@
+.. _usb_api:
+
+USB device support APIs
+#######################
+
+.. toctree::
+   :maxdepth: 1
+
+   usb_dc.rst
+   usb_device.rst
+   usb_device_hid.rst
diff --git a/doc/connectivity/usb/device/api/usb_dc.rst b/doc/connectivity/usb/device/api/usb_dc.rst
@@ -0,0 +1,16 @@
+.. _usb_dc_api:
+
+USB device controller driver API
+################################
+
+The USB device controller driver API is described in
+:zephyr_file:`include/zephyr/drivers/usb/usb_dc.h` and sometimes referred to
+as the ``usb_dc`` API.
+
+This API has some limitations by design, it does not follow :ref:`device_model_api`
+and is being replaced by a new UDC driver API.
+
+API reference
+*************
+
+.. doxygengroup:: _usb_device_controller_api
diff --git a/doc/connectivity/usb/device/api/usb_device.rst b/doc/connectivity/usb/device/api/usb_device.rst
@@ -0,0 +1,28 @@
+.. _usb_device_stack_api:
+
+USB device stack API
+####################
+
+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
diff --git a/doc/connectivity/usb/device/api/usb_device_hid.rst b/doc/connectivity/usb/device/api/usb_device_hid.rst
@@ -0,0 +1,12 @@
+.. _usb_hid_device:
+
+USB HID Class API
+#################
+
+USB device specific part for HID support defined in
+:zephyr_file:`include/zephyr/usb/class/usb_hid.h`.
+
+API Reference
+*************
+
+.. doxygengroup:: usb_hid_device_api