docs: developer_guides: add ALSA Use Case Manager v2 (UCM2) guide and runbook

Add a comprehensive developer guide and practical runbook for ALSA
Use Case Manager v2 (UCM2) under Pillar 3 of Developer Guides.

Topics covered:
- Architectural role of UCM2 in bridging kernel mixer controls/PCMs
  to user-space sound servers (PipeWire, WirePlumber, PulseAudio).
- Evolution from legacy UCM1 to UCM2 comparison matrix.
- Directory hierarchy, lookup precedence, and dynamic CardComponents
  hardware variant parsing via DefineRegex and If conditions.
- UCM2 syntax specification (syntax versions 2 through 7), core
  primitives (SectionUseCase, SectionVerb, SectionDevice, Value blocks),
  and transition sequences.
- Step-by-step authoring walkthrough: hardware enumeration, manual ALSA
  CLI bringup, card master entry, HiFi verb definition, and codec/HDMI
  modularization.
- PipeWire/WirePlumber SPA-ACP engine integration and priority arbitration.
- In-depth diagnostic runbooks for dummy output fallback, muted routing,
  jack detection failures, and live in-system hot-reloading.
- Production readiness checklist and high-resolution architecture diagram.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>

Author: lrgirdwo

developer_guides/index.rst

@@ -200,6 +200,7 @@ Guides for Linux ASoC kernel driver developers, machine drivers, DMI quirk autho
 * :ref:`sof_linux_driver` (Linux kernel ASoC driver architecture, multi-vendor DSP core abstraction, IPC3/IPC4 protocol layers, ACPI/PCI platform probing, DMI machine quirks, runtime PM, and stream DMA management)
 * :ref:`topology2` (ALSA Topology 2.0 architecture, split functional model, pre-processor token parsing, widget and pipeline definition syntax, hardware DAI graph routing, and dynamic UCM2 integration)
 * :ref:`topology` (Legacy ALSA Topology 1.0 architecture, M4 macro expansion templates, pipeline graph generation, and backward-compatibility guidelines)
+* :ref:`ucm2_guide` (ALSA Use Case Manager v2 (UCM2) architecture, card directory layouts, syntax versions 2–7, device definitions, jack detection, sequence verbs, volume mixer remapping, PipeWire/WirePlumber integration, and step-by-step authoring and debugging workflows)
 * :ref:`setup-ktest-environment` (Automated Linux kernel testing and bisection framework with ktest, rapid git bisect workflows, automated kernel build/deploy, and headless serial console validation)
 
 .. toctree::
@@ -208,6 +209,7 @@ Guides for Linux ASoC kernel driver developers, machine drivers, DMI quirk autho
    linux_driver/index
    topology2/topology2
    topology/topology
+   ucm/ucm2_guide
    ktest/setup_ktest_environment
 
 ---

developer_guides/linux_driver/machine_drivers_quirks.rst

@@ -165,8 +165,12 @@ Reload the audio drivers or reboot the system:
 ALSA Use Case Manager (UCM2) Integration
 ****************************************
 
-Once the kernel machine driver binds the audio card and exposes ALSA mixer controls, user-space audio servers (PipeWire, PulseAudio) rely on **ALSA Use Case Manager (UCM2)** configuration profiles:
+Once the kernel machine driver binds the audio card and exposes ALSA mixer controls, user-space audio servers (PipeWire, WirePlumber, PulseAudio) rely on **ALSA Use Case Manager v2 (UCM2)** configuration profiles to discover logical endpoints, manage automated jack sensing, and bind hardware volume sliders:
+
+* **Profile Locations**: Standard configurations reside under ``/usr/share/alsa/ucm2/conf.d/<CardDriver>/`` (matched via the driver string exported in ``/proc/asound/cards``).
+* **Card Components Export**: Machine drivers convey discovered hardware SKU variations (such as microphone channel counts or codec variants) by calling ``snd_component_add()``, populated as ``${CardComponents}`` in UCM2.
+* **Standard Audio Verbs & Devices**: Profiles map low-level kcontrols (e.g., ``Speaker Switch``, ``Headphone Volume``, ``PGA Boost``) into standardized logical endpoints (``Speaker``, ``Headphones``, ``Mic``, ``Headset``, ``HDMI``) under the ``HiFi`` use case verb.
+* **Jack Detection & Hardware Auto-Muting**: UCM2 monitors hardware jack kcontrols (e.g., ``Headphone Jack``) to automatically trigger speaker attenuation and transfer active stream routes.
+
+For the comprehensive, step-by-step authoring walkthrough, syntax version reference, and diagnostic runbooks, consult the authoritative :ref:`ucm2_guide`.
 
-* UCM profiles reside in `/usr/share/alsa/ucm2/`.
-* Profiles map kernel mixer controls (e.g., `Speaker Switch`, `Headphone Volume`, `PGA Boost`) to standardized audio verbs (`HiFi`, `Record`, `VoiceCall`).
-* For newly quirked platforms, ensure appropriate UCM device configurations exist to automatically manage routing, volume levels, and jack detection events.