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: Shivank Garg <shivankg@amd.com>
Signed-off-by: Ingo 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

authored by

Shivank Garg and committed by

Ingo Molnar 1 year ago 1adf7119 25219c25

+31 -19

1 changed file

expand all

arch

x86

pgtable.c

+31 -19

arch/x86/mm/pgtable.c

··· 543 543 #endif 544 544 545 545 /** 546 - * reserve_top_address - reserves a hole in the top of kernel address space 547 - * @reserve - size of hole to reserve 546 + * reserve_top_address - Reserve a hole in the top of the kernel address space 547 + * @reserve: Size of hole to reserve 548 548 * 549 549 * Can be used to relocate the fixmap area and poke a hole in the top 550 - * of kernel address space to make room for a hypervisor. 550 + * of the kernel address space to make room for a hypervisor. 551 551 */ 552 552 void __init reserve_top_address(unsigned long reserve) 553 553 { ··· 594 594 #ifdef CONFIG_HAVE_ARCH_HUGE_VMAP 595 595 #ifdef CONFIG_X86_5LEVEL 596 596 /** 597 - * p4d_set_huge - setup kernel P4D mapping 597 + * p4d_set_huge - Set up kernel P4D mapping 598 + * @p4d: Pointer to the P4D entry 599 + * @addr: Virtual address associated with the P4D entry 600 + * @prot: Protection bits to use 598 601 * 599 602 * No 512GB pages yet -- always return 0 600 603 */ ··· 607 604 } 608 605 609 606 /** 610 - * p4d_clear_huge - clear kernel P4D mapping when it is set 607 + * p4d_clear_huge - Clear kernel P4D mapping when it is set 608 + * @p4d: Pointer to the P4D entry to clear 611 609 * 612 - * No 512GB pages yet -- always return 0 610 + * No 512GB pages yet -- do nothing 613 611 */ 614 612 void p4d_clear_huge(p4d_t *p4d) 615 613 { ··· 618 614 #endif 619 615 620 616 /** 621 - * pud_set_huge - setup kernel PUD mapping 617 + * pud_set_huge - Set up kernel PUD mapping 618 + * @pud: Pointer to the PUD entry 619 + * @addr: Virtual address associated with the PUD entry 620 + * @prot: Protection bits to use 622 621 * 623 622 * MTRRs can override PAT memory types with 4KiB granularity. Therefore, this 624 623 * function sets up a huge page only if the complete range has the same MTRR ··· 652 645 } 653 646 654 647 /** 655 - * pmd_set_huge - setup kernel PMD mapping 648 + * pmd_set_huge - Set up kernel PMD mapping 649 + * @pmd: Pointer to the PMD entry 650 + * @addr: Virtual address associated with the PMD entry 651 + * @prot: Protection bits to use 656 652 * 657 653 * See text over pud_set_huge() above. 658 654 * ··· 684 674 } 685 675 686 676 /** 687 - * pud_clear_huge - clear kernel PUD mapping when it is set 677 + * pud_clear_huge - Clear kernel PUD mapping when it is set 678 + * @pud: Pointer to the PUD entry to clear. 688 679 * 689 680 * Returns 1 on success and 0 on failure (no PUD map is found). 690 681 */ ··· 700 689 } 701 690 702 691 /** 703 - * pmd_clear_huge - clear kernel PMD mapping when it is set 692 + * pmd_clear_huge - Clear kernel PMD mapping when it is set 693 + * @pmd: Pointer to the PMD entry to clear. 704 694 * 705 695 * Returns 1 on success and 0 on failure (no PMD map is found). 706 696 */ ··· 717 705 718 706 #ifdef CONFIG_X86_64 719 707 /** 720 - * pud_free_pmd_page - Clear pud entry and free pmd page. 721 - * @pud: Pointer to a PUD. 722 - * @addr: Virtual address associated with pud. 708 + * pud_free_pmd_page - Clear PUD entry and free PMD page 709 + * @pud: Pointer to a PUD 710 + * @addr: Virtual address associated with PUD 723 711 * 724 - * Context: The pud range has been unmapped and TLB purged. 712 + * Context: The PUD range has been unmapped and TLB purged. 725 713 * Return: 1 if clearing the entry succeeded. 0 otherwise. 726 714 * 727 715 * NOTE: Callers must allow a single page allocation. ··· 764 752 } 765 753 766 754 /** 767 - * pmd_free_pte_page - Clear pmd entry and free pte page. 768 - * @pmd: Pointer to a PMD. 769 - * @addr: Virtual address associated with pmd. 755 + * pmd_free_pte_page - Clear PMD entry and free PTE page. 756 + * @pmd: Pointer to the PMD 757 + * @addr: Virtual address associated with PMD 770 758 * 771 - * Context: The pmd range has been unmapped and TLB purged. 759 + * Context: The PMD range has been unmapped and TLB purged. 772 760 * Return: 1 if clearing the entry succeeded. 0 otherwise. 773 761 */ 774 762 int pmd_free_pte_page(pmd_t *pmd, unsigned long addr) ··· 790 778 791 779 /* 792 780 * Disable free page handling on x86-PAE. This assures that ioremap() 793 - * does not update sync'd pmd entries. See vmalloc_sync_one(). 781 + * does not update sync'd PMD entries. See vmalloc_sync_one(). 794 782 */ 795 783 int pmd_free_pte_page(pmd_t *pmd, unsigned long addr) 796 784 {

Configure Feed

Configure Feed