kernel-doc: make it parse new functions and structs

index 2816bd9f90f8..19e777e2c97e 100644
@@ -106,6 +106,13 @@ class KernRe:
 
         return self.last_match.group(num)
 
+    def groups(self):
+        """
+        Returns the group results of the last match
+        """
+
+        return self.last_match.groups()
+
 
 class NestedMatch:
     """

index 19e777e2c97e..a0402c065d3a 100644
@@ -265,7 +265,7 @@ class NestedMatch:
             out += new_sub
 
             # Drop end ';' if any
-            if line[pos] == ';':
+            if pos < len(line) and line[pos] == ';':
                 pos += 1
 
             cur_pos = pos

index fd57944ae907..0b68b140cd02 100644
@@ -191,6 +191,18 @@ function_xforms  = [
     (KernRe(r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+"), ""),
 ]
 
+#
+# Transforms for variable prototypes
+#
+var_xforms = [
+    (KernRe(r"__read_mostly"), ""),
+    (KernRe(r"__ro_after_init"), ""),
+    (KernRe(r"(?://.*)$"), ""),
+    (KernRe(r"(?:/\*.*\*/)"), ""),
+    (KernRe(r";$"), ""),
+    (KernRe(r"=.*"), ""),
+]
+
 #
 # Ancillary functions
 #

@@ -971,15 +983,6 @@ class KernelDoc:
         ]
         OPTIONAL_VAR_ATTR = "^(?:" + "|".join(VAR_ATTRIBS) + ")?"
 
-        sub_prefixes = [
-            (KernRe(r"__read_mostly"), ""),
-            (KernRe(r"__ro_after_init"), ""),
-            (KernRe(r"(?://.*)$"), ""),
-            (KernRe(r"(?:/\*.*\*/)"), ""),
-            (KernRe(r";$"), ""),
-            (KernRe(r"=.*"), ""),
-        ]
-
         #
         # Store the full prototype before modifying it
         #

@@ -1003,7 +1006,7 @@ class KernelDoc:
         # Drop comments and macros to have a pure C prototype
         #
         if not declaration_name:
-            for r, sub in sub_prefixes:
+            for r, sub in var_xforms:
                 proto = r.sub(sub, proto)
 
         proto = proto.rstrip()

index 0b68b140cd02..3ba2cda2487a 100644
@@ -163,7 +163,7 @@ struct_nested_prefixes = [
 #
 # Transforms for function prototypes
 #
-function_xforms  = [
+function_xforms = [
     (KernRe(r"^static +"), ""),
     (KernRe(r"^extern +"), ""),
     (KernRe(r"^asmlinkage +"), ""),

@@ -1065,10 +1065,7 @@ class KernelDoc:
         found = func_macro = False
         return_type = ''
         decl_type = 'function'
-        #
-        # Apply the initial transformations.
-        #
-        prototype = apply_transforms(function_xforms, prototype)
+
         #
         # If we have a macro, remove the "#define" at the front.
         #

@@ -1087,6 +1084,11 @@ class KernelDoc:
                 declaration_name = r.group(1)
                 func_macro = True
                 found = True
+        else:
+            #
+            # Apply the initial transformations.
+            #
+            prototype = apply_transforms(function_xforms, prototype)
 
         # Yes, this truly is vile.  We are looking for:
         # 1. Return type (may be nothing if we're looking at a macro)

index 3ba2cda2487a..ae5b2ef80f75 100644
@@ -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)

index ae5b2ef80f75..64165d8df84e 100644
@@ -165,6 +165,7 @@ struct_nested_prefixes = [
 # the start delimiter.
 #
 function_nested_prefixes = [
+    (re.compile(r"__attribute__\s*\("), ""),
 ]
 
 #

@@ -195,7 +196,6 @@ function_xforms = [
     (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""),
     (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1, \2"),
     (KernRe(r"__attribute_const__ +"), ""),
-    (KernRe(r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+"), ""),
 ]
 
 #

index 64165d8df84e..201c4f7298d7 100644
@@ -1027,14 +1027,14 @@ class KernelDoc:
 
         default_val = None
 
-        r= KernRe(OPTIONAL_VAR_ATTR + r"\w.*\s+(?:\*+)?([\w_]+)\s*[\d\]\[]*\s*(=.*)?")
+        r= KernRe(OPTIONAL_VAR_ATTR + r"[\w_]*\s+(?:\*+)?([\w_]+)\s*[\d\]\[]*\s*(=.*)?")
         if r.match(proto):
             if not declaration_name:
                 declaration_name = r.group(1)
 
             default_val = r.group(2)
         else:
-            r= KernRe(OPTIONAL_VAR_ATTR + r"(?:\w.*)?\s+(?:\*+)?(?:[\w_]+)\s*[\d\]\[]*\s*(=.*)?")
+            r= KernRe(OPTIONAL_VAR_ATTR + r"(?:[\w_]*)?\s+(?:\*+)?(?:[\w_]+)\s*[\d\]\[]*\s*(=.*)?")
         if r.match(proto):
             default_val = r.group(1)
 

index 201c4f7298d7..cbfdaba39494 100644
@@ -1035,9 +1035,9 @@ class KernelDoc:
             default_val = r.group(2)
         else:
             r= KernRe(OPTIONAL_VAR_ATTR + r"(?:[\w_]*)?\s+(?:\*+)?(?:[\w_]+)\s*[\d\]\[]*\s*(=.*)?")
-        if r.match(proto):
-            default_val = r.group(1)
 
+            if r.match(proto):
+                default_val = r.group(1)
         if not declaration_name:
            self.emit_msg(ln,f"{proto}: can't parse variable")
            return

index cbfdaba39494..ccee4e0bcaab 100644
@@ -1033,11 +1033,19 @@ class KernelDoc:
                 declaration_name = r.group(1)
 
             default_val = r.group(2)
+
+            self.config.log.debug("Variable proto parser: %s from '%s'",
+                                  r.groups(), proto)
+
         else:
             r= KernRe(OPTIONAL_VAR_ATTR + r"(?:[\w_]*)?\s+(?:\*+)?(?:[\w_]+)\s*[\d\]\[]*\s*(=.*)?")
 
             if r.match(proto):
                 default_val = r.group(1)
+
+        if default_val:
+            self.config.log.debug("default: '%s'", default_val)
+
         if not declaration_name:
            self.emit_msg(ln,f"{proto}: can't parse variable")
            return

@@ -1045,6 +1053,9 @@ class KernelDoc:
         if default_val:
             default_val = default_val.lstrip("=").strip()
 
+        self.config.log.debug("'%s' variable prototype: '%s', default: %s",
+                              declaration_name, proto, default_val)
+
         self.output_declaration("var", declaration_name,
                                 full_proto=full_proto,
                                 default_val=default_val,

index ccee4e0bcaab..0b6cba442d72 100644
@@ -207,7 +207,6 @@ var_xforms = [
     (KernRe(r"(?://.*)$"), ""),
     (KernRe(r"(?:/\*.*\*/)"), ""),
     (KernRe(r";$"), ""),
-    (KernRe(r"=.*"), ""),
 ]
 
 #

index 0b6cba442d72..21cc4e19a1e8 100644
@@ -1026,7 +1026,7 @@ class KernelDoc:
 
         default_val = None
 
-        r= KernRe(OPTIONAL_VAR_ATTR + r"[\w_]*\s+(?:\*+)?([\w_]+)\s*[\d\]\[]*\s*(=.*)?")
+        r= KernRe(OPTIONAL_VAR_ATTR + r"\s*[\w_\s]*\s+(?:\*+)?([\w_]+)\s*[\d\]\[]*\s*(=.*)?")
         if r.match(proto):
             if not declaration_name:
                 declaration_name = r.group(1)

@@ -1037,7 +1037,7 @@ class KernelDoc:
                                   r.groups(), proto)
 
         else:
-            r= KernRe(OPTIONAL_VAR_ATTR + r"(?:[\w_]*)?\s+(?:\*+)?(?:[\w_]+)\s*[\d\]\[]*\s*(=.*)?")
+            r= KernRe(OPTIONAL_VAR_ATTR + r"(?:[\w_\s]*)?\s+(?:\*+)?(?:[\w_]+)\s*[\d\]\[]*\s*(=.*)?")
 
             if r.match(proto):
                 default_val = r.group(1)

index 21cc4e19a1e8..92b550189988 100644
@@ -81,6 +81,8 @@ struct_xforms = [
     (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '),
     (KernRe(r'\s*__counted_by\s*\([^;]*\)', re.S), ' '),
     (KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '),
+    (KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ' '),
+    (KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ' '),
     (KernRe(r'\s*__packed\s*', re.S), ' '),
     (KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '),
     (KernRe(r'\s*__private', re.S), ' '),

@@ -165,6 +167,16 @@ struct_nested_prefixes = [
 # the start delimiter.
 #
 function_nested_prefixes = [
+    (re.compile(r"__cond_acquires\s*\("), ""),
+    (re.compile(r"__cond_releases\s*\("), ""),
+    (re.compile(r"__acquires\s*\("), ""),
+    (re.compile(r"__releases\s*\("), ""),
+    (re.compile(r"__must_hold\s*\("), ""),
+    (re.compile(r"__must_not_hold\s*\("), ""),
+    (re.compile(r"__must_hold_shared\s*\("), ""),
+    (re.compile(r"__cond_acquires_shared\s*\("), ""),
+    (re.compile(r"__acquires_shared\s*\("), ""),
+    (re.compile(r"__releases_shared\s*\("), ""),
     (re.compile(r"__attribute__\s*\("), ""),
 ]
 

@@ -195,6 +207,7 @@ function_xforms = [
     (KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), ""),
     (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""),
     (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1, \2"),
+    (KernRe(r"__no_context_analysis\s*"), ""),
     (KernRe(r"__attribute_const__ +"), ""),
 ]
 

@@ -204,6 +217,8 @@ function_xforms = [
 var_xforms = [
     (KernRe(r"__read_mostly"), ""),
     (KernRe(r"__ro_after_init"), ""),
+    (KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ""),
+    (KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ""),
     (KernRe(r"(?://.*)$"), ""),
     (KernRe(r"(?:/\*.*\*/)"), ""),
     (KernRe(r";$"), ""),

index 92b550189988..33710c4be145 100644
@@ -219,6 +219,7 @@ var_xforms = [
     (KernRe(r"__ro_after_init"), ""),
     (KernRe(r'\s*__guarded_by\s*\([^\)]*\)', re.S), ""),
     (KernRe(r'\s*__pt_guarded_by\s*\([^\)]*\)', re.S), ""),
+    (KernRe(r"LIST_HEAD\(([\w_]+)\)"), r"struct list_head \1"),
     (KernRe(r"(?://.*)$"), ""),
     (KernRe(r"(?:/\*.*\*/)"), ""),
     (KernRe(r";$"), ""),

index 33710c4be145..db140363104a 100644
@@ -152,6 +152,7 @@ struct_xforms = [
             struct_args_pattern + r'\)', re.S), r'\1 \2[]'),
     (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + struct_args_pattern + r'\)', re.S), r'dma_addr_t \1'),
     (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)', re.S), r'__u32 \1'),
+    (KernRe(r'VIRTIO_DECLARE_FEATURES\(([\w_]+)\)'), r'union { u64 \1; u64 \1_array[VIRTIO_FEATURES_U64S]; }'),
 ]
 #
 # Struct regexes here are guaranteed to have the end delimiter matching

index a0402c065d3a..1861799f1966 100644
@@ -195,6 +195,8 @@ class NestedMatch:
         for match_re in regex.finditer(line):
             start = match_re.start()
             offset = match_re.end()
+            string_char = None
+            escape = False
 
             d = line[offset - 1]
             if d not in self.DELIMITER_PAIRS:

@@ -208,6 +210,22 @@ class NestedMatch:
 
                 d = line[pos]
 
+                if escape:
+                    escape = False
+                    continue
+
+                if string_char:
+                    if d == '\\':
+                        escape = True
+                    elif d == string_char:
+                        string_char = None
+
+                    continue
+
+                if d in ('"', "'"):
+                    string_char = d
+                    continue
+
                 if d in self.DELIMITER_PAIRS:
                     end = self.DELIMITER_PAIRS[d]
 

index 1861799f1966..f082f82bad67 100644
@@ -52,7 +52,10 @@ class KernRe:
         return self.regex.pattern
 
     def __repr__(self):
-        return f're.compile("{self.regex.pattern}")'
+        if self.regex.flags:
+            return f'KernRe("{self.regex.pattern}", {self.regex.flags})'
+        else:
+            return f'KernRe("{self.regex.pattern}")'
 
     def __add__(self, other):
         """

