Commit 4f6de12b authored by Christoph Hellwig's avatar Christoph Hellwig Committed by Linus Torvalds

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.
Signed-off-by: default avatarChristoph Hellwig <hch@lst.de>
Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
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>
Link: http://lkml.kernel.org/r/20200521152301.2587579-5-hch@lst.deSigned-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent 3ed74084
...@@ -31,29 +31,36 @@ probe_write_common(void __user *dst, const void *src, size_t size) ...@@ -31,29 +31,36 @@ 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 * @dst: pointer to the buffer that shall take the data
* @src: address to read from * @src: address to read from
* @size: size of the data chunk * @size: size of the data chunk
* *
* Safely read from address @src to the buffer at @dst. If a kernel fault * Same as probe_kernel_read_strict() except that for architectures with
* happens, handle that and return -EFAULT. * 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 * 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 * do_page_fault() doesn't attempt to take mmap_lock. This makes
* probe_kernel_read() suitable for use within regions where the caller * probe_kernel_read() suitable for use within regions where the caller
* already holds mmap_lock, or other locks which nest inside mmap_lock. * 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) long __weak probe_kernel_read_strict(void *dst, const void *src, size_t size)
__attribute__((alias("__probe_kernel_read"))); __attribute__((alias("__probe_kernel_read")));
...@@ -154,15 +161,34 @@ EXPORT_SYMBOL_GPL(probe_user_write); ...@@ -154,15 +161,34 @@ EXPORT_SYMBOL_GPL(probe_user_write);
* If @count is smaller than the length of the string, copies @count-1 bytes, * 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. * sets the last byte of @dst buffer to NUL and returns @count.
* *
* strncpy_from_unsafe_strict() is the same as strncpy_from_unsafe() except * Same as strncpy_from_unsafe_strict() except that for architectures with
* for the case where architectures have non-overlapping user and kernel address * not fully separated user and kernel address spaces this function also works
* ranges: strncpy_from_unsafe_strict() will additionally return -EFAULT for * for user address tanges.
* probing memory on a user address range where strncpy_from_unsafe_user() is *
* supposed to be used instead. * 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) long __weak strncpy_from_unsafe(char *dst, const void *unsafe_addr, long count)
__attribute__((alias("__strncpy_from_unsafe"))); __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 __weak strncpy_from_unsafe_strict(char *dst, const void *unsafe_addr,
long count) long count)
__attribute__((alias("__strncpy_from_unsafe"))); __attribute__((alias("__strncpy_from_unsafe")));
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment