Commit 03f62c9c authored by Takashi Iwai's avatar Takashi Iwai

ALSA: docs: A few more words for PCM XRUN handling and stream locks

Enhance the documents about the PCM, missing descriptions for a couple
of helpers like snd_pcm_period_elapsed_under_stream_lock() and
snd_pcm_stop_xrun().

Link: https://lore.kernel.org/r/20230323065237.5062-4-tiwai@suse.deSigned-off-by: default avatarTakashi Iwai <tiwai@suse.de>
parent f84af109
......@@ -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
callback.
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
context.
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,
too.
Constraints
-----------
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment