Changes in kernel-doc

19b100b0 - scripts/kernel-doc: drop dead code for Wcontents_before_sections

Mon, 24 Feb 2025 09:08:12 +0000

scripts/kernel-doc: drop dead code for Wcontents_before_sectionsThere is a warning about contents before sections, which doesn'twork, since in_doc_sect variable is always true at the pointit is checked.Drop the dead code.Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/174a15607fd057c736dc9123c53d0835ce20e68b.1740387599.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet List of files: /linux-6.15/scripts/kernel-doc

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

Mon, 24 Feb 2025 09:08:11 +0000

scripts/kernel-doc: don't add not needed new linesThis helps comparing kernel-doc output with the new .py versionof it.Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/6b036ef7d746f26d7d0044626b04d1f0880a2188.1740387599.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet List of files: /linux-6.15/scripts/kernel-doc

089e06c3 - scripts/kernel-doc: drop Sphinx version check

Tue, 11 Feb 2025 06:19:04 +0000

scripts/kernel-doc: drop Sphinx version checkAs the current minimal supported Sphinx version is 3.4.3, dropsupport for older versions.Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Kees Cook Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/0d002e7550476a68547ee53ad06cfd8fdcaf7c3a.1739254187.git.mchehab+huawei@kernel.org List of files: /linux-6.15/scripts/kernel-doc

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

Wed, 12 Feb 2025 06:02:52 +0000

scripts/kernel-doc: remove an obscure logic from kernel-docKernel-doc has an obscure logic that uses an external fileto map files via a .tmp_filelist.txt file stored at the currentdirectory. 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 from commit 396a6123577d ("v2.4.5.4 -> v2.4.5.5") at the historictree: https://git.kernel.org/pub/scm/linux/kernel/git/history/history.git/Support for separate source and object trees is now done on a differentway via make O=.There's no logic to create such file, so it sounds to me that this isjust dead code.So, drop it.Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/fd3b28dec36ba1668325d6770d4c4754414337fc.1739340170.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet List of files: /linux-6.15/scripts/kernel-doc

da3ecf00 - scripts/kernel-doc: fix identifier parsing regex

Sat, 21 Dec 2024 22:22:14 +0000

scripts/kernel-doc: fix identifier parsing regexJohn 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 /.*/ thatmatches everything up to the last - or : (i.e. $decl_end). Fix it bytightening up this regex and not matching those characters as part of theidentifier.Link: https://lore.kernel.org/all/CAGXJAmzfRzE=A94NT5ETtj3bZc-=2oLg-9E5Kjh4o_-iuw1q8g@mail.gmail.com/Reported-by: John Ousterhout Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Vegard Nossum Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20241221222214.1969823-1-vegard.nossum@oracle.com List of files: /linux-6.15/scripts/kernel-doc

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

Tue, 10 Dec 2024 11:04:15 +0000

scripts/kernel-doc: Get -export option working againSince commit cdd30ebb1b9f ("module: Convert symbol namespace to stringliteral"), exported symbols marked by EXPORT_SYMBOL_NS(_GPL) areignored by "kernel-doc -export" in fresh build of "make htmldocs".This is because regex in the perl script for those markers fails tomatch 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 betoo strict for quoted strings. Instead, use \S, which matches anynon-whitespace character, for compatibility with possible extensionof 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 Cc: Masahiro Yamada Tested-by: Randy Dunlap Acked-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/e5c43f36-45cd-49f4-b7b8-ff342df3c7a4@gmail.com List of files: /linux-6.15/scripts/kernel-doc

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

Tue, 15 Oct 2024 18:11:07 +0000

kernel-doc: allow object-like macros in ReST outputoutput_function_rst() does not handle object-like macros. It presentsa trailing "()" while output_function_man() handles these macroscorrectly.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 thereare no parameters.I have tested this quite a bit with my ad hoc test files for both ReSTand man format outputs. The generated output looks good.Fixes: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros")Signed-off-by: Randy Dunlap Cc: Horia Geanta Tested-by: Vlastimil Babka Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20241015181107.536894-1-rdunlap@infradead.org List of files: /linux-6.15/scripts/kernel-doc

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

Tue, 08 Oct 2024 08:29:04 +0000

scripts/kernel-doc: Do not track section counter across processed filesThe section counter tracks how many sections of kernel-doc were added.The only real use of the counter value is to check if anything wasactually supposed to be output and give a warning is nothing isavailable.The current logic of remembering the initial value and then resettingthe value then when processing each file means that if a file has thesame number of sections as the previously processed one, a warning isincorrectly given.Fixes: 1da177e4c3f4 ("Linux-2.6.12-rc2")Signed-off-by: Chen-Yu Tsai Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20241008082905.4005524-1-wenst@chromium.org List of files: /linux-6.15/scripts/kernel-doc

