[PATCH] docs: kdoc: strip DOMAIN_NS() wrapper in function prototypes

[PATCH] docs: kdoc: strip DOMAIN_NS() wrapper in function prototypes

[Omokefe Emmanuel Onanaroghene]

kernel-doc fails to parse functions whose names are wrapped in the
DOMAIN_NS() namespace macro, e.g. in
drivers/iommu/generic_pt/iommu_pt.h:217:

  ... expecting prototype for iova_to_phys(). Prototype was for
  DOMAIN_NS() instead

function_xforms is the designated place for unwrapping function-name
macros, but it has no entry for DOMAIN_NS(), so the macro name is kept
as the prototype and the real name leaks into the parameter list.

Add a transform expanding DOMAIN_NS(op) to op, following the existing
DEFINE_IDTENTRY_IRQ precedent.

Add a regression test for the wrapped iova_to_phys() declaration.

Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com>
---
 tools/lib/python/kdoc/xforms_lists.py |  6 ++++++
 tools/unittests/test_kdoc_parser.py   | 22 ++++++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py
index e3dda2fe8a53..5e8bd9117895 100644
--- a/tools/lib/python/kdoc/xforms_lists.py
+++ b/tools/lib/python/kdoc/xforms_lists.py
@@ -91,6 +91,12 @@ class CTransforms:
         (CMatch("__diagnose_as"), ""),
         (CMatch("DECL_BUCKET_PARAMS"), r"\1, \2"),
         (CMatch("DEFINE_IDTENTRY_IRQ"), r"static void \1(struct pt_regs *regs, u32 vector)"),
+        #
+        # DOMAIN_NS() wraps a function name with a namespace prefix
+        # (see drivers/iommu/generic_pt/iommu_pt.h). Unwrap it so the
+        # real function name is parsed.
+        #
+        (CMatch("DOMAIN_NS"), r"\1"),
         (CMatch("__cond_acquires"), ""),
         (CMatch("__cond_releases"), ""),
         (CMatch("__acquires"), ""),
diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdoc_parser.py
index c4a76ed13dbc..4b47a858824a 100755
--- a/tools/unittests/test_kdoc_parser.py
+++ b/tools/unittests/test_kdoc_parser.py
@@ -418,6 +418,28 @@ class TestSelfValidate(GenerateKdocItem):
         """
         self.run_test(self.SOURCE, [self.DEFAULT.copy()], self.EXPORTS)
 
+class TestDomainNs(GenerateKdocItem):
+    def test_domain_ns_wrapped_function(self):
+        source = """
+            /**
+             * iova_to_phys() - Return the output address for the given IOVA
+             * @domain: Table to query
+             * @iova: IO virtual address to query
+             */
+            phys_addr_t DOMAIN_NS(iova_to_phys)(struct iommu_domain *domain,
+                                                dma_addr_t iova);
+        """
+
+        kernel_doc = KernelDoc(self.config, "test.c", self.xforms)
+        patcher = patch('builtins.open', new_callable=mock_open,
+                        read_data=dedent(source))
+        with patcher:
+            _, entries = kernel_doc.parse_kdoc()
+
+        self.assertEqual(len(entries), 1)
+        self.assertEqual(entries[0].name, "iova_to_phys")
+        self.assertEqual(entries[0].warnings, [])
+
 #
 # Class and logic to create dynamic tests from YAML
 #
-- 
2.43.0

Re: [PATCH] docs: kdoc: strip DOMAIN_NS() wrapper in function prototypes

[Randy Dunlap]

On 10/1/26 9:15 PM, Omokefe Emmanuel Onanaroghene wrote:
> kernel-doc fails to parse functions whose names are wrapped in the
> DOMAIN_NS() namespace macro, e.g. in
> drivers/iommu/generic_pt/iommu_pt.h:217:
> 
>   ... expecting prototype for iova_to_phys(). Prototype was for
>   DOMAIN_NS() instead
> 
> function_xforms is the designated place for unwrapping function-name
> macros, but it has no entry for DOMAIN_NS(), so the macro name is kept
> as the prototype and the real name leaks into the parameter list.
> 
> Add a transform expanding DOMAIN_NS(op) to op, following the existing
> DEFINE_IDTENTRY_IRQ precedent.
> 
> Add a regression test for the wrapped iova_to_phys() declaration.
> 
> Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com>

Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
>  tools/lib/python/kdoc/xforms_lists.py |  6 ++++++
>  tools/unittests/test_kdoc_parser.py   | 22 ++++++++++++++++++++++
>  2 files changed, 28 insertions(+)
> 
> diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py
> index e3dda2fe8a53..5e8bd9117895 100644
> --- a/tools/lib/python/kdoc/xforms_lists.py
> +++ b/tools/lib/python/kdoc/xforms_lists.py
> @@ -91,6 +91,12 @@ class CTransforms:
>          (CMatch("__diagnose_as"), ""),
>          (CMatch("DECL_BUCKET_PARAMS"), r"\1, \2"),
>          (CMatch("DEFINE_IDTENTRY_IRQ"), r"static void \1(struct pt_regs *regs, u32 vector)"),
> +        #
> +        # DOMAIN_NS() wraps a function name with a namespace prefix
> +        # (see drivers/iommu/generic_pt/iommu_pt.h). Unwrap it so the
> +        # real function name is parsed.
> +        #
> +        (CMatch("DOMAIN_NS"), r"\1"),
>          (CMatch("__cond_acquires"), ""),
>          (CMatch("__cond_releases"), ""),
>          (CMatch("__acquires"), ""),
> diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdoc_parser.py
> index c4a76ed13dbc..4b47a858824a 100755
> --- a/tools/unittests/test_kdoc_parser.py
> +++ b/tools/unittests/test_kdoc_parser.py
> @@ -418,6 +418,28 @@ class TestSelfValidate(GenerateKdocItem):
>          """
>          self.run_test(self.SOURCE, [self.DEFAULT.copy()], self.EXPORTS)
>  
> +class TestDomainNs(GenerateKdocItem):
> +    def test_domain_ns_wrapped_function(self):
> +        source = """
> +            /**
> +             * iova_to_phys() - Return the output address for the given IOVA
> +             * @domain: Table to query
> +             * @iova: IO virtual address to query
> +             */
> +            phys_addr_t DOMAIN_NS(iova_to_phys)(struct iommu_domain *domain,
> +                                                dma_addr_t iova);
> +        """
> +
> +        kernel_doc = KernelDoc(self.config, "test.c", self.xforms)
> +        patcher = patch('builtins.open', new_callable=mock_open,
> +                        read_data=dedent(source))
> +        with patcher:
> +            _, entries = kernel_doc.parse_kdoc()
> +
> +        self.assertEqual(len(entries), 1)
> +        self.assertEqual(entries[0].name, "iova_to_phys")
> +        self.assertEqual(entries[0].warnings, [])
> +
>  #
>  # Class and logic to create dynamic tests from YAML
>  #

-- 
~Randy

Re: [PATCH] docs: kdoc: strip DOMAIN_NS() wrapper in function prototypes

[Jonathan Corbet]

Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com> writes:

> kernel-doc fails to parse functions whose names are wrapped in the
> DOMAIN_NS() namespace macro, e.g. in
> drivers/iommu/generic_pt/iommu_pt.h:217:
>
>   ... expecting prototype for iova_to_phys(). Prototype was for
>   DOMAIN_NS() instead
>
> function_xforms is the designated place for unwrapping function-name
> macros, but it has no entry for DOMAIN_NS(), so the macro name is kept
> as the prototype and the real name leaks into the parameter list.
>
> Add a transform expanding DOMAIN_NS(op) to op, following the existing
> DEFINE_IDTENTRY_IRQ precedent.
>
> Add a regression test for the wrapped iova_to_phys() declaration.
>
> Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com>
> ---
>  tools/lib/python/kdoc/xforms_lists.py |  6 ++++++
>  tools/unittests/test_kdoc_parser.py   | 22 ++++++++++++++++++++++
>  2 files changed, 28 insertions(+)

Neither of these patches applies to docs-next...what did you base them
on?

jon

Re: [PATCH] docs: kdoc: strip DOMAIN_NS() wrapper in function prototypes

[Omokefe Emmanuel Onanaroghene]

On Wed, 14 Oct 2026 11:22:02 -0600, Jonathan Corbet <corbet@lwn.net> wrote:
> Neither of these patches applies to docs-next...what did you base them
> on?

Hi Jon,

I had based both patches on mainline rather than docs-next. I have
rebased both patches on top of docs-next and sent a v2 for both:

- https://lore.kernel.org/all/20261014223134.14772-1-emmaonana18@gmail.com/
- https://lore.kernel.org/all/20261014223437.16164-1-emmaonana18@gmail.com/

