History

seqlock: Properly format kernel-doc code samples

Align the code samples and note sections inside kernel-doc comments with tabs. This way they can be properly parsed and rendered by Sphinx. It also makes the code samples easier to read from text editors.

Ahmed S. Darwish committed 6 years ago

Commit 15cbe671 parent 0d24f651 file · +56 −52Browse files

Unified · Split

include/linux/seqlock.h+56−52
@@ -263,32 +263,32 @@ static inline void raw_write_seqcount_end(seqcount_t *s) · 262 unmodified lines
263263 * atomically, avoiding compiler optimizations; b) to document which writes are
264264 * meant to propagate to the reader critical section. This is necessary because
265265 * neither writes before and after the barrier are enclosed in a seq-writer
266− * critical section that would ensure readers are aware of ongoing writes.
266+ * critical section that would ensure readers are aware of ongoing writes::
267267 *
268− * seqcount_t seq;
269− * bool X = true, Y = false;
268+ * seqcount_t seq;
269+ * bool X = true, Y = false;
270270 *
271− * void read(void)
272− * {
273− * bool x, y;
271+ * void read(void)
272+ * {
273+ * bool x, y;
274274 *
275− * do {
276− * int s = read_seqcount_begin(&seq);
275+ * do {
276+ * int s = read_seqcount_begin(&seq);
277277 *
278− * x = X; y = Y;
278+ * x = X; y = Y;
279279 *
280− * } while (read_seqcount_retry(&seq, s));
280+ * } while (read_seqcount_retry(&seq, s));
281281 *
282− * BUG_ON(!x && !y);
282+ * BUG_ON(!x && !y);
283283 * }
284284 *
285285 * void write(void)
286286 * {
287− * WRITE_ONCE(Y, true);
287+ * WRITE_ONCE(Y, true);
288288 *
289− * raw_write_seqcount_barrier(seq);
289+ * raw_write_seqcount_barrier(seq);
290290 *
291− * WRITE_ONCE(X, false);
291+ * WRITE_ONCE(X, false);
292292 * }
293293 */
294294 static inline void raw_write_seqcount_barrier(seqcount_t *s)
@@ -325,64 +325,68 @@ static inline int raw_read_seqcount_latch(seqcount_t *s) · 30 unmodified lines
325325 * Very simply put: we first modify one copy and then the other. This ensures
326326 * there is always one copy in a stable state, ready to give us an answer.
327327 *
328− * The basic form is a data structure like:
328+ * The basic form is a data structure like::
329329 *
330− * struct latch_struct {
331− * seqcount_t seq;
332− * struct data_struct data[2];
333− * };
330+ * struct latch_struct {
331+ * seqcount_t seq;
332+ * struct data_struct data[2];
333+ * };
334334 *
335335 * Where a modification, which is assumed to be externally serialized, does the
336− * following:
336+ * following::
337337 *
338− * void latch_modify(struct latch_struct *latch, ...)
339− * {
340− * smp_wmb(); <- Ensure that the last data[1] update is visible
341− * latch->seq++;
342− * smp_wmb(); <- Ensure that the seqcount update is visible
338+ * void latch_modify(struct latch_struct *latch, ...)
339+ * {
340+ * smp_wmb(); // Ensure that the last data[1] update is visible
341+ * latch->seq++;
342+ * smp_wmb(); // Ensure that the seqcount update is visible
343343 *
344− * modify(latch->data[0], ...);
344+ * modify(latch->data[0], ...);
345345 *
346− * smp_wmb(); <- Ensure that the data[0] update is visible
347− * latch->seq++;
348− * smp_wmb(); <- Ensure that the seqcount update is visible
346+ * smp_wmb(); // Ensure that the data[0] update is visible
347+ * latch->seq++;
348+ * smp_wmb(); // Ensure that the seqcount update is visible
349349 *
350− * modify(latch->data[1], ...);
351− * }
350+ * modify(latch->data[1], ...);
351+ * }
352352 *
353− * The query will have a form like:
353+ * The query will have a form like::
354354 *
355− * struct entry *latch_query(struct latch_struct *latch, ...)
356− * {
357− * struct entry *entry;
358− * unsigned seq, idx;
355+ * struct entry *latch_query(struct latch_struct *latch, ...)
356+ * {
357+ * struct entry *entry;
358+ * unsigned seq, idx;
359359 *
360− * do {
361− * seq = raw_read_seqcount_latch(&latch->seq);
360+ * do {
361+ * seq = raw_read_seqcount_latch(&latch->seq);
362362 *
363− * idx = seq & 0x01;
364− * entry = data_query(latch->data[idx], ...);
363+ * idx = seq & 0x01;
364+ * entry = data_query(latch->data[idx], ...);
365365 *
366− * smp_rmb();
367− * } while (seq != latch->seq);
366+ * smp_rmb();
367+ * } while (seq != latch->seq);
368368 *
369− * return entry;
370− * }
369+ * return entry;
370+ * }
371371 *
372372 * So during the modification, queries are first redirected to data[1]. Then we
373373 * modify data[0]. When that is complete, we redirect queries back to data[0]
374374 * and we can modify data[1].
375375 *
376− * NOTE: The non-requirement for atomic modifications does _NOT_ include
377− * the publishing of new entries in the case where data is a dynamic
378− * data structure.
376+ * NOTE:
377+ *
378+ * The non-requirement for atomic modifications does _NOT_ include
379+ * the publishing of new entries in the case where data is a dynamic
380+ * data structure.
381+ *
382+ * An iteration might start in data[0] and get suspended long enough
383+ * to miss an entire modification sequence, once it resumes it might
384+ * observe the new entry.
379385 *
380− * An iteration might start in data[0] and get suspended long enough
381− * to miss an entire modification sequence, once it resumes it might
382− * observe the new entry.
386+ * NOTE:
383387 *
384− * NOTE: When data is a dynamic data structure; one should use regular RCU
385− * patterns to manage the lifetimes of the objects within.
388+ * When data is a dynamic data structure; one should use regular RCU
389+ * patterns to manage the lifetimes of the objects within.
386390 */
387391 static inline void raw_write_seqcount_latch(seqcount_t *s)
388392 {