From patchwork Sun Dec 11 11:31:38 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Takashi Sakamoto X-Patchwork-Id: 9469713 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 188F160231 for ; Sun, 11 Dec 2016 11:44:11 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 004F727D0E for ; Sun, 11 Dec 2016 11:44:11 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id D5A60283C1; Sun, 11 Dec 2016 11:44:10 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=2.0 tests=BAYES_00, RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.1 Received: from alsa0.perex.cz (alsa0.perex.cz [77.48.224.243]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id CC32727D0E for ; Sun, 11 Dec 2016 11:44:09 +0000 (UTC) Received: by alsa0.perex.cz (Postfix, from userid 1000) id 0D84D2669C8; Sun, 11 Dec 2016 12:44:06 +0100 (CET) Received: from alsa0.perex.cz (localhost [127.0.0.1]) by alsa0.perex.cz (Postfix) with ESMTP id 34B082666D7; Sun, 11 Dec 2016 12:41:45 +0100 (CET) X-Original-To: alsa-devel@alsa-project.org Delivered-To: alsa-devel@alsa-project.org Received: by alsa0.perex.cz (Postfix, from userid 1000) id 394382668EC; Sun, 11 Dec 2016 12:31:51 +0100 (CET) Received: from smtp-proxy002.phy.lolipop.jp (smtp-proxy002.phy.lolipop.jp [157.7.104.43]) by alsa0.perex.cz (Postfix) with ESMTP id 2DA612666D7 for ; Sun, 11 Dec 2016 12:31:47 +0100 (CET) Received: from smtp-proxy002.phy.lolipop.lan (HELO smtp-proxy002.phy.lolipop.jp) (172.19.44.43) (smtp-auth username m12129643-o-takashi, mechanism plain) by smtp-proxy002.phy.lolipop.jp (qpsmtpd/0.82) with ESMTPA; Sun, 11 Dec 2016 20:31:45 +0900 Received: from 127.0.0.1 (127.0.0.1) by smtp-proxy002.phy.lolipop.jp (LOLIPOP-Fsecure); Sun, 11 Dec 2016 20:31:38 +0900 (JST) X-Virus-Status: clean(LOLIPOP-Fsecure) From: Takashi Sakamoto To: tiwai@suse.de, perex@perex.cz Date: Sun, 11 Dec 2016 20:31:38 +0900 Message-Id: <20161211113138.32468-1-o-takashi@sakamocchi.jp> X-Mailer: git-send-email 2.9.3 Cc: alsa-devel@alsa-project.org Subject: [alsa-devel] [alsa-lib][PATCH] pcm: fix wrong document references to PCM APIs which perform direct memory access with frame copying X-BeenThere: alsa-devel@alsa-project.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Alsa-devel mailing list for ALSA developers - http://www.alsa-project.org" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: alsa-devel-bounces@alsa-project.org Sender: alsa-devel-bounces@alsa-project.org X-Virus-Scanned: ClamAV using ClamSMTP 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 --- 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