index f082f82bad67..b6e11ee0be21 100644
@@ -81,6 +81,13 @@ class KernRe:
         self.last_match = self.regex.search(string)
         return self.last_match
 
+    def finditer(self,  string):
+        """
+        Alias to re.finditer.
+        """
+
+        return self.regex.finditer(string)
+
     def findall(self, string):
         """
         Alias to re.findall.

@@ -116,6 +123,16 @@ class KernRe:
 
         return self.last_match.groups()
 
+#: Nested delimited pairs (brackets and parenthesis)
+DELIMITER_PAIRS = {
+    '{': '}',
+    '(': ')',
+    '[': ']',
+}
+
+#: compiled delimiters
+RE_DELIM = KernRe(r'[\{\}\[\]\(\)]')
+
 
 class NestedMatch:
     """

@@ -165,14 +182,6 @@ class NestedMatch:
     #
     #   FOO(arg1, arg2, arg3)
 
-    DELIMITER_PAIRS = {
-        '{': '}',
-        '(': ')',
-        '[': ']',
-    }
-
-    RE_DELIM = re.compile(r'[\{\}\[\]\(\)]')
-
     def _search(self, regex, line):
         """
         Finds paired blocks for a regex that ends with a delimiter.

@@ -202,13 +211,13 @@ class NestedMatch:
             escape = False
 
             d = line[offset - 1]
-            if d not in self.DELIMITER_PAIRS:
+            if d not in DELIMITER_PAIRS:
                 continue
 
-            end = self.DELIMITER_PAIRS[d]
+            end = DELIMITER_PAIRS[d]
             stack.append(end)
 
-            for match in self.RE_DELIM.finditer(line[offset:]):
+            for match in RE_DELIM.finditer(line[offset:]):
                 pos = match.start() + offset
 
                 d = line[pos]

@@ -229,8 +238,8 @@ class NestedMatch:
                     string_char = d
                     continue
 
-                if d in self.DELIMITER_PAIRS:
-                    end = self.DELIMITER_PAIRS[d]
+                if d in DELIMITER_PAIRS:
+                    end = DELIMITER_PAIRS[d]
 
                     stack.append(end)
                     continue

index db140363104a..4d52a00acfad 100644
@@ -160,7 +160,7 @@ struct_xforms = [
 # is allowed.
 #
 struct_nested_prefixes = [
-    (re.compile(r'\bSTRUCT_GROUP\('), r'\1'),
+    (re.compile(r'\bSTRUCT_GROUP\('), r'\0'),
 ]
 
 #

index b6e11ee0be21..28ca5032f40c 100644
@@ -271,8 +271,9 @@ class NestedMatch:
         It matches a regex that it is followed by a delimiter,
         replacing occurrences only if all delimiters are paired.
 
-        if r'\1' is used, it works just like re: it places there the
-        matched paired data with the delimiter stripped.
+        if r'\0' is used, it works on a similar way of using re.group(0):
+        it places the entire args of the matched paired data, with the
+        delimiter stripped.
 
         If count is different than zero, it will replace at most count
         items.

@@ -288,9 +289,9 @@ class NestedMatch:
             # Value, ignoring start/end delimiters
             value = line[end:pos - 1]
 
-            # replaces \1 at the sub string, if \1 is used there
+            # replaces \0 at the sub string, if \0 is used there
             new_sub = sub
-            new_sub = new_sub.replace(r'\1', value)
+            new_sub = new_sub.replace(r'\0', value)
 
             out += new_sub
 

index 4d52a00acfad..3a5614106af7 100644
@@ -153,32 +153,7 @@ struct_xforms = [
     (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + struct_args_pattern + r'\)', re.S), r'dma_addr_t \1'),
     (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)', re.S), r'__u32 \1'),
     (KernRe(r'VIRTIO_DECLARE_FEATURES\(([\w_]+)\)'), r'union { u64 \1; u64 \1_array[VIRTIO_FEATURES_U64S]; }'),
-]
-#
-# Struct regexes here are guaranteed to have the end delimiter matching
-# the start delimiter. Yet, right now, only one replace group
-# is allowed.
-#
-struct_nested_prefixes = [
-    (re.compile(r'\bSTRUCT_GROUP\('), r'\0'),
-]
-
-#
-# Function Regexes here are guaranteed to have the end delimiter matching
-# the start delimiter.
-#
-function_nested_prefixes = [
-    (re.compile(r"__cond_acquires\s*\("), ""),
-    (re.compile(r"__cond_releases\s*\("), ""),
-    (re.compile(r"__acquires\s*\("), ""),
-    (re.compile(r"__releases\s*\("), ""),
-    (re.compile(r"__must_hold\s*\("), ""),
-    (re.compile(r"__must_not_hold\s*\("), ""),
-    (re.compile(r"__must_hold_shared\s*\("), ""),
-    (re.compile(r"__cond_acquires_shared\s*\("), ""),
-    (re.compile(r"__acquires_shared\s*\("), ""),
-    (re.compile(r"__releases_shared\s*\("), ""),
-    (re.compile(r"__attribute__\s*\("), ""),
+    (NestedMatch(r'\bSTRUCT_GROUP\('), r'\0'),
 ]
 
 #

@@ -210,6 +185,17 @@ function_xforms = [
     (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1, \2"),
     (KernRe(r"__no_context_analysis\s*"), ""),
     (KernRe(r"__attribute_const__ +"), ""),
+    (NestedMatch(r"__cond_acquires\s*\("), ""),
+    (NestedMatch(r"__cond_releases\s*\("), ""),
+    (NestedMatch(r"__acquires\s*\("), ""),
+    (NestedMatch(r"__releases\s*\("), ""),
+    (NestedMatch(r"__must_hold\s*\("), ""),
+    (NestedMatch(r"__must_not_hold\s*\("), ""),
+    (NestedMatch(r"__must_hold_shared\s*\("), ""),
+    (NestedMatch(r"__cond_acquires_shared\s*\("), ""),
+    (NestedMatch(r"__acquires_shared\s*\("), ""),
+    (NestedMatch(r"__releases_shared\s*\("), ""),
+    (NestedMatch(r"__attribute__\s*\("), ""),
 ]
 
 #

@@ -230,7 +216,6 @@ var_xforms = [
 # Ancillary functions
 #
 
-
 multi_space = KernRe(r'\s\s+')
 def trim_whitespace(s):
     """

