leandrof/linux
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Fix reST markup when linking to sections

Browse Source 
During the process of converting the documentation to reST, some links
were converted using the following wrong syntax (and sometimes using %20
instead of spaces):

   `Display text <#section-name-in-html>`__

This syntax isn't valid according to the docutils' spec [1], but more
importantly, it is specific to HTML, since it uses '#' to link to an
HTML anchor.

The right syntax would instead use a docutils hyperlink reference as the
embedded URI to point to the section [2], that is:

   `Display text <Section Name_>`__

This syntax works in both HTML and PDF.

The LaTeX toolchain doesn't mind the HTML anchor syntax when generating
the pdf documentation (make pdfdocs), that is, the build succeeds but
the links don't work, but that syntax causes errors when trying to build
using the not-yet-merged rst2pdf:

   ValueError: format not resolved, probably missing URL scheme or undefined destination target for 'Forcing%20Quiescent%20States'

So, use the correct syntax in order to have it work in all different
output formats.

[1]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#reference-names
[2]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#embedded-uris-and-aliases

Fixes: ccc9971e21 ("docs: rcu: convert some articles from html to ReST")
Fixes: c8cce10a62 ("docs: Fix the reference labels in Locking.rst")
Fixes: e548cdeffc ("docs-rst: convert kernel-locking to ReST")
Fixes: 7ddedebb03 ("ALSA: doc: ReSTize writing-an-alsa-driver document")
Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com>
Reviewed-by: Takashi Iwai <tiwai@suse.de>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/20201228144537.135353-1-nfraprado@protonmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Nícolas F. R. A. Prado 2020-12-28 14:46:07 +00:00 committed by Jonathan Corbet
parent 5c8fe583cc
commit 4f8af077a0
4 changed files with 26 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst
View File

@ -473,7 +473,7 @@ read-side critical sections that follow the idle period (the oval near
the bottom of the diagram above). the bottom of the diagram above).
Plumbing this into the full grace-period execution is described Plumbing this into the full grace-period execution is described
`below <#Forcing%20Quiescent%20States>`__. `below <Forcing Quiescent States_>`__.
CPU-Hotplug Interface CPU-Hotplug Interface
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
@ -494,7 +494,7 @@ mask to detect CPUs having gone offline since the beginning of this
grace period. grace period.
Plumbing this into the full grace-period execution is described Plumbing this into the full grace-period execution is described
`below <#Forcing%20Quiescent%20States>`__. `below <Forcing Quiescent States_>`__.
Forcing Quiescent States Forcing Quiescent States
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
@ -532,7 +532,7 @@ from other CPUs.
| RCU. But this diagram is complex enough as it is, so simplicity | | RCU. But this diagram is complex enough as it is, so simplicity |
| overrode accuracy. You can think of it as poetic license, or you can | | overrode accuracy. You can think of it as poetic license, or you can |
| think of it as misdirection that is resolved in the | | think of it as misdirection that is resolved in the |
| `stitched-together diagram <#Putting%20It%20All%20Together>`__. | | `stitched-together diagram <Putting It All Together_>`__. |
+-----------------------------------------------------------------------+ +-----------------------------------------------------------------------+
Grace-Period Cleanup Grace-Period Cleanup
@ -596,7 +596,7 @@ maintain ordering. For example, if the callback function wakes up a task
that runs on some other CPU, proper ordering must in place in both the that runs on some other CPU, proper ordering must in place in both the
callback function and the task being awakened. To see why this is callback function and the task being awakened. To see why this is
important, consider the top half of the `grace-period important, consider the top half of the `grace-period
cleanup <#Grace-Period%20Cleanup>`__ diagram. The callback might be cleanup`_ diagram. The callback might be
running on a CPU corresponding to the leftmost leaf ``rcu_node`` running on a CPU corresponding to the leftmost leaf ``rcu_node``
structure, and awaken a task that is to run on a CPU corresponding to structure, and awaken a task that is to run on a CPU corresponding to
the rightmost leaf ``rcu_node`` structure, and the grace-period kernel the rightmost leaf ``rcu_node`` structure, and the grace-period kernel