82f5ee35 - scripts/kernel-doc: Fix build time warnings

Thu, 10 Oct 2024 22:59:33 +0000

scripts/kernel-doc: Fix build time warningsAs stated at Documentation/kbuild/llvm.rst, to make usage of ccache onemust set KBUILD_BUILD_TIMESTAMP=''. Setting this together with W=1will trigger the following warning for every compiled file: date: invalid date ‘+%s’This comes from kernel-doc script, that produces the following commandwhen KBUILD_BUILD_TIMESTAMP is empty: date -d"" +%sThat triggers the warning above. Add a space between the flag `-d` andthe string argument to fix date command and remove the warning.Signed-off-by: André Almeida Acked-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20241010225933.166436-1-andrealmeid@igalia.com List of files: /linux-6.15/scripts/kernel-doc

67f2df3b - mm/slab: Plumb kmem_buckets into __do_kmalloc_node()

Mon, 01 Jul 2024 19:12:59 +0000

mm/slab: Plumb kmem_buckets into __do_kmalloc_node()Introduce CONFIG_SLAB_BUCKETS which provides the infrastructure tosupport separated kmalloc buckets (in the following kmem_buckets_create()patches and future codetag-based separation). Since this will providea mitigation for a very common case of exploits, it is recommended toenable this feature for general purpose distros. By default, the newKconfig will be enabled if CONFIG_SLAB_FREELIST_HARDENED is enabled (andit is added to the hardening.config Kconfig fragment).To be able to choose which buckets to allocate from, make the bucketsavailable to the internal kmalloc interfaces by adding them as thesecond argument, rather than depending on the buckets being chosen fromthe 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 thetop-level macros and static inlines use the buckets argument (wherethey are stripped out and compiled out respectively). The actual externfunctions can then be built without the argument, and the internalsfall back to the global kmalloc buckets unconditionally.Co-developed-by: Vlastimil Babka Signed-off-by: Kees Cook Signed-off-by: Vlastimil Babka List of files: /linux-6.15/scripts/kernel-doc

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

Fri, 03 May 2024 18:26:50 +0000

kernel-doc: Added "*" in $type_constants2 to fix 'make htmldocs' warning.Fixed: WARNING: Inline literal start-string without end-string inDocumentation/core-api/workqueue.rstAdded "*" in $type_constants2 in kernel-doc script to include "*" in theconversion to hightlights.Previously: %WQ_* --> ``WQ_``*After Changes: %WQ_* --> ``WQ_*``Need for the fix: ``* is not recognized as a valid end-string for inlineliteral.Link: https://lore.kernel.org/linux-doc/640114d2-5780-48c3-a294-c0eba230f984@gmail.comSigned-off-by: Utkarsh Tripathi Suggested-by: Akira Yokosawa Reviewed-by: Akira Yokosawa Link: https://lore.kernel.org/r/20240503182650.7761-1-utripathi2002@gmail.comSigned-off-by: Jonathan Corbet List of files: /linux-6.15/scripts/kernel-doc

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

Tue, 26 Mar 2024 05:41:49 +0000

scripts/kernel-doc: drop "_noprof" on function prototypesMemory profiling introduces macros as hooks for function-level allocationprofiling[1]. Memory allocation functions that are profiled are namedlike xyz_alloc() for API access to the function. xyz_alloc() then callsxyz_alloc_noprof() to do the allocation work.The kernel-doc comments for the memory allocation functions are introducedwith the xyz_alloc() function names but the function implementations arethe xyz_alloc_noprof() names. This causes kernel-doc warnings formismatched documentation and function prototype names. By dropping the"_noprof" part of the function name, the kernel-doc function name matchesthe function prototype name, so the warnings are resolved.[1] https://lore.kernel.org/all/20240321163705.3067592-1-surenb@google.com/Link: https://lkml.kernel.org/r/20240326054149.2121-1-rdunlap@infradead.orgSigned-off-by: Randy Dunlap Reported-by: Stephen Rothwell Closes: https://lore.kernel.org/all/20240325123603.1bdd6588@canb.auug.org.au/Tested-by: Suren Baghdasaryan Cc: Jonathan Corbet Cc: Kent Overstreet Signed-off-by: Andrew Morton List of files: /linux-6.15/scripts/kernel-doc

5f8e4007 - kernel-doc: fix struct_group_tagged() parsing

Thu, 11 Apr 2024 09:32:08 +0000

