30 Dec, 2020
2 commits
-
[ Upstream commit 7d2c6b1edf790d96e9017a0b27be2425e1af1532 ]
Changeset 6b80975c6308 ("scripts: kernel-doc: fix typedef parsing")
added support for things like:typedef unsigned long foo();
However, it caused a regression on this prototype:
typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle);
This is only noticed after adding a patch that checks if the
kernel-doc identifier matches the typedef:./scripts/kernel-doc -none $(git grep '^.. kernel-doc::' Documentation/ |cut -d ' ' -f 3|sort|uniq) 2>&1|grep expecting
include/media/v4l2-dv-timings.h:38: warning: expecting prototype for typedef v4l2_check_dv_timings_fnc. Prototype was for typedef nc insteadThe problem is that, with the new parsing logic, it is not
checking for complete words at the type part.Fix it by adding a \b at the end of each type word at the
regex.fixes: 6b80975c6308 ("scripts: kernel-doc: fix typedef parsing")
Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/218ff56dcb8e73755005d3fb64586eb1841a276b.1606896997.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet
Signed-off-by: Sasha Levin -
[ Upstream commit ae5b17e464146ddb8fee744fa2150922d6072916 ]
The commit d38c8cfb0571 ("scripts: kernel-doc: add support for typedef enum")
broke anonymous enum parsing. Restore it by relying on members rather than
its name.Fixes: d38c8cfb0571 ("scripts: kernel-doc: add support for typedef enum")
Reported-by: kernel test robot
Signed-off-by: Andy Shevchenko
Reviewed-by: Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/20201102170637.36138-1-andriy.shevchenko@linux.intel.com
Signed-off-by: Jonathan Corbet
Signed-off-by: Sasha Levin
29 Oct, 2020
3 commits
-
Sphinx C domain code after 3.2.1 will start complaning if :c:struct
would be used for an union type:.../Documentation/gpu/drm-kms-helpers:352: ../drivers/video/hdmi.c:851: WARNING: C 'identifier' cross-reference uses wrong tag: reference name is 'union hdmi_infoframe' but found name is 'struct hdmi_infoframe'. Full reference name is 'union hdmi_infoframe'. Full found name is 'struct hdmi_infoframe'.
So, let's address this issue too in advance, in order to
avoid future issues.Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/6e4ec3eec914df62389a299797a3880ae4490f35.1603791716.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet -
The typedef regex for function prototypes are very complex.
Split them into 3 separate regex and then join them using
qr.Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/3a4af999a0d62d4ab9dfae1cdefdfcad93383356.1603792384.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet -
The include/linux/genalloc.h file defined this typedef:
typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);
Because it has a type composite of two words (unsigned long),
the parser gets the typedef name wrong:.. c:macro:: long
**Typedef**: Allocation callback function type definition
Fix the regex in order to accept composite types when
defining a typedef for a function pointer.Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/328e8018041cc44f7a1684e57f8d111230761c4f.1603792384.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet
15 Oct, 2020
10 commits
-
There are a few namespace clashes by using c:macro everywhere:
basically, when using it, we can't have something like:
.. c:struct:: pwm_capture
.. c:macro:: pwm_capture
So, we need to use, instead:
.. c:function:: int pwm_capture (struct pwm_device * pwm, struct pwm_capture * result, unsigned long timeout)
for the function declaration.
The kernel-doc change was proposed by Jakob Lykke Andersen here:
https://github.com/jakobandersen/linux_docs/commit/6fd2076ec001cca7466857493cd678df4dfe4a65
Although I did a different implementation.
Signed-off-by: Mauro Carvalho Chehab
-
Address several issues related to pointing to the wrong line
number:1) ensure that line numbers will always be initialized
When section is the default (Description), the line number
is not initializing, producing this:$ ./scripts/kernel-doc --enable-lineno ./drivers/media/v4l2-core/v4l2-mem2mem.c|less
**Description**
#define LINENO 0
In case of streamoff or release called on any context,
1] If the context is currently running, then abort job will be called
2] If the context is queued, then the context will be removed from
the job_queueWhich is not right. Ensure that the line number will always
be there. After applied, the result now points to the right location:**Description**
#define LINENO 410
In case of streamoff or release called on any context,
1] If the context is currently running, then abort job will be called
2] If the context is queued, then the context will be removed from
the job_queue2) The line numbers for function prototypes are always + 1,
because it is taken at the line after handling the prototype.
Change the logic to point to the next line after the /** */
block;3) The "DOC:" line number should point to the same line as this
markup is found, and not to the next one.Probably part of the issues were due to a but that was causing
the line number offset to be incremented by one, if --export
were used.Signed-off-by: Mauro Carvalho Chehab
-
When kernel-doc is called via kerneldoc.py, there's no need to
auto-detect the Sphinx version, as the Sphinx module already
knows it. So, add an optional parameter to allow changing the
Sphinx dialect.As kernel-doc can also be manually called, keep the auto-detection
logic if the parameter was not specified. On such case, emit
a warning if sphinx-build can't be found at PATH.I ended using a suggestion from Joe for using a more readable
regex, instead of using a complex one with a hidden group like:m/^(\d+)\.(\d+)(?:\.?(\d+)?)/
in order to get the optional argument.
Thanks-to: Joe Perches
Suggested-by: Jonathan Corbet
Signed-off-by: Mauro Carvalho Chehab -
While kernel-doc needs to parse parameters in order to
identify its name, it shouldn't be touching the type,
as parsing it is very difficult, and errors happen.One current error is when parsing this parameter:
const u32 (*tab)[256]
Found at ./lib/crc32.c, on this function:
u32 __pure crc32_be_generic (u32 crc, unsigned char const *p, size_t len, const u32 (*tab)[256], u32 polynomial);
The current logic mangles it, producing this output:
const u32 ( *tab
That's something that it is not recognizeable.
So, instead, let's push the argument as-is, and use it
when printing the function prototype and when describing
each argument.Signed-off-by: Mauro Carvalho Chehab
-
Some typedef expressions are output as normal functions.
As we need to be clearer about the type with Sphinx 3.x,
detect such cases.While here, fix a wrongly-indented block.
Signed-off-by: Mauro Carvalho Chehab
-
Right now, the build system doesn't use -nofunction, as
it is pretty much useless, because it doesn't consider
the other output modes (extern, internal), working only
with all.Also, it is limited to exclude functions.
Re-implement it in order to allow excluding any symbols from
the document output, no matter what mode is used.The parameter was also renamed to "-nosymbol", as it express
better its meaning.Signed-off-by: Mauro Carvalho Chehab
-
There's currently a bug with the way kernel-doc script
counts line numbers that can be seen with:$ ./scripts/kernel-doc -rst -enable-lineno include/linux/math64.h >all && ./scripts/kernel-doc -rst -internal -enable-lineno include/linux/math64.h >int && diff -U0 int all
--- int 2020-09-28 12:58:08.927486808 +0200
+++ all 2020-09-28 12:58:08.905486845 +0200
@@ -1 +1 @@
-#define LINENO 27
+#define LINENO 26
@@ -3 +3 @@
-#define LINENO 16
+#define LINENO 15
@@ -9 +9 @@
-#define LINENO 17
+#define LINENO 16
...This is happening with perl version 5.30.3, but I'm not
so sure if this is a perl bug, or if this is due to something
else.In any case, fixing it is easy. Basically, when "-internal"
parameter is used, the process_export_file() function opens the
handle "IN". This makes the line number to be incremented, as the
handler for the main open is also "IN".Fix the problem by using a different handler for the
main open().While here, add a missing close for it.
Signed-off-by: Mauro Carvalho Chehab
-
Unfortunately, Sphinx 3.x parser for c functions is too pedantic:
https://github.com/sphinx-doc/sphinx/issues/8241
While it could be relaxed with some configurations, there are
several corner cases that it would make it hard to maintain,
and will require teaching conf.py about several macros.So, let's instead use the :c:macro notation. This will
produce an output that it is not as nice as currently, but it
should still be acceptable, and will provide cross-references,
removing thousands of warnings when building with newer
versions of Sphinx.Signed-off-by: Mauro Carvalho Chehab
-
With Sphinx 3.x, the ".. c:type:" tag was changed to accept either:
.. c:type:: typedef-like declaration
.. c:type:: nameUsing it for other types (including functions) don't work anymore.
So, there are newer tags for macro, enum, struct, union, and others,
which doesn't exist on older versions.Add a check for the Sphinx version and change the produced tags
accordingly.Signed-off-by: Mauro Carvalho Chehab
-
The PHY kernel-doc markup has gained support for documenting
a typedef enum.However, right now the parser was not prepared for it.
So, add support for parsing it.
Fixes: 4069a572d423 ("net: phy: Document core PHY structures")
Signed-off-by: Mauro Carvalho Chehab
17 Sep, 2020
1 commit
-
Subroutine dump_struct uses type attributes to check if the struct
syntax is valid. Then, it removes all attributes before using it for
output. `____cacheline_aligned` is an attribute that is
not included in both steps. Add it, since it is used by kernel structs.Based on previous patch to add ____cacheline_aligned_in_smp.
Motivated by patches to reorder this attribute to before the
variable name. Whilst we could do that in all cases, that would
be a massive change and it is more common in the kernel to place
this particular attribute after the variable name. A quick grep
suggests approximately 400 instances of which 341 have this
attribute just before a semicolon and hence after the variable name.Signed-off-by: Jonathan Cameron
Cc: Lee Jones
Link: https://lore.kernel.org/r/20200910185415.653139-1-jic23@kernel.org
Signed-off-by: Jonathan Corbet
11 Sep, 2020
1 commit
-
This should solve bad error reports like this one:
./include/linux/iio/iio.h:0: WARNING: Unknown target name: "devm".
Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/56eed0ba50cd726236acd12b11b55ce54854c5ea.1599660067.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet
01 Aug, 2020
1 commit
-
The kbuild bot recently added the W=1 option, which triggered
documentation cleanups to squelch hundreds of kernel-doc warnings.To make sure new kernel contributions don't add regressions to
kernel-doc descriptors, this patch suggests an option to treat
warnings as errors in CI/automated tests.A -Werror command-line option is added to the kernel-doc script. When
this option is set, the script will return the number of warnings
found. The caller can then treat this positive return value as an
error and stop the build.Using this command line option is however not straightforward when the
kernel-doc script is called from other scripts. To align with typical
kernel compilation or documentation generation, the Werror option is
also set by checking the KCFLAGS environment variable, or if
KDOC_WERROR is defined, as in the following examples:KCFLAGS="-Wall -Werror" make W=1 sound/
KCFLAGS="-Wall -Werror" make W=1 drivers/soundwire/
KDOC_WERROR=1 make htmldocsNote that in the last example the documentation build does not stop,
only an additional log is provided.Credits to Randy Dunlap for suggesting the use of environment variables.
Suggested-by: Randy Dunlap
Signed-off-by: Pierre-Louis Bossart
Link: https://lore.kernel.org/r/20200728162040.92467-1-pierre-louis.bossart@linux.intel.com
Signed-off-by: Jonathan Corbet
27 Jun, 2020
2 commits
-
There are some function pointer prototypes inside the net
includes, like this one:int (*pcs_config)(struct phylink_config *config, unsigned int mode,
phy_interface_t interface, const unsigned long *advertising);There's nothing wrong using it with kernel-doc, but we need to
add a rule for it to parse such kind of prototype.Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/fec520dd731a273013ae06b7653a19c7d15b9562.1592895969.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet -
The __ETHTOOL_DECLARE_LINK_MODE_MASK macro is a variant of
DECLARE_BITMAP(), used by phylink.h. As we have already a
parser for DECLARE_BITMAP(), let's add one for this macro,
in order to avoid such warnings:./include/linux/phylink.h:54: warning: Function parameter or member '__ETHTOOL_DECLARE_LINK_MODE_MASK(advertising' not described in 'phylink_link_state'
./include/linux/phylink.h:54: warning: Function parameter or member '__ETHTOOL_DECLARE_LINK_MODE_MASK(lp_advertising' not described in 'phylink_link_state'Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/d1d1dea67a28117c0b0c33271b139c4455fef287.1592895969.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet
08 Jun, 2020
1 commit
-
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.Deterministic algorithm:
For each file:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.Signed-off-by: Alexander A. Klimov
Link: https://lore.kernel.org/r/20200526060544.25127-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet
21 Apr, 2020
3 commits
-
Sphinx is very pedantic with respect to blank lines. Sometimes,
in order to make it to properly handle something, we need to
add a blank line. However, currently, any blank line inside a
kernel-doc comment like:/*
* @foo: bar
*
* foobar
*
* some descriptionwill be considered as if "foobar" was part of the description.
This patch changes kernel-doc behavior. After it, foobar will
be considered as part of the parameter text. The description
will only be considered as such if it starts with:zero spaces after asterisk:
*foo
one space after asterisk:
* fooor have a explicit Description section:
* Description:
Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/c07d2862792d75a2691d69c9eceb7b89a0164cc0.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet -
On a few places, it sometimes need to indicate a negation of a
parameter, like:!@fshared
This pattern happens, for example, at:
kernel/futex.c
and it is perfectly valid. However, kernel-doc currently
transforms it into:!**fshared**
This won't do what it would be expected.
Fortunately, fixing the script is a simple matter of storing
the "!" before "@" and adding it after the bold markup, like:**!fshared**
Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/0314b47f8c3e1f9db00d5375a73dc3cddd8a21f2.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet -
The pattern @foo->bar() is valid, as it can be used by a
function pointer inside a struct passed as a parameter.Right now, it causes a warning:
./drivers/firewire/core-transaction.c:606: WARNING: Inline strong start-string without end-string.
In this specific case, the kernel-doc markup is:
/**
* fw_core_remove_address_handler() - unregister an address handler
* @handler: callback
*
* To be called in process context.
*
* When fw_core_remove_address_handler() returns, @handler->callback() is
* guaranteed to not run on any CPU anymore.
*/With seems valid on my eyes. So, instead of trying to hack
the kernel-doc markup, let's teach it about how to handle
such things. This should likely remove lots of other similar
warnings as well.Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/48b46426d7bf6ff7529f20e5718fbf4e9758e62c.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet
16 Apr, 2020
1 commit
-
When kernel-doc generates a 'c:function' directive for a function
one of whose arguments is a function pointer, it fails to print
the close-paren after the argument list of the function pointer
argument. For instance:long work_on_cpu(int cpu, long (*fn) (void *, void * arg)
in driver-api/basics.html is missing a ')' separating the
"void *" of the 'fn' arguments from the ", void * arg" which
is an argument to work_on_cpu().Add the missing close-paren, so that we render the prototype
correctly:long work_on_cpu(int cpu, long (*fn)(void *), void * arg)
(Note that Sphinx stops rendering a space between the '(fn*)' and the
'(void *)' once it gets something that's syntactically valid.)Signed-off-by: Peter Maydell
Link: https://lore.kernel.org/r/20200414143743.32677-1-peter.maydell@linaro.org
Signed-off-by: Jonathan Corbet
08 Nov, 2019
1 commit
-
Currently, when kernel-doc encounters a macro with a named variable
argument[1], such as this:#define hlist_for_each_entry_rcu(pos, head, member, cond...)
... it expects the variable argument to be documented as `cond...`,
rather than `cond`. This is semantically wrong, because the name (as
used in the macro body) is actually `cond`.With this patch, kernel-doc will accept the name without dots (`cond`
in the example above) in doc comments, and warn if the name with dots
(`cond...`) is used and verbose mode[2] is enabled.The support for the `cond...` syntax can be removed later, when the
documentation of all such macros has been switched to the new syntax.Testing this patch on top of v5.4-rc6, `make htmldocs` shows a few
changes in log output and HTML output:1) The following warnings[3] are eliminated:
./include/linux/rculist.h:374: warning:
Excess function parameter 'cond' description in 'list_for_each_entry_rcu'
./include/linux/rculist.h:651: warning:
Excess function parameter 'cond' description in 'hlist_for_each_entry_rcu'2) For list_for_each_entry_rcu and hlist_for_each_entry_rcu, the
correct description is shown3) Named variable arguments are shown without dots
[1]: https://gcc.gnu.org/onlinedocs/cpp/Variadic-Macros.html
[2]: scripts/kernel-doc -v
[3]: See also https://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git/commit/?h=dev&id=5bc4bc0d6153617eabde275285b7b5a8137fdf3cSigned-off-by: Jonathan Neuschäfer
Tested-by: Paul E. McKenney
Signed-off-by: Jonathan Corbet
01 Oct, 2019
2 commits
-
Subroutine dump_struct uses type attributes to check if the struct
syntax is valid. Then, it removes all attributes before using it for
output. `____cacheline_aligned_in_smp` is an attribute that is
not included in both steps. Add it, since it is used by kernel structs.Signed-off-by: André Almeida
Signed-off-by: Jonathan Corbet -
The current regular expression for strip attributes of structs (and
for nested ones as well) also removes all whitespaces that may
surround the attribute. After that, the code will split structs and
iterate for each symbol separated by comma at the end of struct
definition (e.g. "} alias1, alias2;"). However, if the nested struct
does not have any alias and has an attribute, it will result in a
empty string at the closing bracket (e.g "};"). This will make the
split return nothing and $newmember will keep uninitialized. Fix
that, by ensuring that the attribute substitution will leave at least
one whitespace.Signed-off-by: André Almeida
Signed-off-by: Jonathan Corbet
13 Aug, 2019
1 commit
-
In C is a valid construction to have an anonymous enumerator.
Though we have now:
drivers/pinctrl/intel/pinctrl-intel.c:240: error: Cannot parse enum!
Support it in the kernel-doc script.
Signed-off-by: Andy Shevchenko
Signed-off-by: Jonathan Corbet
07 Aug, 2019
1 commit
-
Ignore __printf() function attributes just as other __attribute__
strings are ignored.Fixes this kernel-doc warning message:
include/kunit/kunit-stream.h:58: warning: Function parameter or member '2' not described in '__printf'Reported-by: kbuild test robot
Signed-off-by: Randy Dunlap
Cc: Brendan Higgins
Tested-by: Brendan Higgins
Signed-off-by: Jonathan Corbet
27 Jun, 2019
1 commit
-
We now have better automarkup in sphinx itself and, besides, this markup
was incorrect and left :c:func: gunk in the processed docs. Sort of
discouraging that nobody ever noticed...:)As a first step toward the removal of impenetrable regex magic from
kernel-doc it's a tiny one, but you have to start somewhere.Signed-off-by: Jonathan Corbet
28 May, 2019
1 commit
-
The "no structured comments found" warning is not particularly useful if
there are several invocations, one of which is looking for something
wrong. So if something specific has been requested, make it clear that
it's the one we weren't able to find.Signed-off-by: Jonathan Corbet
17 Jan, 2019
1 commit
-
The ability to add kerneldoc comments for fields in embedded structures is
useful, but it brought along a whole bunch of warnings for fields that
could not be described before. In many cases, there's little value in
adding docs for these nested fields, and in cases like:struct a {
struct b {
int c;
} d, e;
};"c" would have to be described twice (as d.c and e.c) to make the warnings
go away.We can no doubt do something smarter, but simply suppressing the warnings
for this case removes about 70 warnings from the docs build, freeing us to
focus on the ones that matter more. So make kerneldoc be silent about
missing descriptions for any field containing a ".".Signed-off-by: Jonathan Corbet
26 Nov, 2018
1 commit
-
The kernel-doc attempts to clear the struct and struct member attributes
from the API documentation it produces. It falls short of the job in the
following respects:- extra whitespaces are left where __attribute__((...)) was removed,
- only a single attribute is removed per struct,
- attributes (such as aligned) containing numbers were not removed,
- attributes are only cleared from struct fields, not structs themselves.
This patch addresses these issues by removing the attributes.
Signed-off-by: Sakari Ailus
Signed-off-by: Jonathan Corbet
08 Nov, 2018
2 commits
-
Currently, function parameter description can match '@type.member'
expressions but fails to match '@type->member'.
Extend the $type_param regex to allow matching bothSigned-off-by: Mike Rapoport
Signed-off-by: Jonathan Corbet -
Signed-off-by: Mike Rapoport
Signed-off-by: Jonathan Corbet
19 Oct, 2018
1 commit
-
Make declaration type determination more robust.
When scripts/kernel-doc is deciding if some kernel-doc notation
contains an enum, a struct, a union, a typedef, or a function,
it does a pattern match on the beginning of the string, looking
for a match with one of "struct", "union", "enum", or "typedef",
and otherwise defaults to a function declaration type.
However, if a function or a function-like macro has a name that
begins with "struct" (e.g., struct_size()), then kernel-doc
incorrectly decides that this is a struct declaration.Fix this by looking for the declaration type keywords having an
ending word boundary (\b), so that "struct_size" will not match
a struct declaration.I compared lots of html before/after output from core-api, driver-api,
and networking. There were no differences in any of the files that
I checked.Signed-off-by: Randy Dunlap
Acked-by: Jani Nikula
Tested-by: Kees Cook
Signed-off-by: Jonathan Corbet
07 Aug, 2018
1 commit
-
Commit 701b3a3c0ac4 ("PATCH scripts/kernel-doc") fixed the two
instances of literal braces that Perl 5.28 warns about, but there are
still more than it doesn't warn about.Escape all left braces that are treated as literal characters. Also
escape literal right braces, for consistency and to avoid confusing
bracket-matching in text editors.Signed-off-by: Ben Hutchings
Signed-off-by: Jonathan Corbet
23 Jul, 2018
1 commit
-
Fix a warning whinge from Perl introduced by "scripts: kernel-doc: parse next structs/unions"
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.32), passed through in regex; marked by
Reviewed-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
30 Mar, 2018
1 commit
-
The logic with parses array has a bug that prevents it to
parse arrays like:
struct {
...
struct {
u64 msdu[IEEE80211_NUM_TIDS + 1];
...
...Fix the parser to accept it.
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
