Message-Id: <20241107200835.3033-1-yesanishhere@gmail.com>
Date: Thu,  7 Nov 2024 12:08:35 -0800
From: anish kumar <yesanishhere@...il.com>
To: lgirdwood@...il.com,
	broonie@...nel.org,
	perex@...ex.cz,
	tiwai@...e.com,
	corbet@....net
Cc: linux-kernel@...r.kernel.org,
	linux-doc@...r.kernel.org,
	linux-sound@...r.kernel.org,
	anish kumar <yesanishhere@...il.com>
Subject: [RFC PATCH] ALSA: Add debugging guide for audio issues

Add a comprehensive debugging guide for ALSA audio issues, covering
topics from bootup to runtime debugging. This document aims to help
developers diagnose and resolve common audio problems in Linux.

The guide includes sections on:
- Bootup/bringup issues
- Runtime debugging
- XRUN debugging
- Audio pops and clicks

This addresses the lack of a centralized debugging resource for ALSA
and should help improve the troubleshooting process for audio drivers.

Inspired by discussions on LKML:
https://lkml.org/lkml/2024/9/24/392

Signed-off-by: anish kumar <yesanishhere@...il.com>
---
 Documentation/sound/soc/debug.rst | 334 ++++++++++++++++++++++++++++++
 Documentation/sound/soc/index.rst |   1 +
 2 files changed, 335 insertions(+)
 create mode 100644 Documentation/sound/soc/debug.rst

