doc: add class docscodex/class-reference-docs

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

1 files changed, 131 insertions, 0 deletions

diff --git a/docs/reference/class/audio.rst b/docs/reference/class/audio.rst
new file mode 100644
index 000000000..6e86dff8c
--- /dev/null
+++ b/docs/reference/class/audio.rst
@@ -0,0 +1,131 @@
+*****
+Audio
+*****
+
+Role: device only.  TinyUSB supports USB Audio Class 1.0 and 2.0 streaming.
+The descriptors define the topology, formats, channels, rates, controls, and
+alternate settings; the application supplies or consumes the audio samples.
+
+Start from an example
+=====================
+
+Audio descriptors and buffer sizes are tightly coupled.  Copy the closest
+example, confirm that it enumerates, and then change one property at a time:
+
+* :doc:`../../examples/device/audio_test` -- one-channel UAC2 microphone;
+* :doc:`../../examples/device/audio_4_channel_mic` -- four-channel microphone;
+* :doc:`../../examples/device/uac2_speaker_fb` -- speaker with feedback;
+* :doc:`../../examples/device/uac2_headset` -- bidirectional headset;
+* :doc:`../../examples/device/audio_test_multi_rate` -- UAC1 at full speed,
+  UAC2 at high speed, with multiple rates.
+
+Configuration
+=============
+
+Set ``CFG_TUD_AUDIO`` to the number of audio functions.  The principal options
+are:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 37 16 47
+
+   * - Option
+     - Default
+     - What it controls
+   * - ``CFG_TUD_AUDIO_CTRL_BUF_SZ``
+     - ``64`` bytes
+     - Largest class control payload, such as a RANGE or channel-cluster
+       response.  Increase it to fit the largest advertised control.
+   * - ``CFG_TUD_AUDIO_ENABLE_EP_IN``
+     - ``0``
+     - Enables microphone/device-to-host streaming.
+   * - ``CFG_TUD_AUDIO_ENABLE_EP_OUT``
+     - ``0``
+     - Enables speaker/host-to-device streaming.
+   * - ``CFG_TUD_AUDIO_FUNC_n_EP_IN_SZ_MAX`` /
+       ``CFG_TUD_AUDIO_FUNC_n_EP_OUT_SZ_MAX``
+     - Required per enabled direction
+     - Maximum endpoint packet size across that function's alternate settings.
+   * - ``CFG_TUD_AUDIO_FUNC_n_EP_IN_SW_BUF_SZ`` /
+       ``CFG_TUD_AUDIO_FUNC_n_EP_OUT_SW_BUF_SZ``
+     - ``0``
+     - Software FIFO size.  Set it to at least the corresponding maximum
+       endpoint size when using the FIFO APIs.
+   * - ``CFG_TUD_AUDIO_EP_IN_FLOW_CONTROL``
+     - ``1``
+     - Adapts IN packet consumption to the FIFO fill level to reduce
+       underruns/overruns.
+   * - ``CFG_TUD_AUDIO_ENABLE_FEEDBACK_EP``
+     - ``0``
+     - Enables an explicit feedback endpoint, normally required by an
+       asynchronous speaker.
+   * - ``CFG_TUD_AUDIO_ENABLE_INTERRUPT_EP``
+     - ``0``
+     - Enables the AudioControl interrupt endpoint for status notifications.
+
+For each enabled direction, define the maximum endpoint size used by any
+advertised alternate setting, for example
+``CFG_TUD_AUDIO_FUNC_1_EP_IN_SZ_MAX``.  A software FIFO such as
+``CFG_TUD_AUDIO_FUNC_1_EP_IN_SW_BUF_SZ`` must be at least that large.  Use
+``TUD_AUDIO_EP_SIZE()`` as the examples do; high-speed audio has more service
+intervals per millisecond than full-speed audio.
+
+Data path
+=========
+
+.. list-table::
+   :header-rows: 1
+   :widths: 34 66
+
+   * - Operation
+     - Main API
+   * - ``tud_audio_mounted()`` / ``tud_audio_version()``
+     - Tests whether function zero is configured and returns its negotiated
+       Audio Class version.
+   * - ``tud_audio_available()`` / ``tud_audio_read()``
+     - Reports and removes speaker bytes from the OUT software FIFO.  The read
+       count can be shorter than requested.
+   * - ``tud_audio_write()``
+     - Copies microphone bytes into the IN software FIFO and returns the number
+       accepted.
+   * - ``tud_audio_clear_ep_*_ff()``
+     - Discards queued samples in the selected endpoint FIFO, useful when a
+       streaming alternate setting closes.
+   * - ``tud_audio_get_ep_*_ff()``
+     - Returns the underlying FIFO object for advanced zero-copy or DMA
+       integration; the application must preserve its invariants.
+   * - ``tud_audio_n_fb_set()``
+     - Supplies the feedback value for one audio function when application
+       feedback mode is used.  Pass 16.16 samples per frame; TinyUSB converts
+       it to full-speed 10.14 format when required.
+   * - ``tud_audio_feedback_update()``
+     - Updates internally calculated feedback from elapsed master-clock cycles
+       and returns the current 16.16 value, or zero on error.
+   * - ``tud_audio_n_*()``
+     - Selects a function explicitly with ``func_id``; helpers without ``n``
+       operate on function zero.
+
+The host starts and stops a stream by selecting interface alternate settings.
+Use ``tud_audio_set_itf_cb()`` and ``tud_audio_set_itf_close_ep_cb()`` to start
+or stop the application-side I2S/DMA path.  Do not produce or consume samples
+merely because the device is mounted; wait until the streaming interface is
+active.
+
+Control requests
+================
+
+Implement the ``tud_audio_get_req_*_cb()`` and ``tud_audio_set_req_*_cb()``
+callbacks for every control advertised by the descriptors, such as clock
+frequency, clock validity, mute, and volume.  A descriptor that advertises a
+control but stalls its normal requests is likely to be rejected or behave
+poorly on a host.
+
+Asynchronous speakers normally need a feedback endpoint.  Enable
+``CFG_TUD_AUDIO_ENABLE_FEEDBACK_EP`` and either configure the feedback method
+through ``tud_audio_feedback_params_cb()`` or provide feedback with
+``tud_audio_n_fb_set()``.  Begin with the speaker-feedback example; incorrect
+feedback causes periodic underruns or overruns even when the nominal sample
+rates match.
+
+Specifications used: *USB Device Class Definition for Audio Devices*, Release
+1.0 and Release 2.0, plus *Audio Data Formats*, Release 2.0.