Apologies for the inconvenience.

Thanks,
Omokefe

Re: [PATCH] docs: kdoc: strip DOMAIN_NS() wrapper in function prototypes

[Omokefe Emmanuel Onanaroghene]

On Wed, 14 Oct 2026 11:22:02 -0600, Jonathan Corbet <corbet@lwn.net> wrote:
>> Neither of these patches applies to docs-next...what did you base them
>> on?
>
> Hi Jon,
>
> I had mistakenly based both patches on mainline rather than docs-next.
> I have rebased both on top of docs-next and sent a v2 for each:
>
> - docs: kdoc: handle TRACE_EVENT_FN() family in tracepoint parser:
>   https://lore.kernel.org/all/20261014223134.14772-1-emmaonana18@gmail.com/
>
> - docs: kdoc: strip DOMAIN_NS() wrapper in function prototypes:
>   https://lore.kernel.org/all/20261014223437.16164-1-emmaonana18@gmail.com/
>

I just noticed another mistake on my part, because I prepared
the two v2 patches on separate independent branches off docs-next, both
patches add their regression test at the exact same location in
tools/unittests/test_kdoc_parser.py (line 444). Applying them sequentially will
cause a merge conflict

I didn't realize that patches modifying the exact same context in a file
should be stacked sequentially on a single branch as a patch series
rather than developed on separate branches.

Should I respin them as a 2-patch series against docs-next,
or would you prefer to resolve when applying?

Thanks,
Omokefe

Re: [PATCH] docs: kdoc: strip DOMAIN_NS() wrapper in function prototypes

[Jonathan Corbet]

Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com> writes:

> On Wed, 14 Oct 2026 11:22:02 -0600, Jonathan Corbet <corbet@lwn.net> wrote:
>>> Neither of these patches applies to docs-next...what did you base them
>>> on?
>>
>> Hi Jon,
>>
>> I had mistakenly based both patches on mainline rather than docs-next.
>> I have rebased both on top of docs-next and sent a v2 for each:
>>
>> - docs: kdoc: handle TRACE_EVENT_FN() family in tracepoint parser:
>>   https://lore.kernel.org/all/20261014223134.14772-1-emmaonana18@gmail.com/
>>
>> - docs: kdoc: strip DOMAIN_NS() wrapper in function prototypes:
>>   https://lore.kernel.org/all/20261014223437.16164-1-emmaonana18@gmail.com/
>>
>
> I just noticed another mistake on my part, because I prepared
> the two v2 patches on separate independent branches off docs-next, both
> patches add their regression test at the exact same location in
> tools/unittests/test_kdoc_parser.py (line 444). Applying them sequentially will
> cause a merge conflict
>
> I didn't realize that patches modifying the exact same context in a file
> should be stacked sequentially on a single branch as a patch series
> rather than developed on separate branches.
>
> Should I respin them as a 2-patch series against docs-next,
> or would you prefer to resolve when applying?

Redo them as a two-patch series if you could.

Thanks,

jon

[PATCH v3 0/2] docs: kdoc: fix TRACE_EVENT_FN and DOMAIN_NS parsing

[Omokefe Emmanuel Onanaroghene]

This series fixes two kernel-doc parsing failures where the
prototype was misidentified and parameters leaked into garbage:

- TRACE_EVENT_FN() family tracepoints (e.g. gpu_power_status)
- DOMAIN_NS() wrapped function names (e.g. iova_to_phys)

Rebased onto docs-next and stacked as a series per Jon's feedback
to avoid both tests landing at the same spot in
test_kdoc_parser.py.


Omokefe Emmanuel Onanaroghene (2):
  docs: kdoc: handle TRACE_EVENT_FN() family in tracepoint parser
  docs: kdoc: strip DOMAIN_NS() wrapper in function prototypes

 tools/lib/python/kdoc/kdoc_parser.py  | 18 +++++++++-
 tools/lib/python/kdoc/xforms_lists.py |  6 ++++
 tools/unittests/test_kdoc_parser.py   | 50 +++++++++++++++++++++++++++
 3 files changed, 73 insertions(+), 1 deletion(-)

-- 
2.43.0

[PATCH v3 1/2] docs: kdoc: handle TRACE_EVENT_FN() family in tracepoint parser

[Omokefe Emmanuel Onanaroghene]

kernel-doc fails to parse tracepoint declarations that use
TRACE_EVENT_FN(), e.g. gpu_power_status:

  drivers/gpu/drm/panthor/panthor_trace.h:28 ... Unrecognized
  tracepoint format ...
  ... expecting prototype for gpu_power_status(). Prototype was for
  TRACE_EVENT_FN() instead

tracepoint_munge() only matches TRACE_EVENT(), so the macro name is
kept as the prototype and the TP_PROTO() arguments leak into the
parameter list as garbage.

Match TRACE_EVENT_FN(), TRACE_EVENT_FN_COND(),
TRACE_EVENT_CONDITION() and TRACE_EVENT_SYSCALL() the same way as
TRACE_EVENT() and list them explicitly at the call site in
process_proto_function().

Add a regression test for the gpu_power_status declaration.

Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com>
---
 tools/lib/python/kdoc/kdoc_parser.py | 18 +++++++++++++++++-
 tools/unittests/test_kdoc_parser.py  | 28 ++++++++++++++++++++++++++++
 2 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index 80d4245acd17..a65bda3e81b9 100644
--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py
@@ -1545,6 +1545,22 @@ class KernelDoc:
         if r.search(proto):
             tracepointname = r.group(1)
 
+        r = KernRe(r'TRACE_EVENT_FN\((.*?),')
+        if r.search(proto):
+            tracepointname = r.group(1)
+
+        r = KernRe(r'TRACE_EVENT_FN_COND\((.*?),')
+        if r.search(proto):
+            tracepointname = r.group(1)
+
+        r = KernRe(r'TRACE_EVENT_CONDITION\((.*?),')
+        if r.search(proto):
+            tracepointname = r.group(1)
+
+        r = KernRe(r'TRACE_EVENT_SYSCALL\((.*?),')
+        if r.search(proto):
+            tracepointname = r.group(1)
+
         r = KernRe(r'DEFINE_SINGLE_EVENT\((.*?),')
         if r.search(proto):
             tracepointname = r.group(1)
@@ -1604,7 +1620,7 @@ class KernelDoc:
                 self.entry.prototype = self.syscall_munge(ln,
                                                           self.entry.prototype)
             else:
-                r = KernRe(r'TRACE_EVENT|DEFINE_EVENT|DEFINE_SINGLE_EVENT')
+                r = KernRe(r'TRACE_EVENT|TRACE_EVENT_FN|TRACE_EVENT_FN_COND|TRACE_EVENT_CONDITION|TRACE_EVENT_SYSCALL|DEFINE_EVENT|DEFINE_SINGLE_EVENT')
                 if r.search(self.entry.prototype):
                     self.entry.prototype = self.tracepoint_munge(ln,
                                                                  self.entry.prototype)
diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdoc_parser.py
index 4baa78ca02b3..04dafae412e4 100755
--- a/tools/unittests/test_kdoc_parser.py
+++ b/tools/unittests/test_kdoc_parser.py
@@ -444,6 +444,34 @@ class TestContextLockStruct(GenerateKdocItem):
         self.assertEqual(entries[0].name, "debugfs_cancellation")
         self.assertEqual(entries[0].warnings, [])
 
+class TestTraceEventFn(GenerateKdocItem):
+    def test_trace_event_fn_declaration(self):
+        source = """
+            /**
+             * gpu_power_status - called when hardware turns on or off
+             * @dev: pointer to device
+             * @shader_bitmap: bitmap
+             */
+            TRACE_EVENT_FN(gpu_power_status,
+                TP_PROTO(const struct device *dev, u64 shader_bitmap),
+                TP_ARGS(dev, shader_bitmap),
+                TP_STRUCT__entry(__field(u64, shader_bitmap)),
+                TP_fast_assign(__entry->shader_bitmap = shader_bitmap;),
+                TP_printk("%s", __get_str(dev_name)),
+                my_register, my_unregister
+            );
+        """
+
+        kernel_doc = KernelDoc(self.config, "test.c", self.xforms)
+        patcher = patch('builtins.open', new_callable=mock_open,
+                        read_data=dedent(source))
+        with patcher:
+            _, entries = kernel_doc.parse_kdoc()
+
+        self.assertEqual(len(entries), 1)
+        self.assertEqual(entries[0].name, "trace_gpu_power_status")
+        self.assertEqual(entries[0].warnings, [])
+
 #
 # Class and logic to create dynamic tests from YAML
 #
-- 
2.43.0

Re: [PATCH v3 1/2] docs: kdoc: handle TRACE_EVENT_FN() family in tracepoint parser

[Mauro Carvalho Chehab]

On Thu, 15 Oct 2026 17:44:47 +0100
Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com> wrote:

> kernel-doc fails to parse tracepoint declarations that use
> TRACE_EVENT_FN(), e.g. gpu_power_status:
> 
>   drivers/gpu/drm/panthor/panthor_trace.h:28 ... Unrecognized
>   tracepoint format ...
>   ... expecting prototype for gpu_power_status(). Prototype was for
>   TRACE_EVENT_FN() instead
> 
> tracepoint_munge() only matches TRACE_EVENT(), so the macro name is
> kept as the prototype and the TP_PROTO() arguments leak into the
> parameter list as garbage.
> 
> Match TRACE_EVENT_FN(), TRACE_EVENT_FN_COND(),
> TRACE_EVENT_CONDITION() and TRACE_EVENT_SYSCALL() the same way as
> TRACE_EVENT() and list them explicitly at the call site in
> process_proto_function().
> 
> Add a regression test for the gpu_power_status declaration.
> 
> Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com>
> ---
>  tools/lib/python/kdoc/kdoc_parser.py | 18 +++++++++++++++++-
>  tools/unittests/test_kdoc_parser.py  | 28 ++++++++++++++++++++++++++++
>  2 files changed, 45 insertions(+), 1 deletion(-)
> 
> diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
> index 80d4245acd17..a65bda3e81b9 100644
> --- a/tools/lib/python/kdoc/kdoc_parser.py
> +++ b/tools/lib/python/kdoc/kdoc_parser.py
> @@ -1545,6 +1545,22 @@ class KernelDoc:
>          if r.search(proto):
>              tracepointname = r.group(1)
>  
> +        r = KernRe(r'TRACE_EVENT_FN\((.*?),')
> +        if r.search(proto):
> +            tracepointname = r.group(1)
> +
> +        r = KernRe(r'TRACE_EVENT_FN_COND\((.*?),')
> +        if r.search(proto):
> +            tracepointname = r.group(1)
> +
> +        r = KernRe(r'TRACE_EVENT_CONDITION\((.*?),')
> +        if r.search(proto):
> +            tracepointname = r.group(1)
> +
> +        r = KernRe(r'TRACE_EVENT_SYSCALL\((.*?),')
> +        if r.search(proto):
> +            tracepointname = r.group(1)
> +
>          r = KernRe(r'DEFINE_SINGLE_EVENT\((.*?),')
>          if r.search(proto):
>              tracepointname = r.group(1)
> @@ -1604,7 +1620,7 @@ class KernelDoc:
>                  self.entry.prototype = self.syscall_munge(ln,
>                                                            self.entry.prototype)
>              else:
> -                r = KernRe(r'TRACE_EVENT|DEFINE_EVENT|DEFINE_SINGLE_EVENT')
> +                r = KernRe(r'TRACE_EVENT|TRACE_EVENT_FN|TRACE_EVENT_FN_COND|TRACE_EVENT_CONDITION|TRACE_EVENT_SYSCALL|DEFINE_EVENT|DEFINE_SINGLE_EVENT')

The best would be instead to move all of them to xforms_lists,
together with SYSCALL_DEFINE.

Regards,
Mauro

>                  if r.search(self.entry.prototype):
>                      self.entry.prototype = self.tracepoint_munge(ln,
>                                                                   self.entry.prototype)
> diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdoc_parser.py
> index 4baa78ca02b3..04dafae412e4 100755
> --- a/tools/unittests/test_kdoc_parser.py
> +++ b/tools/unittests/test_kdoc_parser.py
> @@ -444,6 +444,34 @@ class TestContextLockStruct(GenerateKdocItem):
>          self.assertEqual(entries[0].name, "debugfs_cancellation")
>          self.assertEqual(entries[0].warnings, [])
>  
> +class TestTraceEventFn(GenerateKdocItem):
> +    def test_trace_event_fn_declaration(self):
> +        source = """
> +            /**
> +             * gpu_power_status - called when hardware turns on or off
> +             * @dev: pointer to device
> +             * @shader_bitmap: bitmap
> +             */
> +            TRACE_EVENT_FN(gpu_power_status,
> +                TP_PROTO(const struct device *dev, u64 shader_bitmap),
> +                TP_ARGS(dev, shader_bitmap),
> +                TP_STRUCT__entry(__field(u64, shader_bitmap)),
> +                TP_fast_assign(__entry->shader_bitmap = shader_bitmap;),
> +                TP_printk("%s", __get_str(dev_name)),
> +                my_register, my_unregister
> +            );
> +        """
> +
> +        kernel_doc = KernelDoc(self.config, "test.c", self.xforms)
> +        patcher = patch('builtins.open', new_callable=mock_open,
> +                        read_data=dedent(source))
> +        with patcher:
> +            _, entries = kernel_doc.parse_kdoc()
> +
> +        self.assertEqual(len(entries), 1)
> +        self.assertEqual(entries[0].name, "trace_gpu_power_status")
> +        self.assertEqual(entries[0].warnings, [])
> +
>  #
>  # Class and logic to create dynamic tests from YAML
>  #



Thanks,
Mauro

[PATCH] docs: kdoc: handle TRACE_EVENT_FN() family in tracepoint parser

[Omokefe Emmanuel Onanaroghene]

kernel-doc fails to parse tracepoint declarations that use
TRACE_EVENT_FN(), e.g. gpu_power_status:

  drivers/gpu/drm/panthor/panthor_trace.h:28 ... Unrecognized
  tracepoint format ...
  ... expecting prototype for gpu_power_status(). Prototype was for
  TRACE_EVENT_FN() instead

tracepoint_munge() only matches TRACE_EVENT(), so the macro name is
kept as the prototype and the TP_PROTO() arguments leak into the
parameter list as garbage.

Match TRACE_EVENT_FN(), TRACE_EVENT_FN_COND(),
TRACE_EVENT_CONDITION() and TRACE_EVENT_SYSCALL() the same way as
TRACE_EVENT()

Add a regression test for the gpu_power_status declaration.

Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com>
---
Move tracepoint handling to xforms_lists, together with SYSCALL_DEFINE
as requested by Mauro.

Question for Mauro: is adding syscall_munge() and
tracepoint_munge() in apply() what you meant, or
did you want a pure CMatch? A pure CMatch looks
like it would need a tokenizer fix for nested
commas, so I'd prefer to keep it this way unless
you want the pure CMatch rework.

 tools/lib/python/kdoc/kdoc_parser.py  | 110 ++++++--------------------
 tools/lib/python/kdoc/xforms_lists.py | 109 +++++++++++++++++++++++++
 tools/unittests/test_kdoc_parser.py   |  28 +++++++
 3 files changed, 159 insertions(+), 88 deletions(-)

diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index 80d4245acd17..a274e06b9f23 100644
--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py
@@ -1059,8 +1059,27 @@ class KernelDoc:
             #
             # Apply the initial transformations.
             #
+            # This also handles SYSCALL_DEFINE*() and TRACE_EVENT*()/
+            # DEFINE_EVENT*() via CTransforms (see xforms_lists.py).
+            #
             prototype = self.xforms.apply("func", prototype)
 
+            #
+            # Tracepoints are documented with their short name, e.g.
+            # gpu_power_status for trace_gpu_power_status().
+            # Accept the short name and store the full trace_ name.
+            #
+            r = KernRe(r'\btrace_(\w+)')
+            if r.search(prototype):
+                if self.entry.identifier == r.group(1):
+                    self.entry.identifier = f"trace_{self.entry.identifier}"
+
+
+            r = KernRe(r'TRACE_EVENT|DEFINE_EVENT|DEFINE_SINGLE_EVENT')
+            if r.search(prototype):
+                self.emit_msg(ln,
+                              f"Unrecognized tracepoint format:\n{prototype}\n")
+
         # Yes, this truly is vile.  We are looking for:
         # 1. Return type (may be nothing if we're looking at a macro)
         # 2. Function name
@@ -1493,82 +1512,6 @@ class KernelDoc:
             self.entry.add_text(doc_content.group(1))
         # else ... ??
 
