lkml.org 
[lkml]   [2020]   [May]   [19]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v1 10/25] seqlock: Add RST directives to kernel-doc code samples and notes
    Date
    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 <a.darwish@linutronix.de>
    Acked-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
    ---
    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
    \
     
     \ /
      Last update: 2020-05-19 23:47    [W:3.238 / U:0.008 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site