linux-kernel - Re: [PATCH] scripts/kernel-doc: drop "

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <875xhaf145.fsf@trenco.lwn.net>
Date: Thu, 05 Jun 2025 13:18:50 -0600
From: Jonathan Corbet <corbet@....net>
To: Matthew Wilcox <willy@...radead.org>, Randy Dunlap <rdunlap@...radead.org>
Cc: linux-kernel@...r.kernel.org, linux-doc@...r.kernel.org, Andrew Morton
 <akpm@...ux-foundation.org>, Suren Baghdasaryan <surenb@...gle.com>, Mauro
 Carvalho Chehab <mchehab@...nel.org>
Subject: Re: [PATCH] scripts/kernel-doc: drop "_noprof" on function prototypes

Matthew Wilcox <willy@...radead.org> writes:

> On Mon, Mar 25, 2024 at 10:41:49PM -0700, Randy Dunlap wrote:
>> 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.
>
> This turns out not to be enough.  For example, krealloc() is
> currently undocumented.  This is because we match the function name
> in EXPORT_SYMBOL() against the function name in the comment, and they
> don't match.  This patch restores the documentation, although only
> for the python version of kernel-doc, and I'm pretty sure there's a
> better way to do it (eg building it into the export_symbol* regexes).
> I can turn this into a proper patch if this is the way to go, but for
> now it's just to illustrate the problem.

FWIW, I have no problem with leaving the perl version behind, I expect
we'll drop it in 6.17.

We see other variants of this problem out there, where we want to
document foo(), but that's really just a macro calling _foo(), where the
real code is.

I wonder if we could add some sort of a marker to the kerneldoc comment
saying "we are documenting foo(), but do you checks against _foo()"
instead?  That would be more general than trying to keep a list of
suffixes to hack off.

I'll try to ponder on this...

(Meanwhile I don't object to your fix as a short-term workaround)

jon

> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index 062453eefc7a..bdfa698d5570 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -1176,11 +1176,15 @@ class KernelDoc:
>
>          if export_symbol.search(line):
>              symbol = export_symbol.group(2)
> +            # See alloc_tags.h
> +            symbol = symbol.removesuffix('_noprof')
>              function_set.add(symbol)
>              return
>
>          if export_symbol_ns.search(line):
>              symbol = export_symbol_ns.group(2)
> +            # See alloc_tags.h
> +            symbol = symbol.removesuffix('_noprof')
>              function_set.add(symbol)
>
>      def process_normal(self, ln, line):