doc: add class docscodex/class-reference-docs

Signed-off-by: HiFiPhile <[email protected]>

1 files changed, 168 insertions, 0 deletions

diff --git a/docs/reference/class/hid.rst b/docs/reference/class/hid.rst
new file mode 100644
index 000000000..567bc54e0
--- /dev/null
+++ b/docs/reference/class/hid.rst
@@ -0,0 +1,168 @@
+***
+HID
+***
+
+Roles: device and host.  Human Interface Device (HID) transfers input, output,
+and feature reports described by a compact HID report descriptor.
+
+Device
+======
+
+Enable ``CFG_TUD_HID`` for the required number of HID interfaces and set
+``CFG_TUD_HID_EP_BUFSIZE`` to the largest report transferred on an interrupt
+endpoint.  Use ``TUD_HID_DESCRIPTOR`` for IN-only HID or
+``TUD_HID_INOUT_DESCRIPTOR`` when an interrupt OUT endpoint is required.
+
+``CFG_TUD_HID_EP_BUFSIZE`` defaults to 64 bytes and allocates one endpoint
+buffer per enabled HID instance.  It must include the report ID byte when the
+report descriptor uses IDs.  Increasing it permits longer reports but consumes
+static RAM; it does not change the report descriptor automatically.
+
+Define a report descriptor and return it from
+``tud_hid_descriptor_report_cb()``.  TinyUSB provides templates including
+``TUD_HID_REPORT_DESC_KEYBOARD()``, ``TUD_HID_REPORT_DESC_MOUSE()``, and
+``TUD_HID_REPORT_DESC_GENERIC_INOUT()``.  When several report types share one
+interface, give each a distinct ``HID_REPORT_ID()`` and include that ID in API
+calls and report handling.
+
+Send only when the interface is ready:
+
+.. code-block:: c
+
+   if (tud_hid_ready()) {
+     tud_hid_keyboard_report(REPORT_ID_KEYBOARD, modifier, keycodes);
+   }
+
+Use ``tud_hid_report()`` for a custom layout.  Handle host-to-device output or
+feature reports in ``tud_hid_set_report_cb()`` and provide requested input or
+feature data in ``tud_hid_get_report_cb()``.  The bytes and lengths must match
+the report descriptor exactly.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - Device API or callback
+     - What it does
+   * - ``tud_hid_n_ready()``
+     - Tests whether the interrupt IN endpoint for an instance can accept a
+       report.
+   * - ``tud_hid_n_report()``
+     - Copies and queues a custom input report.  ``false`` means it was not
+       queued; the caller may reuse its source buffer after the call returns.
+   * - ``tud_hid_n_keyboard_report()`` /
+       ``tud_hid_n_mouse_report()`` /
+       ``tud_hid_n_gamepad_report()``
+     - Builds and queues a standard TinyUSB report structure.  Its descriptor
+       template must match the chosen helper.
+   * - ``tud_hid_descriptor_report_cb()``
+     - Returns the report descriptor for an instance.  The returned storage
+       must remain valid.
+   * - ``tud_hid_get_report_cb()``
+     - Fills a control GET_REPORT response and returns its byte count.  Returning
+       zero stalls the request.
+   * - ``tud_hid_set_report_cb()``
+     - Receives an output or feature report from either the control endpoint or
+       interrupt OUT endpoint.
+   * - ``tud_hid_set_protocol_cb()`` / ``tud_hid_set_idle_cb()``
+     - Applies host boot/report protocol and idle-rate requests.  HID idle rate
+       units are 4 ms.
+   * - ``tud_hid_report_complete_cb()`` /
+       ``tud_hid_report_failed_cb()``
+     - Announces that the internal endpoint buffer is reusable, or reports the
+       number of bytes transferred before failure.
+
+For keyboards and buttons, send a release report as well as the press report;
+otherwise the host can retain a stuck key.  The
+:doc:`../../examples/device/hid_composite` and
+:doc:`../../examples/device/hid_generic_inout` examples show both patterns.
+
+Host
+====
+
+Set ``CFG_TUH_HID`` to the maximum simultaneous HID interfaces, not merely the
+number of physical devices.  A keyboard with media controls or a composite
+controller can expose several interfaces.  Size
+``CFG_TUH_HID_EPIN_BUFSIZE`` and ``CFG_TUH_HID_EPOUT_BUFSIZE`` for the largest
+reports the application accepts.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 39 17 44
+
+   * - Option
+     - Default
+     - What it controls
+   * - ``CFG_TUH_HID_EPIN_BUFSIZE``
+     - ``64`` bytes
+     - Largest interrupt IN report that can be received per HID instance.
+   * - ``CFG_TUH_HID_EPOUT_BUFSIZE``
+     - ``64`` bytes
+     - Largest interrupt OUT report that can be sent per HID instance.
+   * - ``CFG_TUH_HID_SET_PROTOCOL_ON_ENUM``
+     - ``1``
+     - Sends SET_PROTOCOL during enumeration for boot-capable interfaces.
+       Set it to ``0`` if the application will select protocol later.
+
+``tuh_hid_mount_cb()`` supplies ``dev_addr``, interface ``idx``, and the report
+descriptor.  Parse and retain the information needed to decode later reports,
+then queue the first receive:
+
+.. code-block:: c
+
+   void tuh_hid_mount_cb(uint8_t dev_addr, uint8_t idx,
+                         uint8_t const *desc, uint16_t desc_len) {
+     parse_report_descriptor(desc, desc_len);
+     tuh_hid_receive_report(dev_addr, idx);
+   }
+
+   void tuh_hid_report_received_cb(uint8_t dev_addr, uint8_t idx,
+                                   uint8_t const *report, uint16_t len) {
+     process_report(report, len);
+     tuh_hid_receive_report(dev_addr, idx); // Re-arm interrupt IN.
+   }
+
+If a report descriptor is larger than ``CFG_TUH_ENUMERATION_BUFSIZE``, the
+mount callback can receive ``desc == NULL`` and ``desc_len == 0``.  Increase
+the enumeration buffer or handle that case without dereferencing the pointer.
+
+Use ``tuh_hid_send_report()`` for an interrupt OUT report and
+``tuh_hid_get_report()``/``tuh_hid_set_report()`` for control transfers.  Boot
+keyboards and mice can use boot protocol; all other devices require report
+protocol and parsing of their descriptor.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - Host API or callback
+     - What it does
+   * - ``tuh_hid_mounted()`` / ``tuh_hid_itf_get_info()``
+     - Tests a device/interface pair and retrieves its cached interface
+       descriptor information.
+   * - ``tuh_hid_interface_protocol()`` / ``tuh_hid_get_protocol()``
+     - Distinguishes keyboard/mouse/none interface protocol from the active
+       boot/report transfer protocol.
+   * - ``tuh_hid_receive_ready()`` / ``tuh_hid_receive_report()``
+     - Tests and arms one interrupt IN transfer.  Re-arm it after every receive
+       callback for continuous input.
+   * - ``tuh_hid_send_ready()`` / ``tuh_hid_send_report()``
+     - Tests and queues one interrupt OUT report.  The send callback releases
+       the internal endpoint buffer; the source is copied before return.
+   * - ``tuh_hid_get_report()`` / ``tuh_hid_set_report()``
+     - Starts a control endpoint report request.  Completion callbacks report
+       zero length on a stall or transfer error; keep the caller's report
+       buffer valid until that callback.
+   * - ``tuh_hid_set_protocol()``
+     - Requests boot or report protocol on boot-capable interfaces; completion
+       is reported asynchronously.
+   * - ``tuh_hid_mount_cb()`` / ``tuh_hid_umount_cb()``
+     - Supplies the report descriptor at mount and announces when the interface
+       index is no longer valid.
+
+See :doc:`../../examples/host/cdc_msc_hid` for keyboard/mouse handling and
+:doc:`../../examples/host/hid_controller` for controller input and output.
+
+Specification used: *Device Class Definition for Human Interface Devices
+(HID)*, Version 1.11.  HID Usage Tables define the individual usage pages and
+codes used inside report descriptors.