[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Message-ID: <f8a09f92-40ff-40e2-a39d-81b195d541b3@amd.com>
Date: Thu, 15 May 2025 23:40:43 +0530
From: Shivank Garg <shivankg@....com>
To: Ingo Molnar <mingo@...nel.org>
Cc: tglx@...utronix.de, mingo@...hat.com, bp@...en8.de,
dave.hansen@...ux.intel.com, x86@...nel.org, hpa@...or.com, luto@...nel.org,
peterz@...radead.org, rafael@...nel.org, pavel@...nel.org,
akpm@...ux-foundation.org, linux-kernel@...r.kernel.org,
linux-pm@...r.kernel.org, sohil.mehta@...el.com, rui.zhang@...el.com,
yuntao.wang@...ux.dev, kai.huang@...el.com, xiaoyao.li@...el.com,
peterx@...hat.com, sandipan.das@....com, ak@...ux.intel.com,
rostedt@...dmis.org
Subject: Re: [PATCH RESEND 1/4] x86/mm: pgtable: Fix W=1 build kernel-doc
warnings
On 5/15/2025 8:36 PM, Ingo Molnar wrote:
>
> * Shivank Garg <shivankg@....com> wrote:
>
>>> Also, similar errors are elsewhere as well.
>>
>> I'm sorry for missing these details in the previous revision.
>> I'm changing the first letter of variable description to capital.
>>
>> https://docs.kernel.org/doc-guide/kernel-doc.html
>> /**
>> * function_name() - Brief description of function.
>> * @arg1: Describe the first argument.
>> * @arg2: Describe the second argument.
>> * One can provide multiple line descriptions
>> * for arguments.
>>
>> Function description also starts with capital letter in the doc-guide
>> and other kernel places so this should make it consistent.
>
> Thank you! This version is much more complete. There were a few other
> things missing, quite a few of them pre-existing, which I fixed up in
> the commit (see the delta patch below).
>
> Note that I standardized on a kernel-doc style variant without full
> stops for simple singular sentences. This is what most of the x86 code
> and the core kernel is doing, and it's contrary to the kernel-doc.html
> recommendation - but you couldn't really have known that.
>
Thank you for the detailed review and fixups.
Best Regards,
Shivank
> Thanks,
>
> Ingo
>
> =====================>
> arch/x86/mm/pgtable.c | 50 +++++++++++++++++++++++++-------------------------
> 1 file changed, 25 insertions(+), 25 deletions(-)
>
> diff --git a/arch/x86/mm/pgtable.c b/arch/x86/mm/pgtable.c
> index 9aa3c60c6afa..59c42dec7076 100644
> --- a/arch/x86/mm/pgtable.c
> +++ b/arch/x86/mm/pgtable.c
> @@ -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,10 +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: Pointer to the P4D entry.
> - * @addr: Virtual address associated with the P4D entry.
> - * @prot: Protection bits to use.
> + * 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
> */
> @@ -608,7 +608,7 @@ 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.
> + * @p4d: Pointer to the P4D entry to clear
> *
> * No 512GB pages yet -- do nothing
> */
> @@ -618,10 +618,10 @@ void p4d_clear_huge(p4d_t *p4d)
> #endif
>
> /**
> - * pud_set_huge - Setup kernel PUD mapping
> - * @pud: Pointer to the PUD entry.
> - * @addr: Virtual address associated with the PUD entry.
> - * @prot: Protection bits to use.
> + * 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
> @@ -652,10 +652,10 @@ int pud_set_huge(pud_t *pud, phys_addr_t addr, pgprot_t prot)
> }
>
> /**
> - * pmd_set_huge - Setup kernel PMD mapping
> - * @pmd: Pointer to the PMD entry.
> - * @addr: Virtual address associated with the PMD entry.
> - * @prot: Protection bits to use.
> + * 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.
> *
> @@ -717,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.
> @@ -764,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)
> @@ -790,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)
> {
Powered by blists - more mailing lists