All of lore.kernel.org
 help / color / mirror / Atom feed
From: Christoph Hellwig <hch@lst.de>
To: x86@kernel.org, Alexei Starovoitov <ast@kernel.org>,
	Daniel Borkmann <daniel@iogearbox.net>,
	Masami Hiramatsu <mhiramat@kernel.org>,
	Linus Torvalds <torvalds@linux-foundation.org>,
	Andrew Morton <akpm@linux-foundation.org>
Cc: linux-parisc@vger.kernel.org, linux-um@lists.infradead.org,
	netdev@vger.kernel.org, bpf@vger.kernel.org, linux-mm@kvack.org,
	linux-kernel@vger.kernel.org
Subject: [PATCH 04/18] maccess: clarify kerneldoc comments
Date: Wed, 13 May 2020 18:00:24 +0200	[thread overview]
Message-ID: <20200513160038.2482415-5-hch@lst.de> (raw)
In-Reply-To: <20200513160038.2482415-1-hch@lst.de>

Add proper kerneldoc comments for probe_kernel_read_strict and
probe_kernel_read strncpy_from_unsafe_strict and explain the different
versus the non-strict version.

Signed-off-by: Christoph Hellwig <hch@lst.de>
---
 mm/maccess.c | 61 ++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 43 insertions(+), 18 deletions(-)

diff --git a/mm/maccess.c b/mm/maccess.c
index 4e7f3b6eb05ae..747581ac50dc9 100644
--- a/mm/maccess.c
+++ b/mm/maccess.c
@@ -31,29 +31,35 @@ probe_write_common(void __user *dst, const void *src, size_t size)
 }
 
 /**
- * probe_kernel_read(): safely attempt to read from a kernel-space location
+ * probe_kernel_read(): safely attempt to read from any location
  * @dst: pointer to the buffer that shall take the data
  * @src: address to read from
  * @size: size of the data chunk
  *
- * Safely read from address @src to the buffer at @dst.  If a kernel fault
- * happens, handle that and return -EFAULT.
+ * Same as probe_kernel_read_strict() except that for architectures with
+ * not fully separated user and kernel address spaces this function also works
+ * for user address tanges.
+ *
+ * DO NOT USE THIS FUNCTION - it is broken on architectures with entirely
+ * separate kernel and user address spaces, and also a bad idea otherwise.
+ */
+long __weak probe_kernel_read(void *dst, const void *src, size_t size)
+    __attribute__((alias("__probe_kernel_read")));
+
+/**
+ * probe_kernel_read_strict(): safely attempt to read from kernel-space
+ * @dst: pointer to the buffer that shall take the data
+ * @src: address to read from
+ * @size: size of the data chunk
+ *
+ * Safely read from kernel address @src to the buffer at @dst.  If a kernel
+ * fault happens, handle that and return -EFAULT.
  *
  * We ensure that the copy_from_user is executed in atomic context so that
  * do_page_fault() doesn't attempt to take mmap_sem.  This makes
  * probe_kernel_read() suitable for use within regions where the caller
  * already holds mmap_sem, or other locks which nest inside mmap_sem.
- *
- * probe_kernel_read_strict() is the same as probe_kernel_read() except for
- * the case where architectures have non-overlapping user and kernel address
- * ranges: probe_kernel_read_strict() will additionally return -EFAULT for
- * probing memory on a user address range where probe_user_read() is supposed
- * to be used instead.
  */
-
-long __weak probe_kernel_read(void *dst, const void *src, size_t size)
-    __attribute__((alias("__probe_kernel_read")));
-
 long __weak probe_kernel_read_strict(void *dst, const void *src, size_t size)
     __attribute__((alias("__probe_kernel_read")));
 
@@ -153,15 +159,34 @@ long probe_user_write(void __user *dst, const void *src, size_t size)
  * If @count is smaller than the length of the string, copies @count-1 bytes,
  * sets the last byte of @dst buffer to NUL and returns @count.
  *
- * strncpy_from_unsafe_strict() is the same as strncpy_from_unsafe() except
- * for the case where architectures have non-overlapping user and kernel address
- * ranges: strncpy_from_unsafe_strict() will additionally return -EFAULT for
- * probing memory on a user address range where strncpy_from_unsafe_user() is
- * supposed to be used instead.
+ * Same as strncpy_from_unsafe_strict() except that for architectures with
+ * not fully separated user and kernel address spaces this function also works
+ * for user address tanges.
+ *
+ * DO NOT USE THIS FUNCTION - it is broken on architectures with entirely
+ * separate kernel and user address spaces, and also a bad idea otherwise.
  */
 long __weak strncpy_from_unsafe(char *dst, const void *unsafe_addr, long count)
     __attribute__((alias("__strncpy_from_unsafe")));
 
+/**
+ * strncpy_from_unsafe_strict: - Copy a NUL terminated string from unsafe
+ *				 address.
+ * @dst:   Destination address, in kernel space.  This buffer must be at
+ *         least @count bytes long.
+ * @unsafe_addr: Unsafe address.
+ * @count: Maximum number of bytes to copy, including the trailing NUL.
+ *
+ * Copies a NUL-terminated string from unsafe address to kernel buffer.
+ *
+ * On success, returns the length of the string INCLUDING the trailing NUL.
+ *
+ * If access fails, returns -EFAULT (some data may have been copied
+ * and the trailing NUL added).
+ *
+ * If @count is smaller than the length of the string, copies @count-1 bytes,
+ * sets the last byte of @dst buffer to NUL and returns @count.
+ */
 long __weak strncpy_from_unsafe_strict(char *dst, const void *unsafe_addr,
 				       long count)
     __attribute__((alias("__strncpy_from_unsafe")));
