Mark all C code samples inside seqlock.h kernel-doc text with the RST 'code-block: c' directive. Sphinx won't properly format the example code and will produce noisy text indentation warnings otherwise.
Mark all kernel-doc "NOTE" sections with the RST 'attention' directive. Otherwise Sphinx produces "duplicate section name 'NOTE'" warnings. Signed-off-by: Ahmed S. Darwish <[email protected]> Acked-by: Sebastian Andrzej Siewior <[email protected]> --- include/linux/seqlock.h | 82 +++++++++++++++++++++++------------------ 1 file changed, 47 insertions(+), 35 deletions(-) diff --git a/include/linux/seqlock.h b/include/linux/seqlock.h index 2a4af746b1da..dfec0c9c19c4 100644 --- a/include/linux/seqlock.h +++ b/include/linux/seqlock.h @@ -232,6 +232,8 @@ static inline void raw_write_seqcount_end(seqcount_t *s) * usual consistency guarantee. It is one wmb cheaper, because we can * collapse the two back-to-back wmb()s. * + * .. code-block:: c + * * seqcount_t seq; * bool X = true, Y = false; * @@ -292,62 +294,72 @@ static inline int raw_read_seqcount_latch(seqcount_t *s) * * The basic form is a data structure like: * - * struct latch_struct { - * seqcount_t seq; - * struct data_struct data[2]; - * }; + * .. code-block:: c + * + * struct latch_struct { + * seqcount_t seq; + * struct data_struct data[2]; + * }; * * Where a modification, which is assumed to be externally serialized, does the * following: * - * void latch_modify(struct latch_struct *latch, ...) - * { - * smp_wmb(); <- Ensure that the last data[1] update is visible - * latch->seq++; - * smp_wmb(); <- Ensure that the seqcount update is visible + * .. code-block:: c * - * modify(latch->data[0], ...); + * void latch_modify(struct latch_struct *latch, ...) + * { + * smp_wmb(); // Ensure that the last data[1] update is visible + * latch->seq++; + * smp_wmb(); // Ensure that the seqcount update is visible * - * smp_wmb(); <- Ensure that the data[0] update is visible - * latch->seq++; - * smp_wmb(); <- Ensure that the seqcount update is visible + * modify(latch->data[0], ...); * - * modify(latch->data[1], ...); - * } + * smp_wmb(); // Ensure that the data[0] update is visible + * latch->seq++; + * smp_wmb(); // Ensure that the seqcount update is visible + * + * modify(latch->data[1], ...); + * } * * The query will have a form like: * - * struct entry *latch_query(struct latch_struct *latch, ...) - * { - * struct entry *entry; - * unsigned seq, idx; + * .. code-block:: c * - * do { - * seq = raw_read_seqcount_latch(&latch->seq); + * struct entry *latch_query(struct latch_struct *latch, ...) + * { + * struct entry *entry; + * unsigned seq, idx; * - * idx = seq & 0x01; - * entry = data_query(latch->data[idx], ...); + * do { + * seq = raw_read_seqcount_latch(&latch->seq); * - * smp_rmb(); - * } while (seq != latch->seq); + * idx = seq & 0x01; + * entry = data_query(latch->data[idx], ...); * - * return entry; - * } + * smp_rmb(); + * } while (seq != latch->seq); + * + * return entry; + * } * * So during the modification, queries are first redirected to data[1]. Then we * modify data[0]. When that is complete, we redirect queries back to data[0] * and we can modify data[1]. * - * NOTE: The non-requirement for atomic modifications does _NOT_ include - * the publishing of new entries in the case where data is a dynamic - * data structure. + * .. attention:: * - * An iteration might start in data[0] and get suspended long enough - * to miss an entire modification sequence, once it resumes it might - * observe the new entry. + * The non-requirement for atomic modifications does _NOT_ include + * the publishing of new entries in the case where data is a dynamic + * data structure. * - * NOTE: When data is a dynamic data structure; one should use regular RCU - * patterns to manage the lifetimes of the objects within. + * An iteration might start in data[0] and get suspended long enough + * to miss an entire modification sequence, once it resumes it might + * observe the new entry. + * + * .. attention:: + * + * When data is a dynamic data structure; one should use regular RCU + * patterns to manage the lifetimes of the objects within. */ static inline void raw_write_seqcount_latch(seqcount_t *s) { -- 2.20.1
