[PATCH v1 0/2] doc: Handle IDTENTRY and fix apic.c

[PATCH v1 0/2] doc: Handle IDTENTRY and fix apic.c

[Andy Shevchenko]

Handle DEFINE_IDTENTRY_IRQ() and fix apic.c kernel-doc issues.
Assumed to go via doc Git tree. Please, Ack.

Andy Shevchenko (2):
  doc: kdoc: Handle DEFINE_IDTENTRY_*() cases
  x86/apic: Update kernel-doc to avoid warnings

 arch/x86/kernel/apic/apic.c     |  4 +++-
 scripts/lib/kdoc/kdoc_parser.py | 27 +++++++++++++++++++++++----
 2 files changed, 26 insertions(+), 5 deletions(-)

-- 
2.50.1

[PATCH v1 1/2] doc: kdoc: Handle DEFINE_IDTENTRY_*() cases

[Andy Shevchenko]

We have an unparsed kernel-doc for spurious_interrupt() IDTENTRY.
Update kdoc to handle that.

Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
 scripts/lib/kdoc/kdoc_parser.py | 27 +++++++++++++++++++++++----
 1 file changed, 23 insertions(+), 4 deletions(-)

diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index f7dbb0868367..b583edd80a52 100644
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -1430,6 +1430,25 @@ class KernelDoc:
 
         return proto
 
+    def idtentry_munge(self, ln, proto):
+        """
+        Handle DEFINE_IDTENTRY_*() definitions
+        """
+
+        name = None
+
+        # Replace DEFINE_IDTENTRY_IRQ with correct return type & function name
+        r = KernRe(r'DEFINE_IDTENTRY_IRQ\((.*?)\)')
+        if r.search(proto):
+            name = r.group(1)
+
+        if not name:
+            self.emit_msg(ln, f"Unrecognized IDTENTRY format:\n{proto}\n")
+        else:
+            proto = f"static inline void {name}((struct pt_regs *regs, unsigned long error_code)"
+
+        return proto
+
     def tracepoint_munge(self, ln, proto):
         """
         Handle tracepoint definitions
@@ -1499,13 +1518,13 @@ class KernelDoc:
             # Handle special declaration syntaxes
             #
             if 'SYSCALL_DEFINE' in self.entry.prototype:
-                self.entry.prototype = self.syscall_munge(ln,
-                                                          self.entry.prototype)
+                self.entry.prototype = self.syscall_munge(ln, self.entry.prototype)
+            elif 'DEFINE_IDTENTRY' in self.entry.prototype:
+                self.entry.prototype = self.idtentry_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)
+                    self.entry.prototype = self.tracepoint_munge(ln, self.entry.prototype)
             #
             # ... and we're done
             #
-- 
2.50.1

Re: [PATCH v1 1/2] doc: kdoc: Handle DEFINE_IDTENTRY_*() cases

[Randy Dunlap]

Hi,

On 11/6/25 2:12 AM, Andy Shevchenko wrote:
> We have an unparsed kernel-doc for spurious_interrupt() IDTENTRY.
> Update kdoc to handle that.
> 
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> ---
>  scripts/lib/kdoc/kdoc_parser.py | 27 +++++++++++++++++++++++----
>  1 file changed, 23 insertions(+), 4 deletions(-)
> 
> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index f7dbb0868367..b583edd80a52 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -1430,6 +1430,25 @@ class KernelDoc:
>  
>          return proto
>  
> +    def idtentry_munge(self, ln, proto):
> +        """
> +        Handle DEFINE_IDTENTRY_*() definitions
> +        """
> +
> +        name = None
> +
> +        # Replace DEFINE_IDTENTRY_IRQ with correct return type & function name
> +        r = KernRe(r'DEFINE_IDTENTRY_IRQ\((.*?)\)')
> +        if r.search(proto):
> +            name = r.group(1)
> +
> +        if not name:
> +            self.emit_msg(ln, f"Unrecognized IDTENTRY format:\n{proto}\n")
> +        else:
> +            proto = f"static inline void {name}((struct pt_regs *regs, unsigned long error_code)"

Seems to be an extra '(' here ...................^^^

Oh, weird: is the comma inside function parameters converted to a '#' somewhere?
See below in SYNOPSIS.


Output from testing says: (-man format output)

NAME
       spurious_interrupt - Catch all for interrupts raised on unused vectors

SYNOPSIS
       void spurious_interrupt ((struct pt_regs *regs# unsigned long error_code
       );

ARGUMENTS
       error_code  The vector number

> +
> +        return proto
> +
>      def tracepoint_munge(self, ln, proto):
>          """
>          Handle tracepoint definitions
> @@ -1499,13 +1518,13 @@ class KernelDoc:
>              # Handle special declaration syntaxes
>              #
>              if 'SYSCALL_DEFINE' in self.entry.prototype:
> -                self.entry.prototype = self.syscall_munge(ln,
> -                                                          self.entry.prototype)
> +                self.entry.prototype = self.syscall_munge(ln, self.entry.prototype)
> +            elif 'DEFINE_IDTENTRY' in self.entry.prototype:
> +                self.entry.prototype = self.idtentry_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)
> +                    self.entry.prototype = self.tracepoint_munge(ln, self.entry.prototype)
>              #
>              # ... and we're done
>              #

