Commit cf38cc9f authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files

locking/refcount: move kernel-doc markups to the proper place 



Changeset a435b9a1 ("locking/refcount: Provide __refcount API to obtain the old value")
added a set of functions starting with __ that have a new
parameter, adding a series of new warnings:

	$ ./scripts/kernel-doc -none include/linux/refcount.h
	include/linux/refcount.h:169: warning: Function parameter or member 'oldp' not described in '__refcount_add_not_zero'
	include/linux/refcount.h:208: warning: Function parameter or member 'oldp' not described in '__refcount_add'
	include/linux/refcount.h:239: warning: Function parameter or member 'oldp' not described in '__refcount_inc_not_zero'
	include/linux/refcount.h:261: warning: Function parameter or member 'oldp' not described in '__refcount_inc'
	include/linux/refcount.h:291: warning: Function parameter or member 'oldp' not described in '__refcount_sub_and_test'
	include/linux/refcount.h:327: warning: Function parameter or member 'oldp' not described in '__refcount_dec_and_test'
	include/linux/refcount.h:347: warning: Function parameter or member 'oldp' not described in '__refcount_dec'

The issue is that the kernel-doc markups are now misplaced,
as they should be added just before the functions.

So, move the kernel-doc markups to the proper places,
in order to drop the warnings.

It should be noticed that git show produces a crappy output,
for this patch without "--patience" flag.

Fixes: a435b9a1 ("locking/refcount: Provide __refcount API to obtain the old value")
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/7985c31d1ace591bc5e1faa05c367f1295b78afd.1603791716.git.mchehab+huawei@kernel.org


Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent e3e7439d

include/linux/refcount.h

+65 −65
Original line number Diff line number Diff line
@@ -147,24 +147,6 @@ static inline unsigned int refcount_read(const refcount_t *r) 
	return atomic_read(&r->refs);

}



/**

 * refcount_add_not_zero - add a value to a refcount unless it is 0

 * @i: the value to add to the refcount

 * @r: the refcount

 *

 * Will saturate at REFCOUNT_SATURATED and WARN.

 *

 * Provides no memory ordering, it is assumed the caller has guaranteed the

 * object memory to be stable (RCU, etc.). It does provide a control dependency

 * and thereby orders future stores. See the comment on top.

 *

 * Use of this function is not recommended for the normal reference counting

 * use case in which references are taken and released one at a time.  In these

 * cases, refcount_inc(), or one of its variants, should instead be used to

 * increment a reference count.

 *

 * Return: false if the passed refcount is 0, true otherwise

 */

static inline __must_check bool __refcount_add_not_zero(int i, refcount_t *r, int *oldp)

