Commit cb262935 authored by Ahmed S. Darwish's avatar Ahmed S. Darwish Committed by Peter Zijlstra
Browse files

seqlock: kernel-doc: Specify when preemption is automatically altered 



The kernel-doc annotations for sequence counters write side functions
are incomplete: they do not specify when preemption is automatically
disabled and re-enabled.

This has confused a number of call-site developers. Fix it.

Signed-off-by: default avatarAhmed S. Darwish <a.darwish@linutronix.de>
Signed-off-by: default avatarPeter Zijlstra (Intel) <peterz@infradead.org>
Link: https://lkml.kernel.org/r/CAHk-=wikhGExmprXgaW+MVXG1zsGpztBbVwOb23vetk41EtTBQ@mail.gmail.com
parent 66bcfcdf

include/linux/seqlock.h

+11 −6
Original line number Diff line number Diff line
@@ -456,6 +456,8 @@ static inline int do_read_seqcount_retry(const seqcount_t *s, unsigned start) 
/**

 * raw_write_seqcount_begin() - start a seqcount_t write section w/o lockdep

 * @s: Pointer to seqcount_t or any of the seqcount_LOCKNAME_t variants

 *

 * Context: check write_seqcount_begin()

 */

#define raw_write_seqcount_begin(s)					\

do {									\
@@ -475,6 +477,8 @@ static inline void do_raw_write_seqcount_begin(seqcount_t *s) 
/**

 * raw_write_seqcount_end() - end a seqcount_t write section w/o lockdep

 * @s: Pointer to seqcount_t or any of the seqcount_LOCKNAME_t variants

 *

 * Context: check write_seqcount_end()

 */

#define raw_write_seqcount_end(s)					\

do {									\
@@ -498,6 +502,7 @@ static inline void do_raw_write_seqcount_end(seqcount_t *s) 
 * @subclass: lockdep nesting level

 *

 * See Documentation/locking/lockdep-design.rst

 * Context: check write_seqcount_begin()

 */

#define write_seqcount_begin_nested(s, subclass)			\

do {									\
@@ -519,11 +524,10 @@ static inline void do_write_seqcount_begin_nested(seqcount_t *s, int subclass) 
 * write_seqcount_begin() - start a seqcount_t write side critical section

 * @s: Pointer to seqcount_t or any of the seqcount_LOCKNAME_t variants

 *

 * write_seqcount_begin opens a write side critical section of the given

 * seqcount_t.

 *

 * Context: seqcount_t write side critical sections must be serialized and

 * non-preemptible. If readers can be invoked from hardirq or softirq

 * Context: sequence counter write side sections must be serialized and

 * non-preemptible. Preemption will be automatically disabled if and

 * only if the seqcount write serialization lock is associated, and

 * preemptible.  If readers can be invoked from hardirq or softirq

 * context, interrupts or bottom halves must be respectively disabled.

 */

#define write_seqcount_begin(s)						\
@@ -545,7 +549,8 @@ static inline void do_write_seqcount_begin(seqcount_t *s) 
 * write_seqcount_end() - end a seqcount_t write side critical section

 * @s: Pointer to seqcount_t or any of the seqcount_LOCKNAME_t variants

 *

 * The write section must've been opened with write_seqcount_begin().

 * Context: Preemption will be automatically re-enabled if and only if

 * the seqcount write serialization lock is associated, and preemptible.

 */

#define write_seqcount_end(s)						\

do {									\

CRA Git | Maintained and supported by SUSTech CRA and CCSE