doc: add class docscodex/class-reference-docs

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

1 files changed, 142 insertions, 0 deletions

diff --git a/docs/reference/class/host.rst b/docs/reference/class/host.rst
new file mode 100644
index 000000000..ef42e3dfb
--- /dev/null
+++ b/docs/reference/class/host.rst
@@ -0,0 +1,142 @@
+******************
+Using Host Classes
+******************
+
+TinyUSB provides application-level host drivers for CDC serial, HID, MIDI 1.0,
+MIDI 2.0, and Mass Storage.  A host application is asynchronous: a mount
+callback reports a ready interface, I/O is queued, and completion or receive
+callbacks advance the application state.
+
+Setup checklist
+===============
+
+1. Enable ``CFG_TUH_ENABLED`` and set each ``CFG_TUH_*`` pool size in
+   ``tusb_config.h``.  HID and MIDI values count interfaces, so allow for more
+   than one interface per physical device.
+2. Set ``CFG_TUH_DEVICE_MAX`` for the number of attached devices and enable
+   ``CFG_TUH_HUB`` if hubs are required.
+3. Initialize a host-capable root port and provide VBUS as required by the
+   board.
+4. Call ``tuh_task()`` continuously, or run it in a dedicated RTOS task.
+5. Start class I/O from its mount callback and requeue receive transfers where
+   the class guide requires it.
+
+Typical configuration:
+
+.. code-block:: c
+
+   #define CFG_TUH_ENABLED    1
+   #define CFG_TUH_DEVICE_MAX 4
+   #define CFG_TUH_HUB        1
+   #define CFG_TUH_CDC        1
+   #define CFG_TUH_HID        (3 * CFG_TUH_DEVICE_MAX)
+   #define CFG_TUH_MSC        1
+
+Common configuration options
+============================
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 18 52
+
+   * - Option
+     - Default
+     - What it controls
+   * - ``CFG_TUH_ENABLED``
+     - Root-port mode
+     - Enables the host stack.  The board must also supply VBUS and a
+       host-capable controller/PHY.
+   * - ``CFG_TUH_MAX_SPEED``
+     - Root-port mode
+     - Highest bus speed supported by the host build.  It does not make a
+       full-speed-only controller operate at high speed.
+   * - ``CFG_TUH_DEVICE_MAX``
+     - ``1``
+     - Number of USB device addresses tracked simultaneously, including hubs.
+   * - ``CFG_TUH_HUB``
+     - ``0``
+     - Number of hubs supported simultaneously.  Hub ports can require higher
+       device and class pool counts.
+   * - ``CFG_TUH_ENUMERATION_BUFSIZE``
+     - ``256`` bytes
+     - Temporary descriptor buffer used during enumeration.  Increase it for
+       long configuration or HID report descriptors; this consumes static RAM.
+   * - ``CFG_TUH_TASK_EVENTS_PER_RUN``
+     - ``16``
+     - Maximum events handled by one ``tuh_task_ext()`` call.  ``0`` is
+       unlimited.
+   * - ``CFG_TUH_MEM_SECTION`` / ``CFG_TUH_MEM_ALIGN``
+     - Common USB settings / 4-byte alignment
+     - Places and aligns host-controller buffers for DMA-accessible RAM.
+   * - ``CFG_TUSB_OS``
+     - ``OPT_OS_NONE``
+     - Selects TinyUSB's synchronization backend.  Set the matching OS option
+       when host APIs and ``tuh_task()`` run in different RTOS tasks.
+
+Each ``CFG_TUH_<CLASS>`` value sizes a simultaneous interface pool.  It is not
+a VID/PID allowlist and, for composite devices, may need to exceed
+``CFG_TUH_DEVICE_MAX``.
+
+Core API and callbacks
+======================
+
+.. list-table::
+   :header-rows: 1
+   :widths: 36 64
+
+   * - API or callback
+     - What it does
+   * - ``tusb_init()``
+     - Initializes a root port with host role and selected speed.  Call it
+       after board/VBUS setup and check its boolean result.
+   * - ``tuh_task()`` / ``tuh_task_ext()``
+     - Advances enumeration and transfers and dispatches callbacks.  The
+       extended form controls wait timeout and ISR context.
+   * - ``tuh_mount_cb()`` / ``tuh_umount_cb()``
+     - Announces a configured device or detachment.  Class mount callbacks
+       provide the interface-specific indices used for I/O.
+   * - ``tuh_mounted()`` / ``tuh_ready()`` / ``tuh_connected()``
+     - Tests whether an address is configured/ready or has merely shown bus
+       activity.  Do not start class I/O based only on ``tuh_connected()``.
+   * - ``tuh_vid_pid_get()`` / ``tuh_speed_get()`` / ``tuh_bus_info_get()``
+     - Returns cached identity, speed, and hub/root-port location for an
+       enumerated address.
+   * - ``tuh_descriptor_get_device_local()``
+     - Copies the cached device descriptor without issuing a USB transfer.
+       Other ``tuh_descriptor_get_*()`` calls queue or perform control
+       transfers to fetch descriptors.
+   * - ``tuh_control_xfer()``
+     - Submits a control transfer described by ``tuh_xfer_t``.  A non-null
+       completion callback makes it asynchronous; a null callback blocks.
+   * - ``tuh_edpt_xfer()``
+     - Submits a bulk or interrupt endpoint transfer.  Application class
+       drivers normally use their class-specific wrappers instead.
+
+Synchronous host control calls are forbidden from the host task when
+``CFG_TUSB_OS_HAS_SCHEDULER`` is true: that task is needed to make the same
+transfer complete.  Prefer callbacks for portable application code.
+
+Addresses and indices
+=====================
+
+``dev_addr`` identifies an enumerated USB device.  Classes that may expose
+multiple interfaces also use a class ``idx``.  Preserve both values supplied by
+the mount callback and use the same pair for later API calls.  An index can be
+reused after unmount, so discard associated application state in the unmount
+callback.
+
+Transfer lifetime
+=================
+
+Unless an API explicitly documents a copy, keep a transfer buffer valid and
+unchanged until its completion callback.  Buffers used directly by a host
+controller may also require alignment, cache maintenance, or placement in
+DMA-accessible memory; follow the board's HCD requirements.
+
+Do not block ``tuh_task()`` while waiting for a callback that only it can
+dispatch.  Prefer the asynchronous APIs.  Where a class provides a synchronous
+helper, use it only from a context in which the host task can still run.
+
+Start with :doc:`../../examples/host/cdc_msc_hid` for CDC, HID, and MSC,
+:doc:`../../examples/host/midi_rx` for MIDI 1.0, or
+:doc:`../../examples/host/midi2_host` for MIDI 2.0.