20
Documentation/RCU/Design/Requirements/Requirements.rst
View File

@ -45,7 +45,7 @@ requirements:
#. `Other RCU Flavors`_ #. `Other RCU Flavors`_
#. `Possible Future Changes`_ #. `Possible Future Changes`_
This is followed by a `summary <#Summary>`__, however, the answers to This is followed by a summary_, however, the answers to
each quick quiz immediately follows the quiz. Select the big white space each quick quiz immediately follows the quiz. Select the big white space
with your mouse to see the answer. with your mouse to see the answer.
@ -1096,7 +1096,7 @@ memory barriers.
| case, voluntary context switch) within an RCU read-side critical | | case, voluntary context switch) within an RCU read-side critical |
| section. However, sleeping locks may be used within userspace RCU | | section. However, sleeping locks may be used within userspace RCU |
| read-side critical sections, and also within Linux-kernel sleepable | | read-side critical sections, and also within Linux-kernel sleepable |
| RCU `(SRCU) <#Sleepable%20RCU>`__ read-side critical sections. In | | RCU `(SRCU) <Sleepable RCU_>`__ read-side critical sections. In |
| addition, the -rt patchset turns spinlocks into a sleeping locks so | | addition, the -rt patchset turns spinlocks into a sleeping locks so |
| that the corresponding critical sections can be preempted, which also | | that the corresponding critical sections can be preempted, which also |
| means that these sleeplockified spinlocks (but not other sleeping | | means that these sleeplockified spinlocks (but not other sleeping |
@ -1186,7 +1186,7 @@ non-preemptible (``CONFIG_PREEMPT=n``) kernels, and thus `tiny
RCU <https://lkml.kernel.org/g/20090113221724.GA15307@linux.vnet.ibm.com>`__ RCU <https://lkml.kernel.org/g/20090113221724.GA15307@linux.vnet.ibm.com>`__
was born. Josh Triplett has since taken over the small-memory banner was born. Josh Triplett has since taken over the small-memory banner
with his `Linux kernel tinification <https://tiny.wiki.kernel.org/>`__ with his `Linux kernel tinification <https://tiny.wiki.kernel.org/>`__
project, which resulted in `SRCU <#Sleepable%20RCU>`__ becoming optional project, which resulted in `SRCU <Sleepable RCU_>`__ becoming optional
for those kernels not needing it. for those kernels not needing it.
The remaining performance requirements are, for the most part, The remaining performance requirements are, for the most part,
@ -1457,8 +1457,8 @@ will vary as the value of ``HZ`` varies, and can also be changed using
the relevant Kconfig options and kernel boot parameters. RCU currently the relevant Kconfig options and kernel boot parameters. RCU currently
does not do much sanity checking of these parameters, so please use does not do much sanity checking of these parameters, so please use
caution when changing them. Note that these forward-progress measures caution when changing them. Note that these forward-progress measures
are provided only for RCU, not for `SRCU <#Sleepable%20RCU>`__ or `Tasks are provided only for RCU, not for `SRCU <Sleepable RCU_>`__ or `Tasks
RCU <#Tasks%20RCU>`__. RCU`_.
RCU takes the following steps in ``call_rcu()`` to encourage timely RCU takes the following steps in ``call_rcu()`` to encourage timely
invocation of callbacks when any given non-\ ``rcu_nocbs`` CPU has invocation of callbacks when any given non-\ ``rcu_nocbs`` CPU has
@ -1477,8 +1477,8 @@ encouragement was provided:
Again, these are default values when running at ``HZ=1000``, and can be Again, these are default values when running at ``HZ=1000``, and can be
overridden. Again, these forward-progress measures are provided only for overridden. Again, these forward-progress measures are provided only for
RCU, not for `SRCU <#Sleepable%20RCU>`__ or `Tasks RCU, not for `SRCU <Sleepable RCU_>`__ or `Tasks
RCU <#Tasks%20RCU>`__. Even for RCU, callback-invocation forward RCU`_. Even for RCU, callback-invocation forward
progress for ``rcu_nocbs`` CPUs is much less well-developed, in part progress for ``rcu_nocbs`` CPUs is much less well-developed, in part
because workloads benefiting from ``rcu_nocbs`` CPUs tend to invoke because workloads benefiting from ``rcu_nocbs`` CPUs tend to invoke
``call_rcu()`` relatively infrequently. If workloads emerge that need ``call_rcu()`` relatively infrequently. If workloads emerge that need
@ -1920,7 +1920,7 @@ Hotplug CPU
The Linux kernel supports CPU hotplug, which means that CPUs can come The Linux kernel supports CPU hotplug, which means that CPUs can come
and go. It is of course illegal to use any RCU API member from an and go. It is of course illegal to use any RCU API member from an
offline CPU, with the exception of `SRCU <#Sleepable%20RCU>`__ read-side offline CPU, with the exception of `SRCU <Sleepable RCU_>`__ read-side
critical sections. This requirement was present from day one in critical sections. This requirement was present from day one in
DYNIX/ptx, but on the other hand, the Linux kernel's CPU-hotplug DYNIX/ptx, but on the other hand, the Linux kernel's CPU-hotplug
implementation is “interesting.” implementation is “interesting.”
@ -2177,7 +2177,7 @@ handles these states differently:
However, RCU must be reliably informed as to whether any given CPU is However, RCU must be reliably informed as to whether any given CPU is
currently in the idle loop, and, for ``NO_HZ_FULL``, also whether that currently in the idle loop, and, for ``NO_HZ_FULL``, also whether that
CPU is executing in usermode, as discussed CPU is executing in usermode, as discussed
`earlier <#Energy%20Efficiency>`__. It also requires that the `earlier <Energy Efficiency_>`__. It also requires that the
scheduling-clock interrupt be enabled when RCU needs it to be: scheduling-clock interrupt be enabled when RCU needs it to be:
#. If a CPU is either idle or executing in usermode, and RCU believes it #. If a CPU is either idle or executing in usermode, and RCU believes it
@ -2294,7 +2294,7 @@ Performance, Scalability, Response Time, and Reliability
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expanding on the `earlier Expanding on the `earlier
discussion <#Performance%20and%20Scalability>`__, RCU is used heavily by discussion <Performance and Scalability_>`__, RCU is used heavily by
hot code paths in performance-critical portions of the Linux kernel's hot code paths in performance-critical portions of the Linux kernel's
networking, security, virtualization, and scheduling code paths. RCU networking, security, virtualization, and scheduling code paths. RCU
must therefore use efficient implementations, especially in its must therefore use efficient implementations, especially in its

8
Documentation/kernel-hacking/locking.rst
View File

@ -118,11 +118,11 @@ spinlock, but you may block holding a mutex. If you can't lock a mutex,
your task will suspend itself, and be woken up when the mutex is your task will suspend itself, and be woken up when the mutex is
released. This means the CPU can do something else while you are released. This means the CPU can do something else while you are
waiting. There are many cases when you simply can't sleep (see waiting. There are many cases when you simply can't sleep (see
`What Functions Are Safe To Call From Interrupts? <#sleeping-things>`__), `What Functions Are Safe To Call From Interrupts?`_),
and so have to use a spinlock instead. and so have to use a spinlock instead.
Neither type of lock is recursive: see Neither type of lock is recursive: see
`Deadlock: Simple and Advanced <#deadlock>`__. `Deadlock: Simple and Advanced`_.
Locks and Uniprocessor Kernels Locks and Uniprocessor Kernels
------------------------------ ------------------------------
@ -179,7 +179,7 @@ perfect world).
Note that you can also use spin_lock_irq() or Note that you can also use spin_lock_irq() or
spin_lock_irqsave() here, which stop hardware interrupts spin_lock_irqsave() here, which stop hardware interrupts
as well: see `Hard IRQ Context <#hard-irq-context>`__. as well: see `Hard IRQ Context`_.
This works perfectly for UP as well: the spin lock vanishes, and this This works perfectly for UP as well: the spin lock vanishes, and this
macro simply becomes local_bh_disable() macro simply becomes local_bh_disable()
@ -230,7 +230,7 @@ The Same Softirq
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
The same softirq can run on the other CPUs: you can use a per-CPU array The same softirq can run on the other CPUs: you can use a per-CPU array
(see `Per-CPU Data <#per-cpu-data>`__) for better performance. If you're (see `Per-CPU Data`_) for better performance. If you're
going so far as to use a softirq, you probably care about scalable going so far as to use a softirq, you probably care about scalable
performance enough to justify the extra complexity. performance enough to justify the extra complexity.

