linux-next: build warning after merge of the rcu tree
Subsystems (3)
Hi all,
After merging the rcu tree, today's linux-next build (htmldocs) produced this warning:
Documentation/RCU/rcubarrier.rst:205: WARNING: Literal block ends without a blank line; unexpected unindent.
Introduced by commit
21c2e3909721 ("doc: Update rcubarrier.rst")
Signature · 2 lines
Cheers, Stephen Rothwell
Paul E. McKenney
maintainerQuoted 10 lines · Stephen Rothwell
Hi all,
After merging the rcu tree, today's linux-next build (htmldocs) produced this warning:
Documentation/RCU/rcubarrier.rst:205: WARNING: Literal block ends without a blank line; unexpected unindent.Introduced by commit
21c2e3909721("doc: Updatercubarrier.rst")
Huh. I guess that numbered code samples are not supposed to have more than nine lines? Ah well, easy to fix by going back to left-justified numbers. I was wondering about that!
Apologies for the hassle!
Thanx, Paul
[-Cc: sfr, linux-next, +Cc: rcu]
Hi Paul,
Quoted 6 lines · Paul E. McKenney
Quoted 5 lines · Stephen Rothwell
Hi all,
After merging the rcu tree, today's linux-next build (htmldocs) produced this warning:
Quoted 8 lines
Quoted 5 lines
Documentation/RCU/rcubarrier.rst:205: WARNING: Literal block ends without a blank line; unexpected unindent.Introduced by commit
21c2e3909721("doc: Updatercubarrier.rst")Huh. I guess that numbered code samples are not supposed to have more than nine lines?
No, the problem was that line 10 of the snippet had the same indent level (ie, no indent) as the line above the snippet and was interpreted as the end of literal block.
Quoted 2 lines
Ah well, easy to fix by going back to left-justified
numbers. I was wondering about that!
Appended is a POC patch (relative to current dev of -rcu tree) making them right-justified and compatible with sphinx processing.
Hope this helps, Akira
Quoted 4 lines
Apologies for the hassle!
Thanx, Paul
Documentation/RCU/rcubarrier.rst +10 -10
@@ -193,16 +193,16 @@ which point, all earlier RCU callbacks are guaranteed to have completed. The original code for rcu_barrier() was roughly as follows:: - 1 void rcu_barrier(void) - 2 { - 3 BUG_ON(in_interrupt()); - 4 /* Take cpucontrol mutex to protect against CPU hotplug */ - 5 mutex_lock(&rcu_barrier_mutex); - 6 init_completion(&rcu_barrier_completion); - 7 atomic_set(&rcu_barrier_cpu_count, 1); - 8 on_each_cpu(rcu_barrier_func, NULL, 0, 1); - 9 if (atomic_dec_and_test(&rcu_barrier_cpu_count)) - 10 complete(&rcu_barrier_completion); + 1 void rcu_barrier(void) + 2 { + 3 BUG_ON(in_interrupt()); + 4 /* Take cpucontrol mutex to protect against CPU hotplug */ + 5 mutex_lock(&rcu_barrier_mutex); + 6 init_completion(&rcu_barrier_completion); + 7 atomic_set(&rcu_barrier_cpu_count, 1); + 8 on_each_cpu(rcu_barrier_func, NULL, 0, 1); + 9 if (atomic_dec_and_test(&rcu_barrier_cpu_count)) + 10 complete(&rcu_barrier_completion); 11 wait_for_completion(&rcu_barrier_completion); 12 mutex_unlock(&rcu_barrier_mutex); 13 }
PATCH 1/1 Documentation: RCU: use code blocks with autogenerated line (was: Re: linux-next: build warning after merge of the rcu tree)
In reply to Paul E. McKenneyQuoted 8 lines · Paul E. McKenney
Quoted 7 lines · Stephen Rothwell
Hi all,
After merging the rcu tree, today's linux-next build (htmldocs) produced this warning:
Documentation/RCU/rcubarrier.rst:205: WARNING: Literal block ends without a blank line; unexpected unindent.
Quoted 8 lines
Quoted 3 lines
Introduced by commit
21c2e3909721("doc: Updatercubarrier.rst")Huh. I guess that numbered code samples are not supposed to have more than nine lines? Ah well, easy to fix by going back to left-justified numbers. I was wondering about that!
I think the proper fix is just let Sphinx generates line number:
---- >8 ----
From 5cea54b61b2dbf2ec5e00479c6c8f9e190b49091 Mon Sep 17 00:00:00 2001
From: Bagas Sanjaya <[email protected]>
Date: Mon, 7 Nov 2022 15:41:31 +0700
Subject: [PATCH] Documentation: RCU: use code blocks with autogenerated line
numbers in RCU barrier doc
Recently Stephen Rothwell reported htmldocs warning in Documentation/RCU/rcubarrier.rst when merging rcu tree [1], which has been fixed by left-justifying the culprit line numbers. However, similar issues can occur when line numbers are manually added without caution.
Instead, use code-block syntax with :linenos: option, which automatically generates line numbers in code snippets.
--- Documentation/RCU/rcubarrier.rst | 213 +++++++++++++++++-------------- 1 file changed, 114 insertions(+), 99 deletions(-)
Documentation/RCU/rcubarrier.rst +114 -99
@@ -70,81 +70,87 @@ If your module uses multiple srcu_struct structures, then it must also use multiple invocations of srcu_barrier() when unloading that module. For example, if it uses call_rcu(), call_srcu() on srcu_struct_1, and call_srcu() on srcu_struct_2, then the following three lines of code -will be required when unloading:: +will be required when unloading: - 1 rcu_barrier(); - 2 srcu_barrier(&srcu_struct_1); - 3 srcu_barrier(&srcu_struct_2); +.. code-block:: c + :linenos: + + rcu_barrier(); + srcu_barrier(&srcu_struct_1); + srcu_barrier(&srcu_struct_2); If latency is of the essence, workqueues could be used to run these three functions concurrently. An ancient version of the rcutorture module makes use of rcu_barrier() -in its exit function as follows:: +in its exit function as follows: - 1 static void - 2 rcu_torture_cleanup(void) - 3 { - 4 int i; - 5 - 6 fullstop = 1; - 7 if (shuffler_task != NULL) { - 8 VERBOSE_PRINTK_STRING("Stopping rcu_torture_shuffle task"); - 9 kthread_stop(shuffler_task); - 10 } - 11 shuffler_task = NULL; - 12 - 13 if (writer_task != NULL) { - 14 VERBOSE_PRINTK_STRING("Stopping rcu_torture_writer task"); - 15 kthread_stop(writer_task); - 16 } - 17 writer_task = NULL; - 18 - 19 if (reader_tasks != NULL) { - 20 for (i = 0; i < nrealreaders; i++) { - 21 if (reader_tasks[i] != NULL) { - 22 VERBOSE_PRINTK_STRING( - 23 "Stopping rcu_torture_reader task"); - 24 kthread_stop(reader_tasks[i]); - 25 } - 26 reader_tasks[i] = NULL; - 27 } - 28 kfree(reader_tasks); - 29 reader_tasks = NULL; - 30 } - 31 rcu_torture_current = NULL; - 32 - 33 if (fakewriter_tasks != NULL) { - 34 for (i = 0; i < nfakewriters; i++) { - 35 if (fakewriter_tasks[i] != NULL) { - 36 VERBOSE_PRINTK_STRING( - 37 "Stopping rcu_torture_fakewriter task"); - 38 kthread_stop(fakewriter_tasks[i]); - 39 } - 40 fakewriter_tasks[i] = NULL; - 41 } - 42 kfree(fakewriter_tasks); - 43 fakewriter_tasks = NULL; - 44 } - 45 - 46 if (stats_task != NULL) { - 47 VERBOSE_PRINTK_STRING("Stopping rcu_torture_stats task"); - 48 kthread_stop(stats_task); - 49 } - 50 stats_task = NULL; - 51 - 52 /* Wait for all RCU callbacks to fire. */ - 53 rcu_barrier(); - 54 - 55 rcu_torture_stats_print(); /* -After- the stats thread is stopped! */ - 56 - 57 if (cur_ops->cleanup != NULL) - 58 cur_ops->cleanup(); - 59 if (atomic_read(&n_rcu_torture_error)) - 60 rcu_torture_print_module_parms("End of test: FAILURE"); - 61 else - 62 rcu_torture_print_module_parms("End of test: SUCCESS"); - 63 } +.. code-block:: c + :linenos: + + static void + rcu_torture_cleanup(void) + { + int i; + + fullstop = 1; + if (shuffler_task != NULL) { + VERBOSE_PRINTK_STRING("Stopping rcu_torture_shuffle task"); + kthread_stop(shuffler_task); + } + shuffler_task = NULL; + + if (writer_task != NULL) { + VERBOSE_PRINTK_STRING("Stopping rcu_torture_writer task"); + kthread_stop(writer_task); + } + writer_task = NULL; + + if (reader_tasks != NULL) { + for (i = 0; i < nrealreaders; i++) { + if (reader_tasks[i] != NULL) { + VERBOSE_PRINTK_STRING( + "Stopping rcu_torture_reader task"); + kthread_stop(reader_tasks[i]); + } + reader_tasks[i] = NULL; + } + kfree(reader_tasks); + reader_tasks = NULL; + } + rcu_torture_current = NULL; + + if (fakewriter_tasks != NULL) { + for (i = 0; i < nfakewriters; i++) { + if (fakewriter_tasks[i] != NULL) { + VERBOSE_PRINTK_STRING( + "Stopping rcu_torture_fakewriter task"); + kthread_stop(fakewriter_tasks[i]); + } + fakewriter_tasks[i] = NULL; + } + kfree(fakewriter_tasks); + fakewriter_tasks = NULL; + } + + if (stats_task != NULL) { + VERBOSE_PRINTK_STRING("Stopping rcu_torture_stats task"); + kthread_stop(stats_task); + } + stats_task = NULL; + + /* Wait for all RCU callbacks to fire. */ + rcu_barrier(); + + rcu_torture_stats_print(); /* -After- the stats thread is stopped! */ + + if (cur_ops->cleanup != NULL) + cur_ops->cleanup(); + if (atomic_read(&n_rcu_torture_error)) + rcu_torture_print_module_parms("End of test: FAILURE"); + else + rcu_torture_print_module_parms("End of test: SUCCESS"); + } Line 6 sets a global variable that prevents any RCU callbacks from re-posting themselves. This will not be necessary in most cases, since
@@ -191,21 +197,24 @@ queues. His implementation queues an RCU callback on each of the per-CPU callback queues, and then waits until they have all started executing, at which point, all earlier RCU callbacks are guaranteed to have completed. -The original code for rcu_barrier() was roughly as follows:: +The original code for rcu_barrier() was roughly as follows: - 1 void rcu_barrier(void) - 2 { - 3 BUG_ON(in_interrupt()); - 4 /* Take cpucontrol mutex to protect against CPU hotplug */ - 5 mutex_lock(&rcu_barrier_mutex); - 6 init_completion(&rcu_barrier_completion); - 7 atomic_set(&rcu_barrier_cpu_count, 1); - 8 on_each_cpu(rcu_barrier_func, NULL, 0, 1); - 9 if (atomic_dec_and_test(&rcu_barrier_cpu_count)) - 10 complete(&rcu_barrier_completion); - 11 wait_for_completion(&rcu_barrier_completion); - 12 mutex_unlock(&rcu_barrier_mutex); - 13 } +.. code-block:: c + :linenos: + + void rcu_barrier(void) + { + BUG_ON(in_interrupt()); + /* Take cpucontrol mutex to protect against CPU hotplug */ + mutex_lock(&rcu_barrier_mutex); + init_completion(&rcu_barrier_completion); + atomic_set(&rcu_barrier_cpu_count, 1); + on_each_cpu(rcu_barrier_func, NULL, 0, 1); + if (atomic_dec_and_test(&rcu_barrier_cpu_count)) + complete(&rcu_barrier_completion); + wait_for_completion(&rcu_barrier_completion); + mutex_unlock(&rcu_barrier_mutex); + } Line 3 verifies that the caller is in process context, and lines 5 and 12 use rcu_barrier_mutex to ensure that only one rcu_barrier() is using the
@@ -230,18 +239,21 @@ This code was rewritten in 2008 and several times thereafter, but this still gives the general idea. The rcu_barrier_func() runs on each CPU, where it invokes call_rcu() -to post an RCU callback, as follows:: +to post an RCU callback, as follows: - 1 static void rcu_barrier_func(void *notused) - 2 { - 3 int cpu = smp_processor_id(); - 4 struct rcu_data *rdp = &per_cpu(rcu_data, cpu); - 5 struct rcu_head *head; - 6 - 7 head = &rdp->barrier; - 8 atomic_inc(&rcu_barrier_cpu_count); - 9 call_rcu(head, rcu_barrier_callback); - 10 } +.. code-block:: c + :linenos: + + static void rcu_barrier_func(void *notused) + { + int cpu = smp_processor_id(); + struct rcu_data *rdp = &per_cpu(rcu_data, cpu); + struct rcu_head *head; + + head = &rdp->barrier; + atomic_inc(&rcu_barrier_cpu_count); + call_rcu(head, rcu_barrier_callback); + } Lines 3 and 4 locate RCU's internal per-CPU rcu_data structure, which contains the struct rcu_head that needed for the later call to
@@ -252,13 +264,16 @@ the current CPU's queue. The rcu_barrier_callback() function simply atomically decrements the rcu_barrier_cpu_count variable and finalizes the completion when it -reaches zero, as follows:: +reaches zero, as follows: - 1 static void rcu_barrier_callback(struct rcu_head *notused) - 2 { - 3 if (atomic_dec_and_test(&rcu_barrier_cpu_count)) - 4 complete(&rcu_barrier_completion); - 5 } +.. code-block:: c + :linenos: + + static void rcu_barrier_callback(struct rcu_head *notused) + { + if (atomic_dec_and_test(&rcu_barrier_cpu_count)) + complete(&rcu_barrier_completion); + } .. _rcubarrier_quiz_3:
base-commit: 2c9ea2f2e0a56cbf6931992812bffe47506f23d0
Thanks.
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH 1/1 Documentation: RCU: use code blocks with autogenerated line (was: Re: linux-next: build warning after merge of the rcu tree)
Hi Bagas,
Quoted 11 lines · Bagas Sanjaya
Quoted 10 lines · Paul E. McKenney
Quoted 9 lines · Stephen Rothwell
Hi all,
After merging the rcu tree, today's linux-next build (htmldocs) produced this warning:
Documentation/RCU/rcubarrier.rst:205: WARNING: Literal block ends without a blank line; unexpected unindent.Introduced by commit
Quoted 8 lines
Quoted 6 lines
Quoted 1 line
21c2e3909721("doc: Updatercubarrier.rst")Huh. I guess that numbered code samples are not supposed to have more than nine lines? Ah well, easy to fix by going back to left-justified numbers. I was wondering about that!
I think the proper fix is just let Sphinx generates line number:
That might be true if all you care about were the generated documents, but we need to pay attention to readers of .rst files as plain-text.
There are a bunch of references to line numbers in RCU documents. If explicit line numbers are removed from snippets, such readers need to count the lines by themselves, which doesn't sound reasonable to me.
If you can put labels to referenced lines within code snippets, auto generation of line numbers might work, but as far as I know, Sphinx doesn't provide such a nice feature.
Of course, you can prove me wrong.
Thanks, Akira
Paul E. McKenney
maintainerRe: [PATCH] Documentation: RCU: use code blocks with autogenerated line (was: Re: linux-next: build warning after merge of the rcu tree)
Quoted 30 lines · Akira Yokosawa
Hi Bagas,
Quoted 11 lines · Bagas Sanjaya
Quoted 10 lines · Paul E. McKenney
Quoted 9 lines · Stephen Rothwell
Hi all,
After merging the rcu tree, today's linux-next build (htmldocs) produced this warning:
Documentation/RCU/rcubarrier.rst:205: WARNING: Literal block ends without a blank line; unexpected unindent.Introduced by commit
Quoted 8 lines
Quoted 6 lines
Quoted 1 line
21c2e3909721("doc: Updatercubarrier.rst")Huh. I guess that numbered code samples are not supposed to have more than nine lines? Ah well, easy to fix by going back to left-justified numbers. I was wondering about that!
I think the proper fix is just let Sphinx generates line number:
That might be true if all you care about were the generated documents, but we need to pay attention to readers of .rst files as plain-text.
There are a bunch of references to line numbers in RCU documents. If explicit line numbers are removed from snippets, such readers need to count the lines by themselves, which doesn't sound reasonable to me.
Quoted 5 lines
If you can put labels to referenced lines within code snippets, auto generation of line numbers might work, but as far as I know, Sphinx doesn't provide such a nice feature.
Of course, you can prove me wrong.
I will give Bagas a few days to prove Akira wrong. ;-)
Either way, thank you both for looking into this!
Thanx, Paul
Re: [PATCH] Documentation: RCU: use code blocks with autogenerated line (was: Re: linux-next: build warning after merge of the rcu tree)
In reply to Akira YokosawaQuoted 7 lines · Akira Yokosawa
That might be true if all you care about were the generated documents, but we need to pay attention to readers of .rst files as plain-text.
There are a bunch of references to line numbers in RCU documents. If explicit line numbers are removed from snippets, such readers need to count the lines by themselves, which doesn't sound reasonable to me.
I think only rcubarrier.rst have explicit references to line numbers.
Also, besides manual line counting, readers seeing rst sources can deduce where actually the lines are from explanation of the snippet. Of course they can make htmldocs and seeing the output if they want.
Quoted 4 lines
If you can put labels to referenced lines within code snippets, auto generation of line numbers might work, but as far as I know, Sphinx doesn't provide such a nice feature.
There's also :emphasize-lines: option to highlight selected line numbers.
Thanks.
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Re: [PATCH] Documentation: RCU: use code blocks with autogenerated line (was: Re: linux-next: build warning after merge of the rcu tree)
[Dropping most CCs]
Quoted 10 lines · Bagas Sanjaya
Quoted 7 lines · Akira Yokosawa
That might be true if all you care about were the generated documents, but we need to pay attention to readers of .rst files as plain-text.
There are a bunch of references to line numbers in RCU documents. If explicit line numbers are removed from snippets, such readers need to count the lines by themselves, which doesn't sound reasonable to me.
I think only
rcubarrier.rsthave explicit references to line numbers.
Oh, I find such references in (not limited to):
- Documentation/RCU/Design/Requirements/Requirements.rst
- Documentation/RCU/Design/Data-Structures/Data-Structures.rst
Quoted 3 lines
Also, besides manual line counting, readers seeing rst sources can deduce where actually the lines are from explanation of the snippet.
Maybe, maybe not... Deducing may take time.
Quoted 2 lines
Of course
they can make htmldocs and seeing the output if they want.
There can be situations where you can't afford such luxuries.
Remember there is a note in Documentation/doc-guide/sphinx.rst which reads:
Please don't go overboard with reStructuredText markup. Keep it simple. For the most part the documentation should be plain text with just enough consistency in formatting that it can be converted to other formats.
My interpretation of above:
.rst sources should be kept as close to plain-text which can be easily understood in dumb terminals, as far as possible.
Quoted 7 lines
Quoted 5 lines
If you can put labels to referenced lines within code snippets, auto generation of line numbers might work, but as far as I know, Sphinx doesn't provide such a nice feature.
There's also :emphasize-lines: option to highlight selected line numbers.
But that option doesn't do any highlighting while viewing .rst files as plain-text. What am I missing?
Thanks, Akira
Quoted 3 lines
Thanks.
Re: [PATCH] Documentation: RCU: use code blocks with autogenerated line (was: Re: linux-next: build warning after merge of the rcu tree)
Quoted 7 lines · Akira Yokosawa
Quoted 1 line
I think only
rcubarrier.rsthave explicit references to line numbers.Oh, I find such references in (not limited to):
-
Documentation/RCU/Design/Requirements/Requirements.rst
-Documentation/RCU/Design/Data-Structures/Data-Structures.rst
Ah, I don't see these above!
Quoted 12 lines
Remember there is a note in
Documentation/doc-guide/sphinx.rstwhich reads:Please don't go overboard with reStructuredText markup. Keep it simple. For the most part the documentation should be plain text with just enough consistency in formatting that it can be converted to other formats.
My interpretation of above:
.rst sources should be kept as close to plain-text which can be easily understood in dumb terminals, as far as possible.
Ah! I always forget that. I'm leaning towards *abusing* the markup, though.
Thanks for the reminder.
Signature · 1 line
An old man doll... just what I always wanted! - Clara