linux-mm.kvack.org archive mirror
 help / color / mirror / Atom feed
From: Andrew Morton <akpm@linux-foundation.org>
To: akpm@linux-foundation.org, ast@kernel.org, daniel@iogearbox.net,
	hch@lst.de, hpa@zytor.com, linux-mm@kvack.org,
	mhiramat@kernel.org, mingo@elte.hu, mm-commits@vger.kernel.org,
	tglx@linutronix.de, torvalds@linux-foundation.org
Subject: [patch 75/93] maccess: clarify kerneldoc comments
Date: Mon, 08 Jun 2020 21:34:07 -0700	[thread overview]
Message-ID: <20200609043407.0_Fv4GM3y%akpm@linux-foundation.org> (raw)
In-Reply-To: <20200608212922.5b7fa74ca3f4e2444441b7f9@linux-foundation.org>

From: Christoph Hellwig <hch@lst.de>
Subject: maccess: clarify kerneldoc comments

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.

Link: http://lkml.kernel.org/r/20200521152301.2587579-5-hch@lst.de
Signed-off-by: Christoph Hellwig <hch@lst.de>
Cc: Alexei Starovoitov <ast@kernel.org>
Cc: Daniel Borkmann <daniel@iogearbox.net>
Cc: "H. Peter Anvin" <hpa@zytor.com>
Cc: Ingo Molnar <mingo@elte.hu>
Cc: Masami Hiramatsu <mhiramat@kernel.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
---

 mm/maccess.c |   60 +++++++++++++++++++++++++++++++++++--------------
 1 file changed, 43 insertions(+), 17 deletions(-)

