Commit 1adf7119 authored by Shivank Garg's avatar Shivank Garg Committed by Ingo Molnar
Browse files

x86/mm: Fix kernel-doc descriptions of various pgtable methods 



So 'make W=1' complains about a couple of kernel-doc descriptions
in our MM primitives in pgtable.c:

  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

Fix them all up, add missing parameter documentation, and fix various spelling
inconsistencies while at it.

[ mingo: Harmonize kernel-doc annotations some more. ]

Signed-off-by: default avatarShivank Garg <shivankg@amd.com>
Signed-off-by: default avatarIngo Molnar <mingo@kernel.org>
Cc: Dave Hansen <dave.hansen@linux.intel.com>
Cc: Andrew Cooper <andrew.cooper3@citrix.com>
Cc: Andy Lutomirski <luto@kernel.org>
Cc: Brian Gerst <brgerst@gmail.com>
Cc: H. Peter Anvin <hpa@zytor.com>
Cc: Juergen Gross <jgross@suse.com>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Rik van Riel <riel@surriel.com>
Link: https://lore.kernel.org/r/20250514062637.3287779-1-shivankg@amd.com
parent 25219c25

arch/x86/mm/pgtable.c

+31 −19
Original line number Diff line number Diff line
@@ -543,11 +543,11 @@ pud_t pudp_invalidate(struct vm_area_struct *vma, unsigned long address, 
#endif



/**

 * reserve_top_address - reserves a hole in the top of kernel address space

 * @reserve - size of hole to reserve

 * reserve_top_address - Reserve a hole in the top of the kernel address space

 * @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.

 * of the kernel address space to make room for a hypervisor.

 */

void __init reserve_top_address(unsigned long reserve)

{
@@ -594,7 +594,10 @@ void native_set_fixmap(unsigned /* enum fixed_addresses */ idx, 
#ifdef CONFIG_HAVE_ARCH_HUGE_VMAP

#ifdef CONFIG_X86_5LEVEL

/**

 * p4d_set_huge - setup kernel P4D mapping

 * p4d_set_huge - Set up kernel P4D mapping

 * @p4d: Pointer to the P4D entry

 * @addr: Virtual address associated with the P4D entry

 * @prot: Protection bits to use

 *

 * No 512GB pages yet -- always return 0

 */
@@ -604,9 +607,10 @@ 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_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)

{
@@ -614,7 +618,10 @@ void p4d_clear_huge(p4d_t *p4d) 
#endif



/**

 * pud_set_huge - setup kernel PUD mapping

 * pud_set_huge - Set up kernel PUD mapping

 * @pud: Pointer to the PUD entry

 * @addr: Virtual address associated with the PUD entry

 * @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
@@ -645,7 +652,10 @@ int pud_set_huge(pud_t *pud, phys_addr_t addr, pgprot_t prot) 
}



/**

 * pmd_set_huge - setup kernel PMD mapping

 * pmd_set_huge - Set up kernel PMD mapping

 * @pmd: Pointer to the PMD entry

 * @addr: Virtual address associated with the PMD entry

 * @prot: Protection bits to use

 *

 * See text over pud_set_huge() above.

 *
@@ -674,7 +684,8 @@ 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_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).

 */
@@ -689,7 +700,8 @@ int pud_clear_huge(pud_t *pud) 
}



/**

 * pmd_clear_huge - clear kernel PMD mapping when it is set

 * 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).

 */
@@ -705,11 +717,11 @@ int pmd_clear_huge(pmd_t *pmd) 


#ifdef CONFIG_X86_64

/**

 * pud_free_pmd_page - Clear pud entry and free pmd page.

 * @pud: Pointer to a PUD.

 * @addr: Virtual address associated with pud.

 * pud_free_pmd_page - Clear PUD entry and free PMD page

 * @pud: Pointer to a PUD

 * @addr: Virtual address associated with PUD

 *

 * Context: The pud range has been unmapped and TLB purged.

 * Context: The PUD range has been unmapped and TLB purged.

 * Return: 1 if clearing the entry succeeded. 0 otherwise.

 *

 * NOTE: Callers must allow a single page allocation.
@@ -752,11 +764,11 @@ int pud_free_pmd_page(pud_t *pud, unsigned long addr) 
}



/**

 * pmd_free_pte_page - Clear pmd entry and free pte page.

 * @pmd: Pointer to a PMD.

 * @addr: Virtual address associated with pmd.

 * pmd_free_pte_page - Clear PMD entry and free PTE page.

 * @pmd: Pointer to the PMD

 * @addr: Virtual address associated with PMD

 *

 * Context: The pmd range has been unmapped and TLB purged.

 * Context: The PMD range has been unmapped and TLB purged.

 * Return: 1 if clearing the entry succeeded. 0 otherwise.

 */

int pmd_free_pte_page(pmd_t *pmd, unsigned long addr)
@@ -778,7 +790,7 @@ int pmd_free_pte_page(pmd_t *pmd, unsigned long addr) 


/*

 * Disable free page handling on x86-PAE. This assures that ioremap()

 * does not update sync'd pmd entries. See vmalloc_sync_one().

 * does not update sync'd PMD entries. See vmalloc_sync_one().

 */

int pmd_free_pte_page(pmd_t *pmd, unsigned long addr)

{