-    def syscall_munge(self, ln, proto):         # pylint: disable=W0613
-        """
-        Handle syscall definitions.
-        """
-
-        is_void = False
-
-        # Strip newlines/CR's
-        proto = re.sub(r'[\r\n]+', ' ', proto)
-
-        # Check if it's a SYSCALL_DEFINE0
-        if 'SYSCALL_DEFINE0' in proto:
-            is_void = True
-
-        # Replace SYSCALL_DEFINE with correct return type & function name
-        proto = KernRe(r'SYSCALL_DEFINE.*\(').sub('long sys_', proto)
-
-        r = KernRe(r'long\s+(sys_.*?),')
-        if r.search(proto):
-            proto = KernRe(',').sub('(', proto, count=1)
-        elif is_void:
-            proto = KernRe(r'\)').sub('(void)', proto, count=1)
-
-        # Now delete all of the odd-numbered commas in the proto
-        # so that argument types & names don't have a comma between them
-        count = 0
-        length = len(proto)
-
-        if is_void:
-            length = 0  # skip the loop if is_void
-
-        for ix in range(length):
-            if proto[ix] == ',':
-                count += 1
-                if count % 2 == 1:
-                    proto = proto[:ix] + ' ' + proto[ix + 1:]
-
-        return proto
-
-    def tracepoint_munge(self, ln, proto):
-        """
-        Handle tracepoint definitions.
-        """
-
-        tracepointname = None
-        tracepointargs = None
-
-        # Match tracepoint name based on different patterns
-        r = KernRe(r'TRACE_EVENT\((.*?),')
-        if r.search(proto):
-            tracepointname = r.group(1)
-
-        r = KernRe(r'DEFINE_SINGLE_EVENT\((.*?),')
-        if r.search(proto):
-            tracepointname = r.group(1)
-
-        r = KernRe(r'DEFINE_EVENT\((.*?),(.*?),')
-        if r.search(proto):
-            tracepointname = r.group(2)
-
-        if tracepointname:
-            tracepointname = tracepointname.lstrip()
-
-        r = KernRe(r'TP_PROTO\((.*?)\)')
-        if r.search(proto):
-            tracepointargs = r.group(1)
-
-        if not tracepointname or not tracepointargs:
-            self.emit_msg(ln,
-                          f"Unrecognized tracepoint format:\n{proto}\n")
-        else:
-            proto = f"static inline void trace_{tracepointname}({tracepointargs})"
-            self.entry.identifier = f"trace_{self.entry.identifier}"
-
-        return proto
-
     def process_proto_function(self, ln, line, source):
         """Ancillary routine to process a function prototype."""
 
@@ -1598,18 +1541,9 @@ class KernelDoc:
             r = KernRe(r'^(\S+\s+)\(\s*\*(\S+)\)')
             self.entry.prototype = r.sub(r'\1\2', self.entry.prototype)
             #
-            # Handle special declaration syntaxes
-            #
-            if 'SYSCALL_DEFINE' in self.entry.prototype:
-                self.entry.prototype = self.syscall_munge(ln,
-                                                          self.entry.prototype)
-            else:
-                r = KernRe(r'TRACE_EVENT|DEFINE_EVENT|DEFINE_SINGLE_EVENT')
-                if r.search(self.entry.prototype):
-                    self.entry.prototype = self.tracepoint_munge(ln,
-                                                                 self.entry.prototype)
-            #
-            # ... and we're done
+            # ... and we're done. SYSCALL_DEFINE*() and TRACE_EVENT*()/
+            # DEFINE_EVENT*() are handled via xforms_lists.CTransforms
+            # inside dump_function().
             #
             self.dump_function(ln, self.entry.prototype, source)
             self.reset_state(ln)
diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py
index 15f6f21c7a9e..aa82dc927ef1 100644
--- a/tools/lib/python/kdoc/xforms_lists.py
+++ b/tools/lib/python/kdoc/xforms_lists.py
@@ -17,6 +17,98 @@ class CTransforms:
     into something we can parse and generate kdoc for.
     """
 
+    @staticmethod
+    def syscall_munge(proto):
+        """
+        Handle syscall definitions.
+
+        Turns SYSCALL_DEFINE*() into a plain C prototype, e.g.::
+
+            SYSCALL_DEFINE3(setpriority, int, which, int, who, int, niceval)
+            -> long sys_setpriority(int which, int who, int niceval)
+        """
+
+        is_void = False
+
+        # Strip newlines/CR's
+        proto = re.sub(r'[\r\n]+', ' ', proto)
+
+        # Check if it's a SYSCALL_DEFINE0
+        if 'SYSCALL_DEFINE0' in proto:
+            is_void = True
+
+        # Replace SYSCALL_DEFINE with correct return type & function name
+        proto = KernRe(r'SYSCALL_DEFINE.*\(').sub('long sys_', proto)
+
+        r = KernRe(r'long\s+(sys_.*?),')
+        if r.search(proto):
+            proto = KernRe(',').sub('(', proto, count=1)
+        elif is_void:
+            proto = KernRe(r'\)').sub('(void)', proto, count=1)
+
+        # Now delete all of the odd-numbered commas in the proto
+        # so that argument types & names don't have a comma between them
+        count = 0
+        length = len(proto)
+
+        if is_void:
+            length = 0  # skip the loop if is_void
+
+        for ix in range(length):
+            if proto[ix] == ',':
+                count += 1
+                if count % 2 == 1:
+                    proto = proto[:ix] + ' ' + proto[ix + 1:]
+
+        return proto
+
+    @staticmethod
+    def tracepoint_munge(proto):
+        """
+        Handle tracepoint definitions.
+
+        Turns TRACE_EVENT*()/DEFINE_EVENT*() into a plain C prototype,
+        e.g.::
+
+            TRACE_EVENT_FN(gpu_power_status, TP_PROTO(...), ...)
+            -> static inline void trace_gpu_power_status(...)
+
+        Returns the original string if the tracepoint format is not
+        recognized, letting the caller emit a warning.
+        """
+
+        tracepointname = None
+        tracepointargs = None
+
+        # Match tracepoint name based on different patterns.
+        # NOTE: DEFINE_EVENT*() takes a template name first, so the
+        # event name is the second argument.
+        for pattern, group in [
+            (r'TRACE_EVENT\((.*?),', 1),
+            (r'TRACE_EVENT_FN\((.*?),', 1),
+            (r'TRACE_EVENT_FN_COND\((.*?),', 1),
+            (r'TRACE_EVENT_CONDITION\((.*?),', 1),
+            (r'TRACE_EVENT_SYSCALL\((.*?),', 1),
+            (r'DEFINE_SINGLE_EVENT\((.*?),', 1),
+            (r'DEFINE_EVENT\((.*?),(.*?),', 2),
+        ]:
+            r = KernRe(pattern)
+            if r.search(proto):
+                tracepointname = r.group(group)
+
+        if tracepointname:
+            tracepointname = tracepointname.lstrip()
+
+        r = KernRe(r'TP_PROTO\((.*?)\)')
+        if r.search(proto):
+            tracepointargs = r.group(1)
+
+        if not tracepointname or not tracepointargs:
+            return proto
+
+        return f"static inline void trace_{tracepointname}({tracepointargs})"
+
+
     #
     # NOTE:
     #      Due to performance reasons, place CMatch rules before KernRe,
@@ -147,6 +239,23 @@ class CTransforms:
         if xforms_type not in self.xforms:
             return source
 
+        #
+        # Handle special declaration syntaxes first, so that the
+        # declarative transforms below see plain C prototypes.
+        #
+        if xforms_type == "func":
+            source_str = str(source)
+            if 'SYSCALL_DEFINE' in source_str:
+                source_str = self.syscall_munge(source_str)
+                source = source_str
+            else:
+                r = KernRe(r'TRACE_EVENT|DEFINE_EVENT|DEFINE_SINGLE_EVENT')
+                if r.search(source_str):
+                    munged = self.tracepoint_munge(source_str)
+                    # tracepoint_munge() returns the input unchanged
+                    # when the format is not recognized.
+                    source = munged
+
         if isinstance(source, str):
             source = CTokenizer(source)
 
diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdoc_parser.py
index 4baa78ca02b3..04dafae412e4 100755
--- a/tools/unittests/test_kdoc_parser.py
+++ b/tools/unittests/test_kdoc_parser.py
@@ -444,6 +444,34 @@ class TestContextLockStruct(GenerateKdocItem):
         self.assertEqual(entries[0].name, "debugfs_cancellation")
         self.assertEqual(entries[0].warnings, [])
 
+class TestTraceEventFn(GenerateKdocItem):
+    def test_trace_event_fn_declaration(self):
+        source = """
+            /**
+             * gpu_power_status - called when hardware turns on or off
+             * @dev: pointer to device
+             * @shader_bitmap: bitmap
+             */
+            TRACE_EVENT_FN(gpu_power_status,
+                TP_PROTO(const struct device *dev, u64 shader_bitmap),
+                TP_ARGS(dev, shader_bitmap),
+                TP_STRUCT__entry(__field(u64, shader_bitmap)),
+                TP_fast_assign(__entry->shader_bitmap = shader_bitmap;),
+                TP_printk("%s", __get_str(dev_name)),
+                my_register, my_unregister
+            );
+        """
+
+        kernel_doc = KernelDoc(self.config, "test.c", self.xforms)
+        patcher = patch('builtins.open', new_callable=mock_open,
+                        read_data=dedent(source))
+        with patcher:
+            _, entries = kernel_doc.parse_kdoc()
+
+        self.assertEqual(len(entries), 1)
+        self.assertEqual(entries[0].name, "trace_gpu_power_status")
+        self.assertEqual(entries[0].warnings, [])
+
 #
 # Class and logic to create dynamic tests from YAML
 #
-- 
2.43.0

Re: [PATCH] docs: kdoc: handle TRACE_EVENT_FN() family in tracepoint parser

[Mauro Carvalho Chehab]

On Fri, 16 Oct 2026 21:43:35 +0100
Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com> wrote:

> kernel-doc fails to parse tracepoint declarations that use
> TRACE_EVENT_FN(), e.g. gpu_power_status:
> 
>   drivers/gpu/drm/panthor/panthor_trace.h:28 ... Unrecognized
>   tracepoint format ...
>   ... expecting prototype for gpu_power_status(). Prototype was for
>   TRACE_EVENT_FN() instead
> 
> tracepoint_munge() only matches TRACE_EVENT(), so the macro name is
> kept as the prototype and the TP_PROTO() arguments leak into the
> parameter list as garbage.
> 
> Match TRACE_EVENT_FN(), TRACE_EVENT_FN_COND(),
> TRACE_EVENT_CONDITION() and TRACE_EVENT_SYSCALL() the same way as
> TRACE_EVENT()
> 
> Add a regression test for the gpu_power_status declaration.
> 
> Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com>
> ---
> Move tracepoint handling to xforms_lists, together with SYSCALL_DEFINE
> as requested by Mauro.
> 
> Question for Mauro: is adding syscall_munge() and
> tracepoint_munge() in apply() what you meant, or
> did you want a pure CMatch? 

I meant a pure CMatch. One of the hardest things to maintain at
kernel-doc are those complex regex logic spread all over it. The
goal for CMatch and the C tokenizer is to avoid adding more - and 
instead - to reduce the existing ones over time.

In the specific case of commas, the tokenizer, ideally double commas
should be generating a singe STRING token and single commas a single
CHAR.

> A pure CMatch looks
> like it would need a tokenizer fix for nested
> commas, so I'd prefer to keep it this way unless
> you want the pure CMatch rework.

If the nested commas logic there is broken, indeed it needs a fix, on a 
separate patch.

> 
>  tools/lib/python/kdoc/kdoc_parser.py  | 110 ++++++--------------------
>  tools/lib/python/kdoc/xforms_lists.py | 109 +++++++++++++++++++++++++
>  tools/unittests/test_kdoc_parser.py   |  28 +++++++
>  3 files changed, 159 insertions(+), 88 deletions(-)
> 
> diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
> index 80d4245acd17..a274e06b9f23 100644
> --- a/tools/lib/python/kdoc/kdoc_parser.py
> +++ b/tools/lib/python/kdoc/kdoc_parser.py
> @@ -1059,8 +1059,27 @@ class KernelDoc:
>              #
>              # Apply the initial transformations.
>              #
> +            # This also handles SYSCALL_DEFINE*() and TRACE_EVENT*()/
> +            # DEFINE_EVENT*() via CTransforms (see xforms_lists.py).
> +            #
>              prototype = self.xforms.apply("func", prototype)
>  
> +            #
> +            # Tracepoints are documented with their short name, e.g.
> +            # gpu_power_status for trace_gpu_power_status().
> +            # Accept the short name and store the full trace_ name.
> +            #
> +            r = KernRe(r'\btrace_(\w+)')
> +            if r.search(prototype):
> +                if self.entry.identifier == r.group(1):
> +                    self.entry.identifier = f"trace_{self.entry.identifier}"
> +
> +
> +            r = KernRe(r'TRACE_EVENT|DEFINE_EVENT|DEFINE_SINGLE_EVENT')
> +            if r.search(prototype):
> +                self.emit_msg(ln,
> +                              f"Unrecognized tracepoint format:\n{prototype}\n")
> +
>          # Yes, this truly is vile.  We are looking for:
>          # 1. Return type (may be nothing if we're looking at a macro)
>          # 2. Function name
> @@ -1493,82 +1512,6 @@ class KernelDoc:
>              self.entry.add_text(doc_content.group(1))
>          # else ... ??
>  
> -    def syscall_munge(self, ln, proto):         # pylint: disable=W0613
> -        """
> -        Handle syscall definitions.
> -        """
> -
> -        is_void = False
> -
> -        # Strip newlines/CR's
> -        proto = re.sub(r'[\r\n]+', ' ', proto)
> -
> -        # Check if it's a SYSCALL_DEFINE0
> -        if 'SYSCALL_DEFINE0' in proto:
> -            is_void = True
> -
> -        # Replace SYSCALL_DEFINE with correct return type & function name
> -        proto = KernRe(r'SYSCALL_DEFINE.*\(').sub('long sys_', proto)
> -
> -        r = KernRe(r'long\s+(sys_.*?),')
> -        if r.search(proto):
> -            proto = KernRe(',').sub('(', proto, count=1)
> -        elif is_void:
> -            proto = KernRe(r'\)').sub('(void)', proto, count=1)
> -
> -        # Now delete all of the odd-numbered commas in the proto
> -        # so that argument types & names don't have a comma between them
> -        count = 0
> -        length = len(proto)
> -
> -        if is_void:
> -            length = 0  # skip the loop if is_void
> -
> -        for ix in range(length):
> -            if proto[ix] == ',':
> -                count += 1
> -                if count % 2 == 1:
> -                    proto = proto[:ix] + ' ' + proto[ix + 1:]
> -
> -        return proto
> -
> -    def tracepoint_munge(self, ln, proto):
> -        """
> -        Handle tracepoint definitions.
> -        """
> -
> -        tracepointname = None
> -        tracepointargs = None
> -
> -        # Match tracepoint name based on different patterns
> -        r = KernRe(r'TRACE_EVENT\((.*?),')
> -        if r.search(proto):
> -            tracepointname = r.group(1)
> -
> -        r = KernRe(r'DEFINE_SINGLE_EVENT\((.*?),')
> -        if r.search(proto):
> -            tracepointname = r.group(1)
> -
> -        r = KernRe(r'DEFINE_EVENT\((.*?),(.*?),')
> -        if r.search(proto):
> -            tracepointname = r.group(2)
> -
> -        if tracepointname:
> -            tracepointname = tracepointname.lstrip()
> -
> -        r = KernRe(r'TP_PROTO\((.*?)\)')
> -        if r.search(proto):
> -            tracepointargs = r.group(1)
> -
> -        if not tracepointname or not tracepointargs:
> -            self.emit_msg(ln,
> -                          f"Unrecognized tracepoint format:\n{proto}\n")
> -        else:
> -            proto = f"static inline void trace_{tracepointname}({tracepointargs})"
> -            self.entry.identifier = f"trace_{self.entry.identifier}"
> -
> -        return proto
> -
>      def process_proto_function(self, ln, line, source):
>          """Ancillary routine to process a function prototype."""
>  
> @@ -1598,18 +1541,9 @@ class KernelDoc:
>              r = KernRe(r'^(\S+\s+)\(\s*\*(\S+)\)')
>              self.entry.prototype = r.sub(r'\1\2', self.entry.prototype)
>              #
> -            # Handle special declaration syntaxes
> -            #
> -            if 'SYSCALL_DEFINE' in self.entry.prototype:
> -                self.entry.prototype = self.syscall_munge(ln,
> -                                                          self.entry.prototype)
> -            else:
> -                r = KernRe(r'TRACE_EVENT|DEFINE_EVENT|DEFINE_SINGLE_EVENT')
> -                if r.search(self.entry.prototype):
> -                    self.entry.prototype = self.tracepoint_munge(ln,
> -                                                                 self.entry.prototype)
> -            #
> -            # ... and we're done
> +            # ... and we're done. SYSCALL_DEFINE*() and TRACE_EVENT*()/
> +            # DEFINE_EVENT*() are handled via xforms_lists.CTransforms
> +            # inside dump_function().
>              #
>              self.dump_function(ln, self.entry.prototype, source)
>              self.reset_state(ln)
> diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py
> index 15f6f21c7a9e..aa82dc927ef1 100644
> --- a/tools/lib/python/kdoc/xforms_lists.py
> +++ b/tools/lib/python/kdoc/xforms_lists.py
> @@ -17,6 +17,98 @@ class CTransforms:
>      into something we can parse and generate kdoc for.
>      """
>  
> +    @staticmethod
> +    def syscall_munge(proto):
> +        """
> +        Handle syscall definitions.
> +
> +        Turns SYSCALL_DEFINE*() into a plain C prototype, e.g.::
> +
> +            SYSCALL_DEFINE3(setpriority, int, which, int, who, int, niceval)
> +            -> long sys_setpriority(int which, int who, int niceval)
> +        """
> +
> +        is_void = False
> +
> +        # Strip newlines/CR's
> +        proto = re.sub(r'[\r\n]+', ' ', proto)
> +
> +        # Check if it's a SYSCALL_DEFINE0
> +        if 'SYSCALL_DEFINE0' in proto:
> +            is_void = True
> +
> +        # Replace SYSCALL_DEFINE with correct return type & function name
> +        proto = KernRe(r'SYSCALL_DEFINE.*\(').sub('long sys_', proto)
> +
> +        r = KernRe(r'long\s+(sys_.*?),')
> +        if r.search(proto):
> +            proto = KernRe(',').sub('(', proto, count=1)
> +        elif is_void:
> +            proto = KernRe(r'\)').sub('(void)', proto, count=1)
> +
> +        # Now delete all of the odd-numbered commas in the proto
> +        # so that argument types & names don't have a comma between them
> +        count = 0
> +        length = len(proto)
> +
> +        if is_void:
> +            length = 0  # skip the loop if is_void
> +
> +        for ix in range(length):
> +            if proto[ix] == ',':
> +                count += 1
> +                if count % 2 == 1:
> +                    proto = proto[:ix] + ' ' + proto[ix + 1:]
> +
> +        return proto
> +
> +    @staticmethod
> +    def tracepoint_munge(proto):
> +        """
> +        Handle tracepoint definitions.
> +
> +        Turns TRACE_EVENT*()/DEFINE_EVENT*() into a plain C prototype,
> +        e.g.::
> +
> +            TRACE_EVENT_FN(gpu_power_status, TP_PROTO(...), ...)
> +            -> static inline void trace_gpu_power_status(...)
> +
> +        Returns the original string if the tracepoint format is not
> +        recognized, letting the caller emit a warning.
> +        """
> +
> +        tracepointname = None
> +        tracepointargs = None
> +
> +        # Match tracepoint name based on different patterns.
> +        # NOTE: DEFINE_EVENT*() takes a template name first, so the
> +        # event name is the second argument.
> +        for pattern, group in [
> +            (r'TRACE_EVENT\((.*?),', 1),
> +            (r'TRACE_EVENT_FN\((.*?),', 1),
> +            (r'TRACE_EVENT_FN_COND\((.*?),', 1),
> +            (r'TRACE_EVENT_CONDITION\((.*?),', 1),
> +            (r'TRACE_EVENT_SYSCALL\((.*?),', 1),
> +            (r'DEFINE_SINGLE_EVENT\((.*?),', 1),
> +            (r'DEFINE_EVENT\((.*?),(.*?),', 2),
> +        ]:
> +            r = KernRe(pattern)
> +            if r.search(proto):
> +                tracepointname = r.group(group)
> +
> +        if tracepointname:
> +            tracepointname = tracepointname.lstrip()
> +
> +        r = KernRe(r'TP_PROTO\((.*?)\)')
> +        if r.search(proto):
> +            tracepointargs = r.group(1)
> +
> +        if not tracepointname or not tracepointargs:
> +            return proto
> +
> +        return f"static inline void trace_{tracepointname}({tracepointargs})"
> +
> +
>      #
>      # NOTE:
>      #      Due to performance reasons, place CMatch rules before KernRe,
> @@ -147,6 +239,23 @@ class CTransforms:
>          if xforms_type not in self.xforms:
>              return source
>  
> +        #
> +        # Handle special declaration syntaxes first, so that the
> +        # declarative transforms below see plain C prototypes.
> +        #
> +        if xforms_type == "func":
> +            source_str = str(source)
> +            if 'SYSCALL_DEFINE' in source_str:
> +                source_str = self.syscall_munge(source_str)
> +                source = source_str
> +            else:
> +                r = KernRe(r'TRACE_EVENT|DEFINE_EVENT|DEFINE_SINGLE_EVENT')
> +                if r.search(source_str):
> +                    munged = self.tracepoint_munge(source_str)
> +                    # tracepoint_munge() returns the input unchanged
> +                    # when the format is not recognized.
> +                    source = munged
> +
>          if isinstance(source, str):
>              source = CTokenizer(source)
>  
> diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdoc_parser.py
> index 4baa78ca02b3..04dafae412e4 100755
> --- a/tools/unittests/test_kdoc_parser.py
> +++ b/tools/unittests/test_kdoc_parser.py
> @@ -444,6 +444,34 @@ class TestContextLockStruct(GenerateKdocItem):
>          self.assertEqual(entries[0].name, "debugfs_cancellation")
>          self.assertEqual(entries[0].warnings, [])
>  
> +class TestTraceEventFn(GenerateKdocItem):
> +    def test_trace_event_fn_declaration(self):
> +        source = """
> +            /**
> +             * gpu_power_status - called when hardware turns on or off
> +             * @dev: pointer to device
> +             * @shader_bitmap: bitmap
> +             */
> +            TRACE_EVENT_FN(gpu_power_status,
> +                TP_PROTO(const struct device *dev, u64 shader_bitmap),
> +                TP_ARGS(dev, shader_bitmap),
> +                TP_STRUCT__entry(__field(u64, shader_bitmap)),
> +                TP_fast_assign(__entry->shader_bitmap = shader_bitmap;),
> +                TP_printk("%s", __get_str(dev_name)),
> +                my_register, my_unregister
> +            );
> +        """
> +
> +        kernel_doc = KernelDoc(self.config, "test.c", self.xforms)
> +        patcher = patch('builtins.open', new_callable=mock_open,
> +                        read_data=dedent(source))
> +        with patcher:
> +            _, entries = kernel_doc.parse_kdoc()
> +
> +        self.assertEqual(len(entries), 1)
> +        self.assertEqual(entries[0].name, "trace_gpu_power_status")
> +        self.assertEqual(entries[0].warnings, [])
> +
>  #
>  # Class and logic to create dynamic tests from YAML
>  #



