[alsa-devel] [alsa-lib][PATCH] pcm: fix wrong document references to PCM APIs which perform direct memory access with frame copying

[Takashi Sakamoto]

In a design of ALSA PCM interface, for PCM frame transmission to/from
kernel space, applications can select from two options; direct memory access
or ioctl(2). Available options are decided depending on device capacity and
machine architecture. Applications can get available options by the first
entry of 'struct snd_pcm_hw_params.masks'.

When the mask includes 'SNDRV_PCM_ACCESS_MMAP_xxx', applications can use
direct memory access. For this use case, userspace library has two types
of PCM API. One is to expose a pointer over the memory to start
reading/writing PCM frames. Another is to copy PCM frames between the
memory and a given buffer.

Current documentation includes wrong references to these APIs to describe
their advantages/disadvantages. This confuses application developers
because the references indicate PCM APIs to execute ioctl(2) operation to
read/write PCM frames.

This commit fixes the bug.

Signed-off-by: Takashi Sakamoto <o-takashi at sakamocchi.jp>
---
 src/pcm/pcm.c | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c
index f2ca02b..0cf740f 100644
--- a/src/pcm/pcm.c
+++ b/src/pcm/pcm.c
@@ -260,8 +260,9 @@ If you like to use the compatibility functions in mmap mode, there are
 read / write routines equaling to standard read / write transfers. Using
 these functions discards the benefits of direct access to memory region.
 See the #snd_pcm_mmap_readi(),
-#snd_pcm_writei(), #snd_pcm_readn()
-and #snd_pcm_writen() functions.
+#snd_pcm_mmap_writei(), #snd_pcm_mmap_readn()
+and #snd_pcm_mmap_writen() functions. These functions use
+#snd_pcm_areas_copy() internally.
 
 \section pcm_errors Error codes
 
-- 
2.9.3