{

	int old = refcount_read(r);
@@ -183,17 +165,12 @@ static inline __must_check bool __refcount_add_not_zero(int i, refcount_t *r, in 
	return old;

}



static inline __must_check bool refcount_add_not_zero(int i, refcount_t *r)

{

	return __refcount_add_not_zero(i, r, NULL);

}



/**

 * refcount_add - add a value to a refcount

 * refcount_add_not_zero - add a value to a refcount unless it is 0

 * @i: the value to add to the refcount

 * @r: the refcount

 *

 * Similar to atomic_add(), but will saturate at REFCOUNT_SATURATED and WARN.

 * Will saturate at REFCOUNT_SATURATED and WARN.

 *

 * Provides no memory ordering, it is assumed the caller has guaranteed the

 * object memory to be stable (RCU, etc.). It does provide a control dependency
@@ -203,7 +180,14 @@ static inline __must_check bool refcount_add_not_zero(int i, refcount_t *r) 
 * use case in which references are taken and released one at a time.  In these

 * cases, refcount_inc(), or one of its variants, should instead be used to

 * increment a reference count.

 *

 * Return: false if the passed refcount is 0, true otherwise

 */

static inline __must_check bool refcount_add_not_zero(int i, refcount_t *r)

{

	return __refcount_add_not_zero(i, r, NULL);

}



static inline void __refcount_add(int i, refcount_t *r, int *oldp)

{

	int old = atomic_fetch_add_relaxed(i, &r->refs);
@@ -217,11 +201,32 @@ static inline void __refcount_add(int i, refcount_t *r, int *oldp) 
		refcount_warn_saturate(r, REFCOUNT_ADD_OVF);

}



/**

 * refcount_add - add a value to a refcount

 * @i: the value to add to the refcount

 * @r: the refcount

 *

 * Similar to atomic_add(), but will saturate at REFCOUNT_SATURATED and WARN.

 *

 * Provides no memory ordering, it is assumed the caller has guaranteed the

 * object memory to be stable (RCU, etc.). It does provide a control dependency

 * and thereby orders future stores. See the comment on top.

 *

 * Use of this function is not recommended for the normal reference counting

 * use case in which references are taken and released one at a time.  In these

 * cases, refcount_inc(), or one of its variants, should instead be used to

 * increment a reference count.

 */

static inline void refcount_add(int i, refcount_t *r)

{

	__refcount_add(i, r, NULL);

}



static inline __must_check bool __refcount_inc_not_zero(refcount_t *r, int *oldp)

{

	return __refcount_add_not_zero(1, r, oldp);

}



/**

 * refcount_inc_not_zero - increment a refcount unless it is 0

 * @r: the refcount to increment
@@ -235,14 +240,14 @@ static inline void refcount_add(int i, refcount_t *r) 
 *

 * Return: true if the increment was successful, false otherwise

 */

static inline __must_check bool __refcount_inc_not_zero(refcount_t *r, int *oldp)

static inline __must_check bool refcount_inc_not_zero(refcount_t *r)

{

	return __refcount_add_not_zero(1, r, oldp);

	return __refcount_inc_not_zero(r, NULL);

}



static inline __must_check bool refcount_inc_not_zero(refcount_t *r)

static inline void __refcount_inc(refcount_t *r, int *oldp)

{

	return __refcount_inc_not_zero(r, NULL);

	__refcount_add(1, r, oldp);

}



/**
@@ -257,14 +262,27 @@ static inline __must_check bool refcount_inc_not_zero(refcount_t *r) 
 * Will WARN if the refcount is 0, as this represents a possible use-after-free

 * condition.

 */

static inline void __refcount_inc(refcount_t *r, int *oldp)

static inline void refcount_inc(refcount_t *r)

{

	__refcount_add(1, r, oldp);

	__refcount_inc(r, NULL);

}



static inline void refcount_inc(refcount_t *r)

static inline __must_check bool __refcount_sub_and_test(int i, refcount_t *r, int *oldp)

{

	__refcount_inc(r, NULL);

	int old = atomic_fetch_sub_release(i, &r->refs);



	if (oldp)

		*oldp = old;



	if (old == i) {

		smp_acquire__after_ctrl_dep();

		return true;

	}



	if (unlikely(old < 0 || old - i < 0))

		refcount_warn_saturate(r, REFCOUNT_SUB_UAF);



	return false;

}



/**
@@ -287,27 +305,14 @@ static inline void refcount_inc(refcount_t *r) 
 *

 * Return: true if the resulting refcount is 0, false otherwise

 */

static inline __must_check bool __refcount_sub_and_test(int i, refcount_t *r, int *oldp)

static inline __must_check bool refcount_sub_and_test(int i, refcount_t *r)

{

	int old = atomic_fetch_sub_release(i, &r->refs);



	if (oldp)

		*oldp = old;



	if (old == i) {

		smp_acquire__after_ctrl_dep();

		return true;

	}



	if (unlikely(old < 0 || old - i < 0))

		refcount_warn_saturate(r, REFCOUNT_SUB_UAF);



	return false;

	return __refcount_sub_and_test(i, r, NULL);

}



static inline __must_check bool refcount_sub_and_test(int i, refcount_t *r)

static inline __must_check bool __refcount_dec_and_test(refcount_t *r, int *oldp)

{

	return __refcount_sub_and_test(i, r, NULL);

	return __refcount_sub_and_test(1, r, oldp);

}



/**
@@ -323,26 +328,11 @@ static inline __must_check bool refcount_sub_and_test(int i, refcount_t *r) 
 *

 * Return: true if the resulting refcount is 0, false otherwise

 */

static inline __must_check bool __refcount_dec_and_test(refcount_t *r, int *oldp)

{

	return __refcount_sub_and_test(1, r, oldp);

}



static inline __must_check bool refcount_dec_and_test(refcount_t *r)

{

	return __refcount_dec_and_test(r, NULL);

}



/**

 * refcount_dec - decrement a refcount

 * @r: the refcount

 *

 * Similar to atomic_dec(), it will WARN on underflow and fail to decrement

 * when saturated at REFCOUNT_SATURATED.

 *

 * Provides release memory ordering, such that prior loads and stores are done

 * before.

 */

static inline void __refcount_dec(refcount_t *r, int *oldp)

{

	int old = atomic_fetch_sub_release(1, &r->refs);
@@ -354,6 +344,16 @@ static inline void __refcount_dec(refcount_t *r, int *oldp) 
		refcount_warn_saturate(r, REFCOUNT_DEC_LEAK);

}



/**

 * refcount_dec - decrement a refcount

 * @r: the refcount

 *

 * Similar to atomic_dec(), it will WARN on underflow and fail to decrement

 * when saturated at REFCOUNT_SATURATED.

 *

 * Provides release memory ordering, such that prior loads and stores are done

 * before.

 */

static inline void refcount_dec(refcount_t *r)

{

	__refcount_dec(r, NULL);

CRA Git | Maintained and supported by SUSTech CRA and CCSE