docs: automarkup: linkify git revs
There aren't a ton of references to commits in the documentation, but
they do exist, and we can use automarkup to linkify them to make them
easier to follow.
Use something like this to find references to commits:
git grep -P 'commit.*[0-9a-f]{8,}' Documentation/
Also fix a few of these to standardize on the exact format that is
already used in changelogs.
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20231027115420.205279-1-vegard.nossum@oracle.com
This commit is contained in:
Vegard Nossum
Jonathan Corbet
parent
d591aefc66
commit
86b17aaf2e
@ -71,7 +71,7 @@ Protocol 2.13 (Kernel 3.14) Support 32- and 64-bit flags being set in
|
||||
|
||||
Protocol 2.14 BURNT BY INCORRECT COMMIT
|
||||
ae7e1238e68f2a472a125673ab506d49158c1889
|
||||
(x86/boot: Add ACPI RSDP address to setup_header)
|
||||
("x86/boot: Add ACPI RSDP address to setup_header")
|
||||
DO NOT USE!!! ASSUME SAME AS 2.13.
|
||||
|
||||
Protocol 2.15 (Kernel 5.5) Added the kernel_info and kernel_info.setup_type_max.
|
||||
|
||||
@ -272,10 +272,8 @@ In this case, if the base type is an int type, it must be a regular int type:
|
||||
* ``BTF_INT_OFFSET()`` must be 0.
|
||||
* ``BTF_INT_BITS()`` must be equal to ``{1,2,4,8,16} * 8``.
|
||||
|
||||
The following kernel patch introduced ``kind_flag`` and explained why both
|
||||
modes exist:
|
||||
|
||||
https://github.com/torvalds/linux/commit/9d5f9f701b1891466fb3dbb1806ad97716f95cc3#diff-fa650a64fdd3968396883d2fe8215ff3
|
||||
Commit 9d5f9f701b18 introduced ``kind_flag`` and explains why both modes
|
||||
exist.
|
||||
|
||||
2.2.6 BTF_KIND_ENUM
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -435,6 +435,15 @@ path.
|
||||
For information on cross-referencing to kernel-doc functions or types, see
|
||||
Documentation/doc-guide/kernel-doc.rst.
|
||||
|
||||
Referencing commits
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
References to git commits are automatically hyperlinked given that they are
|
||||
written in one of these formats::
|
||||
|
||||
commit 72bf4f1767f0
|
||||
commit 72bf4f1767f0 ("net: do not leave an empty skb in write queue")
|
||||
|
||||
.. _sphinx_kfigure:
|
||||
|
||||
Figures & Images
|
||||
|
||||
@ -110,7 +110,7 @@ Global data update
|
||||
------------------
|
||||
|
||||
A pre-patch callback can be useful to update a global variable. For
|
||||
example, 75ff39ccc1bd ("tcp: make challenge acks less predictable")
|
||||
example, commit 75ff39ccc1bd ("tcp: make challenge acks less predictable")
|
||||
changes a global sysctl, as well as patches the tcp_send_challenge_ack()
|
||||
function.
|
||||
|
||||
@ -126,7 +126,7 @@ Although __init and probe functions are not directly livepatch-able, it
|
||||
may be possible to implement similar updates via pre/post-patch
|
||||
callbacks.
|
||||
|
||||
The commit ``48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST")`` change the way that
|
||||
The commit 48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST") change the way that
|
||||
virtnet_probe() initialized its driver's net_device features. A
|
||||
pre/post-patch callback could iterate over all such devices, making a
|
||||
similar change to their hw_features value. (Client functions of the
|
||||
|
||||
@ -313,7 +313,7 @@ https://lwn.net/Articles/576263/
|
||||
|
||||
* TcpExtTCPOrigDataSent
|
||||
|
||||
This counter is explained by `kernel commit f19c29e3e391`_, I pasted the
|
||||
This counter is explained by kernel commit f19c29e3e391, I pasted the
|
||||
explanation below::
|
||||
|
||||
TCPOrigDataSent: number of outgoing packets with original data (excluding
|
||||
@ -323,7 +323,7 @@ explanation below::
|
||||
|
||||
* TCPSynRetrans
|
||||
|
||||
This counter is explained by `kernel commit f19c29e3e391`_, I pasted the
|
||||
This counter is explained by kernel commit f19c29e3e391, I pasted the
|
||||
explanation below::
|
||||
|
||||
TCPSynRetrans: number of SYN and SYN/ACK retransmits to break down
|
||||
@ -331,14 +331,12 @@ explanation below::
|
||||
|
||||
* TCPFastOpenActiveFail
|
||||
|
||||
This counter is explained by `kernel commit f19c29e3e391`_, I pasted the
|
||||
This counter is explained by kernel commit f19c29e3e391, I pasted the
|
||||
explanation below::
|
||||
|
||||
TCPFastOpenActiveFail: Fast Open attempts (SYN/data) failed because
|
||||
the remote does not accept it or the attempts timed out.
|
||||
|
||||
.. _kernel commit f19c29e3e391: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=f19c29e3e391a66a273e9afebaf01917245148cd
|
||||
|
||||
* TcpExtListenOverflows and TcpExtListenDrops
|
||||
|
||||
When kernel receives a SYN from a client, and if the TCP accept queue
|
||||
@ -698,11 +696,9 @@ number of the SACK block. For more details, please refer the comment
|
||||
of the function tcp_is_sackblock_valid in the kernel source code. A
|
||||
SACK option could have up to 4 blocks, they are checked
|
||||
individually. E.g., if 3 blocks of a SACk is invalid, the
|
||||
corresponding counter would be updated 3 times. The comment of the
|
||||
`Add counters for discarded SACK blocks`_ patch has additional
|
||||
explanation:
|
||||
|
||||
.. _Add counters for discarded SACK blocks: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=18f02545a9a16c9a89778b91a162ad16d510bb32
|
||||
corresponding counter would be updated 3 times. The comment of commit
|
||||
18f02545a9a1 ("[TCP] MIB: Add counters for discarded SACK blocks")
|
||||
has additional explanation:
|
||||
|
||||
* TcpExtTCPSACKDiscard
|
||||
|
||||
|
||||
@ -74,6 +74,12 @@ Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap',
|
||||
|
||||
c_namespace = ''
|
||||
|
||||
#
|
||||
# Detect references to commits.
|
||||
#
|
||||
RE_git = re.compile(r'commit\s+(?P<rev>[0-9a-f]{12,40})(?:\s+\(".*?"\))?',
|
||||
flags=re.IGNORECASE | re.DOTALL)
|
||||
|
||||
def markup_refs(docname, app, node):
|
||||
t = node.astext()
|
||||
done = 0
|
||||
@ -90,7 +96,8 @@ def markup_refs(docname, app, node):
|
||||
RE_struct: markup_c_ref,
|
||||
RE_union: markup_c_ref,
|
||||
RE_enum: markup_c_ref,
|
||||
RE_typedef: markup_c_ref}
|
||||
RE_typedef: markup_c_ref,
|
||||
RE_git: markup_git}
|
||||
|
||||
if sphinx.version_info[0] >= 3:
|
||||
markup_func = markup_func_sphinx3
|
||||
@ -276,6 +283,17 @@ def get_c_namespace(app, docname):
|
||||
return match.group(1)
|
||||
return ''
|
||||
|
||||
def markup_git(docname, app, match):
|
||||
# While we could probably assume that we are running in a git
|
||||
# repository, we can't know for sure, so let's just mechanically
|
||||
# turn them into git.kernel.org links without checking their
|
||||
# validity. (Maybe we can do something in the future to warn about
|
||||
# these references if this is explicitly requested.)
|
||||
text = match.group(0)
|
||||
rev = match.group('rev')
|
||||
return nodes.reference('', nodes.Text(text),
|
||||
refuri=f'https://git.kernel.org/torvalds/c/{rev}')
|
||||
|
||||
def auto_markup(app, doctree, name):
|
||||
global c_namespace
|
||||
c_namespace = get_c_namespace(app, name)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user