[PATCH 1/4] x86/mm: pgtable: Fix W=1 build kernel-doc warnings

[PATCH 1/4] x86/mm: pgtable: Fix W=1 build kernel-doc warnings

[Shivank Garg]

Sample warnings generated with 'make W=1':
arch/x86/mm/pgtable.c:623: warning: Function parameter or struct member 'reserve' not described in 'reserve_top_address'
arch/x86/mm/pgtable.c:672: warning: Function parameter or struct member 'p4d' not described in 'p4d_set_huge'
arch/x86/mm/pgtable.c:672: warning: Function parameter or struct member 'addr' not described in 'p4d_set_huge'
... so on

Add missing parameter documentation in page table functions to
fix kernel-doc warnings.

Signed-off-by: Shivank Garg <shivankg@amd.com>
---
 arch/x86/mm/pgtable.c | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/arch/x86/mm/pgtable.c b/arch/x86/mm/pgtable.c
index f7ae44d3dd9e..8a5bc4545ad3 100644
--- a/arch/x86/mm/pgtable.c
+++ b/arch/x86/mm/pgtable.c
@@ -614,7 +614,7 @@ pud_t pudp_invalidate(struct vm_area_struct *vma, unsigned long address,
 
 /**
  * reserve_top_address - reserves a hole in the top of kernel address space
- * @reserve - size of hole to reserve
+ * @reserve: Size of hole to reserve.
  *
  * Can be used to relocate the fixmap area and poke a hole in the top
  * of kernel address space to make room for a hypervisor.
@@ -665,6 +665,9 @@ void native_set_fixmap(unsigned /* enum fixed_addresses */ idx,
 #ifdef CONFIG_X86_5LEVEL
 /**
  * p4d_set_huge - setup kernel P4D mapping
+ * @p4d: Pointer to a p4d entry.
+ * @addr: Virtual Address associated with p4d.
+ * @prot: Protection bits to use.
  *
  * No 512GB pages yet -- always return 0
  */
@@ -675,8 +678,9 @@ int p4d_set_huge(p4d_t *p4d, phys_addr_t addr, pgprot_t prot)
 
 /**
  * p4d_clear_huge - clear kernel P4D mapping when it is set
+ * @p4d: Pointer to the p4d entry to clear.
  *
- * No 512GB pages yet -- always return 0
+ * No 512GB pages yet -- do nothing
  */
 void p4d_clear_huge(p4d_t *p4d)
 {
@@ -685,6 +689,9 @@ void p4d_clear_huge(p4d_t *p4d)
 
 /**
  * pud_set_huge - setup kernel PUD mapping
+ * @pud: Pointer to a pud entry.
+ * @addr: Virtual Address associated with pud.
+ * @prot: Protection bits to use.
  *
  * MTRRs can override PAT memory types with 4KiB granularity. Therefore, this
  * function sets up a huge page only if the complete range has the same MTRR
@@ -716,6 +723,9 @@ int pud_set_huge(pud_t *pud, phys_addr_t addr, pgprot_t prot)
 
 /**
  * pmd_set_huge - setup kernel PMD mapping
+ * @pmd: Pointer to a pmd entry.
+ * @addr: Virtual Address associated with pmd.
+ * @prot: Protection bits to use.
  *
  * See text over pud_set_huge() above.
  *
@@ -745,6 +755,7 @@ int pmd_set_huge(pmd_t *pmd, phys_addr_t addr, pgprot_t prot)
 
 /**
  * pud_clear_huge - clear kernel PUD mapping when it is set
+ * @pud: Pointer to the pud entry to clear.
  *
  * Returns 1 on success and 0 on failure (no PUD map is found).
  */
@@ -760,6 +771,7 @@ int pud_clear_huge(pud_t *pud)
 
 /**
  * pmd_clear_huge - clear kernel PMD mapping when it is set
+ * @pmd: Pointer to the pmd entry to clear.
  *
  * Returns 1 on success and 0 on failure (no PMD map is found).
  */
-- 
2.34.1

[PATCH 2/4] x86/power: hibernate: Fix W=1 build kernel-doc warnings

[Shivank Garg]

Sample warnings generated with 'make W=1':
arch/x86/power/hibernate.c:47: warning: Function parameter or struct member 'pfn' not described in 'pfn_is_nosave'
arch/x86/power/hibernate.c:92: warning: Function parameter or struct member 'max_size' not described in 'arch_hibernation_header_save'

Add missing parameter documentation in hibernate functions to
fix kernel-doc warnings.

Signed-off-by: Shivank Garg <shivankg@amd.com>
---
 arch/x86/power/hibernate.c | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/arch/x86/power/hibernate.c b/arch/x86/power/hibernate.c
index 5b81d19cd114..a7c23f2a58c9 100644
--- a/arch/x86/power/hibernate.c
+++ b/arch/x86/power/hibernate.c
@@ -42,6 +42,7 @@ unsigned long relocated_restore_code __visible;
 
 /**
  *	pfn_is_nosave - check if given pfn is in the 'nosave' section
+ *	@pfn: the page frame number to check.
  */
 int pfn_is_nosave(unsigned long pfn)
 {
@@ -86,7 +87,10 @@ static inline u32 compute_e820_crc32(struct e820_table *table)
 /**
  *	arch_hibernation_header_save - populate the architecture specific part
  *		of a hibernation image header
- *	@addr: address to save the data at
+ *	@addr: address where architecture specific header data will be saved.
+ *	@max_size: maximum size of architecture specific data in hibernation header.
+ *
+ *	Return: 0 on success, -EOVERFLOW if max_size is insufficient.
  */
 int arch_hibernation_header_save(void *addr, unsigned int max_size)
 {
-- 
2.34.1

[PATCH 3/4] x86/mm/pat: Fix W=1 build kernel-doc warning

[Shivank Garg]

Building the kernel with W=1 generates the following warning:
arch/x86/mm/pat/memtype.c:692: warning: Function parameter or struct member 'pfn' not described in 'pat_pfn_immune_to_uc_mtrr'

Add missing parameter documentation to fix the kernel-doc warning.

Signed-off-by: Shivank Garg <shivankg@amd.com>
---
 arch/x86/mm/pat/memtype.c | 1 +
 1 file changed, 1 insertion(+)

diff --git a/arch/x86/mm/pat/memtype.c b/arch/x86/mm/pat/memtype.c
index 72d8cbc61158..51635ae1eb7f 100644
--- a/arch/x86/mm/pat/memtype.c
+++ b/arch/x86/mm/pat/memtype.c
@@ -682,6 +682,7 @@ static enum page_cache_mode lookup_memtype(u64 paddr)
 /**
  * pat_pfn_immune_to_uc_mtrr - Check whether the PAT memory type
  * of @pfn cannot be overridden by UC MTRR memory type.
+ * @pfn: The page frame number to check.
  *
  * Only to be called when PAT is enabled.
  *
-- 
2.34.1

[PATCH 4/4] x86/apic: Fix W=1 build kernel-doc warning

[Shivank Garg]

Building the kernel with W=1 generates the following warning:

arch/x86/kernel/apic/apic.c:2140: warning: Function parameter or struct member 'spurious_interrupt' not described in 'DEFINE_IDTENTRY_IRQ'
arch/x86/kernel/apic/apic.c:2140: warning: expecting prototype for spurious_interrupt(). Prototype was for DEFINE_IDTENTRY_IRQ() instead

Fix the description format to fix the warning.

Signed-off-by: Shivank Garg <shivankg@amd.com>
---
 arch/x86/kernel/apic/apic.c | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/arch/x86/kernel/apic/apic.c b/arch/x86/kernel/apic/apic.c
index 62584a347931..f888a28d400f 100644
--- a/arch/x86/kernel/apic/apic.c
+++ b/arch/x86/kernel/apic/apic.c
@@ -2128,9 +2128,10 @@ 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
+ * DEFINE_IDTENTRY_IRQ - Handler for spurious interrupts
+ * @spurious_interrupt: Catch all for interrupts raised on unused vectors
+ * regs:	Pointer to pt_regs on stack
+ * vector:	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.34.1

Re: [PATCH 2/4] x86/power: hibernate: Fix W=1 build kernel-doc warnings

[Rafael J. Wysocki]

On Wed, Apr 30, 2025 at 1:31 PM Shivank Garg <shivankg@amd.com> wrote:
>
> Sample warnings generated with 'make W=1':
> arch/x86/power/hibernate.c:47: warning: Function parameter or struct member 'pfn' not described in 'pfn_is_nosave'
> arch/x86/power/hibernate.c:92: warning: Function parameter or struct member 'max_size' not described in 'arch_hibernation_header_save'
>
> Add missing parameter documentation in hibernate functions to
> fix kernel-doc warnings.
>
> Signed-off-by: Shivank Garg <shivankg@amd.com>

Acked-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

> ---
>  arch/x86/power/hibernate.c | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
>
> diff --git a/arch/x86/power/hibernate.c b/arch/x86/power/hibernate.c
> index 5b81d19cd114..a7c23f2a58c9 100644
> --- a/arch/x86/power/hibernate.c
> +++ b/arch/x86/power/hibernate.c
> @@ -42,6 +42,7 @@ unsigned long relocated_restore_code __visible;
>
>  /**
>   *     pfn_is_nosave - check if given pfn is in the 'nosave' section
> + *     @pfn: the page frame number to check.
>   */
>  int pfn_is_nosave(unsigned long pfn)
>  {
> @@ -86,7 +87,10 @@ static inline u32 compute_e820_crc32(struct e820_table *table)
>  /**
>   *     arch_hibernation_header_save - populate the architecture specific part
>   *             of a hibernation image header
> - *     @addr: address to save the data at
> + *     @addr: address where architecture specific header data will be saved.
> + *     @max_size: maximum size of architecture specific data in hibernation header.
> + *
> + *     Return: 0 on success, -EOVERFLOW if max_size is insufficient.
>   */
>  int arch_hibernation_header_save(void *addr, unsigned int max_size)
>  {
> --
> 2.34.1
>