From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id 0105DC7EE2D for ; Mon, 22 May 2023 12:53:48 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 8B2CD900002; Mon, 22 May 2023 08:53:48 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 83BB26B0075; Mon, 22 May 2023 08:53:48 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 70588900002; Mon, 22 May 2023 08:53:48 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0010.hostedemail.com [216.40.44.10]) by kanga.kvack.org (Postfix) with ESMTP id 620436B0074 for ; Mon, 22 May 2023 08:53:48 -0400 (EDT) Received: from smtpin19.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay10.hostedemail.com (Postfix) with ESMTP id 35EC7C0263 for ; Mon, 22 May 2023 12:53:48 +0000 (UTC) X-FDA: 80817882936.19.E123B66 Received: from dfw.source.kernel.org (dfw.source.kernel.org [139.178.84.217]) by imf14.hostedemail.com (Postfix) with ESMTP id 7346210001B for ; Mon, 22 May 2023 12:53:45 +0000 (UTC) Authentication-Results: imf14.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=WoCejcij; spf=pass (imf14.hostedemail.com: domain of brauner@kernel.org designates 139.178.84.217 as permitted sender) smtp.mailfrom=brauner@kernel.org; dmarc=pass (policy=none) header.from=kernel.org ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1684760025; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=UnYqomWFSAjn8Uq/ZEgKLnMU81xbuJ0v9IQhDhgeeuM=; b=Sh3bgClAdvF/iDuPFyM3t+QuSoismFzouBbZlmqmWExrsyRMu2svaPhqNpfR7eElDycVXs cYPurSsUln+ndFusP6o3sgiiHRVpG6BAYzw2h6PqAtfEPsZDNIXLVY6Lt85kvzZMdrY37f 3wEyeUYY+Rp1NEkyJhboDXzJ8+twUi4= ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1684760025; a=rsa-sha256; cv=none; b=nP3j7hhwxc+6roAbecx6+DHEqgt22OxmP3Fq8A/nBwaceyiEPkTC8O8P8mk2Ubrm1NTiA4 T52oXa0pXkLz1e0PhqL88NatkmG6iHfG+0s4wDcmkGbHEBfTxg17dzxWjxfdkx80dwV9kn jAvoWxqC9ShEx6Kj4LAJ9YbiVvP7lZs= ARC-Authentication-Results: i=1; imf14.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=WoCejcij; spf=pass (imf14.hostedemail.com: domain of brauner@kernel.org designates 139.178.84.217 as permitted sender) smtp.mailfrom=brauner@kernel.org; dmarc=pass (policy=none) header.from=kernel.org Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dfw.source.kernel.org (Postfix) with ESMTPS id 4ECD4612A1; Mon, 22 May 2023 12:53:44 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 452FFC433EF; Mon, 22 May 2023 12:53:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1684760023; bh=ImInocG/5tz/0H3zPAKjnZJKUJJ7f7gU8sP1cCYTc4M=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=WoCejcijL504amG1JWhHwZTY9ANeFzKIntYQLP07J5uj6is7A9fQS3E45NEVz8wk6 ijfRl5PO3lTu/TTTIv32g7R7yLRypfiWOTi3Uj/0KvpuFrOTVcMel9+d2wSGIkyYdu vUWYxwspLqeF3kuLLovyI+OOPx0h36hOwidawlUZUg9fAT5m8b6iSCy+1CpVnsDVp7 WsqlRyT5zrYfRVFyupWZadvSK20ofoJ9ED4LN+qqMECRszCrYQYsWxjuqjJ6xikft9 Dj+RJ+BTQGXrekuYCaTiR3iKGCv67tOqqWySpi7M8dOONCCzlP1x8letugsbywO8H1 ygjRrnqit//Zw== Date: Mon, 22 May 2023 14:53:31 +0200 From: Christian Brauner To: David Howells Cc: Jens Axboe , Al Viro , Christoph Hellwig , Matthew Wilcox , Jan Kara , Jeff Layton , David Hildenbrand , Jason Gunthorpe , Logan Gunthorpe , Hillf Danton , Linus Torvalds , linux-fsdevel@vger.kernel.org, linux-block@vger.kernel.org, linux-kernel@vger.kernel.org, linux-mm@kvack.org, Christoph Hellwig , Steve French , linux-cifs@vger.kernel.org Subject: Re: [PATCH v21 03/30] splice: Rename direct_splice_read() to copy_splice_read() Message-ID: <20230522-pfund-ferngeblieben-53fad9c0e527@brauner> References: <20230520-sekunde-vorteil-f2d588e40b68@brauner> <20230520000049.2226926-1-dhowells@redhat.com> <20230520000049.2226926-4-dhowells@redhat.com> <2468127.1684742114@warthog.procyon.org.uk> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline In-Reply-To: <2468127.1684742114@warthog.procyon.org.uk> X-Rspamd-Queue-Id: 7346210001B X-Rspam-User: X-Rspamd-Server: rspam11 X-Stat-Signature: gd38zpkj6oezz5k5r9e9u5sesro4u5wn X-HE-Tag: 1684760025-2779 X-HE-Meta: U2FsdGVkX19cXIqdaH4rwcAnLe7Xeliy6Pm0vOPVsEdKArIeDnuB4TYYwYYbmMEuK5Jw6AjD5ndIyt2f6N+Gs+zku5FUFGIC1wqpWg6kGc6cVEMJPu9F8hoDu2fJAk4LIlvAipdSPedzVJA6edESe3SgUGgj4Rx5rCj+UP5WCuro+oPgixfnUWA+BmpN/pqt4CIlC3R4Clj+vP9GSqBlUUjZwuTatm7nh23vQ30uEVXsKMXnI2J0ab0WFLw1G0T1iK4b+nnSiF6YyS3w4ybaZKDLHE5OecZhafTyOpsouEPD6ixs6iuE1QTqaWGK+CGGf7aFS4zkONc6krYgO1q+BGAY3gQfaMR5BVj2uwi5JC0SHoAMA72M9Edljt3OPhRWWtzXjpZBQMV3TlG6vk7/W14VQySR3n44oYpdDzYxDCsHRNkIwQ23Ch22uFO/pb1Ax5azoMUdc4gJlazhxFIvg7Sy4SR7Xqla5sYDhte7amAgW5JNSm+Xs1jTMjGB7vn6McJPGs+j/1OOQCa0t+4I3mAysFMzic42NWkrfWEY7o7gg9GurYiIgvgHJO8RUc1IQTNYdZli+qCGt5jcpDp8jZQy1V3DfWyKElgS2pRgQBPSNCrNBl2yKiG2qAcXT2WCsbSZO9nMtZFHpeRxUG9JdYr6dS3Uq7OTXUVtAzno0gOQf7fUZ3YEPXFp6OwGHix1fKUDz0mEa+cBhBghlslcLLDyezg8KzWUFJQaaWnddGWetAnQ4TxbD8mxC0opi0/yo5TVcoiUqCiZSM/nGYxxYa9XmEyi6TtqcvMc0Z/1kthnPsZ/Rds8ICIDflGS+w9trSE74oItFklqTp0b+f13v04AMMRk1qqlaoaxWX6s6igRQ9u2BZaimE8gNDJhCglZpnVPK0U7+WsEZMTJkZGF/MfH0R8NBRZvbeU2czmyCCa1jM/JktvHmVqtXn428HSkgpeyLAJG4k6358E/Anb HP0Losv8 Q5qCXmZOho+btv3Nctn+Z9S2Ysrfud3ohvyVcBgWIofMB1rfJF3wfsLRADYDJGfQcsuEOCbhs/7xYxDDJkXQj6Q2OHSmO9wjSz7IYCfEE/uWY3hpLiwbOZxM3FmlNiDJXHCG909uAka9LNH47rfGVMBf7lq6ZPPsX049Rp42bVecua0vbSNnNrP+Brew6AYo4kBY4s3+aQ8/M8JBCaCjvHp1d2K+6lMJ8VyUd9dTvilkJ0wYa7m4a21Eg3BYh4qUgX9+Kbk4VWdvNERiAGauMyY2PLUEHo2cOh22oYReCjhLa60wY0XlUUh7/hLDh+GDlhTl8EgbgRM0OcHXVn7Zya5eaDlLJYzGSxCazhEwJ+ryqQp9KvHMNxi4gqTiC95dL1FZ/a/XqnNeT3rKtJ5WXETBjP6//KrZzuxINykpy6byzOf6btW8MCrmwa+e1hsYcPtDd7695Mtu8t/Z15aAIvaHJSUCdABjYzu7Bqj8EafYVrI3H4lUcs7cuV4wJrhY/yc3aIIlblBlNoLyYLiJNnhSYCdGBkJRkt1gcWFMwlLlwcFRaAMWAsbuS5w== X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: On Mon, May 22, 2023 at 08:55:14AM +0100, David Howells wrote: > > For the future it'd be nice if exported functions would always get > > proper kernel doc, > > Something like the attached? > > David > --- > commit 0362042ba0751fc5457b0548fb9006f9d7dfbeca > Author: David Howells > Date: Mon May 22 08:34:24 2023 +0100 > > splice: kdoc for filemap_splice_read() and copy_splice_read() > > Provide kerneldoc comments for filemap_splice_read() and > copy_splice_read(). > > Signed-off-by: David Howells > cc: Christian Brauner > cc: Christoph Hellwig > cc: Jens Axboe > cc: Steve French > cc: Al Viro > cc: linux-mm@kvack.org > cc: linux-block@vger.kernel.org > cc: linux-cifs@vger.kernel.org > cc: linux-fsdevel@vger.kernel.org > > diff --git a/fs/splice.c b/fs/splice.c > index 9be4cb3b9879..5292a8fa929d 100644 > --- a/fs/splice.c > +++ b/fs/splice.c > @@ -299,8 +299,25 @@ void splice_shrink_spd(struct splice_pipe_desc *spd) > kfree(spd->partial); > } > > -/* > - * Copy data from a file into pages and then splice those into the output pipe. > +/** > + * copy_splice_read - Copy data from a file and splice the copy into a pipe > + * @in: The file to read from > + * @ppos: Pointer to the file position to read from > + * @pipe: The pipe to splice into > + * @len: The amount to splice > + * @flags: The SPLICE_F_* flags > + * > + * This function allocates a bunch of pages sufficient to hold the requested > + * amount of data (but limited by the remaining pipe capacity), passes it to > + * the file's ->read_iter() to read into and then splices the used pages into > + * the pipe. > + * > + * On success, the number of bytes read will be returned and *@ppos will be > + * updated if appropriate; 0 will be returned if there is no more data to be > + * read; -EAGAIN will be returned if the pipe had no space, and some other > + * negative error code will be returned on error. A short read may occur if > + * the pipe has insufficient space, we reach the end of the data or we hit a > + * hole. > */ I think kdoc expects: * Return: On success, the number of bytes read will be returned and *@ppos will be * updated if appropriate; 0 will be returned if there is no more data to be * read; -EAGAIN will be returned if the pipe had no space, and some other * negative error code will be returned on error. A short read may occur if * the pipe has insufficient space, we reach the end of the data or we hit a * hole. and similar for filemap_splice_read() other than that this looks good! > ssize_t copy_splice_read(struct file *in, loff_t *ppos, > struct pipe_inode_info *pipe, > diff --git a/mm/filemap.c b/mm/filemap.c > index 603b562d69b1..1f235a6430fd 100644 > --- a/mm/filemap.c > +++ b/mm/filemap.c > @@ -2871,9 +2871,24 @@ size_t splice_folio_into_pipe(struct pipe_inode_info *pipe, > return spliced; > } > > -/* > - * Splice folios from the pagecache of a buffered (ie. non-O_DIRECT) file into > - * a pipe. > +/** > + * filemap_splice_read - Splice data from a file's pagecache into a pipe > + * @in: The file to read from > + * @ppos: Pointer to the file position to read from > + * @pipe: The pipe to splice into > + * @len: The amount to splice > + * @flags: The SPLICE_F_* flags > + * > + * This function gets folios from a file's pagecache and splices them into the > + * pipe. Readahead will be called as necessary to fill more folios. This may > + * be used for blockdevs also. > + * > + * On success, the number of bytes read will be returned and *@ppos will be > + * updated if appropriate; 0 will be returned if there is no more data to be > + * read; -EAGAIN will be returned if the pipe had no space, and some other > + * negative error code will be returned on error. A short read may occur if > + * the pipe has insufficient space, we reach the end of the data or we hit a > + * hole. > */ > ssize_t filemap_splice_read(struct file *in, loff_t *ppos, > struct pipe_inode_info *pipe, >