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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

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