-- 
~Randy

[PATCH v1 2/2] x86/apic: Update kernel-doc to avoid warnings

[Andy Shevchenko]

Validator is not happy about some of the kernel-doc descriptions:

Warning: arch/x86/kernel/apic/apic.c:245 No description found for return value of 'lapic_get_maxlvt'
Warning: arch/x86/kernel/apic/apic.c:2145 function parameter 'error_code' not described in 'spurious_interrupt'

Update them accordingly.

Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
 arch/x86/kernel/apic/apic.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/arch/x86/kernel/apic/apic.c b/arch/x86/kernel/apic/apic.c
index 680d305589a3..4675d1a07fc9 100644
--- a/arch/x86/kernel/apic/apic.c
+++ b/arch/x86/kernel/apic/apic.c
@@ -241,6 +241,8 @@ u64 native_apic_icr_read(void)
 
 /**
  * lapic_get_maxlvt - get the maximum number of local vector table entries
+ *
+ * Return: the maximum number of local vector table entries
  */
 int lapic_get_maxlvt(void)
 {
@@ -2136,7 +2138,7 @@ static noinline void handle_spurious_interrupt(u8 vector)
 /**
  * spurious_interrupt - Catch all for interrupts raised on unused vectors
  * @regs:	Pointer to pt_regs on stack
- * @vector:	The vector number
+ * @error_code:	The vector number
  *
  * This is invoked from ASM entry code to catch all interrupts which
  * trigger on an entry which is routed to the common_spurious idtentry
-- 
2.50.1

Re: [PATCH v1 2/2] x86/apic: Update kernel-doc to avoid warnings

[Randy Dunlap]

On 11/6/25 2:12 AM, Andy Shevchenko wrote:
> Validator is not happy about some of the kernel-doc descriptions:
> 
> Warning: arch/x86/kernel/apic/apic.c:245 No description found for return value of 'lapic_get_maxlvt'
> Warning: arch/x86/kernel/apic/apic.c:2145 function parameter 'error_code' not described in 'spurious_interrupt'
> 
> Update them accordingly.
> 
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

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

Thanks.

> ---
>  arch/x86/kernel/apic/apic.c | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/arch/x86/kernel/apic/apic.c b/arch/x86/kernel/apic/apic.c
> index 680d305589a3..4675d1a07fc9 100644
> --- a/arch/x86/kernel/apic/apic.c
> +++ b/arch/x86/kernel/apic/apic.c
> @@ -241,6 +241,8 @@ u64 native_apic_icr_read(void)
>  
>  /**
>   * lapic_get_maxlvt - get the maximum number of local vector table entries
> + *
> + * Return: the maximum number of local vector table entries
>   */
>  int lapic_get_maxlvt(void)
>  {
> @@ -2136,7 +2138,7 @@ static noinline void handle_spurious_interrupt(u8 vector)
>  /**
>   * spurious_interrupt - Catch all for interrupts raised on unused vectors
>   * @regs:	Pointer to pt_regs on stack
> - * @vector:	The vector number
> + * @error_code:	The vector number
>   *
>   * This is invoked from ASM entry code to catch all interrupts which
>   * trigger on an entry which is routed to the common_spurious idtentry

-- 
~Randy