scripts/kernel-doc: drop dead code for Wcontents_before_sections

There is a warning about contents before sections, which doesn't
work, since in_doc_sect variable is always true at the point
it is c

scripts/kernel-doc: drop dead code for Wcontents_before_sections

There is a warning about contents before sections, which doesn't
work, since in_doc_sect variable is always true at the point
it is checked.

Drop the dead code.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Link: https://lore.kernel.org/r/174a15607fd057c736dc9123c53d0835ce20e68b.1740387599.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

scripts/kernel-doc: don't add not needed new lines

This helps comparing kernel-doc output with the new .py version
of it.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Link: http

scripts/kernel-doc: don't add not needed new lines

This helps comparing kernel-doc output with the new .py version
of it.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Link: https://lore.kernel.org/r/6b036ef7d746f26d7d0044626b04d1f0880a2188.1740387599.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

scripts/kernel-doc: drop Sphinx version check

As the current minimal supported Sphinx version is 3.4.3, drop
support for older versions.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.

scripts/kernel-doc: drop Sphinx version check

As the current minimal supported Sphinx version is 3.4.3, drop
support for older versions.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Kees Cook <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/0d002e7550476a68547ee53ad06cfd8fdcaf7c3a.1739254187.git.mchehab+huawei@kernel.org

show more ...

scripts/kernel-doc: remove an obscure logic from kernel-doc

Kernel-doc has an obscure logic that uses an external file
to map files via a .tmp_filelist.txt file stored at the current
directory. The

scripts/kernel-doc: remove an obscure logic from kernel-doc

Kernel-doc has an obscure logic that uses an external file
to map files via a .tmp_filelist.txt file stored at the current
directory. The rationale for such code predates git time,
as it was added on Kernel v2.4.5.5, with the following description:

# 26/05/2001 - Support for separate source and object trees.
# Return error code.
# Keith Owens <[email protected]>

from commit 396a6123577d ("v2.4.5.4 -> v2.4.5.5") at the historic
tree:
https://git.kernel.org/pub/scm/linux/kernel/git/history/history.git/

Support for separate source and object trees is now done on a different
way via make O=<object>.

There's no logic to create such file, so it sounds to me that this is
just dead code.

So, drop it.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Link: https://lore.kernel.org/r/fd3b28dec36ba1668325d6770d4c4754414337fc.1739340170.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

scripts/kernel-doc: fix identifier parsing regex

John wrote:

> kernel-doc gets confused by code like the following:
>
> /**
> * define HOMA_MIN_DEFAULT_PORT - The 16-bit port space is divided into

scripts/kernel-doc: fix identifier parsing regex

John wrote:

> kernel-doc gets confused by code like the following:
>
> /**
> * define HOMA_MIN_DEFAULT_PORT - The 16-bit port space is divided into
> * two nonoverlapping regions. Ports 1-32767 are reserved exclusively
> * for well-defined server ports. The remaining ports are used for client
> * ports; these are allocated automatically by Homa. Port 0 is reserved.
> */
> #define HOMA_MIN_DEFAULT_PORT 0x8000
>
> It seems to use the last "-" on the line (the one in "16-bit") rather
> than the first one, so it produces the following false error message:
>
> homa.h:50: warning: expecting prototype for HOMA_MIN_DEFAULT_PORT -
> The 16(). Prototype was for HOMA_MIN_DEFAULT_PORT() instead
>
> There are similar problems if there is a ":" later on the line.

The problem is the regex for the identifier, which is a greedy /.*/ that
matches everything up to the last - or : (i.e. $decl_end). Fix it by
tightening up this regex and not matching those characters as part of the
identifier.

Link: https://lore.kernel.org/all/CAGXJAmzfRzE=A94NT5ETtj3bZc-=2oLg-9E5Kjh4o_-iuw1q8g@mail.gmail.com/
Reported-by: John Ousterhout <[email protected]>
Reviewed-by: Randy Dunlap <[email protected]>
Tested-by: Randy Dunlap <[email protected]>
Signed-off-by: Vegard Nossum <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

scripts/kernel-doc: Get -export option working again

