applications: nrf_desktop: Add HID reportq documentation

Change introduces documentation for the HID report queue utility.

Jira: NCSDK-28433

Signed-off-by: Marek Pieta <[email protected]>

applications/nrf_desktop/doc/hid_reportq.rst

@@ -0,0 +1,78 @@
+.. _nrf_desktop_hid_reportq:
+
+HID report queue utility
+########################
+
+.. contents::
+   :local:
+   :depth: 2
+
+A HID subscriber (for example an USB HID class instance handled by :ref:`nrf_desktop_usb_state`) limits maximum number of HID input reports that can be handled simultaneously.
+Enqueuing reports locally at the source may be necessary to prevent HID report drops.
+The HID report queue utility can be used by an application module to simplify enqueuing HID input reports received from connected HID peripherals before providing them to HID subscriber.
+
+Configuration
+*************
+
+Make sure that heap size (:kconfig:option:`CONFIG_HEAP_MEM_POOL_SIZE`) is big enough.
+Data structures used to enqueue HID reports are dynamically allocated using :c:func:`k_malloc`.
+When no longer needed, the structured are freed using :c:func:`k_free`.
+
+Use the :ref:`CONFIG_DESKTOP_HID_REPORTQ <config_desktop_app_options>` Kconfig option to enable the utility.
+The utility can be used only on HID dongles (:ref:`CONFIG_DESKTOP_ROLE_HID_DONGLE <config_desktop_app_options>`).
+
+You can also configure the following properties:
+
+* Maximum number of enqueued HID reports (:ref:`CONFIG_DESKTOP_HID_REPORTQ_MAX_ENQUEUED_REPORTS <config_desktop_app_options>`)
+* Number of supported HID report queues (:ref:`CONFIG_DESKTOP_HID_REPORTQ_QUEUE_COUNT <config_desktop_app_options>`)
+
+See Kconfig help for more details.
+
+Using HID report queue
+**********************
+
+The utility acts as a middleware between a connected HID peripheral and a HID subscriber.
+The following sections describe how to integrate HID report queue APIs in an application module.
+
+The :ref:`nrf_desktop_hid_forward` is an example of application module that uses the HID report queue utility.
+Refer to the module's implementation (:file:`src/modules/hid_forward.c`) for an example of HID report queue integration.
+
+Allocation
+==========
+
+HID report queue instance must be allocated with :c:func:`hid_reportq_alloc` before it's used.
+A separate HID report queue object needs to be allocated per HID report subscriber.
+During allocation, the caller specifies the HID subscriber identifier.
+The :c:func:`hid_reportq_get_sub_id` can be used to access the identifier later.
+After the HID report queue object is no longer used, it should be freed with :c:func:`hid_reportq_free`.
+
+HID subscriptions
+=================
+
+A HID report queue instance tracks HID input report subscriptions enabled by a HID subscriber.
+The :c:func:`hid_reportq_subscribe` and :c:func:`hid_reportq_unsubscribe` functions can be used to update state of enabled subscriptions.
+The functions should be called while handling an :c:struct:`hid_report_subscription_event`.
+The :c:func:`hid_reportq_is_subscribed` function can be used to check if subscription is enabled for the specified HID input report.
+
+Enqueuing HID input reports
+===========================
+
+An application module can call :c:func:`hid_reportq_report_add` for a received HID input report to enqueue the report.
+The function allocates a :c:struct:`hid_report_event` for the received HID input report.
+If HID subscriber can handle the :c:struct:`hid_report_event`, the event is instantly passed to the subscriber.
+Otherwise the event is enqueued and will be submitted later.
+
+When HID subscriber (for example an USB HID class instance) delivers a HID input report to the HID host (on :c:struct:`hid_report_sent_event`), the :c:struct:`hid_reportq_report_sent` API needs to be called to notify the HID report queue.
+This allows the queue to track state of HID reports provided to the HID subscriber.
+If there is an enqueued report, the HID report queue object will instantly submit the subsequent :c:struct:`hid_report_event`.
+The enqueued report to be sent is chosen in the round-robin fashion.
+
+API documentation
+*****************
+
+Application modules can use the following API of the HID report queue:
+
+| Header file: :file:`applications/nrf_desktop/src/util/hid_reportq.h`
+| Source file: :file:`applications/nrf_desktop/src/util/hid_reportq.c`
+
+.. doxygengroup:: hid_reportq

applications/nrf_desktop/modules.rst

@@ -49,6 +49,7 @@ These are valid for events that have many listeners or sources, and are gathered
    doc/fn_keys.rst
    doc/bas.rst
    doc/hid_forward.rst
+   doc/hid_reportq.rst
    doc/hid_state.rst
    doc/hid_state_pm.rst
    doc/hids.rst

applications/nrf_desktop/src/util/hid_reportq.h

@@ -58,6 +58,12 @@ const void *hid_reportq_get_sub_id(struct hid_reportq *q);
 /**
  * @brief Add a HID report to the queue.
  *
+ * The function returns an error if HID report subscription is disabled for the added HID report.
+ *
+ * If number of enqueued reports with a given report ID exceeds limit defined by the configuration
+ * (@kconfig{CONFIG_DESKTOP_HID_REPORTQ_MAX_ENQUEUED_REPORTS}), the oldest enqueued HID report with the ID
+ * is dropped.
+ *
  * @param[in] q		Pointer to the queue instance.
  * @param[in] src_id    ID of HID report source.
  * @param[in] rep_id	HID report ID.
@@ -99,6 +105,9 @@ void hid_reportq_subscribe(struct hid_reportq *q, uint8_t rep_id);
 /**
  * @brief Unsubscribe from HID report with given ID.
  *
+ * Disabling subscription for a given HID report ID, drops all of the enqueued HID reports related
+ * to the ID.
+ *
  * @param[in] q		Pointer to the queue instance.
  * @param[in] rep_id	HID report ID.
  */

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

@@ -202,7 +202,8 @@ nRF5340 Audio
 nRF Desktop
 -----------
 
-|no_changes_yet_note|
+* Added :ref:`nrf_desktop_hid_reporq`.
+  The utility can be used by an application module to simplify enqueuing HID input reports received from connected HID peripherals before providing them to HID subscriber.
 
 nRF Machine Learning (Edge Impulse)
 -----------------------------------