linux-kernel - Re: [PATCH v21 03/30] splice: Rename direct_splice_read() to copy_splice

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Mon, 22 May 2023 08:55:14 +0100
From:   David Howells <dhowells@...hat.com>
To:     Christian Brauner <brauner@...nel.org>
Cc:     dhowells@...hat.com, Jens Axboe <axboe@...nel.dk>,
        Al Viro <viro@...iv.linux.org.uk>,
        Christoph Hellwig <hch@...radead.org>,
        Matthew Wilcox <willy@...radead.org>, Jan Kara <jack@...e.cz>,
        Jeff Layton <jlayton@...nel.org>,
        David Hildenbrand <david@...hat.com>,
        Jason Gunthorpe <jgg@...dia.com>,
        Logan Gunthorpe <logang@...tatee.com>,
        Hillf Danton <hdanton@...a.com>,
        Linus Torvalds <torvalds@...ux-foundation.org>,
        linux-fsdevel@...r.kernel.org, linux-block@...r.kernel.org,
        linux-kernel@...r.kernel.org, linux-mm@...ck.org,
        Christoph Hellwig <hch@....de>,
        Steve French <sfrench@...ba.org>, linux-cifs@...r.kernel.org
Subject: Re: [PATCH v21 03/30] splice: Rename direct_splice_read() to copy_splice_read()

> 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 <dhowells@...hat.com>
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 <dhowells@...hat.com>
    cc: Christian Brauner <brauner@...nel.org>
    cc: Christoph Hellwig <hch@....de>
    cc: Jens Axboe <axboe@...nel.dk>
    cc: Steve French <smfrench@...il.com>
    cc: Al Viro <viro@...iv.linux.org.uk>
    cc: linux-mm@...ck.org
    cc: linux-block@...r.kernel.org
    cc: linux-cifs@...r.kernel.org
    cc: linux-fsdevel@...r.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 *@...s 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 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 *@...s 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,