--- a/mm/maccess.c~maccess-clarify-kerneldoc-comments
+++ a/mm/maccess.c
@@ -31,29 +31,36 @@ probe_write_common(void __user *dst, con
 }
 
 /**
- * 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_lock.  This makes
  * probe_kernel_read() suitable for use within regions where the caller
  * already holds mmap_lock, or other locks which nest inside mmap_lock.
- *
- * 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")));
 
@@ -154,15 +161,34 @@ EXPORT_SYMBOL_GPL(probe_user_write);
  * 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")));
_


  parent reply	other threads:[~2020-06-09  4:34 UTC|newest]

Thread overview: 101+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-06-09  4:29 incoming Andrew Morton
2020-06-09  4:29 ` [patch 01/93] kallsyms/printk: add loglvl to print_ip_sym() Andrew Morton
2020-06-09  4:30 ` [patch 02/93] alpha: add show_stack_loglvl() Andrew Morton
2020-06-09  4:30 ` [patch 03/93] arc: " Andrew Morton
2020-06-09  4:30 ` [patch 04/93] arm/asm: add loglvl to c_backtrace() Andrew Morton
2020-06-09  4:30 ` [patch 05/93] arm: add loglvl to unwind_backtrace() Andrew Morton
2020-06-09  4:30 ` [patch 06/93] arm: add loglvl to dump_backtrace() Andrew Morton
2020-06-09  4:30 ` [patch 07/93] arm: wire up dump_backtrace_{entry,stm} Andrew Morton
2020-06-09  4:30 ` [patch 08/93] arm: add show_stack_loglvl() Andrew Morton
2020-06-09  4:30 ` [patch 09/93] arm64: add loglvl to dump_backtrace() Andrew Morton
2020-06-09  4:30 ` [patch 10/93] arm64: add show_stack_loglvl() Andrew Morton
2020-06-09  4:30 ` [patch 11/93] c6x: " Andrew Morton
2020-06-09  4:30 ` [patch 12/93] csky: " Andrew Morton
2020-06-09  4:30 ` [patch 13/93] h8300: " Andrew Morton
2020-06-09  4:30 ` [patch 14/93] hexagon: " Andrew Morton
2020-06-09  4:30 ` [patch 15/93] ia64: pass log level as arg into ia64_do_show_stack() Andrew Morton
2020-06-09  4:30 ` [patch 16/93] ia64: add show_stack_loglvl() Andrew Morton
2020-06-09  4:30 ` [patch 17/93] m68k: " Andrew Morton
2020-06-09  4:30 ` [patch 18/93] microblaze: add loglvl to microblaze_unwind_inner() Andrew Morton
2020-06-09  4:30 ` [patch 19/93] microblaze: add loglvl to microblaze_unwind() Andrew Morton
2020-06-09  4:30 ` [patch 20/93] microblaze: add show_stack_loglvl() Andrew Morton
2020-06-09  4:30 ` [patch 21/93] mips: " Andrew Morton
2020-06-09  4:31 ` [patch 22/93] nds32: " Andrew Morton
2020-06-09  4:31 ` [patch 23/93] nios2: " Andrew Morton
2020-06-09  4:31 ` [patch 24/93] openrisc: " Andrew Morton
2020-06-09  4:31 ` [patch 25/93] parisc: " Andrew Morton
2020-06-09  4:31 ` [patch 26/93] powerpc: " Andrew Morton
2020-06-09  4:31 ` [patch 27/93] riscv: " Andrew Morton
2020-06-09  4:31 ` [patch 28/93] s390: " Andrew Morton
2020-06-09  4:31 ` [patch 29/93] sh: add loglvl to dump_mem() Andrew Morton
2020-06-09  4:31 ` [patch 30/93] sh: remove needless printk() Andrew Morton
2020-06-09  4:31 ` [patch 31/93] sh: add loglvl to printk_address() Andrew Morton
2020-06-09  4:31 ` [patch 32/93] sh: add loglvl to show_trace() Andrew Morton
2020-06-09  4:31 ` [patch 33/93] sh: add show_stack_loglvl() Andrew Morton
2020-06-09  4:31 ` [patch 34/93] sparc: " Andrew Morton
2020-06-09  4:31 ` [patch 35/93] um/sysrq: remove needless variable sp Andrew Morton
2020-06-09  4:31 ` [patch 36/93] um: add show_stack_loglvl() Andrew Morton
2020-06-09  4:31 ` [patch 37/93] unicore32: remove unused pmode argument in c_backtrace() Andrew Morton
2020-06-09  4:31 ` [patch 38/93] unicore32: add loglvl to c_backtrace() Andrew Morton
2020-06-09  4:31 ` [patch 39/93] unicore32: add show_stack_loglvl() Andrew Morton
2020-06-09  4:31 ` [patch 40/93] x86: add missing const qualifiers for log_lvl Andrew Morton
2020-06-09  4:32 ` [patch 41/93] x86: add show_stack_loglvl() Andrew Morton
2020-06-09  4:32 ` [patch 42/93] xtensa: add loglvl to show_trace() Andrew Morton
2020-06-09  4:32 ` [patch 43/93] xtensa: add show_stack_loglvl() Andrew Morton
2020-06-09  4:32 ` [patch 44/93] sysrq: use show_stack_loglvl() Andrew Morton
2020-06-09  4:32 ` [patch 45/93] x86/amd_gart: print stacktrace for a leak with KERN_ERR Andrew Morton
2020-06-09  4:32 ` [patch 46/93] power: use show_stack_loglvl() Andrew Morton
2020-06-09  4:32 ` [patch 47/93] kdb: don't play with console_loglevel Andrew Morton
2020-06-09  4:32 ` [patch 48/93] sched: print stack trace with KERN_INFO Andrew Morton
2020-06-09  4:32 ` [patch 49/93] kernel: use show_stack_loglvl() Andrew Morton
2020-06-09  4:32 ` [patch 50/93] kernel: rename show_stack_loglvl() => show_stack() Andrew Morton
2020-06-09  4:32 ` [patch 51/93] mm: don't include asm/pgtable.h if linux/mm.h is already included Andrew Morton
2020-06-09  4:32 ` [patch 52/93] mm: introduce include/linux/pgtable.h Andrew Morton
2020-06-09  4:32 ` [patch 53/93] mm: reorder includes after introduction of linux/pgtable.h Andrew Morton
2020-06-09  4:32 ` [patch 54/93] csky: replace definitions of __pXd_offset() with pXd_index() Andrew Morton
2020-06-09  4:32 ` [patch 55/93] m68k/mm/motorola: move comment about page table allocation funcitons Andrew Morton
2020-06-09  4:32 ` [patch 56/93] m68k/mm: move {cache,nocahe}_page() definitions close to their user Andrew Morton
2020-06-09  4:33 ` [patch 57/93] x86/mm: simplify init_trampoline() and surrounding logic Andrew Morton
2020-06-09  4:33 ` [patch 58/93] mm: pgtable: add shortcuts for accessing kernel PMD and PTE Andrew Morton
2020-06-09  4:33 ` [patch 59/93] mm: consolidate pte_index() and pte_offset_*() definitions Andrew Morton
2020-06-09  4:33 ` [patch 60/93] mmap locking API: initial implementation as rwsem wrappers Andrew Morton
2020-06-09  4:33 ` [patch 61/93] MMU notifier: use the new mmap locking API Andrew Morton
2020-06-09  4:33 ` [patch 62/93] DMA reservations: " Andrew Morton
2020-06-09  4:33 ` [patch 63/93] mmap locking API: use coccinelle to convert mmap_sem rwsem call sites Andrew Morton
2020-06-09  4:33 ` [patch 64/93] mmap locking API: convert mmap_sem call sites missed by coccinelle Andrew Morton
2020-06-09  4:33 ` [patch 65/93] mmap locking API: convert nested write lock sites Andrew Morton
2020-06-09  4:33 ` [patch 66/93] mmap locking API: add mmap_read_trylock_non_owner() Andrew Morton
2020-06-09  4:33 ` [patch 67/93] mmap locking API: add MMAP_LOCK_INITIALIZER Andrew Morton
2020-06-09  4:33 ` [patch 68/93] mmap locking API: add mmap_assert_locked() and mmap_assert_write_locked() Andrew Morton
2020-06-09  4:33 ` [patch 69/93] mmap locking API: rename mmap_sem to mmap_lock Andrew Morton
2020-06-09  4:33 ` [patch 70/93] mmap locking API: convert mmap_sem API comments Andrew Morton
2020-06-09  4:33 ` [patch 71/93] mmap locking API: convert mmap_sem comments Andrew Morton
2020-06-09  4:33 ` [patch 72/93] maccess: unexport probe_kernel_write() Andrew Morton
2020-06-09  4:34 ` [patch 73/93] maccess: remove various unused weak aliases Andrew Morton
2020-06-09  4:34 ` [patch 74/93] maccess: remove duplicate kerneldoc comments Andrew Morton
2020-06-09  4:34 ` Andrew Morton [this message]
2020-06-09  4:34 ` [patch 76/93] maccess: update the top of file comment Andrew Morton
2020-06-09  4:34 ` [patch 77/93] maccess: rename strncpy_from_unsafe_user to strncpy_from_user_nofault Andrew Morton
2020-06-09  4:34 ` [patch 78/93] maccess: rename strncpy_from_unsafe_strict to strncpy_from_kernel_nofault Andrew Morton
2020-06-09  4:34 ` [patch 79/93] maccess: rename strnlen_unsafe_user to strnlen_user_nofault Andrew Morton
2020-06-09  4:34 ` [patch 80/93] maccess: remove probe_read_common and probe_write_common Andrew Morton
2020-06-09  4:34 ` [patch 81/93] maccess: unify the probe kernel arch hooks Andrew Morton
2020-06-09  4:34 ` [patch 82/93] bpf: factor out a bpf_trace_copy_string helper Andrew Morton
2020-06-09  4:34 ` [patch 83/93] bpf: handle the compat string in bpf_trace_copy_string better Andrew Morton
2020-06-09  4:34 ` [patch 84/93] bpf:bpf_seq_printf(): handle potentially unsafe format string better Andrew Morton
2020-06-09  4:34 ` [patch 85/93] bpf: rework the compat kernel probe handling Andrew Morton
2020-06-09  4:34 ` [patch 86/93] tracing/kprobes: handle mixed kernel/userspace probes better Andrew Morton
2020-06-09  4:34 ` [patch 87/93] maccess: remove strncpy_from_unsafe Andrew Morton
2020-06-09  4:34 ` [patch 88/93] maccess: always use strict semantics for probe_kernel_read Andrew Morton
2020-06-09  4:34 ` [patch 89/93] maccess: move user access routines together Andrew Morton
2020-06-09  4:34 ` [patch 90/93] maccess: allow architectures to provide kernel probing directly Andrew Morton
2020-06-09  4:35 ` [patch 91/93] x86: use non-set_fs based maccess routines Andrew Morton
2020-06-09 18:01   ` Linus Torvalds
2020-06-09 18:06     ` Linus Torvalds
2020-06-10  6:57       ` Christoph Hellwig
2020-06-09  4:35 ` [patch 92/93] maccess: return -ERANGE when probe_kernel_read() fails Andrew Morton
2020-06-09  4:35 ` [patch 93/93] include/linux/cache.h: expand documentation over __read_mostly Andrew Morton
2020-06-17 15:51   ` Christopher Lameter
2020-06-09  5:34 ` mmotm 2020-06-08-22-33 uploaded Andrew Morton
2020-06-09  5:36 ` mmotm 2020-06-08-22-35 uploaded Andrew Morton
2020-06-09 16:58 ` incoming Linus Torvalds

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=20200609043407.0_Fv4GM3y%akpm@linux-foundation.org \
    --to=akpm@linux-foundation.org \
    --cc=ast@kernel.org \
    --cc=daniel@iogearbox.net \
    --cc=hch@lst.de \
    --cc=hpa@zytor.com \
    --cc=linux-mm@kvack.org \
    --cc=mhiramat@kernel.org \
    --cc=mingo@elte.hu \
    --cc=mm-commits@vger.kernel.org \
    --cc=tglx@linutronix.de \
    --cc=torvalds@linux-foundation.org \
    --subject='Re: [patch 75/93] 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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).