Since commit cdd30ebb1b9f ("module: Convert symbol namespace to string
literal"), exported symbols marked by EXPORT_SYMBOL_NS(_GPL) are
ignored b

scripts/kernel-doc: Get -export option working again

Since commit cdd30ebb1b9f ("module: Convert symbol namespace to string
literal"), exported symbols marked by EXPORT_SYMBOL_NS(_GPL) are
ignored by "kernel-doc -export" in fresh build of "make htmldocs".

This is because regex in the perl script for those markers fails to
match the new signatures:

- EXPORT_SYMBOL_NS(symbol, "ns");
- EXPORT_SYMBOL_NS_GPL(symbol, "ns");

Update the regex so that it matches quoted string.

Note: Escape sequence of \w is good for C identifiers, but can be
too strict for quoted strings. Instead, use \S, which matches any
non-whitespace character, for compatibility with possible extension
of namespace convention in the future [1].

Fixes: cdd30ebb1b9f ("module: Convert symbol namespace to string literal")
Link: https://lore.kernel.org/CAK7LNATMufXP0EA6QUE9hBkZMa6vJO6ZiaYuak2AhOrd2nSVKQ@mail.gmail.com/ [1]
Signed-off-by: Akira Yokosawa <[email protected]>
Cc: Masahiro Yamada <[email protected]>
Tested-by: Randy Dunlap <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

kernel-doc: allow object-like macros in ReST output

output_function_rst() does not handle object-like macros. It presents
a trailing "()" while output_function_man() handles these macros
correctly.

kernel-doc: allow object-like macros in ReST output

output_function_rst() does not handle object-like macros. It presents
a trailing "()" while output_function_man() handles these macros
correctly.

Update output_function_rst() to handle object-like macros.
Don't show the "Parameters" heading if there are no parameters.

For output_function_man(), don't show the "ARGUMENTS" heading if there
are no parameters.

I have tested this quite a bit with my ad hoc test files for both ReST
and man format outputs. The generated output looks good.

Fixes: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros")
Signed-off-by: Randy Dunlap <[email protected]>
Cc: Horia Geanta <[email protected]>
Tested-by: Vlastimil Babka <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

scripts/kernel-doc: Do not track section counter across processed files

The section counter tracks how many sections of kernel-doc were added.
The only real use of the counter value is to check if a

scripts/kernel-doc: Do not track section counter across processed files

The section counter tracks how many sections of kernel-doc were added.
The only real use of the counter value is to check if anything was
actually supposed to be output and give a warning is nothing is
available.

The current logic of remembering the initial value and then resetting
the value then when processing each file means that if a file has the
same number of sections as the previously processed one, a warning is
incorrectly given.

Fixes: 1da177e4c3f4 ("Linux-2.6.12-rc2")
Signed-off-by: Chen-Yu Tsai <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

scripts/kernel-doc: Fix build time warnings

As stated at Documentation/kbuild/llvm.rst, to make usage of ccache one
must set KBUILD_BUILD_TIMESTAMP=''. Setting this together with W=1
will trigger th

scripts/kernel-doc: Fix build time warnings

As stated at Documentation/kbuild/llvm.rst, to make usage of ccache one
must set KBUILD_BUILD_TIMESTAMP=''. Setting this together with W=1
will trigger the following warning for every compiled file:

date: invalid date ‘+%s’

This comes from kernel-doc script, that produces the following command
when KBUILD_BUILD_TIMESTAMP is empty:

date -d"" +%s

That triggers the warning above. Add a space between the flag `-d` and
the string argument to fix date command and remove the warning.

Signed-off-by: André Almeida <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

mm/slab: Plumb kmem_buckets into __do_kmalloc_node()

Introduce CONFIG_SLAB_BUCKETS which provides the infrastructure to
support separated kmalloc buckets (in the following kmem_buckets_create()
patc

mm/slab: Plumb kmem_buckets into __do_kmalloc_node()

Introduce CONFIG_SLAB_BUCKETS which provides the infrastructure to
support separated kmalloc buckets (in the following kmem_buckets_create()
patches and future codetag-based separation). Since this will provide
a mitigation for a very common case of exploits, it is recommended to
enable this feature for general purpose distros. By default, the new
Kconfig will be enabled if CONFIG_SLAB_FREELIST_HARDENED is enabled (and
it is added to the hardening.config Kconfig fragment).

To be able to choose which buckets to allocate from, make the buckets
available to the internal kmalloc interfaces by adding them as the
second argument, rather than depending on the buckets being chosen from
the fixed set of global buckets. Where the bucket is not available,
pass NULL, which means "use the default system kmalloc bucket set"
(the prior existing behavior), as implemented in kmalloc_slab().

To avoid adding the extra argument when !CONFIG_SLAB_BUCKETS, only the
top-level macros and static inlines use the buckets argument (where
they are stripped out and compiled out respectively). The actual extern
functions can then be built without the argument, and the internals
fall back to the global kmalloc buckets unconditionally.

Co-developed-by: Vlastimil Babka <[email protected]>
Signed-off-by: Kees Cook <[email protected]>
Signed-off-by: Vlastimil Babka <[email protected]>

show more ...

kernel-doc: Added "*" in $type_constants2 to fix 'make htmldocs' warning.

Fixed: WARNING: Inline literal start-string without end-string in
Documentation/core-api/workqueue.rst

Added "*" in $type_c

kernel-doc: Added "*" in $type_constants2 to fix 'make htmldocs' warning.

Fixed: WARNING: Inline literal start-string without end-string in
Documentation/core-api/workqueue.rst

Added "*" in $type_constants2 in kernel-doc script to include "*" in the
conversion to hightlights.
Previously: %WQ_* --> ``WQ_``*
After Changes: %WQ_* --> ``WQ_*``
Need for the fix: ``* is not recognized as a valid end-string for inline
literal.

Link: https://lore.kernel.org/linux-doc/[email protected]
Signed-off-by: Utkarsh Tripathi <[email protected]>
Suggested-by: Akira Yokosawa <[email protected]>
Reviewed-by: Akira Yokosawa <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

scripts/kernel-doc: drop "_noprof" on function prototypes

Memory profiling introduces macros as hooks for function-level allocation
profiling[1]. Memory allocation functions that are profiled are n

scripts/kernel-doc: drop "_noprof" on function prototypes

Memory profiling introduces macros as hooks for function-level allocation
profiling[1]. Memory allocation functions that are profiled are named
like xyz_alloc() for API access to the function. xyz_alloc() then calls
xyz_alloc_noprof() to do the allocation work.

The kernel-doc comments for the memory allocation functions are introduced
with the xyz_alloc() function names but the function implementations are
the xyz_alloc_noprof() names. This causes kernel-doc warnings for
mismatched documentation and function prototype names. By dropping the
"_noprof" part of the function name, the kernel-doc function name matches
the function prototype name, so the warnings are resolved.

[1] https://lore.kernel.org/all/[email protected]/

Link: https://lkml.kernel.org/r/[email protected]
Signed-off-by: Randy Dunlap <[email protected]>
Reported-by: Stephen Rothwell <[email protected]>
Closes: https://lore.kernel.org/all/[email protected]/
Tested-by: Suren Baghdasaryan <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Cc: Kent Overstreet <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>

show more ...

kernel-doc: fix struct_group_tagged() parsing

kernel-doc emits a warning on struct_group_tagged() if you describe your
struct group member:

include/net/libeth/rx.h:69: warning: Excess struct member

kernel-doc: fix struct_group_tagged() parsing

kernel-doc emits a warning on struct_group_tagged() if you describe your
struct group member:

include/net/libeth/rx.h:69: warning: Excess struct member 'fp' description in 'libeth_fq'

The code:

/**
* struct libeth_fq - structure representing a buffer queue
* @fp: hotpath part of the structure
* @pp: &page_pool for buffer management
[...]
*/
struct libeth_fq {
struct_group_tagged(libeth_fq_fp, fp,
struct page_pool *pp;
[...]
);

When a struct_group_tagged() is encountered, we need to build a
`struct TAG NAME;` from it, so that it will be treated as a valid
embedded struct.
Decouple the regex and do the replacement there. As far as I can see,
this doesn't produce any new warnings on the current mainline tree.

Reported-by: Jakub Kicinski <[email protected]>
Closes: https://lore.kernel.org/netdev/[email protected]
Fixes: 50d7bd38c3aa ("stddef: Introduce struct_group() helper macro")
Signed-off-by: Kees Cook <[email protected]>
Co-developed-by: Alexander Lobakin <[email protected]>
Signed-off-by: Alexander Lobakin <[email protected]>
Reviewed-by: Przemek Kitszel <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

docs: Fix bitfield handling in kernel-doc

kernel-doc doesn't handle bitfields that are specified with symbolic
name, e.g. u32 cs_index_mask : SPI_CS_CNT_MAX

This results in the following warnings w

docs: Fix bitfield handling in kernel-doc

kernel-doc doesn't handle bitfields that are specified with symbolic
name, e.g. u32 cs_index_mask : SPI_CS_CNT_MAX

This results in the following warnings when running `make htmldocs`:

include/linux/spi/spi.h:246: warning: Function parameter or struct member 'cs_index_mask:SPI_CS_CNT_MAX' not described in 'spi_device'
include/linux/spi/spi.h:246: warning: Excess struct member 'cs_index_mask' description in 'spi_device'

Update the regexp for bitfields to accept all word chars, not just
digits.

Signed-off-by: Donald Hunter <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Tested-by: Randy Dunlap <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

compiler_types: add Endianness-dependent __counted_by_{le,be}

Some structures contain flexible arrays at the end and the counter for
them, but the counter has explicit Endianness and thus __counted_

compiler_types: add Endianness-dependent __counted_by_{le,be}

Some structures contain flexible arrays at the end and the counter for
them, but the counter has explicit Endianness and thus __counted_by()
can't be used directly.

To increase test coverage for potential problems without breaking
anything, introduce __counted_by_{le,be}() defined depending on
platform's Endianness to either __counted_by() when applicable or noop
otherwise.
Maybe it would be a good idea to introduce such attributes on compiler
level if possible, but for now let's stop on what we have.

Acked-by: Kees Cook <[email protected]>
Acked-by: Gustavo A. R. Silva <[email protected]>
Signed-off-by: Alexander Lobakin <[email protected]>
Reviewed-by: Przemek Kitszel <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jakub Kicinski <[email protected]>

show more ...

kernel-doc: Add unary operator * to $type_param_ref

In kernel-doc comments, unary operator * collides with Sphinx/
docutil's markdown for emphasizing.

This resulted in additional warnings from "mak

kernel-doc: Add unary operator * to $type_param_ref

In kernel-doc comments, unary operator * collides with Sphinx/
docutil's markdown for emphasizing.

This resulted in additional warnings from "make htmldocs":

WARNING: Inline emphasis start-string without end-string.

, as reported recently [1].

Those have been worked around either by escaping * (like \*param) or by
using inline-literal form of ``*param``, both of which are specific
to Sphinx/docutils.

Such workarounds are against the kenrel-doc's ideal and should better
be avoided.

Instead, add "*" to the list of unary operators kernel-doc recognizes
and make the form of *@param available in kernel-doc comments.

Reported-by: Stephen Rothwell <[email protected]>
Link: [1] https://lore.kernel.org/r/[email protected]/
Acked-by: Christoph Hellwig <[email protected]>
Signed-off-by: Akira Yokosawa <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Cc: Mauro Carvalho Chehab <[email protected]>
Acked-by: Jonathan Corbet <[email protected]>
Signed-off-by: Chandan Babu R <[email protected]>

show more ...

kernel-doc: handle #if in enums as well

In addition to #ifdef, #define and #endif, also handle
any #if since we may be using e.g. #if IS_ENABLED(...).

I didn't find any instances of this in the ker

kernel-doc: handle #if in enums as well

In addition to #ifdef, #define and #endif, also handle
any #if since we may be using e.g. #if IS_ENABLED(...).

I didn't find any instances of this in the kernel now,
there are enums with such ifs inside, but I didn't find
any with kernel-doc as well. However, it came up as we
were adding such a construct in our driver and warnings
from kernel-doc were the result.

Signed-off-by: Johannes Berg <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/20240214142937.80ee86a3beae.Ibcc5bd97a20cd10a792663e4b254cd46c7e8b520@changeid

show more ...

scripts/kernel-doc: simplify signature printing

Untangle some of the $is_macro logic and the nested conditionals.

This makes it easier to see where and how the signature is actually
printed.

No fu

scripts/kernel-doc: simplify signature printing

Untangle some of the $is_macro logic and the nested conditionals.

This makes it easier to see where and how the signature is actually
printed.

No functional change.

Signed-off-by: Vegard Nossum <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

scripts/kernel-doc: separate out function signature

Format the entire function signature and place it in a separate variable;
this both makes it easier to understand what these lines of code are doi

scripts/kernel-doc: separate out function signature

Format the entire function signature and place it in a separate variable;
this both makes it easier to understand what these lines of code are doing
and will allow us to simplify the code further in the following patch.

No functional change.

Signed-off-by: Vegard Nossum <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

scripts/kernel-doc: simplify function printing

Get rid of the $start variable, since it's really not necessary.

No functional change.

Signed-off-by: Vegard Nossum <[email protected]>
Review

scripts/kernel-doc: simplify function printing

Get rid of the $start variable, since it's really not necessary.

No functional change.

Signed-off-by: Vegard Nossum <[email protected]>
Reviewed-by: Randy Dunlap <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

scripts/kernel-doc: add modeline for vim users

Set 'softtabstop' to 4 spaces, which will hopefully help keep the
indentation in this file consistent going forwards.

This mirrors the modeline in scr

scripts/kernel-doc: add modeline for vim users

Set 'softtabstop' to 4 spaces, which will hopefully help keep the
indentation in this file consistent going forwards.

This mirrors the modeline in scripts such as recordmcount.pl, ktest.pl,
and others.

Emacs seems to use 4 spaces to indent by default, so it doesn't require
anything special here.

No functional change.

Signed-off-by: Vegard Nossum <[email protected]>
Reviewed-by: Randy Dunlap <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

scripts/kernel-doc: reindent

This file is using an ungodly mixture of 4 spaces, 2-wide tabs, 4-wide
tabs, _and_ 8-wide tabs, making it really hard to find good editor
settings for working with this

scripts/kernel-doc: reindent

This file is using an ungodly mixture of 4 spaces, 2-wide tabs, 4-wide
tabs, _and_ 8-wide tabs, making it really hard to find good editor
settings for working with this file.

Bite the bullet and reindent it by hand. I tried using both perltidy
and vim, but neither of them were up to the task without changing too
much or getting confused about what they were supposed to be doing.

I did change a few instances of

}
else

into

} else

(and same for elsif); the file is again written using both styles, and
I left functions which already seemed self-consistent alone.

You can verify that this commit only changes whitespace using e.g.:

git diff --ignore-all-space --word-diff

or to see (only) the instances where newlines were added/removed:

git diff --ignore-all-space

You can also see the delta from what perltidy would have wanted to
do to this file (when asked to only indent it), which isn't that much
in the end:

perltidy -io -fnl scripts/kernel-doc
git diff --no-index scripts/kernel-doc{,.tdy}

Signed-off-by: Vegard Nossum <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

kernel-doc: Support arrays of pointers struct fields

In a rather unusual arrangement in include/media/v4l2-vp9.h struct
v4l2_vp9_frame_symbol_counts has fields that are arrays of pointers, not a
poi

kernel-doc: Support arrays of pointers struct fields

In a rather unusual arrangement in include/media/v4l2-vp9.h struct
v4l2_vp9_frame_symbol_counts has fields that are arrays of pointers, not a
pointer to an array, which is what's usually done.

Add support for such arrays of pointers to kernel-doc.

Signed-off-by: Sakari Ailus <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Tested-by: Randy Dunlap <[email protected]>
Tested-by: Ricardo Ribalda <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

kernel-doc: drop looking for "MACDOC"

Linux kernel does not use "MACDOC" in any documenation or any
source files, so stop searching for it.

Signed-off-by: Randy Dunlap <[email protected]>
Cc: J

kernel-doc: drop looking for "MACDOC"

Linux kernel does not use "MACDOC" in any documenation or any
source files, so stop searching for it.

Signed-off-by: Randy Dunlap <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

scripts/kernel-doc: Do not process backslash lines in comments

To prevent this, do the pre-processing only for lines which are no
comments, e.g. do not start with ' *'.

Suggested-by: Matthew Wilcox

scripts/kernel-doc: Do not process backslash lines in comments

To prevent this, do the pre-processing only for lines which are no
comments, e.g. do not start with ' *'.

Suggested-by: Matthew Wilcox <[email protected]>
Signed-off-by: Anna-Maria Behnsen <[email protected]>
Tested-by: Randy Dunlap <[email protected]>
Acked-by: Daniel Vetter <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...