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

[Takashi Iwai]

At Mon, 27 Oct 2014 13:11:42 +0100,
David Henningsson wrote:
> 
> While reading alsa-lib code, I discovered that snd_pcm_avail_update
> does require a user-kernel context switch:

Not "does" but "may"...

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

... since this depends on the setup.  sync_ptr() calls sync_ptr1()
only when the status mmap isn't done.


Takashi

> 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
>