Thanks,
Mauro

[PATCH v2 0/2] docs: kdoc: convert tracepoint parsing to CMatch

[Omokefe Emmanuel Onanaroghene]

Mauro suggested handling tracepoint and syscall declarations with pure
CMatch transformations, and keeping any nested-comma tokenizer correction
in a separate patch. This series follows that split.

Patch 1 fixes CMatch argument grouping so delimiters inside nested
expressions do not split the outer macro arguments. Patch 2 replaces the
procedural syscall and tracepoint munging with CMatch transformations,
including support for the TRACE_EVENT_FN() family, and adds parser tests.


Omokefe Emmanuel Onanaroghene (2):
  docs: kdoc: handle nested commas in CMatch arguments
  docs: kdoc: handle TRACE_EVENT_FN() with CMatch

 tools/lib/python/kdoc/c_lex.py        | 22 ++++++-
 tools/lib/python/kdoc/kdoc_parser.py  | 94 ++-------------------------
 tools/lib/python/kdoc/xforms_lists.py | 39 +++++++++++
 tools/unittests/test_cmatch.py        |  7 ++
 tools/unittests/test_kdoc_parser.py   | 56 ++++++++++++++++
 5 files changed, 129 insertions(+), 89 deletions(-)


base-commit: 90d9f76ccb72ec024ef476b4229f3dd1957d7b26
-- 
2.43.0

[PATCH v2 1/2] docs: kdoc: handle nested commas in CMatch arguments

[Omokefe Emmanuel Onanaroghene]

CMatch argument extraction splits macro arguments at top-level commas,
but it currently also splits on commas inside nested expressions.
This breaks transformations that capture a macro argument containing a nested call.

Only treat delimiters at the outer macro argument level as separators.

add a regression test for a nested call with comma-separated arguments.

Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com>
---
 tools/lib/python/kdoc/c_lex.py | 3 ++-
 tools/unittests/test_cmatch.py | 7 +++++++
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/tools/lib/python/kdoc/c_lex.py b/tools/lib/python/kdoc/c_lex.py
index efbc23c01abd..532e2c5a815e 100644
--- a/tools/lib/python/kdoc/c_lex.py
+++ b/tools/lib/python/kdoc/c_lex.py
@@ -430,7 +430,8 @@ class CTokenArgs:
                 if inner_level < 0:
                     break
 
