Fix 26 kernel-doc notation warnings by converting the function
documentation to kernel-doc format.
Warning example:
instrumented.h:155: warning: Function parameter or member 'to' not described in 'instrument_copy_from_user_after'
instrumented.h:155: warning: Function parameter or member 'from' not described in 'instrument_copy_from_user_after'
instrumented.h:155: warning: Function parameter or member 'n' not described in 'instrument_copy_from_user_after'
instrumented.h:155: warning: Function parameter or member 'left' not described in 'instrument_copy_from_user_after'
Fixes: 36e4d4dd4fc4 ("include/linux: Add instrumented.h infrastructure")
Fixes: 00047c2e6d7c ("instrumented.h: Introduce read-write instrumentation hooks")
Fixes: 33b75c1d884e ("instrumented.h: allow instrumenting both sides of copy_from_user()")
Fixes: 888f84a6da4d ("x86: asm: instrument usercopy in get_user() and put_user()")
Signed-off-by: Randy Dunlap <[email protected]>
Cc: Arnd Bergmann <[email protected]>
Cc: Marco Elver <[email protected]>
Cc: Alexander Potapenko <[email protected]>
Cc: Andrew Morton <[email protected]>
Cc: Dmitry Vyukov <[email protected]>
Cc: Paul E. McKenney <[email protected]>
Cc: Ingo Molnar <[email protected]>
---
include/linux/instrumented.h | 63 +++++++++++++--------------------
1 file changed, 26 insertions(+), 37 deletions(-)
diff -- a/include/linux/instrumented.h b/include/linux/instrumented.h
--- a/include/linux/instrumented.h
+++ b/include/linux/instrumented.h
@@ -15,12 +15,11 @@
/**
* instrument_read - instrument regular read access
+ * @v: address of access
+ * @size: size of access
*
* Instrument a regular read access. The instrumentation should be inserted
* before the actual read happens.
- *
- * @ptr address of access
- * @size size of access
*/
static __always_inline void instrument_read(const volatile void *v, size_t size)
{
@@ -30,12 +29,11 @@ static __always_inline void instrument_r
/**
* instrument_write - instrument regular write access
+ * @v: address of access
+ * @size: size of access
*
* Instrument a regular write access. The instrumentation should be inserted
* before the actual write happens.
- *
- * @ptr address of access
- * @size size of access
*/
static __always_inline void instrument_write(const volatile void *v, size_t size)
{
@@ -45,12 +43,11 @@ static __always_inline void instrument_w
/**
* instrument_read_write - instrument regular read-write access
+ * @v: address of access
+ * @size: size of access
*
* Instrument a regular write access. The instrumentation should be inserted
* before the actual write happens.
- *
- * @ptr address of access
- * @size size of access
*/
static __always_inline void instrument_read_write(const volatile void *v, size_t size)
{
@@ -60,12 +57,11 @@ static __always_inline void instrument_r
/**
* instrument_atomic_read - instrument atomic read access
+ * @v: address of access
+ * @size: size of access
*
* Instrument an atomic read access. The instrumentation should be inserted
* before the actual read happens.
- *
- * @ptr address of access
- * @size size of access
*/
static __always_inline void instrument_atomic_read(const volatile void *v, size_t size)
{
@@ -75,12 +71,11 @@ static __always_inline void instrument_a
/**
* instrument_atomic_write - instrument atomic write access
+ * @v: address of access
+ * @size: size of access
*
* Instrument an atomic write access. The instrumentation should be inserted
* before the actual write happens.
- *
- * @ptr address of access
- * @size size of access
*/
static __always_inline void instrument_atomic_write(const volatile void *v, size_t size)
{
@@ -90,12 +85,11 @@ static __always_inline void instrument_a
/**
* instrument_atomic_read_write - instrument atomic read-write access
+ * @v: address of access
+ * @size: size of access
*
* Instrument an atomic read-write access. The instrumentation should be
* inserted before the actual write happens.
- *
- * @ptr address of access
- * @size size of access
*/
static __always_inline void instrument_atomic_read_write(const volatile void *v, size_t size)
{
@@ -105,13 +99,12 @@ static __always_inline void instrument_a
/**
* instrument_copy_to_user - instrument reads of copy_to_user
+ * @to: destination address
+ * @from: source address
+ * @n: number of bytes to copy
*
* Instrument reads from kernel memory, that are due to copy_to_user (and
* variants). The instrumentation must be inserted before the accesses.
- *
- * @to destination address
- * @from source address
- * @n number of bytes to copy
*/
static __always_inline void
instrument_copy_to_user(void __user *to, const void *from, unsigned long n)
@@ -123,13 +116,12 @@ instrument_copy_to_user(void __user *to,
/**
* instrument_copy_from_user_before - add instrumentation before copy_from_user
+ * @to: destination address
+ * @from: source address
+ * @n: number of bytes to copy
*
* Instrument writes to kernel memory, that are due to copy_from_user (and
* variants). The instrumentation should be inserted before the accesses.
- *
- * @to destination address
- * @from source address
- * @n number of bytes to copy
*/
static __always_inline void
instrument_copy_from_user_before(const void *to, const void __user *from, unsigned long n)
@@ -140,14 +132,13 @@ instrument_copy_from_user_before(const v
/**
* instrument_copy_from_user_after - add instrumentation after copy_from_user
+ * @to: destination address
+ * @from: source address
+ * @n: number of bytes to copy
+ * @left: number of bytes not copied (as returned by copy_from_user)
*
* Instrument writes to kernel memory, that are due to copy_from_user (and
* variants). The instrumentation should be inserted after the accesses.
- *
- * @to destination address
- * @from source address
- * @n number of bytes to copy
- * @left number of bytes not copied (as returned by copy_from_user)
*/
static __always_inline void
instrument_copy_from_user_after(const void *to, const void __user *from,
@@ -158,12 +149,11 @@ instrument_copy_from_user_after(const vo
/**
* instrument_get_user() - add instrumentation to get_user()-like macros
+ * @to: destination variable, may not be address-taken
*
* get_user() and friends are fragile, so it may depend on the implementation
* whether the instrumentation happens before or after the data is copied from
* the userspace.
- *
- * @to destination variable, may not be address-taken
*/
#define instrument_get_user(to) \
({ \
@@ -175,14 +165,13 @@ instrument_copy_from_user_after(const vo
/**
* instrument_put_user() - add instrumentation to put_user()-like macros
+ * @from: source address
+ * @ptr: userspace pointer to copy to
+ * @size: number of bytes to copy
*
* put_user() and friends are fragile, so it may depend on the implementation
* whether the instrumentation happens before or after the data is copied from
* the userspace.
- *
- * @from source address
- * @ptr userspace pointer to copy to
- * @size number of bytes to copy
*/
#define instrument_put_user(from, ptr, size) \
({ \
On Mon, 27 Feb 2023 at 02:17, Randy Dunlap <[email protected]> wrote:
>
> Fix 26 kernel-doc notation warnings by converting the function
> documentation to kernel-doc format.
>
> Warning example:
>
> instrumented.h:155: warning: Function parameter or member 'to' not described in 'instrument_copy_from_user_after'
> instrumented.h:155: warning: Function parameter or member 'from' not described in 'instrument_copy_from_user_after'
> instrumented.h:155: warning: Function parameter or member 'n' not described in 'instrument_copy_from_user_after'
> instrumented.h:155: warning: Function parameter or member 'left' not described in 'instrument_copy_from_user_after'
>
> Fixes: 36e4d4dd4fc4 ("include/linux: Add instrumented.h infrastructure")
> Fixes: 00047c2e6d7c ("instrumented.h: Introduce read-write instrumentation hooks")
> Fixes: 33b75c1d884e ("instrumented.h: allow instrumenting both sides of copy_from_user()")
> Fixes: 888f84a6da4d ("x86: asm: instrument usercopy in get_user() and put_user()")
> Signed-off-by: Randy Dunlap <[email protected]>
> Cc: Arnd Bergmann <[email protected]>
> Cc: Marco Elver <[email protected]>
> Cc: Alexander Potapenko <[email protected]>
> Cc: Andrew Morton <[email protected]>
> Cc: Dmitry Vyukov <[email protected]>
> Cc: Paul E. McKenney <[email protected]>
> Cc: Ingo Molnar <[email protected]>
Reviewed-by: Marco Elver <[email protected]>
Thanks for the fixes.
> ---
> include/linux/instrumented.h | 63 +++++++++++++--------------------
> 1 file changed, 26 insertions(+), 37 deletions(-)
>
> diff -- a/include/linux/instrumented.h b/include/linux/instrumented.h
> --- a/include/linux/instrumented.h
> +++ b/include/linux/instrumented.h
> @@ -15,12 +15,11 @@
>
> /**
> * instrument_read - instrument regular read access
> + * @v: address of access
> + * @size: size of access
> *
> * Instrument a regular read access. The instrumentation should be inserted
> * before the actual read happens.
> - *
> - * @ptr address of access
> - * @size size of access
> */
> static __always_inline void instrument_read(const volatile void *v, size_t size)
> {
> @@ -30,12 +29,11 @@ static __always_inline void instrument_r
>
> /**
> * instrument_write - instrument regular write access
> + * @v: address of access
> + * @size: size of access
> *
> * Instrument a regular write access. The instrumentation should be inserted
> * before the actual write happens.
> - *
> - * @ptr address of access
> - * @size size of access
> */
> static __always_inline void instrument_write(const volatile void *v, size_t size)
> {
> @@ -45,12 +43,11 @@ static __always_inline void instrument_w
>
> /**
> * instrument_read_write - instrument regular read-write access
> + * @v: address of access
> + * @size: size of access
> *
> * Instrument a regular write access. The instrumentation should be inserted
> * before the actual write happens.
> - *
> - * @ptr address of access
> - * @size size of access
> */
> static __always_inline void instrument_read_write(const volatile void *v, size_t size)
> {
> @@ -60,12 +57,11 @@ static __always_inline void instrument_r
>
> /**
> * instrument_atomic_read - instrument atomic read access
> + * @v: address of access
> + * @size: size of access
> *
> * Instrument an atomic read access. The instrumentation should be inserted
> * before the actual read happens.
> - *
> - * @ptr address of access
> - * @size size of access
> */
> static __always_inline void instrument_atomic_read(const volatile void *v, size_t size)
> {
> @@ -75,12 +71,11 @@ static __always_inline void instrument_a
>
> /**
> * instrument_atomic_write - instrument atomic write access
> + * @v: address of access
> + * @size: size of access
> *
> * Instrument an atomic write access. The instrumentation should be inserted
> * before the actual write happens.
> - *
> - * @ptr address of access
> - * @size size of access
> */
> static __always_inline void instrument_atomic_write(const volatile void *v, size_t size)
> {
> @@ -90,12 +85,11 @@ static __always_inline void instrument_a
>
> /**
> * instrument_atomic_read_write - instrument atomic read-write access
> + * @v: address of access
> + * @size: size of access
> *
> * Instrument an atomic read-write access. The instrumentation should be
> * inserted before the actual write happens.
> - *
> - * @ptr address of access
> - * @size size of access
> */
> static __always_inline void instrument_atomic_read_write(const volatile void *v, size_t size)
> {
> @@ -105,13 +99,12 @@ static __always_inline void instrument_a
>
> /**
> * instrument_copy_to_user - instrument reads of copy_to_user
> + * @to: destination address
> + * @from: source address
> + * @n: number of bytes to copy
> *
> * Instrument reads from kernel memory, that are due to copy_to_user (and
> * variants). The instrumentation must be inserted before the accesses.
> - *
> - * @to destination address
> - * @from source address
> - * @n number of bytes to copy
> */
> static __always_inline void
> instrument_copy_to_user(void __user *to, const void *from, unsigned long n)
> @@ -123,13 +116,12 @@ instrument_copy_to_user(void __user *to,
>
> /**
> * instrument_copy_from_user_before - add instrumentation before copy_from_user
> + * @to: destination address
> + * @from: source address
> + * @n: number of bytes to copy
> *
> * Instrument writes to kernel memory, that are due to copy_from_user (and
> * variants). The instrumentation should be inserted before the accesses.
> - *
> - * @to destination address
> - * @from source address
> - * @n number of bytes to copy
> */
> static __always_inline void
> instrument_copy_from_user_before(const void *to, const void __user *from, unsigned long n)
> @@ -140,14 +132,13 @@ instrument_copy_from_user_before(const v
>
> /**
> * instrument_copy_from_user_after - add instrumentation after copy_from_user
> + * @to: destination address
> + * @from: source address
> + * @n: number of bytes to copy
> + * @left: number of bytes not copied (as returned by copy_from_user)
> *
> * Instrument writes to kernel memory, that are due to copy_from_user (and
> * variants). The instrumentation should be inserted after the accesses.
> - *
> - * @to destination address
> - * @from source address
> - * @n number of bytes to copy
> - * @left number of bytes not copied (as returned by copy_from_user)
> */
> static __always_inline void
> instrument_copy_from_user_after(const void *to, const void __user *from,
> @@ -158,12 +149,11 @@ instrument_copy_from_user_after(const vo
>
> /**
> * instrument_get_user() - add instrumentation to get_user()-like macros
> + * @to: destination variable, may not be address-taken
> *
> * get_user() and friends are fragile, so it may depend on the implementation
> * whether the instrumentation happens before or after the data is copied from
> * the userspace.
> - *
> - * @to destination variable, may not be address-taken
> */
> #define instrument_get_user(to) \
> ({ \
> @@ -175,14 +165,13 @@ instrument_copy_from_user_after(const vo
>
> /**
> * instrument_put_user() - add instrumentation to put_user()-like macros
> + * @from: source address
> + * @ptr: userspace pointer to copy to
> + * @size: number of bytes to copy
> *
> * put_user() and friends are fragile, so it may depend on the implementation
> * whether the instrumentation happens before or after the data is copied from
> * the userspace.
> - *
> - * @from source address
> - * @ptr userspace pointer to copy to
> - * @size number of bytes to copy
> */
> #define instrument_put_user(from, ptr, size) \
> ({ \
On Mon, Feb 27, 2023 at 09:12:53AM +0100, Marco Elver wrote:
> On Mon, 27 Feb 2023 at 02:17, Randy Dunlap <[email protected]> wrote:
> >
> > Fix 26 kernel-doc notation warnings by converting the function
> > documentation to kernel-doc format.
> >
> > Warning example:
> >
> > instrumented.h:155: warning: Function parameter or member 'to' not described in 'instrument_copy_from_user_after'
> > instrumented.h:155: warning: Function parameter or member 'from' not described in 'instrument_copy_from_user_after'
> > instrumented.h:155: warning: Function parameter or member 'n' not described in 'instrument_copy_from_user_after'
> > instrumented.h:155: warning: Function parameter or member 'left' not described in 'instrument_copy_from_user_after'
> >
> > Fixes: 36e4d4dd4fc4 ("include/linux: Add instrumented.h infrastructure")
> > Fixes: 00047c2e6d7c ("instrumented.h: Introduce read-write instrumentation hooks")
> > Fixes: 33b75c1d884e ("instrumented.h: allow instrumenting both sides of copy_from_user()")
> > Fixes: 888f84a6da4d ("x86: asm: instrument usercopy in get_user() and put_user()")
> > Signed-off-by: Randy Dunlap <[email protected]>
> > Cc: Arnd Bergmann <[email protected]>
> > Cc: Marco Elver <[email protected]>
> > Cc: Alexander Potapenko <[email protected]>
> > Cc: Andrew Morton <[email protected]>
> > Cc: Dmitry Vyukov <[email protected]>
> > Cc: Paul E. McKenney <[email protected]>
> > Cc: Ingo Molnar <[email protected]>
>
> Reviewed-by: Marco Elver <[email protected]>
>
> Thanks for the fixes.
I pulled this in for v6.4, thank you both!
Thanx, Paul
> > ---
> > include/linux/instrumented.h | 63 +++++++++++++--------------------
> > 1 file changed, 26 insertions(+), 37 deletions(-)
> >
> > diff -- a/include/linux/instrumented.h b/include/linux/instrumented.h
> > --- a/include/linux/instrumented.h
> > +++ b/include/linux/instrumented.h
> > @@ -15,12 +15,11 @@
> >
> > /**
> > * instrument_read - instrument regular read access
> > + * @v: address of access
> > + * @size: size of access
> > *
> > * Instrument a regular read access. The instrumentation should be inserted
> > * before the actual read happens.
> > - *
> > - * @ptr address of access
> > - * @size size of access
> > */
> > static __always_inline void instrument_read(const volatile void *v, size_t size)
> > {
> > @@ -30,12 +29,11 @@ static __always_inline void instrument_r
> >
> > /**
> > * instrument_write - instrument regular write access
> > + * @v: address of access
> > + * @size: size of access
> > *
> > * Instrument a regular write access. The instrumentation should be inserted
> > * before the actual write happens.
> > - *
> > - * @ptr address of access
> > - * @size size of access
> > */
> > static __always_inline void instrument_write(const volatile void *v, size_t size)
> > {
> > @@ -45,12 +43,11 @@ static __always_inline void instrument_w
> >
> > /**
> > * instrument_read_write - instrument regular read-write access
> > + * @v: address of access
> > + * @size: size of access
> > *
> > * Instrument a regular write access. The instrumentation should be inserted
> > * before the actual write happens.
> > - *
> > - * @ptr address of access
> > - * @size size of access
> > */
> > static __always_inline void instrument_read_write(const volatile void *v, size_t size)
> > {
> > @@ -60,12 +57,11 @@ static __always_inline void instrument_r
> >
> > /**
> > * instrument_atomic_read - instrument atomic read access
> > + * @v: address of access
> > + * @size: size of access
> > *
> > * Instrument an atomic read access. The instrumentation should be inserted
> > * before the actual read happens.
> > - *
> > - * @ptr address of access
> > - * @size size of access
> > */
> > static __always_inline void instrument_atomic_read(const volatile void *v, size_t size)
> > {
> > @@ -75,12 +71,11 @@ static __always_inline void instrument_a
> >
> > /**
> > * instrument_atomic_write - instrument atomic write access
> > + * @v: address of access
> > + * @size: size of access
> > *
> > * Instrument an atomic write access. The instrumentation should be inserted
> > * before the actual write happens.
> > - *
> > - * @ptr address of access
> > - * @size size of access
> > */
> > static __always_inline void instrument_atomic_write(const volatile void *v, size_t size)
> > {
> > @@ -90,12 +85,11 @@ static __always_inline void instrument_a
> >
> > /**
> > * instrument_atomic_read_write - instrument atomic read-write access
> > + * @v: address of access
> > + * @size: size of access
> > *
> > * Instrument an atomic read-write access. The instrumentation should be
> > * inserted before the actual write happens.
> > - *
> > - * @ptr address of access
> > - * @size size of access
> > */
> > static __always_inline void instrument_atomic_read_write(const volatile void *v, size_t size)
> > {
> > @@ -105,13 +99,12 @@ static __always_inline void instrument_a
> >
> > /**
> > * instrument_copy_to_user - instrument reads of copy_to_user
> > + * @to: destination address
> > + * @from: source address
> > + * @n: number of bytes to copy
> > *
> > * Instrument reads from kernel memory, that are due to copy_to_user (and
> > * variants). The instrumentation must be inserted before the accesses.
> > - *
> > - * @to destination address
> > - * @from source address
> > - * @n number of bytes to copy
> > */
> > static __always_inline void
> > instrument_copy_to_user(void __user *to, const void *from, unsigned long n)
> > @@ -123,13 +116,12 @@ instrument_copy_to_user(void __user *to,
> >
> > /**
> > * instrument_copy_from_user_before - add instrumentation before copy_from_user
> > + * @to: destination address
> > + * @from: source address
> > + * @n: number of bytes to copy
> > *
> > * Instrument writes to kernel memory, that are due to copy_from_user (and
> > * variants). The instrumentation should be inserted before the accesses.
> > - *
> > - * @to destination address
> > - * @from source address
> > - * @n number of bytes to copy
> > */
> > static __always_inline void
> > instrument_copy_from_user_before(const void *to, const void __user *from, unsigned long n)
> > @@ -140,14 +132,13 @@ instrument_copy_from_user_before(const v
> >
> > /**
> > * instrument_copy_from_user_after - add instrumentation after copy_from_user
> > + * @to: destination address
> > + * @from: source address
> > + * @n: number of bytes to copy
> > + * @left: number of bytes not copied (as returned by copy_from_user)
> > *
> > * Instrument writes to kernel memory, that are due to copy_from_user (and
> > * variants). The instrumentation should be inserted after the accesses.
> > - *
> > - * @to destination address
> > - * @from source address
> > - * @n number of bytes to copy
> > - * @left number of bytes not copied (as returned by copy_from_user)
> > */
> > static __always_inline void
> > instrument_copy_from_user_after(const void *to, const void __user *from,
> > @@ -158,12 +149,11 @@ instrument_copy_from_user_after(const vo
> >
> > /**
> > * instrument_get_user() - add instrumentation to get_user()-like macros
> > + * @to: destination variable, may not be address-taken
> > *
> > * get_user() and friends are fragile, so it may depend on the implementation
> > * whether the instrumentation happens before or after the data is copied from
> > * the userspace.
> > - *
> > - * @to destination variable, may not be address-taken
> > */
> > #define instrument_get_user(to) \
> > ({ \
> > @@ -175,14 +165,13 @@ instrument_copy_from_user_after(const vo
> >
> > /**
> > * instrument_put_user() - add instrumentation to put_user()-like macros
> > + * @from: source address
> > + * @ptr: userspace pointer to copy to
> > + * @size: number of bytes to copy
> > *
> > * put_user() and friends are fragile, so it may depend on the implementation
> > * whether the instrumentation happens before or after the data is copied from
> > * the userspace.
> > - *
> > - * @from source address
> > - * @ptr userspace pointer to copy to
> > - * @size number of bytes to copy
> > */
> > #define instrument_put_user(from, ptr, size) \
> > ({ \