Commit 7b4ff1ad authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

mutex, futex: adjust kernel-doc markups to generate ReST 



There are a few issues on some kernel-doc markups that was
causing troubles with kernel-doc output on ReST format:

./kernel/futex.c:492: WARNING: Inline emphasis start-string without end-string.
./kernel/futex.c:1264: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:1721: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:2338: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:2426: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:2899: WARNING: Block quote ends without a blank line; unexpected unindent.
./kernel/futex.c:2972: WARNING: Block quote ends without a blank line; unexpected unindent.

Fix them.

No functional changes.

Acked-by: default avatarDarren Hart (VMware) <dvhart@infradead.org>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent e548cdef

include/linux/mutex.h

+3 −3
Original line number Diff line number Diff line
@@ -214,9 +214,9 @@ enum mutex_trylock_recursive_enum { 
 * raisins, and once those are gone this will be removed.

 *

 * Returns:

 *  MUTEX_TRYLOCK_FAILED    - trylock failed,

 *  MUTEX_TRYLOCK_SUCCESS   - lock acquired,

 *  MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.

 *  - MUTEX_TRYLOCK_FAILED    - trylock failed,

 *  - MUTEX_TRYLOCK_SUCCESS   - lock acquired,

 *  - MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.

 */

static inline /* __deprecated */ __must_check enum mutex_trylock_recursive_enum

mutex_trylock_recursive(struct mutex *lock)

kernel/futex.c

+20 −20
Original line number Diff line number Diff line
@@ -488,7 +488,7 @@ static void drop_futex_key_refs(union futex_key *key) 
 *

 * Return: a negative error code or 0

 *

 * The key words are stored in *key on success.

 * The key words are stored in @key on success.

 *

 * For shared mappings, it's (page->index, file_inode(vma->vm_file),

 * offset_within_page).  For private mappings, it's (uaddr, current->mm).
@@ -1259,9 +1259,9 @@ static int lock_pi_update_atomic(u32 __user *uaddr, u32 uval, u32 newval) 
 * @set_waiters:	force setting the FUTEX_WAITERS bit (1) or not (0)

 *

 * Return:

 *  0 - ready to wait;

 *  1 - acquired the lock;

 * <0 - error

 *  -  0 - ready to wait;

 *  -  1 - acquired the lock;

 *  - <0 - error

 *

 * The hb->lock and futex_key refs shall be held by the caller.

 */
@@ -1717,9 +1717,9 @@ void requeue_pi_wake_futex(struct futex_q *q, union futex_key *key, 
 * hb1 and hb2 must be held by the caller.

 *

 * Return:

 *  0 - failed to acquire the lock atomically;

 * >0 - acquired the lock, return value is vpid of the top_waiter

 * <0 - error

 *  -  0 - failed to acquire the lock atomically;

 *  - >0 - acquired the lock, return value is vpid of the top_waiter

 *  - <0 - error

 */

static int futex_proxy_trylock_atomic(u32 __user *pifutex,

				 struct futex_hash_bucket *hb1,
@@ -1785,8 +1785,8 @@ static int futex_proxy_trylock_atomic(u32 __user *pifutex, 
 * uaddr2 atomically on behalf of the top waiter.

 *

 * Return:

 * >=0 - on success, the number of tasks requeued or woken;

 *  <0 - on error

 *  - >=0 - on success, the number of tasks requeued or woken;

 *  -  <0 - on error

 */

static int futex_requeue(u32 __user *uaddr1, unsigned int flags,

			 u32 __user *uaddr2, int nr_wake, int nr_requeue,
@@ -2142,8 +2142,8 @@ static inline void queue_me(struct futex_q *q, struct futex_hash_bucket *hb) 
 * be paired with exactly one earlier call to queue_me().

 *

 * Return:

 *   1 - if the futex_q was still queued (and we removed unqueued it);

 *   0 - if the futex_q was already removed by the waking thread

 *  - 1 - if the futex_q was still queued (and we removed unqueued it);

 *  - 0 - if the futex_q was already removed by the waking thread

 */

static int unqueue_me(struct futex_q *q)

{
@@ -2333,9 +2333,9 @@ static long futex_wait_restart(struct restart_block *restart); 
 * acquire the lock. Must be called with the hb lock held.

 *

 * Return:

 *  1 - success, lock taken;

 *  0 - success, lock not taken;

 * <0 - on error (-EFAULT)

 *  -  1 - success, lock taken;

 *  -  0 - success, lock not taken;

 *  - <0 - on error (-EFAULT)

 */

static int fixup_owner(u32 __user *uaddr, struct futex_q *q, int locked)

{
@@ -2422,8 +2422,8 @@ static void futex_wait_queue_me(struct futex_hash_bucket *hb, struct futex_q *q, 
 * with no q.key reference on failure.

 *

 * Return:

 *  0 - uaddr contains val and hb has been locked;

 * <1 - -EFAULT or -EWOULDBLOCK (uaddr does not contain val) and hb is unlocked

 *  -  0 - uaddr contains val and hb has been locked;

 *  - <1 - -EFAULT or -EWOULDBLOCK (uaddr does not contain val) and hb is unlocked

 */

static int futex_wait_setup(u32 __user *uaddr, u32 val, unsigned int flags,

			   struct futex_q *q, struct futex_hash_bucket **hb)
@@ -2895,8 +2895,8 @@ pi_faulted: 
 * called with the hb lock held.

 *

 * Return:

 *  0 = no early wakeup detected;

 * <0 = -ETIMEDOUT or -ERESTARTNOINTR

 *  -  0 = no early wakeup detected;

 *  - <0 = -ETIMEDOUT or -ERESTARTNOINTR

 */

static inline

int handle_early_requeue_pi_wakeup(struct futex_hash_bucket *hb,
@@ -2968,8 +2968,8 @@ int handle_early_requeue_pi_wakeup(struct futex_hash_bucket *hb, 
 * If 4 or 7, we cleanup and return with -ETIMEDOUT.

 *

 * Return:

 *  0 - On success;

 * <0 - On error

 *  -  0 - On success;

 *  - <0 - On error

 */

static int futex_wait_requeue_pi(u32 __user *uaddr, unsigned int flags,

				 u32 val, ktime_t *abs_time, u32 bitset,

kernel/locking/mutex.c

+3 −3
Original line number Diff line number Diff line
@@ -229,7 +229,7 @@ static void __sched __mutex_lock_slowpath(struct mutex *lock); 
 *

 * (The CONFIG_DEBUG_MUTEXES .config option turns on debugging

 * checks that will enforce the restrictions and will also do

 *   deadlock debugging. )

 * deadlock debugging)

 *

 * This function is similar to (but not equivalent to) down().

 */

CRA Git | Maintained and supported by SUSTech CRA and CCSE