-            if tok.kind in [CToken.PUNC, CToken.ENDSTMT] and delim == tok.value:
+            if (inner_level == 0 and tok.value == delim and
+                    tok.kind in [CToken.PUNC, CToken.ENDSTMT]):
                 pos += 1
                 if self.greedy and pos > self.max_group:
                     pos -= 1
diff --git a/tools/unittests/test_cmatch.py b/tools/unittests/test_cmatch.py
index 109141cd2ab8..978e02acfa4d 100755
--- a/tools/unittests/test_cmatch.py
+++ b/tools/unittests/test_cmatch.py
@@ -259,6 +259,13 @@ class TestSubSimple(TestCaseDiff):
 
         self.assertLogicallyEqual("REPLACE(arg1, arg2)\nbar();", result)
 
+    def test_sub_nested_commas(self):
+        """Commas in nested expressions aren't macro argument delimiters"""
+        line = f"{self.MACRO}(a, inner(b, c), d)"
+        result = self.matcher.sub(r"\1|\2|\3", line)
+
+        self.assertLogicallyEqual("a| inner(b, c)| d", result)
+
     def test_sub_mixed_placeholders(self):
         """Replacement rule for \0, \1 and additional text"""
         line = f"{self.MACRO}(foo, bar)\nbaz();"
-- 
2.43.0

[PATCH v2 2/2] docs: kdoc: handle TRACE_EVENT_FN() with CMatch

[Omokefe Emmanuel Onanaroghene]

kernel-doc fails to parse tracepoint declarations that use TRACE_EVENT_FN(), e.g. gpu_power_status:

  ... Unrecognized tracepoint format ...

  ... expecting prototype for gpu_power_status(). Prototype was for TRACE_EVENT_FN() instead

Convert SYSCALL_DEFINE0() through SYSCALL_DEFINE6(), the TRACE_EVENT() and DEFINE_EVENT() families,
DEFINE_SINGLE_EVENT(), and TP_PROTO() to CMatch transformations.
Add a CMatch back-reference form that trims whitespace around selected macro arguments,
and retain nested commas within arguments.

Add regression tests for TRACE_EVENT_FN() and SYSCALL_DEFINE0/3().

Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com>
---
 tools/lib/python/kdoc/c_lex.py        | 19 ++++++
 tools/lib/python/kdoc/kdoc_parser.py  | 94 ++-------------------------
 tools/lib/python/kdoc/xforms_lists.py | 39 +++++++++++
 tools/unittests/test_kdoc_parser.py   | 56 ++++++++++++++++
 4 files changed, 120 insertions(+), 88 deletions(-)

diff --git a/tools/lib/python/kdoc/c_lex.py b/tools/lib/python/kdoc/c_lex.py
index 532e2c5a815e..4adc1b211b54 100644
--- a/tools/lib/python/kdoc/c_lex.py
+++ b/tools/lib/python/kdoc/c_lex.py
@@ -338,6 +338,11 @@ class CTokenArgs:
 
             sub_str = KernRe(r'(\\\d+)[+]').sub(r"\1", sub_str)
 
+        self.trim_groups = set()
+        for match in KernRe(r'\\(\d+)-').finditer(sub_str):
+            self.trim_groups.add(int(match.group(1)))
+        sub_str = KernRe(r'(\\\d+)-').sub(r"\1", sub_str)
+
         self.sub_str = sub_str
         self.sub_tokeninzer = CTokenizer(sub_str)
 
@@ -448,8 +453,22 @@ class CTokenArgs:
         if pos < self.max_group:
             log.error(fr"{self.sub_str} groups are up to {pos} instead of {self.max_group}")
 
+        groups_list = [self._trim_group(group) if i in self.trim_groups else group
+                       for i, group in enumerate(groups_list)]
+
         return level, groups_list
 
+    @staticmethod
+    def _trim_group(tokens):
+        """Return macro argument tokens without surrounding whitespace."""
+        start = 0
+        end = len(tokens)
+        while start < end and tokens[start].kind == CToken.SPACE:
+            start += 1
+        while end > start and tokens[end - 1].kind == CToken.SPACE:
+            end -= 1
+        return tokens[start:end]
+
     def tokens(self, new_tokenizer):
         level, groups = self.groups(new_tokenizer)
 
diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index 80d4245acd17..5057a131117b 100644
--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py
@@ -1493,82 +1493,6 @@ class KernelDoc:
             self.entry.add_text(doc_content.group(1))
         # else ... ??
 
-    def syscall_munge(self, ln, proto):         # pylint: disable=W0613
-        """
-        Handle syscall definitions.
-        """
-
-        is_void = False
-
-        # Strip newlines/CR's
-        proto = re.sub(r'[\r\n]+', ' ', proto)
-
-        # Check if it's a SYSCALL_DEFINE0
-        if 'SYSCALL_DEFINE0' in proto:
-            is_void = True
-
-        # Replace SYSCALL_DEFINE with correct return type & function name
-        proto = KernRe(r'SYSCALL_DEFINE.*\(').sub('long sys_', proto)
-
-        r = KernRe(r'long\s+(sys_.*?),')
-        if r.search(proto):
-            proto = KernRe(',').sub('(', proto, count=1)
-        elif is_void:
-            proto = KernRe(r'\)').sub('(void)', proto, count=1)
-
-        # Now delete all of the odd-numbered commas in the proto
-        # so that argument types & names don't have a comma between them
-        count = 0
-        length = len(proto)
-
-        if is_void:
-            length = 0  # skip the loop if is_void
-
-        for ix in range(length):
-            if proto[ix] == ',':
-                count += 1
-                if count % 2 == 1:
-                    proto = proto[:ix] + ' ' + proto[ix + 1:]
-
-        return proto
-
-    def tracepoint_munge(self, ln, proto):
-        """
-        Handle tracepoint definitions.
-        """
-
-        tracepointname = None
-        tracepointargs = None
-
-        # Match tracepoint name based on different patterns
-        r = KernRe(r'TRACE_EVENT\((.*?),')
-        if r.search(proto):
-            tracepointname = r.group(1)
-
-        r = KernRe(r'DEFINE_SINGLE_EVENT\((.*?),')
-        if r.search(proto):
-            tracepointname = r.group(1)
-
-        r = KernRe(r'DEFINE_EVENT\((.*?),(.*?),')
-        if r.search(proto):
-            tracepointname = r.group(2)
-
-        if tracepointname:
-            tracepointname = tracepointname.lstrip()
-
-        r = KernRe(r'TP_PROTO\((.*?)\)')
-        if r.search(proto):
-            tracepointargs = r.group(1)
-
-        if not tracepointname or not tracepointargs:
-            self.emit_msg(ln,
-                          f"Unrecognized tracepoint format:\n{proto}\n")
-        else:
-            proto = f"static inline void trace_{tracepointname}({tracepointargs})"
-            self.entry.identifier = f"trace_{self.entry.identifier}"
-
-        return proto
-
     def process_proto_function(self, ln, line, source):
         """Ancillary routine to process a function prototype."""
 
@@ -1597,18 +1521,12 @@ class KernelDoc:
             #
             r = KernRe(r'^(\S+\s+)\(\s*\*(\S+)\)')
             self.entry.prototype = r.sub(r'\1\2', self.entry.prototype)
-            #
-            # Handle special declaration syntaxes
-            #
-            if 'SYSCALL_DEFINE' in self.entry.prototype:
-                self.entry.prototype = self.syscall_munge(ln,
-                                                          self.entry.prototype)
-            else:
-                r = KernRe(r'TRACE_EVENT|DEFINE_EVENT|DEFINE_SINGLE_EVENT')
-                if r.search(self.entry.prototype):
-                    self.entry.prototype = self.tracepoint_munge(ln,
-                                                                 self.entry.prototype)
-            #
+            # Tracepoint documentation uses the short event name, while its
+            # generated function has the trace_ prefix. The declaration itself
+            # is normalized by CTransforms in dump_function().
+            if self.xforms.is_tracepoint(self.entry.prototype):
+                self.entry.identifier = f"trace_{self.entry.identifier}"
+
             # ... and we're done
             #
             self.dump_function(ln, self.entry.prototype, source)
diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py
index 15f6f21c7a9e..315b54feff33 100644
--- a/tools/lib/python/kdoc/xforms_lists.py
+++ b/tools/lib/python/kdoc/xforms_lists.py
@@ -17,6 +17,13 @@ class CTransforms:
     into something we can parse and generate kdoc for.
     """
 
+    tracepoint_pattern = (
+        r"(?:TRACE_EVENT(?:_FN(?:_COND)?|_CONDITION|_SYSCALL)?|"
+        r"DEFINE_EVENT(?:_FN|_PRINT|_CONDITION|_NOP|_WRITABLE)?|"
+        r"DEFINE_SINGLE_EVENT)"
+    )
+    tracepoint_match = CMatch(tracepoint_pattern)
+
     #
     # NOTE:
     #      Due to performance reasons, place CMatch rules before KernRe,
@@ -108,6 +115,32 @@ class CTransforms:
         (CMatch("STATIC_IFN_KUNIT"), ""),
         (CMatch("INLINE_IFN_KUNIT"), ""),
 
+        # Turn syscall declaration macros into ordinary function prototypes.
+        (CMatch("SYSCALL_DEFINE0"), r"long sys_\1( void )"),
+        (CMatch("SYSCALL_DEFINE1"), r"long sys_\1(\2- \3-)"),
+        (CMatch("SYSCALL_DEFINE2"), r"long sys_\1(\2- \3-, \4- \5-)"),
+        (CMatch("SYSCALL_DEFINE3"),
+         r"long sys_\1(\2- \3-, \4- \5-, \6- \7-)"),
+        (CMatch("SYSCALL_DEFINE4"),
+         r"long sys_\1(\2- \3-, \4- \5-, \6- \7-, \8- \9-)"),
+        (CMatch("SYSCALL_DEFINE5"),
+         r"long sys_\1(\2- \3-, \4- \5-, \6- \7-, \8- \9-, "
+         r"\10- \11-)"),
+        (CMatch("SYSCALL_DEFINE6"),
+         r"long sys_\1(\2- \3-, \4- \5-, \6- \7-, \8- \9-, "
+         r"\10- \11-, \12- \13-)"),
+
+        # Tracepoint documentation uses the event name, while the generated
+        # function has the trace_ prefix. The proto argument is unwrapped
+        # separately below.
+        (CMatch(r"TRACE_EVENT(?:_FN(?:_COND)?|_CONDITION|_SYSCALL)?"),
+         r"static inline void trace_\1-(\2-)"),
+        (CMatch(r"DEFINE_EVENT(?:_FN|_PRINT|_CONDITION|_NOP|_WRITABLE)?"),
+         r"static inline void trace_\2-(\3-)"),
+        (CMatch("DEFINE_SINGLE_EVENT"),
+         r"static inline void trace_\1-(\2-)"),
+        (CMatch("TP_PROTO"), r"\0"),
+
         #
         # HACK: this is similar to process_export() hack. It is meant to
         # drop _noproof from function name. See for instance:
@@ -159,3 +192,9 @@ class CTransforms:
 
             source = search.sub(subst, source)
         return str(source)
+
+    @classmethod
+    def is_tracepoint(cls, source):
+        """Return whether source starts with a supported tracepoint macro."""
+
+        return any(cls.tracepoint_match.search(source))
diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdoc_parser.py
index 4baa78ca02b3..1702f912c897 100755
--- a/tools/unittests/test_kdoc_parser.py
+++ b/tools/unittests/test_kdoc_parser.py
@@ -444,6 +444,62 @@ class TestContextLockStruct(GenerateKdocItem):
         self.assertEqual(entries[0].name, "debugfs_cancellation")
         self.assertEqual(entries[0].warnings, [])
 
+
+class TestSpecialFunctionMacros(GenerateKdocItem):
+    def _parse(self, source):
+        kernel_doc = KernelDoc(self.config, "test.c", self.xforms)
+        patcher = patch('builtins.open', new_callable=mock_open,
+                        read_data=dedent(source))
+        with patcher:
+            return kernel_doc.parse_kdoc()[1]
+
+    def test_trace_event_fn(self):
+        entries = self._parse("""
+            /**
+             * gpu_power_status - called when hardware turns on or off
+             * @dev: pointer to device
+             * @shader_bitmap: bitmap
+             *
+             * Description of the tracepoint.
+             */
+            TRACE_EVENT_FN(gpu_power_status, TP_PROTO(const struct device *dev, u64 shader_bitmap), TP_ARGS(dev, shader_bitmap), TP_STRUCT__entry(__field(u64, shader_bitmap)), TP_fast_assign(__entry->shader_bitmap = shader_bitmap;), TP_printk("%s", __get_str(dev_name)), my_register, my_unregister);
+        """)
+
+        self.assertEqual(len(entries), 1)
+        self.assertEqual(entries[0].name, "trace_gpu_power_status")
+        self.assertEqual(entries[0].warnings, [])
+
+    def test_syscall_define_zero(self):
+        entries = self._parse("""
+            /**
+             * sys_demo - demo syscall
+             *
+             * Return: zero
+             */
+            SYSCALL_DEFINE0(demo);
+        """)
+
+        self.assertEqual(len(entries), 1)
+        self.assertEqual(entries[0].name, "sys_demo")
+        self.assertEqual(entries[0].warnings, [])
+
+    def test_syscall_define_three(self):
+        entries = self._parse("""
+            /**
+             * sys_demo - demo syscall
+             * @one: first value
+             * @two: second value
+             * @three: third value
+             *
+             * Return: zero
+             */
+            SYSCALL_DEFINE3(demo, int, one, long, two, unsigned int, three);
+        """)
+
+        self.assertEqual(len(entries), 1)
+        self.assertEqual(entries[0].name, "sys_demo")
+        self.assertEqual(entries[0].warnings, [])
+
 #
 # Class and logic to create dynamic tests from YAML
 #
-- 
2.43.0

[PATCH v3 2/2] docs: kdoc: strip DOMAIN_NS() wrapper in function prototypes

[Omokefe Emmanuel Onanaroghene]

kernel-doc fails to parse functions whose names are wrapped in the
DOMAIN_NS() namespace macro, e.g. in
drivers/iommu/generic_pt/iommu_pt.h:217:

  ... expecting prototype for iova_to_phys(). Prototype was for
  DOMAIN_NS() instead

function_xforms is the designated place for unwrapping function-name
macros, but it has no entry for DOMAIN_NS(), so the macro name is kept
as the prototype and the real name leaks into the parameter list.

Add a transform expanding DOMAIN_NS(op) to op, following the existing
DEFINE_IDTENTRY_IRQ precedent.

Add a regression test for the wrapped iova_to_phys() declaration.

Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@gmail.com>
---
 tools/lib/python/kdoc/xforms_lists.py |  6 ++++++
 tools/unittests/test_kdoc_parser.py   | 22 ++++++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py
index 15f6f21c7a9e..c9ce9bddebba 100644
--- a/tools/lib/python/kdoc/xforms_lists.py
+++ b/tools/lib/python/kdoc/xforms_lists.py
@@ -92,6 +92,12 @@ class CTransforms:
         (CMatch("__diagnose_as"), ""),
         (CMatch("DECL_BUCKET_PARAMS"), r"\1, \2"),
         (CMatch("DEFINE_IDTENTRY_IRQ"), r"static void \1(struct pt_regs *regs, u32 vector)"),
+        #
+        # DOMAIN_NS() wraps a function name with a namespace prefix
+        # (see drivers/iommu/generic_pt/iommu_pt.h). Unwrap it so the
+        # real function name is parsed.
+        #
+        (CMatch("DOMAIN_NS"), r"\1"),
         (CMatch("__cond_acquires"), ""),
         (CMatch("__cond_releases"), ""),
         (CMatch("__acquires"), ""),
diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdoc_parser.py
index 04dafae412e4..e4f44535d0dc 100755
--- a/tools/unittests/test_kdoc_parser.py
+++ b/tools/unittests/test_kdoc_parser.py
@@ -472,6 +472,28 @@ class TestTraceEventFn(GenerateKdocItem):
         self.assertEqual(entries[0].name, "trace_gpu_power_status")
         self.assertEqual(entries[0].warnings, [])
 
+class TestDomainNs(GenerateKdocItem):
+    def test_domain_ns_wrapped_function(self):
+        source = """
+            /**
+             * iova_to_phys() - Return the output address for the given IOVA
+             * @domain: Table to query
+             * @iova: IO virtual address to query
+             */
+            phys_addr_t DOMAIN_NS(iova_to_phys)(struct iommu_domain *domain,
+                                                dma_addr_t iova);
+        """
+
+        kernel_doc = KernelDoc(self.config, "test.c", self.xforms)
+        patcher = patch('builtins.open', new_callable=mock_open,
+                        read_data=dedent(source))
+        with patcher:
+            _, entries = kernel_doc.parse_kdoc()
+
+        self.assertEqual(len(entries), 1)
+        self.assertEqual(entries[0].name, "iova_to_phys")
+        self.assertEqual(entries[0].warnings, [])
+
 #
 # Class and logic to create dynamic tests from YAML
 #
-- 
2.43.0