diff --git a/Documentation/sound/soc/debug.rst b/Documentation/sound/soc/debug.rst
new file mode 100644
index 000000000000..3905fc9e4c58
--- /dev/null
+++ b/Documentation/sound/soc/debug.rst
@@ -0,0 +1,334 @@
+===================================================
+ALSA Debugging Tools and Techniques in Linux Kernel
+===================================================
+
+:Author: Anish Kumar <yesanishhere@...il.com>
+
+Abstract
+--------
+
+This document provides different tools and techniques useful for debugging audio
+issues in Linux, covering problems from booting to shutdown. This guide is not
+exhaustive but aims to explain potential audio issues or bugs that can arise
+when bringing up audio drivers on Linux or fixing existing audio corruption
+issues during playback or capture.
+
+1. Introduction
+===============
+
+Audio debugging in Linux systems requires a systematic approach to identify and
+resolve issues at various stages of the audio pipeline. This document presents a
+comprehensive guide to audio debugging tools and techniques, covering bootup
+issues, runtime debugging, and specific problems such as audio corruption and
+XRUNs.
+
+2. Bootup/Bringup Issues
+========================
+
+In order to provide audio services, the ALSA sound card is the first component
+that gets registered in the system. If you are not hearing boot-up sounds, check
+the following in the procfs filesystem:
+
+- **/proc/asound/**: This is a virtual filesystem in Linux that provides
+  information about the ALSA sound system. It allows users to interact with and
+  obtain details about audio devices.
+
+- Check if **/proc/asound/cards** is populated. If it is not, this means sound
+  card registration has failed. All sound cards are listed there. This entry can
+  be useful for:
+
+  - Verifying if a sound card has been properly registered and is present in the
+    system.
+  - Finding the index of a given card. Card indexes are dynamically assigned as
+    cards are registered. User-space software may assume cards have certain
+    indexes, which could change depending on runtime dynamics. For example,
+    index 0 may be assigned to card B instead of card A if card A's registration
+    is deferred due to a missing dependency (e.g., an I2C codec that has not
+    been probed yet).
+
+If the sound card is registered, check its capabilities and devices for
+playback. There are various devices that can be connected to the system, such as
+wired headsets, Bluetooth headsets, and internal speakers. If you are looking to
+play audio on a wired headset, look for the corresponding entry in:
+
+- **/proc/asound/pcm**: This lists all PCM devices for all sound cards present
+  in the system. Each PCM device has a directory structure like:
+  :file:`/proc/asound/cardX/pcmY[p,c]/*`. Here, X is the card index number (as found
+  in **/proc/asound/cards**) and Y is the PCM device index (as found in
+  **/proc/asound/pcm**). The [p,c] indicates the direction of the PCM stream:
+
+  - p: Playback stream. Represents the PCM device used for audio output (e.g.,
+    sending audio data to speakers).
+  - c: Capture stream. Represents the PCM device used for audio input (e.g.,
+    receiving audio data from a microphone).
+
+For playback, the relevant PCM device should be listed as:
+:file:`/proc/asound/card0/pcm0p0c0`. Example output from my system::
+
+    00-00: CX20632 Analog : CX20632 Analog : playback 1 : capture 1
+    00-02: HDMI 0 : HDMI 0 : playback 1
+
+This output indicates that I have only one sound card in my system, with
+starting index 0, capable of both playing and capturing audio. The same sound
+card also provides HDMI playback capability, but no ARCIN, so there is no
+capture path.
+
+2.1 How Sound Card Registration Happens
+---------------------------------------
+
+If the sound card is not registered, or if it is registered but the
+corresponding device node is not created, it is important to understand how the
+ASoC core creates these nodes. In summary, it creates PCM nodes once it finds
+all the CPU DAI, codec DAI, and platform DAI associated with the particular
+``snd_soc_dai_link`` instance. For example, in the kernel source file
+:file:`sound/soc/samsung/littlemill.c`:
+
+.. code-block:: c
+
+    SND_SOC_DAILINK_DEFS(cpu,
+        DAILINK_COMP_ARRAY(COMP_CPU("samsung-i2s.0")),
+        DAILINK_COMP_ARRAY(COMP_CODEC("wm8994-codec", "wm8994-aif1")),
+        DAILINK_COMP_ARRAY(COMP_PLATFORM("samsung-i2s.0")));
+
+    SND_SOC_DAILINK_DEFS(baseband,
+        DAILINK_COMP_ARRAY(COMP_CPU("wm8994-aif2")),
+        DAILINK_COMP_ARRAY(COMP_CODEC("wm1250-ev1.1-0027", "wm1250-ev1")));
+
+The ``SND_SOC_DAILINK_DEFS`` macro helps define the parameters for a digital
+audio interface (DAI) link in a structured way. The macro typically includes
+definitions for several important components of a DAI link:
+
+- **CPU DAI**: The data interface associated with the CPU that handles audio
+  data. It defines how the CPU interacts with the audio subsystem.
+- **Codec DAI**: The data interface for the audio codec, which converts digital
+  audio data to an analog signal (and vice versa). This is crucial for playback
+  and capture.
+- **Platform DAI**: Represents the platform layer that connects the CPU and
+  codec DAI. It handles the specifics of data transfer between the CPU and
+  codec.
+- **Stream Names**: Defines the names for playback and capture streams, which
+  are used by the audio subsystem for routing audio data.
+
+This can be simplified as follows for easier understanding:
+
+.. code-block:: c
+
+    SND_SOC_DAILINK_DEFS(my_dai_link,
+        SND_SOC_DAILINK_REG(cpu_dai),
+        SND_SOC_DAILINK_REG(codec_dai),
+        SND_SOC_DAILINK_REG(platform_dai)
+    );
+
+When ``devm_snd_soc_register_card`` is called, the ASoC core checks if the CPU,
+codec, and platform DAI probe callbacks are successful. If any of these fail,
+the sound card registration fails. There are two probes involved: one for the
+registration of the device (which could be I2C, I2S, or any hardware device) and
+the other is the probe callback from the ASoC core. Both must succeed for the
+devices to show up in the proc filesystem. For example, if the codec driver is
+I2C-based, the first probe for the I2C driver should succeed, and as part of
+this, the ASoC component gets registered. When the card is being registered by
+the machine driver, the ASoC core checks if the codec component probe is
+successful. The same applies to other CPU and platform components.
+
+3. Runtime Debugging
+====================
+
+Once the sound card and corresponding PCM nodes appear in the procfs filesystem,
+basic audio booting is successful. However, this does not guarantee successful
+playback using the ``aplay`` command. For example::
+
+    aplay -D hw:0,0 sound.wav
+
+If audio does not play, check the following:
+
+- **Unsupported Sample Rate**: Ensure the audio file's sample rate matches the
+  hardware's supported rates. Use::
+
+    aplay -f S16_LE -c 2 -r 44100 sound.wav
+
+  If the hardware does not support the requested sample rate, it may lead to
+  playback issues.
+
+- **Incorrect Channels**: Verify that the number of channels in your audio file
+  matches the hardware's supported configuration (e.g., stereo vs. mono).
+
+- **Bit Depth Issues**: Ensure the bit depth of the audio file is supported by
+  the hardware.
+
+- **Device Configuration**: Confirm that the card and device numbers are correct
+  by checking your device list with::
+
+    aplay -l
+
+- **Format Conversion**: If the format is unsupported, convert it to a
+  compatible format (e.g., WAV).
+
+4. Noise Debugging
+==================
+
+If you are experiencing noise issues, it may be beneficial to check if you are
+encountering XRUN issues. XRUNs can often manifest as audible noise or glitches
+in the audio output.
+
+4.1 What is XRUN?
+-----------------
+XRUN refers to an overflow or underflow condition in the audio buffer during
+playback or recording.
+
+4.2 Types of XRUN
+-----------------
+- **Overflow (XRUN)**: This occurs when the audio playback buffer runs out of
+  data to play. This situation arises when the application is not supplying data
+  to the buffer quickly enough, leading to dropouts or gaps in the sound.
+
+- **Underflow (XRUN)**: This happens when the audio capture buffer fills up
+  before the application can process the incoming data. If the application does
+  not read the data quickly enough, it causes data loss, and the capture stream
+  fails to record audio smoothly.
+
+4.3 Causes of XRUNs
+-------------------
+- **High CPU Load**: If the system is under heavy load, it may not process audio
+  interrupts on time, leading to missed interrupts.
+
+- **Incorrect Period Size**: A period size that is too small may result in
+  system scheduling delays, causing interrupts to be handled late and leading to
+  frame drops and ultimately XRUNs.
+
+- **Inefficient Audio Processing by Userspace**: If userspace tasks take too
+  long to execute, this can delay the feeding or retrieval of data from the
+  buffer.
+
+- **I/O Latency**: Latency from I/O in single-threaded, non-optimized audio
+  applications can cause significant problems related to XRUN. Due to large I/O
+  latencies, the ALSA buffer is likely to overflow or underflow. Applications
+  like aplay, arecord, tinyplay, and tinyrecord may suffer from this issue
+  because they are single-threaded.
+
+- **Misconfiguration**: Improper settings in the audio application or driver
+  configuration can contribute to XRUN occurrences.
+
+4.4 Debugging XRUN
+------------------
+Diagnosing the exact cause of XRUNs can be challenging. However, the following
+steps can help identify the issue:
+
+1. **Reduce CPU Load**: Stop any applications other than the playback
+   application to see if the XRUNs cease.
+
+2. **Increase Period Size**: Adjusting the period size can give the system more
+   time to handle interrupts.
+
+3. **Test with Special Files**: If I/O latency is suspected, try playing audio
+   via special files like ``/dev/zero`` (e.g., ``aplay -D hw:0,0 -f CD -d 30``),
+   as this reads data from RAM rather than I/O.
+
+4. **Change Userspace Application**: Switch to a different application to see if
+   it is the source of the problem.
+
+5. **Use ftrace**: Profile the call flow of the ALSA drivers using ftrace to
+   determine if any function calls are taking too long to execute during XRUN
+   events.
+
+6. **Check ALSA Documentation**: Refer to the ALSA XRUN Debugging Guide [#f1]_
+   for additional troubleshooting steps.
+
+7. **Inspect procfs Filesystem**: Use the command
+   ``cat /proc/asound/cardX/pcmY/subZ/status`` to dump the hardware and software
+   pointers of the ring buffer used by ALSA. Check if the pointers are
+   incrementing correctly. If they do not change, it indicates that the
+   underlying hardware is unable to process data, which could be due to
+   misconfiguration or some bug in interrupt processing.
+
+4.5 Example Status Output
+-------------------------
+The following command displays the status output for a specific PCM device::
+
+    # cat /proc/asound/card0/pcm0p/sub0/status
+
+The output is as follows::
+
+    state: RUNNING
+    owner_pid: 1234
+    trigger_time: 1000000.1000000
+    tstamp: 1000000.1000000
+    delay: 1234
+    avail: 0
+    avail_max: 0
+    hw_ptr: 64
+    appl_ptr: 4192
+
+**Description of Fields**:
+
+- **state**: Current state of the PCM device (e.g., RUNNING).
+- **owner_pid**: Process ID of the owner of the PCM stream.
+- **trigger_time**: Time when the last trigger occurred.
+- **tstamp**: Timestamp of the last audio sample processed.
+- **delay**: Current delay in microseconds.
+- **avail**: Available frames in the buffer.
+- **avail_max**: Maximum frames that can be made available.
+- **hw_ptr**: Hardware pointer indicating the position in the buffer.
+- **appl_ptr**: Application pointer indicating the position in the buffer.
+
+4.6 Fixing XRUNs
+----------------
+- **Optimize Application**: Convert single-threaded applications like
+  aplay/arecord/tinyplay/tinyrecord to multi-threaded ones. This allows one
+  thread to read multimedia data while another thread writes to the hardware. An
+  additional RAM circular buffer may be needed to manage I/O latency. The thread
+  reading from I/O should read larger amounts of data into the circular buffer,
+  while the thread writing to hardware reads from this buffer.
+
+- **Increase Period Size**: Adjusting the period size can help accommodate
+  delays in audio processing, allowing the CPU more time to handle interrupts.
+
+- **Optimize System Performance**: Reducing CPU load or prioritizing audio
+  processing can help mitigate XRUNs.
+
+5. Audio Pops and Clicks
+========================
+
+For detailed information about audio pops and clicks, refer to :doc:`/sound/soc/pops-clicks`.
+
+5.1 Debugging Pop Issues
+------------------------
+To diagnose and resolve pop issues, consider the following steps:
+
+1. **Check Sequencing**:
+
+   - Ensure that the sequencing mentioned in the above document is being
+     followed correctly.
+
+2. **Device Switching**:
+
+   - If pops occur during the switch from one device to another, test by playing
+     zero data to determine if the issue persists::
+
+       aplay -f dat /dev/zero
+
+   - If the pops continue, it indicates that the device switch is causing the
+     problem.
+
+3. **Register Write Events**:
+
+   - If pops occur during register writes due to triggered events, you can
+     introduce a delay between register writes with the following command::
+
+       echo 1 > /sys/module/snd_soc_core/parameters/regmap_sync_cache
+
+   - This command introduces a delay between register writes, which may help in
+     identifying the specific register causing the pop.
+
+6. Conclusion
+=============
+
+Audio debugging in Linux systems requires a methodical approach and
+understanding of various components in the audio pipeline. By following the
+techniques and utilizing the tools described in this document, developers can
+effectively diagnose and resolve audio-related issues in Linux environments.
+Regular system monitoring, proactive debugging, and staying updated with the
+latest ALSA developments are key to maintaining optimal audio performance in
+Linux systems.
+
+.. [#f1] ALSA XRUN Debugging Guide:
+   https://www.alsa-project.org/main/index.php/XRUN_Debug
diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index e57df2dab2fd..667d18681583 100644
--- a/Documentation/sound/soc/index.rst
+++ b/Documentation/sound/soc/index.rst
@@ -18,3 +18,4 @@ The documentation is spilt into the following sections:-
    jack
    dpcm
    codec-to-codec
+   debug
-- 
2.39.3 (Apple Git-146)

Powered by blists - more mailing lists