[alsa-devel] [PATCH] pcm: Fix snd_pcm_avail_update description

[David Henningsson]

While reading alsa-lib code, I discovered that snd_pcm_avail_update
does require a user-kernel context switch:

snd_pcm_avail_update() -> snd_pcm_hw_avail_update() -> sync_ptr()
-> sync_ptr1() -> ioctl()

The documentation says it does not, so let's fix the documentation.

Signed-off-by: David Henningsson <david.henningsson at canonical.com>
---
 src/pcm/pcm.c | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c
index 4a7be6c..e57e362 100644
--- a/src/pcm/pcm.c
+++ b/src/pcm/pcm.c
@@ -403,10 +403,12 @@ The function #snd_pcm_avail_update() updates the current
 available count of samples for writing (playback) or filled samples for
 reading (capture). This call is mandatory for updating actual r/w pointer.
 Using standalone, it is a light method to obtain current stream position,
-because it does not require the user <-> kernel context switch, but the value
-is less accurate, because ring buffer pointers are updated in kernel drivers
+because while it does require a user <-> kernel context switch, the value is
+just copied from the kernel, and not updated by synchronously asking the hardware
+about its current position. The ring buffer pointers are updated in kernel drivers
 only when an interrupt occurs. If you want to get accurate stream state,
-use functions #snd_pcm_avail(), #snd_pcm_delay() or #snd_pcm_avail_delay().
+use functions #snd_pcm_avail(), #snd_pcm_delay(), #snd_pcm_avail_delay() or
+#snd_pcm_status().
 </p>
 <p>
 The function #snd_pcm_avail() reads the current hardware pointer
-- 
1.9.1