add audio host class doc Signed-off-by: HiFiPHile <admin@hifiphile.com>
diff --git a/docs/reference/class/audio.rst b/docs/reference/class/audio.rst index 6e86dff..9a74223 100644 --- a/docs/reference/class/audio.rst +++ b/docs/reference/class/audio.rst
@@ -2,12 +2,17 @@ Audio ***** -Role: device only. TinyUSB supports USB Audio Class 1.0 and 2.0 streaming. +TinyUSB supports USB Audio Class 1.0 and 2.0 streaming in device and host +roles. + +Device driver +============= + 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: @@ -20,7 +25,7 @@ UAC2 at high speed, with multiple rates. Configuration -============= +------------- Set ``CFG_TUD_AUDIO`` to the number of audio functions. The principal options are: @@ -71,7 +76,7 @@ intervals per millisecond than full-speed audio. Data path -========= +--------- .. list-table:: :header-rows: 1 @@ -112,7 +117,7 @@ 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 @@ -129,3 +134,147 @@ Specifications used: *USB Device Class Definition for Audio Devices*, Release 1.0 and Release 2.0, plus *Audio Data Formats*, Release 2.0. + +Host driver +=========== + +The host driver discovers one playback stream and one capture stream in each +supported AudioControl function. It presents each usable alternate setting +and discrete sample rate as a complete ``format``, ``sample_rate``, and +``channels`` configuration. The application selects one of these tuples; +TinyUSB manages interface alternate settings, endpoints, packet sizing, and +explicit feedback. + +Start from :doc:`../../examples/host/audio_host`. It discovers configurations, +selects signed 16-bit capture and playback streams, and cycles through +microphone, speaker, and loopback operation. + +Configuration +------------- + +Set ``CFG_TUH_AUDIO`` to enable the driver. The principal options are: + +.. list-table:: + :header-rows: 1 + :widths: 36 18 46 + + * - Option + - Default + - What it controls + * - ``CFG_TUH_AUDIO`` + - ``0`` + - Enables the Audio host class. A nonzero value includes the driver. + * - ``CFG_TUH_AUDIO_PROTOCOLS`` + - UAC1 + - Bitmask of ``TUH_AUDIO_PROTOCOL_UAC1`` and + ``TUH_AUDIO_PROTOCOL_UAC2``. Combine them to accept both versions. + * - ``CFG_TUH_AUDIO_MAX`` + - ``1`` + - Maximum number of mounted AudioControl functions. + * - ``CFG_TUH_AUDIO_MAX_AS`` + - ``4`` + - Maximum number of nonzero-bandwidth alternate settings retained per + logical stream. + * - ``CFG_TUH_AUDIO_MAX_SAM_FREQ`` + - ``5`` + - Maximum discrete sample rates retained per UAC1 alternate setting or + UAC2 Clock Source. + * - ``CFG_TUH_AUDIO_EPIN_BUFSIZE`` / + ``CFG_TUH_AUDIO_EPOUT_BUFSIZE`` + - ``256`` bytes + - Largest capture/playback packet the driver can submit. A configuration + whose packet for one polling interval is larger is rejected. + * - ``CFG_TUH_AUDIO_STREAM_BUFSIZE`` + - ``1024`` bytes + - Per-stream FIFO depth. Playback sends silence when a complete packet + is unavailable; capture overwrites the oldest complete frames when the + FIFO is full. + +Increase the endpoint buffers for high channel counts, sample rates, or sample +widths. All buffers are statically allocated, so these maxima directly affect +RAM use. + +Stream lifecycle +---------------- + +After ``tuh_audio_mount_cb()``, enumerate stream indices from zero through +``tuh_audio_stream_count() - 1``. Use ``tuh_audio_stream_direction()`` to +distinguish ``TUH_AUDIO_STREAM_PLAYBACK`` (host to device) from +``TUH_AUDIO_STREAM_CAPTURE`` (device to host). Then enumerate the stream's +configurations with ``tuh_audio_config_count()`` and +``tuh_audio_config_get()``. + +For each stream: + +1. Call ``tuh_audio_configure()`` with a supported configuration index while + the stream is stopped. +2. Call ``tuh_audio_start()``. A ``true`` return means that startup was + submitted, not that it completed. +3. Wait for ``TUH_AUDIO_EVENT_START_COMPLETE`` in ``tuh_audio_event_cb()`` and + check that its transfer result is successful before handling samples. +4. Use the non-blocking frame FIFO APIs while the stream runs. +5. Call ``tuh_audio_stop()`` and wait for + ``TUH_AUDIO_EVENT_STOP_COMPLETE`` before reconfiguring the stream. + +Capture and playback streams in the same AudioControl function must use the +same sample rate while they run concurrently. ``tuh_audio_active_config()`` +returns ``TUSB_INDEX_INVALID_8`` when no configuration is selected. + +Audio data is counted in frames, not bytes. One frame contains one sample for +every channel; obtain its byte size with ``tuh_audio_config_frame_size()``. +``tuh_audio_read()`` removes whole frames from a capture FIFO, while +``tuh_audio_write()`` queues whole frames for playback. Their return values +may be shorter than requested. Use ``tuh_audio_read_available()`` and +``tuh_audio_write_available()`` to service the FIFOs from the application task; +the transfer callbacks are notifications and need not drive FIFO servicing. + +Callbacks and failures +---------------------- + +``tuh_audio_descriptor_cb()`` runs during enumeration, before the mount +callback. Its descriptor pointers are valid only during the call. Copy any +entity IDs or descriptor fields needed for later raw controls, but do not +submit control transfers from this callback. + +``tuh_audio_capture_cb()`` and ``tuh_audio_playback_cb()`` report successful +isochronous transfers. ``tuh_audio_event_cb()`` reports asynchronous start and +stop completion and ``TUH_AUDIO_EVENT_XFER_FAILED``. A failed stream has been +stopped; the application may reconfigure or restart it. Clear all saved +indices and associated state in ``tuh_audio_umount_cb()`` because an index may +be reused by a later device. + +Run ``tuh_task()`` continuously. Isochronous transfers follow the endpoint's +polling interval, and delaying the host task can exhaust the FIFO even when its +average producer and consumer rates match. + +Feature Unit controls +--------------------- + +The driver discovers master mute and volume capabilities before the mount +callback. Test mute with ``tuh_audio_mute_supported()`` and retrieve the +cached volume range with ``tuh_audio_volume_range_get()``. Volume values use +signed 1/256 dB units; ``TUH_AUDIO_VOLUME_SILENCE`` represents silence, and +``TUH_AUDIO_CHANNEL_MASTER`` selects the master channel. + +The asynchronous ``tuh_audio_mute_*()`` and ``tuh_audio_volume_*()`` APIs use +a completion callback. Their synchronous helpers block until completion and +should only be used while audio streaming is stopped; synchronous transfers +can disrupt isochronous traffic. Use ``tuh_audio_control_xfer()`` for other +class-specific entity controls. Buffers passed to asynchronous controls must +remain valid until their completion callbacks run. + +Supported formats and limitations +--------------------------------- + +The host accepts Type-I PCM in signed 8-, 16-, packed 24-, 24-in-32-, and +32-bit little-endian formats. UAC1 descriptors must list discrete sample +rates; continuous ranges are not supported. UAC2 requires a directly +connected Clock Source. Clock Selectors, Clock Multipliers, Sampling Rate +Converters, Clock Validity, and Valid Alternate Settings controls are not +handled. + +Explicit feedback endpoints using 10.14 or 16.16 values are supported. +Implicit-feedback IN endpoints are treated as ordinary capture endpoints and +do not pace playback. ``MaxPacketsOnly`` endpoints are not supported: OUT +packets are not padded to ``wMaxPacketSize``, and padding in IN packets is not +removed from the captured data.
diff --git a/docs/reference/class/host.rst b/docs/reference/class/host.rst index ef42e3d..ebb5a55 100644 --- a/docs/reference/class/host.rst +++ b/docs/reference/class/host.rst
@@ -2,10 +2,10 @@ 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. +TinyUSB provides application-level host drivers for Audio, 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 =============== @@ -28,6 +28,7 @@ #define CFG_TUH_ENABLED 1 #define CFG_TUH_DEVICE_MAX 4 #define CFG_TUH_HUB 1 + #define CFG_TUH_AUDIO 1 #define CFG_TUH_CDC 1 #define CFG_TUH_HID (3 * CFG_TUH_DEVICE_MAX) #define CFG_TUH_MSC 1 @@ -137,6 +138,7 @@ 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, +Start with :doc:`../../examples/host/audio_host` for Audio, +: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.
diff --git a/docs/reference/class/index.rst b/docs/reference/class/index.rst index 2f8e577..dff38aa 100644 --- a/docs/reference/class/index.rst +++ b/docs/reference/class/index.rst
@@ -24,7 +24,7 @@ - Guide * - Audio 1.0/2.0 - Yes - - No + - Yes - :doc:`audio` * - Bluetooth HCI - Yes