[PATCH 0/3] ALSA: More PCM and documentation updates
Hi,
this is a patch set following my change to the PCM core for adding the -EPIPE handling to ack ops.
Takashi
===
Takashi Iwai (3): ALSA: pcm: Improved XRUN handling for indirect PCM helpers ALSA: docs: Add description about ack callback -EPIPE error handling ALSA: docs: A few more words for PCM XRUN handling and stream locks
.../kernel-api/writing-an-alsa-driver.rst | 22 +++++++++++++++++-- include/sound/pcm-indirect.h | 22 ++++++++++++++----- 2 files changed, 36 insertions(+), 8 deletions(-)
As PCM ack callback may handle the XRUN situation gracefully now, change the indirect PCM helpers to give a proper error (-EPIPE). Also, change the pointer callback helpers to deal with the XRUN error properly, too.
This requires the PCM core change by the commit 8c721c53dda5 ("ALSA: usb-audio: Fix recursive locking at XRUN during syncing").
Signed-off-by: Takashi Iwai tiwai@suse.de --- include/sound/pcm-indirect.h | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-)
diff --git a/include/sound/pcm-indirect.h b/include/sound/pcm-indirect.h index 04127686e8d0..98e06ea73b2b 100644 --- a/include/sound/pcm-indirect.h +++ b/include/sound/pcm-indirect.h @@ -44,7 +44,7 @@ snd_pcm_indirect_playback_transfer(struct snd_pcm_substream *substream, if (diff < -(snd_pcm_sframes_t) (runtime->boundary / 2)) diff += runtime->boundary; if (diff < 0) - return -EINVAL; + return -EPIPE; rec->sw_ready += (int)frames_to_bytes(runtime, diff); rec->appl_ptr = appl_ptr; } @@ -83,6 +83,8 @@ snd_pcm_indirect_playback_pointer(struct snd_pcm_substream *substream, struct snd_pcm_indirect *rec, unsigned int ptr) { int bytes = ptr - rec->hw_io; + int err; + if (bytes < 0) bytes += rec->hw_buffer_size; rec->hw_io = ptr; @@ -90,8 +92,11 @@ snd_pcm_indirect_playback_pointer(struct snd_pcm_substream *substream, rec->sw_io += bytes; if (rec->sw_io >= rec->sw_buffer_size) rec->sw_io -= rec->sw_buffer_size; - if (substream->ops->ack) - substream->ops->ack(substream); + if (substream->ops->ack) { + err = substream->ops->ack(substream); + if (err == -EPIPE) + return SNDRV_PCM_POS_XRUN; + } return bytes_to_frames(substream->runtime, rec->sw_io); }
@@ -112,7 +117,7 @@ snd_pcm_indirect_capture_transfer(struct snd_pcm_substream *substream, if (diff < -(snd_pcm_sframes_t) (runtime->boundary / 2)) diff += runtime->boundary; if (diff < 0) - return -EINVAL; + return -EPIPE; rec->sw_ready -= frames_to_bytes(runtime, diff); rec->appl_ptr = appl_ptr; } @@ -152,6 +157,8 @@ snd_pcm_indirect_capture_pointer(struct snd_pcm_substream *substream, { int qsize; int bytes = ptr - rec->hw_io; + int err; + if (bytes < 0) bytes += rec->hw_buffer_size; rec->hw_io = ptr; @@ -162,8 +169,11 @@ snd_pcm_indirect_capture_pointer(struct snd_pcm_substream *substream, rec->sw_io += bytes; if (rec->sw_io >= rec->sw_buffer_size) rec->sw_io -= rec->sw_buffer_size; - if (substream->ops->ack) - substream->ops->ack(substream); + if (substream->ops->ack) { + err = substream->ops->ack(substream); + if (err == -EPIPE) + return SNDRV_PCM_POS_XRUN; + } return bytes_to_frames(substream->runtime, rec->sw_io); }
Add a brief description about the newly added behavior of the PCM ack callback with -EPIPE error.
Signed-off-by: Takashi Iwai tiwai@suse.de --- Documentation/sound/kernel-api/writing-an-alsa-driver.rst | 4 ++++ 1 file changed, 4 insertions(+)
diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index 5c9523b7d55c..6b8f3495407f 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -2137,6 +2137,10 @@ This callback is also not mandatory. This callback is called when the emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the internal buffer, and this callback is useful only for such a purpose.
+The callback function may return 0 or a negative error. When the +return value is ``-EPIPE``, PCM core treats as a buffer XRUN happens, +and changes the state to ``SNDRV_PCM_STATE_XRUN`` automatically. + This callback is atomic as default.
page callback
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().
Signed-off-by: Takashi Iwai tiwai@suse.de --- .../kernel-api/writing-an-alsa-driver.rst | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-)
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 +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 -----------
participants (1)
-
Takashi Iwai