@@ -424,8 +409,6 @@ 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

@@ -523,14 +506,11 @@ class KernelDoc:
         # State flags
         self.state = state.NORMAL
 
-    def apply_transforms(self, regex_xforms, nested_xforms, text):
+    def apply_transforms(self, xforms, text):
         """Apply a set of transforms to a block of text."""
-        for search, subst in regex_xforms:
+        for search, subst in 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,

@@ -909,8 +889,7 @@ class KernelDoc:
         # Go through the list of members applying all of our transformations.
         #
         members = trim_private_members(members)
-        members = self.apply_transforms(struct_xforms, struct_nested_prefixes,
-                                        members)
+        members = self.apply_transforms(struct_xforms, members)
 
         #
         # Deal with embedded struct and union members, and drop enums entirely.

@@ -1125,9 +1104,7 @@ class KernelDoc:
             #
             # Apply the initial transformations.
             #
-            prototype = self.apply_transforms(function_xforms,
-                                              function_nested_prefixes,
-                                              prototype)
+            prototype = self.apply_transforms(function_xforms, prototype)
 
         # Yes, this truly is vile.  We are looking for:
         # 1. Return type (may be nothing if we're looking at a macro)

index 28ca5032f40c..aabfd6c4fd71 100644
@@ -182,7 +182,10 @@ class NestedMatch:
     #
     #   FOO(arg1, arg2, arg3)
 
-    def _search(self, regex, line):
+    def __init__(self, regex):
+        self.regex = KernRe(regex)
+
+    def _search(self, line):
         """
         Finds paired blocks for a regex that ends with a delimiter.
 

@@ -204,7 +207,7 @@ class NestedMatch:
 
         stack = []
 
-        for match_re in regex.finditer(line):
+        for match_re in self.regex.finditer(line):
             start = match_re.start()
             offset = match_re.end()
             string_char = None

@@ -252,7 +255,7 @@ class NestedMatch:
                         yield start, offset, pos + 1
                         break
 
-    def search(self, regex, line):
+    def search(self, line):
         """
         This is similar to re.search:
 

@@ -260,11 +263,11 @@ class NestedMatch:
         returning occurrences only if all delimiters are paired.
         """
 
-        for t in self._search(regex, line):
+        for t in self._search(line):
 
             yield line[t[0]:t[2]]
 
-    def sub(self, regex, sub, line, count=0):
+    def sub(self, sub, line, count=0):
         """
         This is similar to re.sub:
 

@@ -283,7 +286,7 @@ class NestedMatch:
         cur_pos = 0
         n = 0
 
-        for start, end, pos in self._search(regex, line):
+        for start, end, pos in self._search(line):
             out += line[cur_pos:start]
 
             # Value, ignoring start/end delimiters

index aabfd6c4fd71..f49a568b9155 100644
@@ -267,6 +267,59 @@ class NestedMatch:
 
             yield line[t[0]:t[2]]
 
