From patchwork Mon Aug 14 11:55:21 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Takashi Iwai X-Patchwork-Id: 135367 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:b824:0:b0:3f2:4152:657d with SMTP id z4csp2701742vqi; Mon, 14 Aug 2023 05:14:05 -0700 (PDT) X-Google-Smtp-Source: AGHT+IEM7/bO3FDe+T8jPTYAXucxzuNog62UtwRz4UbrJ+HHpLvUacMdmRFPBtaYeRcJRogWsU/O X-Received: by 2002:a05:6e02:d49:b0:349:5e6:4953 with SMTP id h9-20020a056e020d4900b0034905e64953mr12142458ilj.7.1692015245496; Mon, 14 Aug 2023 05:14:05 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1692015245; cv=none; d=google.com; s=arc-20160816; b=mz5eGJi+e3xN8/mM7QaOVmLkID5H4HMr9tTsG9o8QLJGqIxn3f37tzxU6oZfHDY5Ru gRBW6hF25tdBOk7VW+NbTAhJrzqvwcr7fSaisNDSy+1K0QP3Wwgn3YZThG+/wm5cWdv/ bu/4dGxD7PgmW/S+5Hr8n3r/O2xJD8UjzHOG8O3PCpf8IMGxZyy/4hJM0HF7Zj+ExhPD CiV+8ZmkTZhIsIWqXVmU8sbSiVyndBbE5vqkJFou50sQIKpIdGiivg8CfEu1YXrLhtM9 i/ArfDeSI7xnw4/a7LEeNLNwrfXztoRhfXl7zMapFawRiOt5qgUgrIjQR3QXZ9ZjqNor A7ZQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature:dkim-signature; bh=T8//wcNQwPthyNc3xqkx3W41Gepnl5c0ocQ4zcQs/T8=; fh=DP61/jJCya+1W1X7P2vK6pKSD4lkczCotBkmA6jh/us=; b=iJmrhcdnZCAdP7p5S3xXWqLNJ3BaW35xzDhqNMVCS826iRpowerAdHeaI97E8Kq5bt MfF5TF5dG/lEyC3rMg+DCvgB/n1ILt1P/XPWf+ukr4Y39DA60oM1L9NZm4+3k84kYmE2 jZ0+Zm7/08/EJdSSrFU19BONXkmHby3l8DNsiPSPelx6xwluKoT70ylegAfBy723HJ5f 6VQEz6HH/kXNbPaf2dFkreAJBwhy0e3C5oe6p3jsL1g9HktFyNR+QezO1R7nlwHpfY0Y 3Wh6vTKY/tBcZRdhZcV+TfInjd9VrvCOYLk0xPufFONi4rc5q6UT7ZxVYzbqfgNs5RGJ O9cg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@suse.de header.s=susede2_rsa header.b=ahIr5qVA; dkim=neutral (no key) header.i=@suse.de header.s=susede2_ed25519 header.b=hlDhrNK6; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=suse.de Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id q14-20020a63cc4e000000b005652bd28000si7956385pgi.4.2023.08.14.05.13.47; Mon, 14 Aug 2023 05:14:05 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@suse.de header.s=susede2_rsa header.b=ahIr5qVA; dkim=neutral (no key) header.i=@suse.de header.s=susede2_ed25519 header.b=hlDhrNK6; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=suse.de Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230329AbjHNL5X (ORCPT + 99 others); Mon, 14 Aug 2023 07:57:23 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:57502 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233016AbjHNL4q (ORCPT ); Mon, 14 Aug 2023 07:56:46 -0400 Received: from smtp-out2.suse.de (smtp-out2.suse.de [IPv6:2001:67c:2178:6::1d]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 032D9199E for ; Mon, 14 Aug 2023 04:56:31 -0700 (PDT) Received: from imap2.suse-dmz.suse.de (imap2.suse-dmz.suse.de [192.168.254.74]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-521) server-digest SHA512) (No client certificate requested) by smtp-out2.suse.de (Postfix) with ESMTPS id 97A581FD6C; Mon, 14 Aug 2023 11:55:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_rsa; t=1692014156; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=T8//wcNQwPthyNc3xqkx3W41Gepnl5c0ocQ4zcQs/T8=; b=ahIr5qVAWhmupEIPhvZCvLbNS1cPp6yzet/3ILBxDZHn2B3YGoYaKZw/vLv0tphRXo+9Ug ReOjVwzqK4M2nxgiNbyUXhjBnuV7J82LoI75EIPAtqQbogsyaKjDtnQLNa8Iyj+zPByOyp A9SntWNq3spdFHD3SXMLcUbqG6C01ys= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_ed25519; t=1692014156; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=T8//wcNQwPthyNc3xqkx3W41Gepnl5c0ocQ4zcQs/T8=; b=hlDhrNK6jq4VcVo8WYfFGbrjqrouo2V6YOFEOXK7T3/ue7U/kD1HKOtwCtN3HnT222JzH3 NJOb4bLLjdIFeeAQ== Received: from imap2.suse-dmz.suse.de (imap2.suse-dmz.suse.de [192.168.254.74]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-521) server-digest SHA512) (No client certificate requested) by imap2.suse-dmz.suse.de (Postfix) with ESMTPS id 773BD138EE; Mon, 14 Aug 2023 11:55:56 +0000 (UTC) Received: from dovecot-director2.suse.de ([192.168.254.65]) by imap2.suse-dmz.suse.de with ESMTPSA id 4HkHHEwW2mRnMAAAMHmgww (envelope-from ); Mon, 14 Aug 2023 11:55:56 +0000 From: Takashi Iwai To: alsa-devel@alsa-project.org Cc: linux-kernel@vger.kernel.org, Takashi Iwai Subject: [PATCH 23/25] ALSA: doc: Update description for the new PCM copy ops Date: Mon, 14 Aug 2023 13:55:21 +0200 Message-Id: <20230814115523.15279-24-tiwai@suse.de> X-Mailer: git-send-email 2.35.3 In-Reply-To: <20230814115523.15279-1-tiwai@suse.de> References: <20230814115523.15279-1-tiwai@suse.de> MIME-Version: 1.0 X-Spam-Status: No, score=-4.4 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_MED,SPF_HELO_NONE, SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1774206578359108995 X-GMAIL-MSGID: 1774206578359108995 Update the documentation about the PCM copy callbacks. The update was kept minimalistic, just correcting the use of copy_user ops with the single copy ops, and drop/update the text mentioning the copy_kernel. Signed-off-by: Takashi Iwai --- .../kernel-api/writing-an-alsa-driver.rst | 58 ++++++------------- 1 file changed, 19 insertions(+), 39 deletions(-) diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index 4335c98b3d82..cd421856409e 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -2018,8 +2018,8 @@ sleeping poll threads, etc. This callback is also atomic by default. -copy_user, copy_kernel and fill_silence ops -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +copy and fill_silence ops +~~~~~~~~~~~~~~~~~~~~~~~~~ These callbacks are not mandatory, and can be omitted in most cases. These callbacks are used when the hardware buffer cannot be in the @@ -3444,8 +3444,8 @@ external hardware buffer in interrupts (or in tasklets, preferably). The first case works fine if the external hardware buffer is large enough. This method doesn't need any extra buffers and thus is more -efficient. You need to define the ``copy_user`` and ``copy_kernel`` -callbacks for the data transfer, in addition to the ``fill_silence`` +efficient. You need to define the ``copy`` callback +for the data transfer, in addition to the ``fill_silence`` callback for playback. However, there is a drawback: it cannot be mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM. @@ -3458,22 +3458,22 @@ Another case is when the chip uses a PCI memory-map region for the buffer instead of the host memory. In this case, mmap is available only on certain architectures like the Intel one. In non-mmap mode, the data cannot be transferred as in the normal way. Thus you need to define the -``copy_user``, ``copy_kernel`` and ``fill_silence`` callbacks as well, +``copy`` and ``fill_silence`` callbacks as well, as in the cases above. Examples are found in ``rme32.c`` and ``rme96.c``. -The implementation of the ``copy_user``, ``copy_kernel`` and +The implementation of the ``copy`` and ``silence`` callbacks depends upon whether the hardware supports -interleaved or non-interleaved samples. The ``copy_user`` callback is +interleaved or non-interleaved samples. The ``copy`` callback is defined like below, a bit differently depending on whether the direction is playback or capture:: - static int playback_copy_user(struct snd_pcm_substream *substream, + static int playback_copy(struct snd_pcm_substream *substream, int channel, unsigned long pos, - void __user *src, unsigned long count); - static int capture_copy_user(struct snd_pcm_substream *substream, + struct iov_iter *src, unsigned long count); + static int capture_copy(struct snd_pcm_substream *substream, int channel, unsigned long pos, - void __user *dst, unsigned long count); + struct iov_iter *dst, unsigned long count); In the case of interleaved samples, the second argument (``channel``) is not used. The third argument (``pos``) specifies the position in bytes. @@ -3490,18 +3490,17 @@ of data (``count``) at the specified pointer (``src``) to the specified offset (``pos``) in the hardware buffer. When coded like memcpy-like way, the copy would look like:: - my_memcpy_from_user(my_buffer + pos, src, count); + my_memcpy_from_iter(my_buffer + pos, src, count); For the capture direction, you copy the given amount of data (``count``) at the specified offset (``pos``) in the hardware buffer to the specified pointer (``dst``):: - my_memcpy_to_user(dst, my_buffer + pos, count); + my_memcpy_to_iter(dst, my_buffer + pos, count); -Here the functions are named ``from_user`` and ``to_user`` because -it's the user-space buffer that is passed to these callbacks. That -is, the callback is supposed to copy data from/to the user-space -directly to/from the hardware buffer. +The given ``src`` or ``dst`` a struct iov_iter pointer containing the +pointer and the size. Use the existing helpers to copy or access the +data as defined in ``linux/uio.h``. Careful readers might notice that these callbacks receive the arguments in bytes, not in frames like other callbacks. It's because @@ -3519,25 +3518,6 @@ the given user-space buffer, but only for the given channel. For details, please check ``isa/gus/gus_pcm.c`` or ``pci/rme9652/rme9652.c`` as examples. -The above callbacks are the copies from/to the user-space buffer. There -are some cases where we want to copy from/to the kernel-space buffer -instead. In such a case, the ``copy_kernel`` callback is called. It'd -look like:: - - static int playback_copy_kernel(struct snd_pcm_substream *substream, - int channel, unsigned long pos, - void *src, unsigned long count); - static int capture_copy_kernel(struct snd_pcm_substream *substream, - int channel, unsigned long pos, - void *dst, unsigned long count); - -As found easily, the only difference is that the buffer pointer is -without a ``__user`` prefix; that is, a kernel-buffer pointer is passed -in the fourth argument. Correspondingly, the implementation would be -a version without the user-copy, such as:: - - my_memcpy(my_buffer + pos, src, count); - Usually for the playback, another callback ``fill_silence`` is defined. It's implemented in a similar way as the copy callbacks above:: @@ -3545,10 +3525,10 @@ above:: static int silence(struct snd_pcm_substream *substream, int channel, unsigned long pos, unsigned long count); -The meanings of arguments are the same as in the ``copy_user`` and -``copy_kernel`` callbacks, although there is no buffer pointer +The meanings of arguments are the same as in the ``copy`` callback, +although there is no buffer pointer argument. In the case of interleaved samples, the channel argument has -no meaning, as for the ``copy_*`` callbacks. +no meaning, as for the ``copy`` callback. The role of the ``fill_silence`` callback is to set the given amount (``count``) of silence data at the specified offset (``pos``) in the