[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <aCYC2pYpXeYVlxA1@gmail.com>
Date: Thu, 15 May 2025 17:06:02 +0200
From: Ingo Molnar <mingo@...nel.org>
To: Shivank Garg <shivankg@....com>
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
* 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.
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