[PATCH 0/3] iov_iter documentation

[PATCH 0/3] iov_iter documentation

[Matthew Wilcox (Oracle)]

I couldn't remember what the return value from copy_to_iter() was, so
I wrote some documentation and linked it into the kernel-doc tree.

Matthew Wilcox (Oracle) (3):
  iov_iter: Add skeleton documentation
  iov_iter: Add kernel-doc
  iov_iter: Move internal documentation

 Documentation/core-api/index.rst    |  1 +
 Documentation/core-api/iov_iter.rst | 21 ++++++++
 include/linux/uio.h                 | 74 +++++++++++++++++++++++++++++
 lib/iov_iter.c                      | 41 ----------------
 4 files changed, 96 insertions(+), 41 deletions(-)
 create mode 100644 Documentation/core-api/iov_iter.rst

-- 
2.33.0

[PATCH 1/3] iov_iter: Add skeleton documentation

[Matthew Wilcox (Oracle)]

This is just somewhere to include the kernel-doc from for now.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
---
 Documentation/core-api/index.rst    |  1 +
 Documentation/core-api/iov_iter.rst | 21 +++++++++++++++++++++
 2 files changed, 22 insertions(+)
 create mode 100644 Documentation/core-api/iov_iter.rst

diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 5de2c7a4b1b3..082143baa983 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -43,6 +43,7 @@ Library functionality that is used throughout the kernel.
    this_cpu_ops
    timekeeping
    errseq
+   iov_iter
 
 Concurrency primitives
 ======================
diff --git a/Documentation/core-api/iov_iter.rst b/Documentation/core-api/iov_iter.rst
new file mode 100644
index 000000000000..541c16caf958
--- /dev/null
+++ b/Documentation/core-api/iov_iter.rst
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+========
+iov_iter
+========
+
+:Author: Matthew Wilcox
+
+Overview
+========
+
+The iov_iter is used to represent the source or destination for a read or
+write.  It can point to many different kinds of memory, including user
+memory, kernel memory, pipes and biovecs.
+
+Functions and structures
+========================
+
+.. kernel-doc:: include/linux/uio.h
+.. kernel-doc:: lib/iov_iter.c
+   :export:
-- 
2.33.0

Re: [PATCH 1/3] iov_iter: Add skeleton documentation

[Christoph Hellwig]

Looks good,

Reviewed-by: Christoph Hellwig <hch@lst.de>

[PATCH 2/3] iov_iter: Add kernel-doc

[Matthew Wilcox (Oracle)]

Document enum iter_type, copy_to_iter() and copy_from_iter()

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
---
 include/linux/uio.h | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/include/linux/uio.h b/include/linux/uio.h
index 6350354f97e9..9fbce8c92545 100644
--- a/include/linux/uio.h
+++ b/include/linux/uio.h
@@ -17,6 +17,15 @@ struct kvec {
 	size_t iov_len;
 };
 