+    @staticmethod
+    def _split_args(all_args, delim=","):
+        """
+        Helper method to split comma-separated function arguments
+        or struct elements, if delim is set to ";".
+
+        It returns a list of arguments that can be used later on by
+        the sub() method.
+        """
+        args = [all_args]
+        stack = []
+        arg_start = 0
+        string_char = None
+        escape = False
+
+        for idx, d in enumerate(all_args):
+            if escape:
+                escape = False
+                continue
+
+            if string_char:
+                if d == '\\':
+                    escape = True
+                elif d == string_char:
+                    string_char = None
+
+                continue
+
+            if d in ('"', "'"):
+                string_char = d
+                continue
+
+            if d in DELIMITER_PAIRS:
+                end = DELIMITER_PAIRS[d]
+
+                stack.append(end)
+                continue
+
+            if stack and d == stack[-1]:
+                stack.pop()
+                continue
+
+            if d == delim and not stack:
+                args.append(all_args[arg_start:idx].strip())
+                arg_start = idx + 1
+
+        # Add the last argument (if any)
+        last = all_args[arg_start:].strip()
+        if last:
+            args.append(last)
+
+        return args
+
     def sub(self, sub, line, count=0):
         """
         This is similar to re.sub:

@@ -292,9 +345,13 @@ class NestedMatch:
             # Value, ignoring start/end delimiters
             value = line[end:pos - 1]
 
-            # replaces \0 at the sub string, if \0 is used there
+            # replace arguments
             new_sub = sub
-            new_sub = new_sub.replace(r'\0', value)
+            if "\\" in sub:
+                args = self._split_args(value)
+
+                new_sub = re.sub(r'\\(\d+)',
+                                 lambda m: args[int(m.group(1))], new_sub)
 
             out += new_sub
 

new file mode 100755
index 000000000000..e438472fa704
@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-2.0
+# Copyright(c) 2025-2026: Mauro Carvalho Chehab <[email protected]>.
+#
+# pylint: disable=C0103,R0912,R0914,E1101
+
+"""
+Helper class to better display unittest results.
+
+Those help functions provide a nice colored output summary of each
+executed test and, when a test fails, it shows the different in diff
+format when running in verbose mode, like::
+
+    $ tools/unittests/nested_match.py -v
+    ...
+    Traceback (most recent call last):
+    File "/new_devel/docs/tools/unittests/nested_match.py", line 69, in test_count_limit
+        self.assertEqual(replaced, "bar(a); bar(b); foo(c)")
+        ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    AssertionError: 'bar(a) foo(b); foo(c)' != 'bar(a); bar(b); foo(c)'
+    - bar(a) foo(b); foo(c)
+    ?       ^^^^
+    + bar(a); bar(b); foo(c)
+    ?       ^^^^^
+    ...
+
+It also allows filtering what tests will be executed via ``-k`` parameter.
+
+Typical usage is to do::
+
+    from unittest_helper import run_unittest
+    ...
+
+    if __name__ == "__main__":
+        run_unittest(__file__)
+
+If passing arguments is needed, on a more complex scenario, it can be
+used like on this example::
+
+    from unittest_helper import TestUnits, run_unittest
+    ...
+    env = {'sudo': ""}
+    ...
+    if __name__ == "__main__":
+        runner = TestUnits()
+        base_parser = runner.parse_args()
+        base_parser.add_argument('--sudo', action='store_true',
+                                help='Enable tests requiring sudo privileges')
+
+        args = base_parser.parse_args()
+
+        # Update module-level flag
+        if args.sudo:
+            env['sudo'] = "1"
+
+        # Run tests with customized arguments
+        runner.run(__file__, parser=base_parser, args=args, env=env)
+"""
+
+import argparse
+import atexit
+import os
+import re
+import unittest
+import sys
+
+from unittest.mock import patch
+
+
+class Summary(unittest.TestResult):
+    """
+    Overrides unittest.TestResult class to provide a nice colored
+    summary. When in verbose mode, displays actual/expected difference in
+    unified diff format.
+    """
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+        #: Dictionary to store organized test results
+        self.test_results = {}
+
+        #: max length of the test names
+        self.max_name_length = 0
+
+    def startTest(self, test):
+        super().startTest(test)
+        test_id = test.id()
+        parts = test_id.split(".")
+        # Extract module, class, and method names
+        if len(parts) >= 3:
+            module_name = parts[-3]
+        else:
+            module_name = ""
+        if len(parts) >= 2:
+            class_name = parts[-2]
+        else:
+            class_name = ""
+        method_name = parts[-1]
+        # Build the hierarchical structure
+        if module_name not in self.test_results:
+            self.test_results[module_name] = {}
+        if class_name not in self.test_results[module_name]:
+            self.test_results[module_name][class_name] = []
+        # Track maximum test name length for alignment
+        display_name = f"{method_name}:"
+
+        self.max_name_length = max(len(display_name), self.max_name_length)
+
+    def _record_test(self, test, status):
+        test_id = test.id()
+        parts = test_id.split(".")
+        if len(parts) >= 3:
+            module_name = parts[-3]
+        else:
+            module_name = ""
+        if len(parts) >= 2:
+            class_name = parts[-2]
+        else:
+            class_name = ""
+        method_name = parts[-1]
+        self.test_results[module_name][class_name].append((method_name, status))
+
+    def addSuccess(self, test):
+        super().addSuccess(test)
+        self._record_test(test, "OK")
+
+    def addFailure(self, test, err):
+        super().addFailure(test, err)
+        self._record_test(test, "FAIL")
+
+    def addError(self, test, err):
+        super().addError(test, err)
+        self._record_test(test, "ERROR")
+
+    def addSkip(self, test, reason):
+        super().addSkip(test, reason)
+        self._record_test(test, f"SKIP ({reason})")
+
+    def printResults(self):
+        """
+        Print results using colors if tty.
+        """
+        # Check for ANSI color support
+        use_color = sys.stdout.isatty()
+        COLORS = {
+            "OK":            "\033[32m",   # Green
+            "FAIL":          "\033[31m",   # Red
+            "SKIP":          "\033[1;33m", # Yellow
+            "PARTIAL":       "\033[33m",   # Orange
+            "EXPECTED_FAIL": "\033[36m",   # Cyan
+            "reset":         "\033[0m",    # Reset to default terminal color
+        }
+        if not use_color:
+            for c in COLORS:
+                COLORS[c] = ""
+
+        # Calculate maximum test name length
+        if not self.test_results:
+            return
+        try:
+            lengths = []
+            for module in self.test_results.values():
+                for tests in module.values():
+                    for test_name, _ in tests:
+                        lengths.append(len(test_name) + 1)  # +1 for colon
+            max_length = max(lengths) + 2  # Additional padding
+        except ValueError:
+            sys.exit("Test list is empty")
+
+        # Print results
+        for module_name, classes in self.test_results.items():
+            print(f"{module_name}:")
+            for class_name, tests in classes.items():
+                print(f"    {class_name}:")
+                for test_name, status in tests:
+                    # Get base status without reason for SKIP
+                    if status.startswith("SKIP"):
+                        status_code = status.split()[0]
+                    else:
+                        status_code = status
+                    color = COLORS.get(status_code, "")
+                    print(
+                        f"        {test_name + ':':<{max_length}}{color}{status}{COLORS['reset']}"
+                    )
+            print()
+
+        # Print summary
+        print(f"\nRan {self.testsRun} tests", end="")
+        if hasattr(self, "timeTaken"):
+            print(f" in {self.timeTaken:.3f}s", end="")
+        print()
+
+        if not self.wasSuccessful():
+            print(f"\n{COLORS['FAIL']}FAILED (", end="")
+            failures = getattr(self, "failures", [])
+            errors = getattr(self, "errors", [])
+            if failures:
+                print(f"failures={len(failures)}", end="")
+            if errors:
+                if failures:
+                    print(", ", end="")
+                print(f"errors={len(errors)}", end="")
+            print(f"){COLORS['reset']}")
+
+
+def flatten_suite(suite):
+    """Flatten test suite hierarchy"""
+    tests = []
+    for item in suite:
+        if isinstance(item, unittest.TestSuite):
+            tests.extend(flatten_suite(item))
+        else:
+            tests.append(item)
+    return tests
+
+
+class TestUnits:
+    """
+    Helper class to set verbosity level
+    """
+    def parse_args(self):
+        """Returns a parser for command line arguments."""
+        parser = argparse.ArgumentParser(description="Test runner with regex filtering")
+        parser.add_argument("-v", "--verbose", action="count", default=1)
+        parser.add_argument("-f", "--failfast", action="store_true")
+        parser.add_argument("-k", "--keyword",
+                            help="Regex pattern to filter test methods")
+        return parser
+
+    def run(self, caller_file, parser=None, args=None, env=None):
+        """Execute all tests from the unity test file"""
+        if not args:
+            if not parser:
+                parser = self.parse_args()
+            args = parser.parse_args()
+
+        if env:
+            patcher = patch.dict(os.environ, env)
+            patcher.start()
+            # ensure it gets stopped after
+            atexit.register(patcher.stop)
+
+        verbose = args.verbose
+
+        if verbose >= 2:
+            unittest.TextTestRunner(verbosity=verbose).run = lambda suite: suite
+
+        # Load ONLY tests from the calling file
+        loader = unittest.TestLoader()
+        suite = loader.discover(start_dir=os.path.dirname(caller_file),
+                                pattern=os.path.basename(caller_file))
+
+        # Flatten the suite for environment injection
+        tests_to_inject = flatten_suite(suite)
+
+        # Filter tests by method name if -k specified
+        if args.keyword:
+            try:
+                pattern = re.compile(args.keyword)
+                filtered_suite = unittest.TestSuite()
+                for test in tests_to_inject:  # Use the pre-flattened list
+                    method_name = test.id().split(".")[-1]
+                    if pattern.search(method_name):
+                        filtered_suite.addTest(test)
+                suite = filtered_suite
+            except re.error as e:
+                sys.stderr.write(f"Invalid regex pattern: {e}\n")
+                sys.exit(1)
+        else:
+            # Maintain original suite structure if no keyword filtering
+            suite = unittest.TestSuite(tests_to_inject)
+
+        if verbose >= 2:
+            resultclass = None
+        else:
+            resultclass = Summary
+
+        runner = unittest.TextTestRunner(verbosity=args.verbose,
+                                            resultclass=resultclass,
+                                            failfast=args.failfast)
+        result = runner.run(suite)
+        if resultclass:
+            result.printResults()
+
+        sys.exit(not result.wasSuccessful())
+
+
+def run_unittest(fname):
+    """
+    Basic usage of TestUnits class.
+    Use it when there's no need to pass any extra argument to the tests.
+    """
+    TestUnits().run(fname)

new file mode 100755
index 000000000000..570e98730b28
@@ -0,0 +1,589 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-2.0
+# Copyright(c) 2026: Mauro Carvalho Chehab <[email protected]>.
+#
+# pylint: disable=C0413,R0904
+
+
+"""
+Unit tests for kernel-doc NestedMatch.
+"""
+
+import os
+import re
+import sys
+import unittest
+
+# Import Python modules
+
+SRC_DIR = os.path.dirname(os.path.realpath(__file__))
+sys.path.insert(0, os.path.join(SRC_DIR, "../lib/python"))
+
+from kdoc.kdoc_re import NestedMatch
+from unittest_helper import run_unittest
+
+# --------------------------------------------------------------------------
+# Verify if struct_group matches are properly handled
+# --------------------------------------------------------------------------
+
+
+class TestStructGroup(unittest.TestCase):
+    """
+    Test diferent struct_group patterns.
+
+    Please notice that in this class, there are multiple whitespaces on
+    some places. That's because it tries to mimic how kernel-doc parser
+    internally works.
+    """
+
+    @classmethod
+    def setUpClass(cls):
+        """
+        Define a NestedMatch to be used for all tests picking all
+        struct_group macros.
+        """
+        cls.matcher = NestedMatch(r"\bstruct_group[\w\_]*\(")
+
+    def _check_matches(self, line: str, expected_count: int):
+        """count and validate each match"""
+
+        matches = list(self.matcher.search(line))
+        self.assertEqual(len(matches), expected_count,
+                         msg=f"Expected {expected_count} matches, got {len(matches)}")
+
+        for m in matches:
+            self.assertTrue(m.startswith("struct_group") and "(" in m,
+                            msg=f"Match does not start correctly: {m!r}")
+            self.assertTrue(m.endswith(")"),
+                            msg=f"Match does not end correctly: {m!r}")
+
+    def test_struct_group_01(self):
+        """one struct_group with nested delimiters."""
+        line = (
+            "__be16 id; struct_group(body, __be16 epl_len; u8 lpl_len; u8"
+            " chk_code; u8 resv1; u8 resv2; u8"
+            " payload[ETHTOOL_CMIS_CDB_LPL_MAX_PL_LENGTH]; ); u8 *epl;"
+        )
+        self._check_matches(line, 1)
+
+    def test_struct_group_02(self):
+        """two struct_group_tagged, one per page_pool_params."""
+        line = (
+            "struct_group_tagged(page_pool_params_fast, fast, unsigned int   "
+            " order; unsigned int    pool_size; int             nid; struct"
+            " device   *dev; struct napi_struct *napi; enum dma_data_direction"
+            " dma_dir; unsigned int    max_len; unsigned int    offset; );"
+            " struct_group_tagged(page_pool_params_slow, slow, struct"
+            " net_device *netdev; unsigned int queue_idx; unsigned int   "
+            " flags;)"
+        )
+        self._check_matches(line, 2)
+
+    def test_struct_group_03(self):
+        """two struct_group_tagged, one with nested structs."""
+        line = (
+            "struct_group_tagged(libeth_xskfq_fp, fp, struct xsk_buff_pool   "
+            " *pool; struct libeth_xdp_buff  **fqes; void                   "
+            " *descs; u32                     ntu; u32                    "
+            " count; );u32                     pending; u32                   "
+            "  thresh; u32                     buf_len; int                   "
+            "  nid;"
+        )
+        self._check_matches(line, 1)
+
+    def test_struct_group_04(self):
+        """one struct_group_tagged with many fields."""
+        line = (
+            "struct_group_tagged(libeth_fq_fp, fp, struct page_pool       "
+            " *pp; struct libeth_fqe       *fqes; u32                    "
+            " truesize; u32                     count; );enum libeth_fqe_type "
+            "   type:2; bool                    hsplit:1; bool                "
+            "    xdp:1; u32                     buf_len; int                  "
+            "   nid;"
+        )
+        self._check_matches(line, 1)
+
+    def test_struct_group_05(self):
+        """long line with a struct_group(priv_flags_fast)."""
+        line = (
+            "  struct_group(priv_flags_fast, unsigned long          "
+            " priv_flags:32; unsigned long           lltx:1; unsigned long    "
+            "       netmem_tx:1; ); const struct net_device_ops *netdev_ops;"
+            " const struct header_ops *header_ops; struct netdev_queue    "
+            " *_tx; netdev_features_t       gso_partial_features; unsigned int"
+            "            real_num_tx_queues; unsigned int           "
+            " gso_max_size; unsigned int            gso_ipv4_max_size; u16    "
+            "                 gso_max_segs; s16                    "
+            " num_tc;unsigned int            mtu; unsigned short         "
+            " needed_headroom; struct netdev_tc_txq   "
+            " tc_to_txq[TC_MAX_QUEUE]; #ifdef CONFIG_XPS; struct xps_dev_maps "
+            " *xps_maps[XPS_MAPS_MAX]; #endif; #ifdef CONFIG_NETFILTER_EGRESS;"
+            " struct nf_hook_entries  *nf_hooks_egress; #endif; #ifdef"
+            " CONFIG_NET_XGRESS; struct bpf_mprog_entry  *tcx_egress; #endif;"
+            " union { struct pcpu_lstats __percpu             *lstats; struct"
+            " pcpu_sw_netstats __percpu        *tstats; struct pcpu_dstats"
+            " __percpu             *dstats; }; unsigned long           state;"
+            " unsigned int            flags; unsigned short         "
+            " hard_header_len; netdev_features_t       features; struct"
+            " inet6_dev   *ip6_ptr; struct bpf_prog    *xdp_prog; struct"
+            " list_head        ptype_specific; int                    "
+            " ifindex; unsigned int            real_num_rx_queues; struct"
+            " netdev_rx_queue  *_rx; unsigned int            gro_max_size;"
+            " unsigned int            gro_ipv4_max_size; rx_handler_func_t "
+            " *rx_handler; void               *rx_handler_data; possible_net_t"
+            "                  nd_net; #ifdef CONFIG_NETPOLL; struct"
+            " netpoll_info        *npinfo; #endif; #ifdef CONFIG_NET_XGRESS;"
+            " struct bpf_mprog_entry  *tcx_ingress; #endif; char              "
+            "      name[IFNAMSIZ]; struct netdev_name_node *name_node; struct"
+            " dev_ifalias  *ifalias;unsigned long           mem_end; unsigned"
+            " long           mem_start; unsigned long          "
+            " base_addr;struct list_head        dev_list; struct list_head    "
+            "    napi_list; struct list_head        unreg_list; struct"
+            " list_head        close_list; struct list_head        ptype_all;"
+            " struct { struct list_head upper; struct list_head lower; }"
+            " adj_list;xdp_features_t          xdp_features; const struct"
+            " xdp_metadata_ops *xdp_metadata_ops; const struct"
+            " xsk_tx_metadata_ops *xsk_tx_metadata_ops; unsigned short        "
+            "  gflags; unsigned short          needed_tailroom;"
+            " netdev_features_t       hw_features; netdev_features_t      "
+            " wanted_features; netdev_features_t       vlan_features;"
+            " netdev_features_t       hw_enc_features; netdev_features_t      "
+            " mpls_features; unsigned int            min_mtu; unsigned int    "
+            "        max_mtu; unsigned short          type; unsigned char     "
+            "      min_header_len; unsigned char           name_assign_type;"
+            " int                     group; struct net_device_stats"
+            " stats;struct net_device_core_stats __percpu *core_stats;atomic_t"
+            " tx_request;"
+        )
+        self._check_matches(line, 1)
+
+    def test_struct_group_06(self):
+        """struct_group(addrs)."""
+        line = (
+            "struct_group(addrs, unsigned char   h_dest[ETH_ALEN]; unsigned"
+            " char   h_source[ETH_ALEN]; ); __be16          h_vlan_proto;"
+            " __be16          h_vlan_TCI; __be16         "
+            " h_vlan_encapsulated_proto;"
+        )
+        self._check_matches(line, 1)
+
+    def test_struct_group_07(self):
+        """one struct_group(headers)."""
+        line = (
+            "union { struct {struct sk_buff          *next; struct sk_buff    "
+            "      *prev; union { struct net_device       *dev;unsigned long  "
+            "         dev_scratch; }; }; struct rb_node          rbnode;struct"
+            " list_head        list; struct llist_node       ll_node; };"
+            " struct sock             *sk; union { ktime_t         tstamp; u64"
+            "             skb_mstamp_ns;};char                    cb[48] ;"
+            " union { struct { unsigned long   _skb_refdst; void           "
+            " (*destructor)(struct sk_buff *skb); }; struct list_head       "
+            " tcp_tsorted_anchor; #ifdef CONFIG_NET_SOCK_MSG; unsigned long   "
+            "        _sk_redir; #endif; }; #if defined(CONFIG_NF_CONNTRACK) ||"
+            " defined(CONFIG_NF_CONNTRACK_MODULE); unsigned long           "
+            " _nfct; #endif; unsigned int            len, data_len; __u16     "
+            "              mac_len, hdr_len;__u16                  "
+            " queue_mapping;#ifdef __BIG_ENDIAN_BITFIELD; #define CLONED_MASK "
+            "    (1 << 7); #else; #define CLONED_MASK     1; #endif; #define"
+            " CLONED_OFFSET           offsetof(struct sk_buff,"
+            " __cloned_offset);  __u8                    cloned:1, nohdr:1,"
+            " fclone:2, peeked:1, head_frag:1, pfmemalloc:1,"
+            " pp_recycle:1;#ifdef CONFIG_SKB_EXTENSIONS; __u8                 "
+            "   active_extensions; #endif;struct_group(headers,  __u8         "
+            "           pkt_type:3;__u8                    ignore_df:1; __u8  "
+            "                  dst_pending_confirm:1; __u8                   "
+            " ip_summed:2; __u8                    ooo_okay:1;  __u8          "
+            "          tstamp_type:2;#ifdef CONFIG_NET_XGRESS; __u8           "
+            "         tc_at_ingress:1;__u8                   "
+            " tc_skip_classify:1; #endif; __u8                   "
+            " remcsum_offload:1; __u8                    csum_complete_sw:1;"
+            " __u8                    csum_level:2; __u8                   "
+            " inner_protocol_type:1; __u8                    l4_hash:1; __u8  "
+            "                  sw_hash:1; #ifdef CONFIG_WIRELESS; __u8        "
+            "            wifi_acked_valid:1; __u8                   "
+            " wifi_acked:1; #endif; __u8                    no_fcs:1;__u8     "
+            "               encapsulation:1; __u8                   "
+            " encap_hdr_csum:1; __u8                    csum_valid:1; #ifdef"
+            " CONFIG_IPV6_NDISC_NODETYPE; __u8                   "
+            " ndisc_nodetype:2; #endif; #if IS_ENABLED(CONFIG_IP_VS); __u8    "
+            "                ipvs_property:1; #endif; #if"
+            " IS_ENABLED(CONFIG_NETFILTER_XT_TARGET_TRACE) ||"
+            " IS_ENABLED(CONFIG_NF_TABLES); __u8                   "
+            " nf_trace:1; #endif; #ifdef CONFIG_NET_SWITCHDEV; __u8           "
+            "         offload_fwd_mark:1; __u8                   "
+            " offload_l3_fwd_mark:1; #endif; __u8                   "
+            " redirected:1; #ifdef CONFIG_NET_REDIRECT; __u8                  "
+            "  from_ingress:1; #endif; #ifdef CONFIG_NETFILTER_SKIP_EGRESS;"
+            " __u8                    nf_skip_egress:1; #endif; #ifdef"
+            " CONFIG_SKB_DECRYPTED; __u8                    decrypted:1;"
+            " #endif; __u8                    slow_gro:1; #if"
+            " IS_ENABLED(CONFIG_IP_SCTP); __u8                   "
+            " csum_not_inet:1; #endif; __u8                    unreadable:1;"
+            " #if defined(CONFIG_NET_SCHED) || defined(CONFIG_NET_XGRESS);"
+            " __u16                   tc_index;#endif; u16                    "
+            " alloc_cpu; union { __wsum          csum; struct { __u16  "
+            " csum_start; __u16   csum_offset; }; }; __u32                  "
+            " priority; int                     skb_iif; __u32                "
+            "   hash; union { u32             vlan_all; struct { __be16 "
+            " vlan_proto; __u16   vlan_tci; }; }; #if"
+            " defined(CONFIG_NET_RX_BUSY_POLL) || defined(CONFIG_XPS); union {"
+            " unsigned int    napi_id; unsigned int    sender_cpu; }; };"
+            " #ifdef CONFIG_NETWORK_SECMARK; __u32           secmark; #endif;"
+            " union { __u32           mark; __u32           reserved_tailroom;"
+            " }; union { __be16          inner_protocol; __u8           "
+            " inner_ipproto; }; __u16                  "
+            " inner_transport_header; __u16                  "
+            " inner_network_header; __u16                   inner_mac_header;"
+            " __be16                  protocol; __u16                  "
+            " transport_header; __u16                   network_header; __u16 "
+            "                  mac_header; #ifdef CONFIG_KCOV; u64            "
+            "         kcov_handle; #endif; );sk_buff_data_t          tail;"
+            " sk_buff_data_t          end; unsigned char           *head,"
+            " *data; unsigned int            truesize; refcount_t             "
+            " users; #ifdef CONFIG_SKB_EXTENSIONS;struct skb_ext         "
+            " *extensions; #endif;"
+        )
+        self._check_matches(line, 1)
+
+    def test_struct_group_08(self):
+        """two struct_group(stats)."""
+        line = (
+            "enum ethtool_mac_stats_src src; struct_group(stats, u64"
+            " tx_pause_frames; u64 rx_pause_frames; ); enum"
+            " ethtool_mac_stats_src src; struct_group(stats, u64"
+            " undersize_pkts; u64 oversize_pkts; u64 fragments; u64 jabbers;"
+            " u64 hist[ETHTOOL_RMON_HIST_MAX]; u64"
+            " hist_tx[ETHTOOL_RMON_HIST_MAX]; );"
+        )
+        self._check_matches(line, 2)
+
+    def test_struct_group_09(self):
+        """struct_group(tx_stats)."""
+        line = (
+            "struct_group(tx_stats, u64 pkts; u64 onestep_pkts_unconfirmed;"
+            " u64 lost; u64 err; );"
+        )
+        self._check_matches(line, 1)
+
+    def test_struct_group_10(self):
+        """struct_group(zeroed_on_hw_restart) with a nested struct."""
+        line = (
+            "struct_group(zeroed_on_hw_restart, u16 fw_id; struct { u8"
+            " allocated:1; u8 stop_full:1; } status; ); struct list_head list;"
+            " atomic_t tx_request;"
+        )
+        self._check_matches(line, 1)
+
+    def test_struct_group_11(self):
+        """struct_group(zeroed_on_hw_restart) with many fields."""
+        line = (
+            "struct_group(zeroed_on_hw_restart, unsigned int status; u32"
+            " uid_status[IWL_MAX_UMAC_SCANS]; u64 start_tsf; bool"
+            " last_ebs_failed; enum iwl_mld_pass_all_sched_results_states"
+            " pass_all_sched_res; u8 fw_link_id; struct { u32"
+            " last_stats_ts_usec; enum iwl_mld_traffic_load status; }"
+            " traffic_load; );size_t cmd_size; void *cmd; unsigned long"
+            " last_6ghz_passive_jiffies; unsigned long"
+            " last_start_time_jiffies; u64 last_mlo_scan_time;"
+        )
+        self._check_matches(line, 1)
+
+    def test_struct_group_12(self):
+        """struct_group(zeroed_on_hw_restart) with a huge struct."""
+        line = (
+            "struct_group(zeroed_on_hw_restart, struct ieee80211_bss_conf "
+            " *fw_id_to_bss_conf[IWL_FW_MAX_LINK_ID + 1]; struct ieee80211_vif"
+            "  *fw_id_to_vif[NUM_MAC_INDEX_DRIVER]; struct ieee80211_txq "
+            " *fw_id_to_txq[IWL_MAX_TVQM_QUEUES]; u8 used_phy_ids:"
+            " NUM_PHY_CTX; u8 num_igtks; struct { bool on; u32 ampdu_ref; bool"
+            " ampdu_toggle; u8 p80; struct { struct"
+            " iwl_rx_phy_air_sniffer_ntfy data; u8 valid:1, used:1; } phy;"
+            " #ifdef CONFIG_IWLWIFI_DEBUGFS; __le16 cur_aid; u8"
+            " cur_bssid[ETH_ALEN]; bool ptp_time; #endif; } monitor; #ifdef"
+            " CONFIG_PM_SLEEP; bool netdetect; #endif; struct ieee80211_vif"
+            " *p2p_device_vif; bool bt_is_active; struct ieee80211_vif"
+            " *nan_device_vif; ); struct ieee80211_link_sta "
+            " *fw_id_to_link_sta[IWL_STATION_COUNT_MAX];struct device *dev;"
+            " struct iwl_trans *trans; const struct iwl_rf_cfg *cfg; const"
+            " struct iwl_fw *fw; struct ieee80211_hw *hw; struct wiphy *wiphy;"
+            " struct wiphy_iftype_ext_capab"
+            " ext_capab[IWL_MLD_EXT_CAPA_NUM_IFTYPES]; u8"
+            " sta_ext_capab[IWL_MLD_STA_EXT_CAPA_SIZE]; struct iwl_nvm_data"
+            " *nvm_data; struct iwl_fw_runtime fwrt; struct dentry"
+            " *debugfs_dir; struct iwl_notif_wait_data notif_wait; struct"
+            " list_head async_handlers_list; spinlock_t async_handlers_lock;"
+            " struct wiphy_work async_handlers_wk; struct wiphy_delayed_work"
+            " ct_kill_exit_wk; struct { u32 running:1, do_not_dump_once:1,"
+            " #ifdef CONFIG_PM_SLEEP; in_d3:1, resuming:1, #endif;"
+            " in_hw_restart:1; } fw_status; struct { u32 hw:1, ct:1; }"
+            " radio_kill; u32 power_budget_mw; struct mac_address"
+            " addresses[IWL_MLD_MAX_ADDRESSES]; struct iwl_mld_scan scan;"
+            " struct iwl_mld_survey *channel_survey; #ifdef CONFIG_PM_SLEEP;"
+            " struct wiphy_wowlan_support wowlan; u32 debug_max_sleep; #endif;"
+            " #ifdef CONFIG_IWLWIFI_LEDS; struct led_classdev led; #endif;"
+            " enum iwl_mcc_source mcc_src; bool bios_enable_puncturing; struct"
+            " iwl_mld_baid_data  *fw_id_to_ba[IWL_MAX_BAID]; u8"
+            " num_rx_ba_sessions; struct iwl_mld_rx_queues_sync rxq_sync;"
+            " struct list_head txqs_to_add; struct wiphy_work add_txqs_wk;"
+            " spinlock_t add_txqs_lock; u8 *error_recovery_buf; struct"
+            " iwl_mcast_filter_cmd *mcast_filter_cmd; u8 mgmt_tx_ant; u8"
+            " set_tx_ant; u8 set_rx_ant; bool fw_rates_ver_3; struct"
+            " iwl_mld_low_latency low_latency; bool ibss_manager; #ifdef"
+            " CONFIG_THERMAL; struct thermal_zone_device *tzone; struct"
+            " iwl_mld_cooling_device cooling_dev; #endif; struct ptp_data"
+            " ptp_data; struct iwl_mld_time_sync_data  *time_sync; struct"
+            " ftm_initiator_data ftm_initiator;"
+        )
+        self._check_matches(line, 1)
+
+    def test_struct_group_13(self):
+        """struct_group(zeroed_on_not_authorized)."""
+        line = (
+            "struct_group(zeroed_on_not_authorized, u8 primary; u8"
+            " selected_primary; u16 selected_links; enum iwl_mld_emlsr_blocked"
+            " blocked_reasons; enum iwl_mld_emlsr_exit last_exit_reason;"
+            " unsigned long last_exit_ts; u8 exit_repeat_count; unsigned long"
+            " last_entry_ts; ); struct wiphy_work unblock_tpt_wk; struct"
+            " wiphy_delayed_work check_tpt_wk; struct wiphy_delayed_work"
+            " prevent_done_wk; struct wiphy_delayed_work tmp_non_bss_done_wk;"
+        )
+        self._check_matches(line, 1)
+
+    def test_struct_group_14(self):
+        """struct_group(zeroed_on_hw_restart) with nested struct."""
+        line = (
+            "struct_group(zeroed_on_hw_restart, u8 fw_id; struct"
+            " iwl_mld_session_protect session_protect; struct ieee80211_sta"
+            " *ap_sta; bool authorized; u8 num_associated_stas; bool"
+            " ap_ibss_active; enum iwl_mld_cca_40mhz_wa_status"
+            " cca_40mhz_workaround; #ifdef CONFIG_IWLWIFI_DEBUGFS; bool"
+            " beacon_inject_active; #endif; u8 low_latency_causes; bool"
+            " ps_disabled; time64_t last_link_activation_time; );struct"
+            " iwl_mld *mld; struct iwl_mld_link deflink; struct iwl_mld_link "
+            " *link[IEEE80211_MLD_MAX_NUM_LINKS]; struct iwl_mld_emlsr emlsr;"
+            " #ifdef CONFIG_PM_SLEEP; struct iwl_mld_wowlan_data wowlan_data;"
+            " #endif; #ifdef CONFIG_IWLWIFI_DEBUGFS; bool use_ps_poll; bool"
+            " disable_bf; struct dentry *dbgfs_slink; #endif; enum"
+            " iwl_roc_activity roc_activity; struct iwl_mld_int_sta aux_sta;"
+            " struct wiphy_delayed_work mlo_scan_start_wk;"
+        )
+        self._check_matches(line, 1)
+
+    def test_struct_group_15(self):
+        """struct_group(zeroed_on_hw_restart) with small struct."""
+        line = (
+            "struct_group(zeroed_on_hw_restart, u32 last_rate_n_flags; bool"
+            " in_fw; s8 signal_avg; );struct rcu_head rcu_head; u32 fw_id;"
+        )
+        self._check_matches(line, 1)
+
+    def test_struct_group_16(self):
+        """struct_group(zeroed_on_hw_restart) with many enums."""
+        line = (
+            "struct_group(zeroed_on_hw_restart, enum ieee80211_sta_state"
+            " sta_state; enum iwl_fw_sta_type sta_type; );struct iwl_mld *mld;"
+            " struct ieee80211_vif *vif; struct iwl_mld_rxq_dup_data"
+            " *dup_data; u8 tid_to_baid[IWL_MAX_TID_COUNT]; u8 data_tx_ant;"
+            " struct iwl_mld_link_sta deflink; struct iwl_mld_link_sta "
+            " *link[IEEE80211_MLD_MAX_NUM_LINKS]; struct iwl_mld_ptk_pn "
+            " *ptk_pn[IWL_NUM_DEFAULT_KEYS]; struct iwl_mld_per_q_mpdu_counter"
+            " *mpdu_counters;"
+        )
+        self._check_matches(line, 1)
+
+    def test_struct_group_17(self):
+        """struct_group(zeroed_on_hw_restart) with channel data."""
+        line = (
+            "struct_group(zeroed_on_hw_restart, u8 fw_id; struct"
+            " cfg80211_chan_def chandef; );u32 channel_load_by_us; u32"
+            " avg_channel_load_not_by_us; struct iwl_mld *mld;"
+        )
+        self._check_matches(line, 1)
+
+    def test_struct_group_18(self):
+        """mixture of struct_group and struct rcu_head."""
+        line = (
+            "struct rcu_head rcu_head;struct_group(zeroed_on_hw_restart, u8"
+            " fw_id; bool active; struct ieee80211_tx_queue_params"
+            " queue_params[IEEE80211_NUM_ACS]; struct ieee80211_chanctx_conf "
+            " *chan_ctx; bool he_ru_2mhz_block; struct ieee80211_key_conf"
+            " *igtk; struct ieee80211_key_conf  *bigtks[2]; );struct"
+            " iwl_mld_int_sta bcast_sta; struct iwl_mld_int_sta mcast_sta;"
+            " struct iwl_mld_int_sta mon_sta;struct ieee80211_key_conf"
+            " *ap_early_keys[6]; u32 average_beacon_energy; bool"
+            " silent_deactivation; struct iwl_probe_resp_data "
+            " *probe_resp_data;"
+        )
+        self._check_matches(line, 1)
+
+    def test_struct_group_19(self):
+        """x(ice_health_tx_hang_buf)."""
+        line = (
+            "struct devlink_health_reporter *fw; struct"
+            " devlink_health_reporter *mdd; struct devlink_health_reporter"
+            " *port; struct devlink_health_reporter *tx_hang;"
+            " struct_group_tagged(ice_health_tx_hang_buf, tx_hang_buf, struct"
+            " ice_tx_ring *tx_ring; u32 head; u32 intr; u16 vsi_num; ); struct"
+            " ice_aqc_health_status_elem fw_status; struct"
+            " ice_aqc_health_status_elem port_status;"
+        )
+        self._check_matches(line, 1)
+
+    def test_struct_group_sub(self):
+        """Replace struct_group body with a placeholder."""
+        line = "foo bar struct_group(my, a(b{c}), d); qux;"
+
+        result = NestedMatch(r"\bstruct_group\(").sub("REPLACED", line)
+        expected = "foo bar REPLACED qux;"
+
+        self.assertEqual(result, expected)
+
+
+class TestSubMacros(unittest.TestCase):
+    """
+    Test macros that will be dropped.
+    """
+
+    def test_acquires_simple(self):
+        """Simple replacement test with __acquires"""
+        line = "__acquires(ctx) foo();"
+        result = NestedMatch(r"__acquires\s*\(").sub("REPLACED", line)
+
+        self.assertNotIn("__acquires(", result)
+        self.assertIn("foo();", result)
+
+    def test_acquires_multiple(self):
+        """Multiple __acquires"""
+        line = "__acquires(ctx) __acquires(other) bar();"
+        result = NestedMatch(r"__acquires\s*\(").sub("REPLACED", line)
+
+        self.assertNotIn("__acquires(", result)
+        self.assertEqual(result.count("REPLACED"), 2)
+
+    def test_acquires_nested_paren(self):
+        """__acquires with nested pattern"""
+        line = "__acquires((ctx1, ctx2)) baz();"
+        result = NestedMatch(r"__acquires\s*\(").sub("REPLACED", line)
+
+        self.assertNotIn("__acquires(", result)
+        self.assertIn("baz();", result)
+
+    def test_must_hold(self):
+        """__must_hold with a pointer"""
+        line = "__must_hold(&lock) do_something();"
+        result = NestedMatch(r"__must_hold\s*\(").sub("REPLACED", line)
+
+        self.assertNotIn("__must_hold(", result)
+        self.assertIn("do_something();", result)
+
+    def test_must_hold_shared(self):
+        """__must_hold with an upercase defined value"""
+        line = "__must_hold_shared(RCU) other();"
+        result = NestedMatch(r"__must_hold_shared\s*\(").sub("REPLACED", line)
+
+        self.assertNotIn("__must_hold_shared(", result)
+        self.assertIn("other();", result)
+
+    def test_no_false_positive(self):
+        """
+        Ensure that unrelated text containing similar patterns is preserved
+        """
+        line = "call__acquires(foo);  // should stay intact"
+        result = NestedMatch(r"\b__acquires\s*\(").sub("REPLACED", line)
+
+        self.assertEqual(result, line)
+
+    def test_mixed_macros(self):
+        """Add a mix of macros"""
+        line = "__acquires(ctx) __releases(ctx) __must_hold(&lock) foo();"
+
+        result = NestedMatch(r"__acquires\s*\(").sub("REPLACED", line)
+        result = NestedMatch(r"__releases\s*\(").sub("REPLACED", result)
+        result = NestedMatch(r"__must_hold\s*\(").sub("REPLACED", result)
+
+        self.assertNotIn("__acquires(", result)
+        self.assertNotIn("__releases(", result)
+        self.assertNotIn("__must_hold(", result)
+
+        self.assertIn("foo();", result)
+
+    def test_no_macro_remains(self):
+        """Ensures that unmatched macros are untouched"""
+        line = "do_something_else();"
+        result = NestedMatch(r"__acquires\s*\(").sub("REPLACED", line)
+
+        self.assertEqual(result, line)
+
+
+class TestSubReplacement(unittest.TestCase):
+    """Test argument replacements"""
+
+    @classmethod
+    def setUpClass(cls):
+        """Define a NestedMatch to be used for all tests"""
+        cls.matcher = NestedMatch(re.compile(r"__acquires\s*\("))
+
+    def test_sub_with_capture(self):
+        """Test all arguments replacement with a single arg"""
+        line = "__acquires(&ctx) foo();"
+
+        result = self.matcher.sub(r"ACQUIRED(\0)", line)
+
+        self.assertIn("ACQUIRED(&ctx)", result)
+        self.assertIn("foo();", result)
+
+    def test_sub_zero_placeholder(self):
+        """Test all arguments replacement with a multiple args"""
+        line = "__acquires(arg1, arg2) bar();"
+
+        result = self.matcher.sub(r"REPLACED(\0)", line)
+
+        self.assertIn("bar();", result)
+        self.assertIn("REPLACED(arg1, arg2)", result)
+
+    def test_sub_single_placeholder(self):
+        """Single replacement rule for \1"""
+        line = "__acquires(ctx) foo();"
+        result = self.matcher.sub(r"ACQUIRED(\1)", line)
+
+        self.assertIn("foo();", result)
+        self.assertIn("ACQUIRED(ctx)", result)
+
+    def test_sub_multiple_placeholders(self):
+        """Replacement rule for both \1 and \2"""
+        line = "__acquires(arg1, arg2) bar();"
+        result = self.matcher.sub(r"REPLACE(\1, \2)", line)
+
+        self.assertIn("bar();", result)
+        self.assertIn("REPLACE(arg1, arg2)", result)
+
+    def test_sub_mixed_placeholders(self):
+        """Replacement rule for \0, \1 and additional text"""
+        line = "__acquires(foo, bar) baz();"
+        result = self.matcher.sub(r"START(\0) END(\1)", line)
+
+        self.assertIn("baz();", result)
+        self.assertIn("START(foo, bar) END(foo)", result)
+
+    def test_sub_no_placeholder(self):
+        """Replacement without placeholders"""
+        line = "__acquires(arg) foo();"
+        result = self.matcher.sub(r"NO_BACKREFS()", line)
+
+        self.assertIn("foo();", result)
+        self.assertIn("NO_BACKREFS()", result)
+
+    def test_sub_count_parameter(self):
+        """Verify that the algorithm stops after the requested count"""
+        line = "__acquires(a1) x(); __acquires(a2) y();"
+        result = self.matcher.sub(r"ONLY_FIRST(\1)", line, count=1)
+
+        self.assertIn("ONLY_FIRST(a1) x();", result)
+        self.assertIn("__acquires(a2) y();", result)
+
+
+# ----------------------------------------------------------------------
+# Run all tests
+# ----------------------------------------------------------------------
+if __name__ == "__main__":
+    run_unittest(__file__)

index e438472fa704..3cf1075b1de4 100755
@@ -8,21 +8,7 @@
 Helper class to better display unittest results.
 
 Those help functions provide a nice colored output summary of each
-executed test and, when a test fails, it shows the different in diff
-format when running in verbose mode, like::
-
-    $ tools/unittests/nested_match.py -v
-    ...
-    Traceback (most recent call last):
-    File "/new_devel/docs/tools/unittests/nested_match.py", line 69, in test_count_limit
-        self.assertEqual(replaced, "bar(a); bar(b); foo(c)")
-        ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-    AssertionError: 'bar(a) foo(b); foo(c)' != 'bar(a); bar(b); foo(c)'
-    - bar(a) foo(b); foo(c)
-    ?       ^^^^
-    + bar(a); bar(b); foo(c)
-    ?       ^^^^^
-    ...
+executed test.
 
 It also allows filtering what tests will be executed via ``-k`` parameter.
 

index 3a5614106af7..d2eb93f9d489 100644
@@ -124,10 +124,11 @@ struct_xforms = [
     # matched. So, the implementation to drop STRUCT_GROUP() will be
     # handled in separate.
     #
-    (KernRe(r'\bstruct_group\s*\(([^,]*,)', re.S), r'STRUCT_GROUP('),
-    (KernRe(r'\bstruct_group_attr\s*\(([^,]*,){2}', re.S), r'STRUCT_GROUP('),
-    (KernRe(r'\bstruct_group_tagged\s*\(([^,]*),([^,]*),', re.S), r'struct \1 \2; STRUCT_GROUP('),
-    (KernRe(r'\b__struct_group\s*\(([^,]*,){3}', re.S), r'STRUCT_GROUP('),
+    (NestedMatch(r'\bstruct_group\s*\('), r'\2'),
+    (NestedMatch(r'\bstruct_group_attr\s*\('), r'\3'),
+    (NestedMatch(r'\bstruct_group_tagged\s*\('), r'struct \1 { \3 } \2;'),
+    (NestedMatch(r'\b__struct_group\s*\('), r'\4'),
+
     #
     # Replace macros
     #

@@ -153,7 +154,6 @@ struct_xforms = [
     (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + struct_args_pattern + r'\)', re.S), r'dma_addr_t \1'),
     (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)', re.S), r'__u32 \1'),
     (KernRe(r'VIRTIO_DECLARE_FEATURES\(([\w_]+)\)'), r'union { u64 \1; u64 \1_array[VIRTIO_FEATURES_U64S]; }'),
-    (NestedMatch(r'\bSTRUCT_GROUP\('), r'\0'),
 ]
 
 #

index f49a568b9155..8d4cfdf8f479 100644
@@ -206,6 +206,9 @@ class NestedMatch:
         """
 
         stack = []