-- 
2.26.2


  parent reply	other threads:[~2020-05-13 16:02 UTC|newest]

Thread overview: 54+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-05-13 16:00 clean up and streamline probe_kernel_* and friends v2 Christoph Hellwig
2020-05-13 16:00 ` [PATCH 01/18] maccess: unexport probe_kernel_write and probe_user_write Christoph Hellwig
2020-05-13 16:00 ` [PATCH 02/18] maccess: remove various unused weak aliases Christoph Hellwig
2020-05-13 16:00 ` [PATCH 03/18] maccess: remove duplicate kerneldoc comments Christoph Hellwig
2020-05-13 16:00 ` Christoph Hellwig [this message]
2020-05-13 16:00 ` [PATCH 05/18] maccess: update the top of file comment Christoph Hellwig
2020-05-13 16:00 ` [PATCH 06/18] maccess: rename strncpy_from_unsafe_user to strncpy_from_user_nofault Christoph Hellwig
2020-05-13 16:00 ` [PATCH 07/18] maccess: rename strncpy_from_unsafe_strict to strncpy_from_kernel_nofault Christoph Hellwig
2020-05-13 16:00 ` [PATCH 08/18] maccess: rename strnlen_unsafe_user to strnlen_user_nofault Christoph Hellwig
2020-05-13 16:00 ` [PATCH 09/18] maccess: remove probe_read_common and probe_write_common Christoph Hellwig
2020-05-13 16:00 ` [PATCH 10/18] maccess: unify the probe kernel arch hooks Christoph Hellwig
2020-05-14  1:13   ` Masami Hiramatsu
2020-05-19  5:46     ` Christoph Hellwig
2020-05-13 16:00 ` [PATCH 11/18] maccess: remove strncpy_from_unsafe Christoph Hellwig
2020-05-13 19:11   ` Linus Torvalds
2020-05-13 19:11     ` Linus Torvalds
2020-05-13 19:28     ` Christoph Hellwig
2020-05-13 22:36       ` Daniel Borkmann
2020-05-13 23:03         ` Linus Torvalds
2020-05-13 23:03           ` Linus Torvalds
2020-05-13 23:24           ` Daniel Borkmann
2020-05-13 23:20         ` Masami Hiramatsu
2020-05-13 23:59           ` Linus Torvalds
2020-05-13 23:59             ` Linus Torvalds
2020-05-14  1:00             ` Masami Hiramatsu
2020-05-14  2:43               ` Linus Torvalds
2020-05-14  2:43                 ` Linus Torvalds
2020-05-14  9:44                 ` Masami Hiramatsu
2020-05-14 10:27                   ` Daniel Borkmann
2020-05-13 23:28         ` Al Viro
2020-05-13 23:58           ` Daniel Borkmann
2020-05-14 10:01             ` David Laight
2020-05-14 10:21               ` Daniel Borkmann
2020-05-13 16:00 ` [PATCH 12/18] maccess: always use strict semantics for probe_kernel_read Christoph Hellwig
2020-05-13 16:00 ` [PATCH 13/18] maccess: move user access routines together Christoph Hellwig
2020-05-13 16:00 ` [PATCH 14/18] maccess: allow architectures to provide kernel probing directly Christoph Hellwig
2020-05-13 19:36   ` Linus Torvalds
2020-05-13 19:36     ` Linus Torvalds
2020-05-13 19:40     ` Christoph Hellwig
2020-05-13 19:48       ` Linus Torvalds
2020-05-13 19:48         ` Linus Torvalds
2020-05-13 19:54         ` Christoph Hellwig
2020-05-16  3:42   ` Masami Hiramatsu
2020-05-18 15:09     ` Christoph Hellwig
2020-05-13 16:00 ` [PATCH 15/18] x86: use non-set_fs based maccess routines Christoph Hellwig
2020-05-13 16:00 ` [PATCH 16/18] maccess: rename probe_kernel_{read,write} to copy_{from,to}_kernel_nofault Christoph Hellwig
2020-05-13 16:00 ` [PATCH 17/18] maccess: rename probe_user_{read,write} to copy_{from,to}_user_nofault Christoph Hellwig
2020-05-13 16:00 ` [PATCH 18/18] maccess: rename probe_kernel_address to get_kernel_nofault Christoph Hellwig
2020-05-13 19:37 ` clean up and streamline probe_kernel_* and friends v2 Linus Torvalds
2020-05-13 19:37   ` Linus Torvalds
2020-05-13 23:04 ` Daniel Borkmann
2020-05-13 23:20   ` Linus Torvalds
2020-05-13 23:20     ` Linus Torvalds
2020-05-19  5:50   ` Christoph Hellwig

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200513160038.2482415-5-hch@lst.de \
    --to=hch@lst.de \
    --cc=akpm@linux-foundation.org \
    --cc=ast@kernel.org \
    --cc=bpf@vger.kernel.org \
    --cc=daniel@iogearbox.net \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-mm@kvack.org \
    --cc=linux-parisc@vger.kernel.org \
    --cc=linux-um@lists.infradead.org \
    --cc=mhiramat@kernel.org \
    --cc=netdev@vger.kernel.org \
    --cc=torvalds@linux-foundation.org \
    --cc=x86@kernel.org \
    --subject='Re: [PATCH 04/18] maccess: clarify kerneldoc comments' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.