+/**
+ * enum iter_type - The type of memory referred to by the iterator.
+ * @ITER_IOVEC: An array of ranges of userspace memory.
+ * @ITER_KVEC: An array of ranges of kernel memory.
+ * @ITER_BVEC: An array of &struct bio_vec.
+ * @ITER_PIPE: A pipe.
+ * @ITER_XARRAY: A &struct xarray of pages.
+ * @ITER_DISCARD: No memory here; discard all writes.
+ */
 enum iter_type {
 	/* iter types */
 	ITER_IOVEC,
@@ -146,6 +155,18 @@ size_t _copy_to_iter(const void *addr, size_t bytes, struct iov_iter *i);
 size_t _copy_from_iter(void *addr, size_t bytes, struct iov_iter *i);
 size_t _copy_from_iter_nocache(void *addr, size_t bytes, struct iov_iter *i);
 
+/**
+ * copy_to_iter() - Copy from kernel memory to an iterator.
+ * @addr: Kernel memory address.
+ * @bytes: Number of bytes to copy.
+ * @i: Destination of copy.
+ *
+ * Copy @bytes from @addr to @i.  The region of memory pointed to by @i must
+ * not overlap the region pointed to by @addr.  @i may point to any kind
+ * of &enum iter_type memory.
+ *
+ * Return: Number of bytes successfully copied to the iterator.
+ */
 static __always_inline __must_check
 size_t copy_to_iter(const void *addr, size_t bytes, struct iov_iter *i)
 {
@@ -155,6 +176,18 @@ size_t copy_to_iter(const void *addr, size_t bytes, struct iov_iter *i)
 		return _copy_to_iter(addr, bytes, i);
 }
 
+/**
+ * copy_from_iter() - Copy from an iterator to kernel memory.
+ * @addr: Kernel memory address.
+ * @bytes: Number of bytes to copy.
+ * @i: Source of memory.
+ *
+ * Copy @bytes from @i to @addr.  The region of memory pointed to by @i must
+ * not overlap the region pointed to by @addr.  @i may point to any kind
+ * of &enum iter_type memory.
+ *
+ * Return: Number of bytes successfully copied from the iterator.
+ */
 static __always_inline __must_check
 size_t copy_from_iter(void *addr, size_t bytes, struct iov_iter *i)
 {
-- 
2.33.0

Re: [PATCH 2/3] iov_iter: Add kernel-doc

[Christoph Hellwig]

On Mon, Dec 06, 2021 at 02:52:19PM +0000, Matthew Wilcox (Oracle) wrote:
> Document enum iter_type, copy_to_iter() and copy_from_iter()

Looks good,

Reviewed-by: Christoph Hellwig <hch@lst.de>

[PATCH 3/3] iov_iter: Move internal documentation

[Matthew Wilcox (Oracle)]

Document the interfaces we want users to call (ie copy_mc_to_iter()
and copy_from_iter_flushcache()), not the internal interfaces.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
---
 include/linux/uio.h | 41 +++++++++++++++++++++++++++++++++++++++++
 lib/iov_iter.c      | 41 -----------------------------------------
 2 files changed, 41 insertions(+), 41 deletions(-)

diff --git a/include/linux/uio.h b/include/linux/uio.h
index 9fbce8c92545..4e5ad9053c97 100644
--- a/include/linux/uio.h
+++ b/include/linux/uio.h
@@ -244,6 +244,22 @@ size_t _copy_mc_to_iter(const void *addr, size_t bytes, struct iov_iter *i);
 #define _copy_mc_to_iter _copy_to_iter
 #endif
 
+/**
+ * copy_from_iter_flushcache() - Write destination through cpu cache.
+ * @addr: destination kernel address
+ * @bytes: total transfer length
+ * @i: source iterator
+ *
+ * The pmem driver arranges for filesystem-dax to use this facility via
+ * dax_copy_from_iter() for ensuring that writes to persistent memory
+ * are flushed through the CPU cache. It is differentiated from
+ * _copy_from_iter_nocache() in that guarantees all data is flushed for
+ * all iterator types. The _copy_from_iter_nocache() only attempts to
+ * bypass the cache for the ITER_IOVEC case, and on some archs may use
+ * instructions that strand dirty-data in the cache.
+ *
+ * Return: Number of bytes copied (may be %0).
+ */
 static __always_inline __must_check
 size_t copy_from_iter_flushcache(void *addr, size_t bytes, struct iov_iter *i)
 {
@@ -253,6 +269,31 @@ size_t copy_from_iter_flushcache(void *addr, size_t bytes, struct iov_iter *i)
 		return _copy_from_iter_flushcache(addr, bytes, i);
 }
 
+/**
+ * copy_mc_to_iter() - Copy to iter with source memory error exception handling.
+ * @addr: source kernel address
+ * @bytes: total transfer length
+ * @i: destination iterator
+ *
+ * The pmem driver deploys this for the dax operation
+ * (dax_copy_to_iter()) for dax reads (bypass page-cache and the
+ * block-layer). Upon #MC read(2) aborts and returns EIO or the bytes
+ * successfully copied.
+ *
+ * The main differences between this and typical _copy_to_iter().
+ *
+ * * Typical tail/residue handling after a fault retries the copy
+ *   byte-by-byte until the fault happens again. Re-triggering machine
+ *   checks is potentially fatal so the implementation uses source
+ *   alignment and poison alignment assumptions to avoid re-triggering
+ *   hardware exceptions.
+ *
+ * * ITER_KVEC, ITER_PIPE, and ITER_BVEC can return short copies.
+ *   Compare to copy_to_iter() where only ITER_IOVEC attempts might return
+ *   a short copy.
+ *
+ * Return: Number of bytes copied (may be %0).
+ */
 static __always_inline __must_check
 size_t copy_mc_to_iter(void *addr, size_t bytes, struct iov_iter *i)
 {
diff --git a/lib/iov_iter.c b/lib/iov_iter.c
index 66a740e6e153..03b0e1dac27e 100644
--- a/lib/iov_iter.c
+++ b/lib/iov_iter.c
@@ -715,31 +715,6 @@ static size_t copy_mc_pipe_to_iter(const void *addr, size_t bytes,
 	return xfer;
 }
 
-/**
- * _copy_mc_to_iter - copy to iter with source memory error exception handling
- * @addr: source kernel address
- * @bytes: total transfer length
- * @i: destination iterator
- *
- * The pmem driver deploys this for the dax operation
- * (dax_copy_to_iter()) for dax reads (bypass page-cache and the
- * block-layer). Upon #MC read(2) aborts and returns EIO or the bytes
- * successfully copied.
- *
- * The main differences between this and typical _copy_to_iter().
- *
- * * Typical tail/residue handling after a fault retries the copy
- *   byte-by-byte until the fault happens again. Re-triggering machine
- *   checks is potentially fatal so the implementation uses source
- *   alignment and poison alignment assumptions to avoid re-triggering
- *   hardware exceptions.
- *
- * * ITER_KVEC, ITER_PIPE, and ITER_BVEC can return short copies.
- *   Compare to copy_to_iter() where only ITER_IOVEC attempts might return
- *   a short copy.
- *
- * Return: number of bytes copied (may be %0)
- */
 size_t _copy_mc_to_iter(const void *addr, size_t bytes, struct iov_iter *i)
 {
 	if (unlikely(iov_iter_is_pipe(i)))
@@ -789,22 +764,6 @@ size_t _copy_from_iter_nocache(void *addr, size_t bytes, struct iov_iter *i)
 EXPORT_SYMBOL(_copy_from_iter_nocache);
 
 #ifdef CONFIG_ARCH_HAS_UACCESS_FLUSHCACHE
-/**
- * _copy_from_iter_flushcache - write destination through cpu cache
- * @addr: destination kernel address
- * @bytes: total transfer length
- * @i: source iterator
- *
- * The pmem driver arranges for filesystem-dax to use this facility via
- * dax_copy_from_iter() for ensuring that writes to persistent memory
- * are flushed through the CPU cache. It is differentiated from
- * _copy_from_iter_nocache() in that guarantees all data is flushed for
- * all iterator types. The _copy_from_iter_nocache() only attempts to
- * bypass the cache for the ITER_IOVEC case, and on some archs may use
- * instructions that strand dirty-data in the cache.
- *
- * Return: number of bytes copied (may be %0)
- */
 size_t _copy_from_iter_flushcache(void *addr, size_t bytes, struct iov_iter *i)
 {
 	if (unlikely(iov_iter_is_pipe(i))) {
-- 
2.33.0

Re: [PATCH 3/3] iov_iter: Move internal documentation

[Christoph Hellwig]

On Mon, Dec 06, 2021 at 02:52:20PM +0000, Matthew Wilcox (Oracle) wrote:
> Document the interfaces we want users to call (ie copy_mc_to_iter()
> and copy_from_iter_flushcache()), not the internal interfaces.

Except that no one actually calls them, and I have series to remove them
that just needs a little brushing off.

Re: [PATCH 3/3] iov_iter: Move internal documentation

[Matthew Wilcox]

On Mon, Dec 06, 2021 at 03:55:34PM +0100, Christoph Hellwig wrote:
> On Mon, Dec 06, 2021 at 02:52:20PM +0000, Matthew Wilcox (Oracle) wrote:
> > Document the interfaces we want users to call (ie copy_mc_to_iter()
> > and copy_from_iter_flushcache()), not the internal interfaces.
> 
> Except that no one actually calls them, and I have series to remove them
> that just needs a little brushing off.

Glad I didn't spend any time fixing the grammar.  I have no problem with
dropping this patch from the series.