linux-kernel - Re: [PATCH] x86/intel_rdt/cqm: fix kernel-doc warnings

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <5589e93d-9a9c-4199-a187-ab60fb127236@intel.com>
Date:   Mon, 9 Oct 2023 10:07:02 -0700
From:   Reinette Chatre <reinette.chatre@...el.com>
To:     Randy Dunlap <rdunlap@...radead.org>,
        <linux-kernel@...r.kernel.org>
CC:     kernel test robot <lkp@...el.com>,
        Vikas Shivappa <vikas.shivappa@...ux.intel.com>,
        Tony Luck <tony.luck@...el.com>,
        "Thomas Gleixner" <tglx@...utronix.de>,
        Fenghua Yu <fenghua.yu@...el.com>,
        Ingo Molnar <mingo@...hat.com>, Borislav Petkov <bp@...en8.de>,
        Dave Hansen <dave.hansen@...ux.intel.com>, <x86@...nel.org>
Subject: Re: [PATCH] x86/intel_rdt/cqm: fix kernel-doc warnings

Hi Randy,

Thank you very much for noticing the bug report and taking the time
to fix it.

To match the custom of this area, could you please modify
the subject to be:
	x86/resctrl: Fix kernel-doc warnings

On 10/6/2023 4:51 PM, Randy Dunlap wrote:
> The kernel test robot reported kernel-doc warnings here:
> 
> monitor.c:34: warning: Cannot understand  * @rmid_free_lru    A least recently used list of free RMIDs
>  on line 34 - I thought it was a doc line
> monitor.c:41: warning: Cannot understand  * @rmid_limbo_count     count of currently unused but (potentially)
>  on line 41 - I thought it was a doc line
> monitor.c:50: warning: Cannot understand  * @rmid_entry - The entry in the limbo and free lists.
>  on line 50 - I thought it was a doc line
> 
> We don't have a syntax for documenting individual data items via
> kernel-doc, so remove the "/**" kernel-doc markers and add a hyphen
> for consistency.
> 
> Fixes: 6a445edce657 ("x86/intel_rdt/cqm: Add RDT monitoring initialization")
> Fixes: 24247aeeabe9 ("x86/intel_rdt/cqm: Improve limbo list processing")
> Signed-off-by: Randy Dunlap <rdunlap@...radead.org>
> Reported-by: kernel test robot <lkp@...el.com>

Could you please swap the above two tags to follow the tag ordering
custom followed by the tip maintainers? For reference you can find the
details in section "Ordering of commit tags" of 
Documentation/process/maintainer-tip.rst

Also, below the "Link:" follows the "Cc:".

> Link: https://lore.kernel.org/all/202310062356.lX3xpLP9-lkp@intel.com/
> Cc: Vikas Shivappa <vikas.shivappa@...ux.intel.com>
> Cc: Tony Luck <tony.luck@...el.com>
> Cc: Thomas Gleixner <tglx@...utronix.de>
> Cc: Fenghua Yu <fenghua.yu@...el.com>
> Cc: Reinette Chatre <reinette.chatre@...el.com>
> Cc: Ingo Molnar <mingo@...hat.com>
> Cc: Borislav Petkov <bp@...en8.de>
> Cc: Dave Hansen <dave.hansen@...ux.intel.com>
> Cc: x86@...nel.org
> ---
> Not using Closes: since this patch only addresses some of the issues
>   reported.

I am aware of these issues. The person working on this previously
seems to have moved on. I'll share this work with folks looking for
this type of opportunity and ensure that it is completed this time.
 
>  arch/x86/kernel/cpu/resctrl/monitor.c |   10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
> 
> diff -- a/arch/x86/kernel/cpu/resctrl/monitor.c b/arch/x86/kernel/cpu/resctrl/monitor.c
> --- a/arch/x86/kernel/cpu/resctrl/monitor.c
> +++ b/arch/x86/kernel/cpu/resctrl/monitor.c
> @@ -30,15 +30,15 @@ struct rmid_entry {
>  	struct list_head		list;
>  };
>  
> -/**
> - * @rmid_free_lru    A least recently used list of free RMIDs
> +/*
> + * @rmid_free_lru - A least recently used list of free RMIDs
>   *     These RMIDs are guaranteed to have an occupancy less than the
>   *     threshold occupancy
>   */
>  static LIST_HEAD(rmid_free_lru);
>  
> -/**
> - * @rmid_limbo_count     count of currently unused but (potentially)
> +/*
> + * @rmid_limbo_count - count of currently unused but (potentially)
>   *     dirty RMIDs.
>   *     This counts RMIDs that no one is currently using but that
>   *     may have a occupancy value > resctrl_rmid_realloc_threshold. User can
> @@ -46,7 +46,7 @@ static LIST_HEAD(rmid_free_lru);
>   */
>  static unsigned int rmid_limbo_count;
>  
> -/**
> +/*
>   * @rmid_entry - The entry in the limbo and free lists.
>   */
>  static struct rmid_entry	*rmid_ptrs;

Thank you very much.

I just have the comments regarding this area's customs. With that
addressed:

Reviewed-by: Reinette Chatre <reinette.chatre@...el.com>

Reinette