diff mbox series

[3/3] ALSA: docs: A few more words for PCM XRUN handling and stream locks

Message ID 20230323065237.5062-4-tiwai@suse.de (mailing list archive)
State New, archived
Headers show
Series ALSA: More PCM and documentation updates | expand

Commit Message

Takashi Iwai March 23, 2023, 6:52 a.m. UTC
Enhance the documents about the PCM, missing descriptions for a couple
of helpers like snd_pcm_period_elapsed_under_stream_lock() and

Signed-off-by: Takashi Iwai <tiwai@suse.de>
 .../kernel-api/writing-an-alsa-driver.rst      | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)
diff mbox series


diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index 6b8f3495407f..a368529e8ed3 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -2215,6 +2215,12 @@  Typical code would be like:
               return IRQ_HANDLED;
+Also, when the device can detect a buffer underrun/overrun, the driver
+can notify the XRUN status to the PCM core by calling
+:c:func:`snd_pcm_stop_xrun()`. This function stops the stream and sets
+the PCM state to ``SNDRV_PCM_STATE_XRUN``. Note that it must be called
+outside the PCM stream lock, hence it can't be called from the atomic
 High frequency timer interrupts
@@ -2294,8 +2300,9 @@  mutexes or semaphores instead.
 As already seen, some pcm callbacks are atomic and some are not. For
 example, the ``hw_params`` callback is non-atomic, while ``trigger``
 callback is atomic. This means, the latter is called already in a
-spinlock held by the PCM middle layer. Please take this atomicity into
-account when you choose a locking scheme in the callbacks.
+spinlock held by the PCM middle layer, the PCM stream lock. Please
+take this atomicity into account when you choose a locking scheme in
+the callbacks.
 In the atomic callbacks, you cannot use functions which may call
 :c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and
@@ -2318,6 +2325,13 @@  in the PCM core instead of spin and rwlocks, so that you can call all PCM
 functions safely in a non-atomic
+Also, in some cases, you might need to call
+:c:func:`snd_pcm_period_elapsed()` in the atomic context (e.g. the
+period gets elapsed during ``ack`` or other callback). There is a
+variant that can be called inside the PCM stream lock
+:c:func:`snd_pcm_period_elapsed_under_stream_lock()` for that purpose,