+        start = 0
+        offset = 0
+        pos = 0
 
         for match_re in self.regex.finditer(line):
             start = match_re.start()

@@ -255,6 +258,11 @@ class NestedMatch:
                         yield start, offset, pos + 1
                         break
 
+        # When /* private */ is used, it may end the end delimiterq
+        if stack:
+            stack.pop()
+            yield start, offset, len(line) + 1
+
     def search(self, line):
         """
         This is similar to re.search:

index 3cf1075b1de4..af16acc3af17 100755
@@ -213,7 +213,7 @@ class TestUnits:
                             help="Regex pattern to filter test methods")
         return parser
 
-    def run(self, caller_file, parser=None, args=None, env=None):
+    def run(self, caller_file, suite=None, parser=None, args=None, env=None):
         """Execute all tests from the unity test file"""
         if not args:
             if not parser:

@@ -232,9 +232,10 @@ class TestUnits:
             unittest.TextTestRunner(verbosity=verbose).run = lambda suite: suite
 
         # Load ONLY tests from the calling file
-        loader = unittest.TestLoader()
-        suite = loader.discover(start_dir=os.path.dirname(caller_file),
-                                pattern=os.path.basename(caller_file))
+        if not suite:
+            loader = unittest.TestLoader()
+            suite = loader.discover(start_dir=os.path.dirname(caller_file),
+                                    pattern=os.path.basename(caller_file))
 
         # Flatten the suite for environment injection
         tests_to_inject = flatten_suite(suite)

new file mode 100755
index 000000000000..2a5a754219de
@@ -0,0 +1,17 @@
+#!/bin/env python3
+import os
+import unittest
+import sys
+
+TOOLS_DIR=os.path.join(os.path.dirname(os.path.realpath(__file__)), "..")
+sys.path.insert(0, TOOLS_DIR)
+
+from lib.python.unittest_helper import TestUnits
+
+if __name__ == "__main__":
+    loader = unittest.TestLoader()
+
+    suite = loader.discover(start_dir=os.path.join(TOOLS_DIR, "unittests"),
+                            pattern="*.py")
+
+    TestUnits().run("", suite=suite)