linux-kernel - Re: [PATCH v3 1/2] kernel-doc: add support for handling global variables

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 for Android: free password hash cracker in your pocket

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

Message-ID: <81442fc3-d8db-4446-8071-e72febceab69@infradead.org>
Date: Tue, 18 Nov 2025 21:18:06 -0800
From: Randy Dunlap <rdunlap@...radead.org>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: Linux Doc Mailing List <linux-doc@...r.kernel.org>,
 Jonathan Corbet <corbet@....net>, Mauro Carvalho Chehab
 <mchehab@...nel.org>, linux-kernel@...r.kernel.org
Subject: Re: [PATCH v3 1/2] kernel-doc: add support for handling global
 variables



On 11/18/25 1:02 AM, Mauro Carvalho Chehab wrote:
> Em Mon, 17 Nov 2025 22:59:24 -0800
> Randy Dunlap <rdunlap@...radead.org> escreveu:
> 
>> Hi,
>>
>> On 11/16/25 3:23 AM, Mauro Carvalho Chehab wrote:
>>> Specially on kAPI, sometimes it is desirable to be able to
>>> describe global variables that are part of kAPI.
>>>
>>> Documenting vars with Sphinx is simple, as we don't need
>>> to parse a data struct. All we need is the variable
>>> declaration and use natice C domain ::c:var: to format it
>>> for us.
>>>
>>> Add support for it.
>>>
>>> Link: https://lore.kernel.org/linux-doc/491c3022-cef8-4860-a945-c9c4a3b63c09@infradead.org/T/#m947c25d95cb1d96a394410ab1131dc8e9e5013f1
>>> Suggested-by: Randy Dunlap <rdunlap@...radead.org>
>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
>>> ---
>>>  scripts/lib/kdoc/kdoc_output.py | 45 ++++++++++++++++++++++++++
>>>  scripts/lib/kdoc/kdoc_parser.py | 56 ++++++++++++++++++++++++++++++++-
>>>  2 files changed, 100 insertions(+), 1 deletion(-)  
>>
>> Thanks for the update. It's looking much better.
> 
> Great!
> 
>> I have a few comments/questions, all about typedefs.
> 

Hi Mauro,

I just noticed that in my sample init/kdoc-globals-test.c file
(I have s/global/var/ in it), there is one global var that is missing
or misparsed:

// from net/core/rtnetlink.c:
/**
 * var rtnl_mutex - historical global lock for networking control operations.
 *
 * @rtnl_mutex is used to serialize rtnetlink requests
 * and protect all kernel internal data structures related to networking.
 *
 * See Documentation/networking/netdevices.rst for details.
 * Often known as the rtnl_lock, although rtnl_lock is a kernel function.
 */
static DEFINE_MUTEX(rtnl_mutex);

This var is completely missing in the html output. In the man output,
it is rendered like this:

NAME
       static DEFINE_MUTEX - historical global lock for networking control  op‐
       erations.

SYNOPSIS
       static DEFINE_MUTEX;

Description
       rtnl_mutex  is used to serialize rtnetlink requests and protect all ker‐
       nel internal data structures  related  to  networking.   See  Documenta‐
       tion/networking/netdevices.rst   for   details.    Often  known  as  the
       rtnl_lock, although rtnl_lock is a kernel function.


-- 
~Randy