Pull more documentation updates from Jonathan Corbet:
"Some late-arriving documentation improvements.
This is mostly build-system fixes from Mauro and Akira; I also took
the liberty of dropping in my 'messy diffstat' document"
* tag 'docs-5.18-2' of git://git.lwn.net/linux:
docs: Add a document on how to fix a messy diffstat
docs: sphinx/requirements: Limit jinja2<3.1
Documentation: kunit: Fix cross-referencing warnings
scripts/kernel-doc: change the line number meta info
scripts/get_abi: change the file/line number meta info
docs: kernel_include.py: add sphinx build dependencies
docs: kernel_abi.py: add sphinx build dependencies
docs: kernel_feat.py: add build dependencies
scripts/get_feat.pl: allow output the parsed file names
docs: kfigure.py: Don't warn of missing PDF converter in 'make htmldocs'
Documentation: Fix duplicate statement about raw_spinlock_t type
As parsing the sysfs entries can take a long time, add
progress information.
The progress logic will update the stats on every second,
or on 1% steps of the progress.
When STDERR is a console, it will use a single line, using
a VT-100 command to erase the line before rewriting it.
Otherwise, it will put one message on a separate line.
That would help to identify what parts of sysfs checking
that it is taking more time to process.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/4e581dcbec21ad8a60fff883498018f96f13dd1c.1632823172.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
It doesn't make any sense to parse ABI entries under
/sys/firmware, as those are either specified by ACPI specs
or by Documentation/devicetree.
The current logic to ignore firmware entries is incomplete,
as it ignores just the relative name of the file, and not
its absolute name. This cause errors while parsing the
symlinks.
So, rewrite the logic for it to do a better job.
Tested with both x86 and arm64 (HiKey970) systems.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/1c806eaec96f6706db4b041bbe6a0e2519e9637e.1632750315.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
As warned, /sys/bus/iio/devices/iio:deviceX/fault_ovuv is defined 2 times:
Warning: /sys/bus/iio/devices/iio:deviceX/fault_ovuv is defined 2 times: ./Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856:14 ./Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865:0
The logic with joins the two entries is just places the paragraph
for the second entry after the previous one. That could cause more
warnings, as the produced ReST may become invalid, as in the case of
this specific symbol, which ends with a table:
/new_devel/v4l/docs/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856:2: WARNING: Malformed table.
No bottom table border found or no blank line after table bottom.
=== =======================================================
'1' The input voltage is negative or greater than VDD.
'0' The input voltage is positive and less than VDD (normal
state).
=== =======================================================
/new_devel/v4l/docs/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856:2: WARNING: Blank line required after table.
Address it by adding two blank lines before joining duplicated
symbols.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/4ad2e3a65f781f0f8d40bb75aa5a07aca80564d6.1632740376.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
The way the search algorithm works is that reduces the number of regex
expressions that will be checked for a given file entry at sysfs. It
does that by looking at the devnode name. For instance, when it checks for
this file:
/sys/bus/pci/drivers/iosf_mbi_pci/bind
The logic will seek only the "What:" expressions that end with "bind".
Currently, there are just a couple of What expressions that matches
it:
What: /sys/bus/fsl\-mc/drivers/.*/bind
What: /sys/bus/pci/drivers/.*/bind
It will then run an O(n²) algorithm to seek, which runs quickly
when there are few regexs to seek. There are, however, some What:
expressions that end with a wildcard. Those are harder to process.
Right now, they're all grouped together at the "others" group.
As those don't depend on the basename of the node, add an extra
loop to ensure that those will be processed at the end, if
not done yet.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/9fe7ab46f67575def5db9e83034e9fab43846d84.1632411447.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Searching for symlinks is an expensive operation with the current
logic, as it is at the order of O(n^3). In practice, running the
check spends 2-3 minutes to check all symbols.
Fix it by storing the directory tree into a graph, and using
a Breadth First Search (BFS) to find the links for each sysfs node.
With such improvement, it can now report issues with ~11 seconds
on my machine.
It comes with a price, though: there are more symbols reported
as undefined after this change. I suspect it is due to some
sysfs circular loops that are dropped by BFS. Despite such
increase, it seems that the reports are now more coherent.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/f5c1e7b14a27132821c08f0459ba9aea3ed69028.1631957565.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
The search algorithm used inside check_undefined_symbols
has an optimization: it seeks only whats that have the same
leave name. This helps not only to speedup the search, but
it also allows providing a hint about a partial match.
There's a drawback, however: when "what:" finishes with a
wildcard, the logic will skip the what, reporting it as
"not found".
Fix it by grouping the remaining cases altogether, and
disabing any hints for such cases.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/79ba5139643355230e3bba136b20991cfc92020f.1631957565.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Change every shebang which does not need an argument to use /usr/bin/env.
This is needed as not every distro has everything under /usr/bin,
sometimes not even bash.
Signed-off-by: Finn Behrens <me@kloenk.de>
Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
The ReST output should only contain documentation titles
automatically created by the script.
There are two reasons for that:
1) Consistency.
just a handful ABI docs define titles
2) To avoid critical errors.
Docutils (which is the basis for Sphinx) allows a free
assign of documentation title markups. So, one document
could be doing things like:
Level 1
=======
Level 2
-------
While another one could do the reverse:
Level 1
-------
Level 2
=======
But the same document can't mix.
As the output of get_abi.pl will join contents from multiple
files, if they don't define the levels on a consistent errors,
errors like this can happen:
Sphinx parallel build error:
docutils.utils.SystemMessage: /home/rdunlap/lnx/lnx-510-rc2/Documentation/ABI/testing/sysfs-bus-rapidio:2: (SEVERE/4) Title level inconsistent:
Attributes Common for All RapidIO Devices
-----------------------------------------
Which cause some versions of Sphinx to go into an endless
loop.
It should be noticed that an alternative to that would
be to replace all title occurrences by a single markup,
but that will make the parser more complex, and, due to
(1) it would generate an inconsistent output.
So, better to just remove the titles defined at the ABI
files from the output.
Reported-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/6c62ef5c01d39dee8d891f8390c816d2a889670a.1604312590.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
The files under Documentation/ABI should follow the syntax
as defined at Documentation/ABI/README.
Allow checking if they're following the syntax by running
the ABI parser script on COMPILE_TEST.
With that, when there's a problem with a file under
Documentation/ABI, it would produce a warning like:
Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#14:
What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor' doesn't have a description
Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#21:
What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal' doesn't have a description
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/57a38de85cb4b548857207cf1fc1bf1ee08613c9.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
