| 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
| ||
|
Message-ID: <20251117104543.42419bc5@foz.lan>
Date: Mon, 17 Nov 2025 10:45:43 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Randy Dunlap <rdunlap@...radead.org>
Cc: Linux Doc Mailing List <linux-doc@...r.kernel.org>, Jonathan Corbet
<corbet@....net>, linux-kernel@...r.kernel.org
Subject: Re: [PATCH] kernel-doc: add support for handling global variables
Em Tue, 9 Sep 2025 00:27:20 -0700
Randy Dunlap <rdunlap@...radead.org> escreveu:
> Hi Mauro,
>
> I have a few patch nits below, then some testing info.
>
>
> On 9/7/25 9:22 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 | 31 +++++++++++++++++++++++++++++++
> > scripts/lib/kdoc/kdoc_parser.py | 25 ++++++++++++++++++++++++-
> > 2 files changed, 55 insertions(+), 1 deletion(-)
> >
> > diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output.py
> > index 1eca9a918558..405a5c407522 100644
> > --- a/scripts/lib/kdoc/kdoc_output.py
> > +++ b/scripts/lib/kdoc/kdoc_output.py
> > @@ -199,6 +199,10 @@ class OutputFormat:
> > self.out_enum(fname, name, args)
> > return self.data
> >
> > + if dtype == "global":
> > + self.out_global(fname, name, args)
> > + return self.data
> > +
> > if dtype == "typedef":
> > self.out_typedef(fname, name, args)
> > return self.data
> > @@ -227,6 +231,9 @@ class OutputFormat:
> > def out_enum(self, fname, name, args):
> > """Outputs an enum"""
> >
> > + def out_global(self, fname, name, args):
> > + """Outputs a global variable"""
> > +
> > def out_typedef(self, fname, name, args):
> > """Outputs a typedef"""
> >
> > @@ -472,6 +479,18 @@ class RestFormat(OutputFormat):
> > self.lineprefix = oldprefix
> > self.out_section(args)
> >
> > + def out_global(self, fname, name, args):
> > + oldprefix = self.lineprefix
> > + ln = args.declaration_start_line
> > + prototype = args.other_stuff["var_type"]
> > +
> > + self.data += f"
> >
> > .. c:var:: {prototype}
> >
> > "
>
> Are the 5 lines above supposed to be on one line? Did git send-email split that up for you?
> There are a few others like this below.
> patch(1) complains when I try to apply the patch from this email.
This was a problem with my the mailbomb script I wrote in Python.
I was unable to make it transparent to encoding. Also, it replaced
\n with new lines.
I ended rolling back to my old Perl script.
>
> > +
> > + self.print_lineno(ln)
> > + self.lineprefix = " "
> > + self.output_highlight(args.get('purpose', ''))
> > + self.data += "
> > "
> > +
> > def out_typedef(self, fname, name, args):
> >
> > oldprefix = self.lineprefix
> > @@ -772,6 +791,18 @@ class ManFormat(OutputFormat):
> > self.data += f'.SH "{section}"' + "
> > "
> > self.output_highlight(text)
> >
> > + def out_global(self, fname, name, args):
> > + out_name = self.arg_name(args, name)
> > + prototype = args.other_stuff["var_type"]
> > +
> > + self.data += f'.TH "{self.modulename}" 9 "{out_name}" "{self.man_date}" "API Manual" LINUX' + "
> > "
> > +
> > + self.data += ".SH NAME
> > "
> > + self.data += f"{prototype} \- {args['purpose']}
>
> Python complains about the "\-" above. Other places nearby use "\\-"
Again, this was due to the mailbomb script not being transparent.
> so I changed it to that instead. Hope that's OK.
Yeah, \\ is the right way.
>
> > "
> > +
> > + self.data += ".SH SYNOPSIS
> > "
> > + self.data += f"enum {name}" + " {
> > "
> > +
> > def out_typedef(self, fname, name, args):
> > module = self.modulename
> > purpose = args.get('purpose')
> > diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> > index 574972e1f741..e2a3f4574894 100644
> > --- a/scripts/lib/kdoc/kdoc_parser.py
> > +++ b/scripts/lib/kdoc/kdoc_parser.py
> > @@ -64,7 +64,7 @@ type_param = KernRe(r"@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=False)
> > # Tests for the beginning of a kerneldoc block in its various forms.
> > #
> > doc_block = doc_com + KernRe(r'DOC:\s*(.*)?', cache=False)
> > -doc_begin_data = KernRe(r"^\s*\*?\s*(struct|union|enum|typedef).\s*(\w*)", cache = False)
> > +doc_begin_data = KernRe(r"^\s*\*?\s*(struct|union|enum|typedef|global).\s*(\w*)", cache = False)
> > doc_begin_func = KernRe(str(doc_com) + # initial " * '
> > r"(?:\w+\s*\*\s*)?" + # type (not captured)
> > r'(?:define\s+)?' + # possible "define" (not captured)
> > @@ -886,6 +886,27 @@ class KernelDoc:
> > self.output_declaration('enum', declaration_name,
> > purpose=self.entry.declaration_purpose)
> >
> > + def dump_global(self, ln, proto):
> > + """
> > + Stores global variables that are part of kAPI.
> > + """
> > + VAR_ATTRIBS = [
> > + "extern",
> > + ]
> > + OPTIONAL_VAR_ATTR = "^(?:" + "|".join(VAR_ATTRIBS) + ")?"
> > +
> > + r= KernRe(OPTIONAL_VAR_ATTR + r"(\w.*)\s+([\w_]+)[\d\]\[]*\s*;(?:#.*)?$")
> > + if not r.match(proto):
> > + self.emit_msg(ln,f"{proto}: can't parse variable")
> > + return
> > +
> > + declaration_name = r.group(2)
> > + var_type = r.group(0)
> > +
> > + self.output_declaration("global", declaration_name,
> > + var_type=var_type,
> > + purpose=self.entry.declaration_purpose)
> > +
> > def dump_declaration(self, ln, prototype):
> > """
> > Stores a data declaration inside self.entries array.
> > @@ -897,6 +918,8 @@ class KernelDoc:
> > self.dump_typedef(ln, prototype)
> > elif self.entry.decl_type in ["union", "struct"]:
> > self.dump_struct(ln, prototype)
> > + elif self.entry.decl_type == "global":
> > + self.dump_global(ln, prototype)
> > else:
> > # This would be a bug
> > self.emit_message(ln, f'Unknown declaration type: {self.entry.decl_type}')
> So, I grabbed some global data from 6-8 places in the kernel and put them intoinit/kdoc-globals-test.c. Then I modified Documentation/core-api/kernel-api.rst
> like this at the end of that file:
>
> +
> +Kernel Globals
> +==========================
> +
> +.. kernel-doc:: init/kdoc-globals-test.c
> + :identifiers:
>
> The html output says
> "Kernel Globals"
> but nothing else.
With the version I sent yesterday, after replacing:
global -> var
the symbols are there.
Thanks,
Mauro
Powered by blists - more mailing lists