linux-kernel - RE: [Intel-wired-lan] [PATCH v3 05/30] docs: kdoc_parser: add functions support for NestedMatch

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: <IA3PR11MB89860FD08C812DF59CA6F004E59EA@IA3PR11MB8986.namprd11.prod.outlook.com>
Date: Thu, 29 Jan 2026 10:27:05 +0000
From: "Loktionov, Aleksandr" <aleksandr.loktionov@...el.com>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>, Jonathan Corbet
	<corbet@....net>, Linux Doc Mailing List <linux-doc@...r.kernel.org>
CC: "bpf@...r.kernel.org" <bpf@...r.kernel.org>,
	"intel-wired-lan@...ts.osuosl.org" <intel-wired-lan@...ts.osuosl.org>,
	"linux-hardening@...r.kernel.org" <linux-hardening@...r.kernel.org>,
	"linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
	"netdev@...r.kernel.org" <netdev@...r.kernel.org>, Mauro Carvalho Chehab
	<mchehab@...nel.org>, Randy Dunlap <rdunlap@...radead.org>
Subject: RE: [Intel-wired-lan] [PATCH v3 05/30] docs: kdoc_parser: add
 functions support for NestedMatch



> -----Original Message-----
> From: Intel-wired-lan <intel-wired-lan-bounces@...osl.org> On Behalf
> Of Mauro Carvalho Chehab
> Sent: Thursday, January 29, 2026 9:08 AM
> To: Jonathan Corbet <corbet@....net>; Linux Doc Mailing List <linux-
> doc@...r.kernel.org>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>;
> bpf@...r.kernel.org; intel-wired-lan@...ts.osuosl.org; linux-
> hardening@...r.kernel.org; linux-kernel@...r.kernel.org;
> netdev@...r.kernel.org; Mauro Carvalho Chehab <mchehab@...nel.org>;
> Randy Dunlap <rdunlap@...radead.org>
> Subject: [Intel-wired-lan] [PATCH v3 05/30] docs: kdoc_parser: add
> functions support for NestedMatch
> 
> Some annotations macros may have nested parenthesis, causing normal
> regex parsing to fail.
> 
> Extend apply_transforms to also use NestedMatch and add support for
> nested functions.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
> Acked-by: Randy Dunlap <rdunlap@...radead.org>
> Tested-by: Randy Dunlap <rdunlap@...radead.org>
> ---
>  tools/lib/python/kdoc/kdoc_parser.py | 38 ++++++++++++++++++---------
> -
>  1 file changed, 25 insertions(+), 13 deletions(-)
> 
> diff --git a/tools/lib/python/kdoc/kdoc_parser.py
> b/tools/lib/python/kdoc/kdoc_parser.py
> index 3ba2cda2487a..ae5b2ef80f75 100644
> --- a/tools/lib/python/kdoc/kdoc_parser.py
> +++ b/tools/lib/python/kdoc/kdoc_parser.py
> @@ -152,7 +152,7 @@ struct_xforms = [
>      (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern +
> r'\)', re.S), r'__u32 \1'),  ]  # -# Regexes here are guaranteed to
> have the end delimiter matching
> +# Struct regexes here are guaranteed to have the end delimiter
> matching
>  # the start delimiter. Yet, right now, only one replace group  # is
> allowed.
>  #
> @@ -160,6 +160,13 @@ struct_nested_prefixes = [
>      (re.compile(r'\bSTRUCT_GROUP\('), r'\1'),  ]
> 
> +#
> +# Function Regexes here are guaranteed to have the end delimiter
> +matching # the start delimiter.
> +#
> +function_nested_prefixes = [
> +]
> +
>  #
>  # Transforms for function prototypes
>  #
> @@ -207,13 +214,6 @@ var_xforms = [
>  # Ancillary functions
>  #
> 
> -def apply_transforms(xforms, text):
> -    """
> -    Apply a set of transforms to a block of text.
> -    """
> -    for search, subst in xforms:
> -        text = search.sub(subst, text)
> -    return text
> 
>  multi_space = KernRe(r'\s\s+')
>  def trim_whitespace(s):
> @@ -408,6 +408,8 @@ class KernelDoc:
>          # Place all potential outputs into an array
>          self.entries = []
> 
> +        self.nested = NestedMatch()
> +
>          #
>          # We need Python 3.7 for its "dicts remember the insertion
>          # order" guarantee
> @@ -505,6 +507,16 @@ class KernelDoc:
>          # State flags
>          self.state = state.NORMAL
> 
> +    def apply_transforms(self, regex_xforms, nested_xforms, text):
> +        """Apply a set of transforms to a block of text."""
> +        for search, subst in regex_xforms:
> +            text = search.sub(subst, text)
> +
> +        for search, sub in nested_xforms:
> +            text = self.nested.sub(search, sub, text)
> +
> +        return text.strip()
> +
>      def push_parameter(self, ln, decl_type, param, dtype,
>                         org_arg, declaration_name):
>          """
> @@ -881,11 +893,9 @@ class KernelDoc:
>          # Go through the list of members applying all of our
> transformations.
>          #
>          members = trim_private_members(members)
> -        members = apply_transforms(struct_xforms, members)
> +        members = self.apply_transforms(struct_xforms,
> struct_nested_prefixes,
> +                                        members)
> 
> -        nested = NestedMatch()
> -        for search, sub in struct_nested_prefixes:
> -            members = nested.sub(search, sub, members)
>          #
>          # Deal with embedded struct and union members, and drop enums
> entirely.
>          #
> @@ -1088,7 +1098,9 @@ class KernelDoc:
>              #
>              # Apply the initial transformations.
>              #
> -            prototype = apply_transforms(function_xforms, prototype)
> +            prototype = self.apply_transforms(function_xforms,
> +
> function_nested_prefixes,
> +                                              prototype)
> 
>          # Yes, this truly is vile.  We are looking for:
>          # 1. Return type (may be nothing if we're looking at a macro)
> --
> 2.52.0

Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@...el.com>