kernel-doc: fix struct_group_tagged() parsingkernel-doc emits a warning on struct_group_tagged() if you describe yourstruct 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 validembedded 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 Closes: https://lore.kernel.org/netdev/20240405212513.0d189968@kernel.orgFixes: 50d7bd38c3aa ("stddef: Introduce struct_group() helper macro")Signed-off-by: Kees Cook Co-developed-by: Alexander Lobakin Signed-off-by: Alexander Lobakin Reviewed-by: Przemek Kitszel Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240411093208.2483580-1-aleksander.lobakin@intel.com List of files: /linux-6.15/scripts/kernel-doc

0ec69b3b - docs: Fix bitfield handling in kernel-doc

Tue, 26 Mar 2024 17:38:25 +0000

docs: Fix bitfield handling in kernel-dockernel-doc doesn't handle bitfields that are specified with symbolicname, e.g. u32 cs_index_mask : SPI_CS_CNT_MAXThis 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 justdigits.Signed-off-by: Donald Hunter Acked-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240326173825.99190-1-donald.hunter@gmail.com List of files: /linux-6.15/scripts/kernel-doc

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

Wed, 27 Mar 2024 14:22:39 +0000

compiler_types: add Endianness-dependent __counted_by_{le,be}Some structures contain flexible arrays at the end and the counter forthem, but the counter has explicit Endianness and thus __counted_by()can't be used directly.To increase test coverage for potential problems without breakinganything, introduce __counted_by_{le,be}() defined depending onplatform's Endianness to either __counted_by() when applicable or noopotherwise.Maybe it would be a good idea to introduce such attributes on compilerlevel if possible, but for now let's stop on what we have.Acked-by: Kees Cook Acked-by: Gustavo A. R. Silva Signed-off-by: Alexander Lobakin Reviewed-by: Przemek Kitszel Link: https://lore.kernel.org/r/20240327142241.1745989-2-aleksander.lobakin@intel.comSigned-off-by: Jakub Kicinski List of files: /linux-6.15/scripts/kernel-doc

69fc23ef - kernel-doc: Add unary operator * to $type_param_ref

Tue, 27 Feb 2024 05:03:30 +0000

kernel-doc: Add unary operator * to $type_param_refIn 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 byusing inline-literal form of ``*param``, both of which are specificto Sphinx/docutils.Such workarounds are against the kenrel-doc's ideal and should betterbe avoided.Instead, add "*" to the list of unary operators kernel-doc recognizesand make the form of *@param available in kernel-doc comments.Reported-by: Stephen Rothwell Link: [1] https://lore.kernel.org/r/20240223153636.41358be5@canb.auug.org.au/Acked-by: Christoph Hellwig Signed-off-by: Akira Yokosawa Cc: Jonathan Corbet Cc: Mauro Carvalho Chehab Acked-by: Jonathan Corbet Signed-off-by: Chandan Babu R List of files: /linux-6.15/scripts/kernel-doc

8e93cb78 - kernel-doc: handle #if in enums as well

Wed, 14 Feb 2024 13:29:38 +0000

kernel-doc: handle #if in enums as wellIn addition to #ifdef, #define and #endif, also handleany #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 findany with kernel-doc as well. However, it came up as wewere adding such a construct in our driver and warningsfrom kernel-doc were the result.Signed-off-by: Johannes Berg Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240214142937.80ee86a3beae.Ibcc5bd97a20cd10a792663e4b254cd46c7e8b520@changeid List of files: /linux-6.15/scripts/kernel-doc

9f6f4c11 - scripts/kernel-doc: simplify signature printing

Thu, 15 Feb 2024 13:48:27 +0000

scripts/kernel-doc: simplify signature printingUntangle some of the $is_macro logic and the nested conditionals.This makes it easier to see where and how the signature is actuallyprinted.No functional change.Signed-off-by: Vegard Nossum Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240215134828.1277109-5-vegard.nossum@oracle.com List of files: /linux-6.15/scripts/kernel-doc

d3c55a71 - scripts/kernel-doc: separate out function signature

Thu, 15 Feb 2024 13:48:26 +0000

scripts/kernel-doc: separate out function signatureFormat the entire function signature and place it in a separate variable;this both makes it easier to understand what these lines of code are doingand will allow us to simplify the code further in the following patch.No functional change.Signed-off-by: Vegard Nossum Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240215134828.1277109-4-vegard.nossum@oracle.com List of files: /linux-6.15/scripts/kernel-doc

e8ebb853 - scripts/kernel-doc: simplify function printing

Thu, 15 Feb 2024 13:48:25 +0000

scripts/kernel-doc: simplify function printingGet rid of the $start variable, since it's really not necessary.No functional change.Signed-off-by: Vegard Nossum Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240215134828.1277109-3-vegard.nossum@oracle.com List of files: /linux-6.15/scripts/kernel-doc