16
Documentation/sound/kernel-api/writing-an-alsa-driver.rst
View File

@ -71,7 +71,7 @@ core/oss
The codes for PCM and mixer OSS emulation modules are stored in this The codes for PCM and mixer OSS emulation modules are stored in this
directory. The rawmidi OSS emulation is included in the ALSA rawmidi directory. The rawmidi OSS emulation is included in the ALSA rawmidi
code since it's quite small. The sequencer code is stored in code since it's quite small. The sequencer code is stored in
``core/seq/oss`` directory (see `below <#core-seq-oss>`__). ``core/seq/oss`` directory (see `below <core/seq/oss_>`__).
core/seq core/seq
~~~~~~~~ ~~~~~~~~
@ -382,7 +382,7 @@ where ``enable[dev]`` is the module option.
Each time the ``probe`` callback is called, check the availability of Each time the ``probe`` callback is called, check the availability of
the device. If not available, simply increment the device index and the device. If not available, simply increment the device index and
returns. dev will be incremented also later (`step 7 returns. dev will be incremented also later (`step 7
<#set-the-pci-driver-data-and-return-zero>`__). <7) Set the PCI driver data and return zero._>`__).
2) Create a card instance 2) Create a card instance
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
@ -450,10 +450,10 @@ field contains the information shown in ``/proc/asound/cards``.
5) Create other components, such as mixer, MIDI, etc. 5) Create other components, such as mixer, MIDI, etc.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here you define the basic components such as `PCM <#PCM-Interface>`__, Here you define the basic components such as `PCM <PCM Interface_>`__,
mixer (e.g. `AC97 <#API-for-AC97-Codec>`__), MIDI (e.g. mixer (e.g. `AC97 <API for AC97 Codec_>`__), MIDI (e.g.
`MPU-401 <#MIDI-MPU401-UART-Interface>`__), and other interfaces. `MPU-401 <MIDI (MPU401-UART) Interface_>`__), and other interfaces.
Also, if you want a `proc file <#Proc-Interface>`__, define it here, Also, if you want a `proc file <Proc Interface_>`__, define it here,
too. too.
6) Register the card instance. 6) Register the card instance.
@ -941,7 +941,7 @@ The allocation of an interrupt source is done like this:
chip->irq = pci->irq; chip->irq = pci->irq;
where :c:func:`snd_mychip_interrupt()` is the interrupt handler where :c:func:`snd_mychip_interrupt()` is the interrupt handler
defined `later <#pcm-interface-interrupt-handler>`__. Note that defined `later <PCM Interrupt Handler_>`__. Note that
``chip->irq`` should be defined only when :c:func:`request_irq()` ``chip->irq`` should be defined only when :c:func:`request_irq()`
succeeded. succeeded.
@ -3104,7 +3104,7 @@ processing the output stream in the irq handler.
If the MPU-401 interface shares its interrupt with the other logical If the MPU-401 interface shares its interrupt with the other logical
devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
`below <#MIDI-Interrupt-Handler>`__). `below <MIDI Interrupt Handler_>`__).
Usually, the port address corresponds to the command port and port + 1 Usually, the port address corresponds to the command port and port + 1
corresponds to the data port. If not, you may change the ``cport`` corresponds to the data port. If not, you may change the ``cport``