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

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

[Randy Dunlap]

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@infradead.org>
Reported-by: kernel test robot <lkp@intel.com>
Link: https://lore.kernel.org/all/202310062356.lX3xpLP9-lkp@intel.com/
Cc: Vikas Shivappa <vikas.shivappa@linux.intel.com>
Cc: Tony Luck <tony.luck@intel.com>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Fenghua Yu <fenghua.yu@intel.com>
Cc: Reinette Chatre <reinette.chatre@intel.com>
Cc: Ingo Molnar <mingo@redhat.com>
Cc: Borislav Petkov <bp@alien8.de>
Cc: Dave Hansen <dave.hansen@linux.intel.com>
Cc: x86@kernel.org
---
Not using Closes: since this patch only addresses some of the issues
  reported.

 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;

[tip: x86/urgent] x86/resctrl: Fix kernel-doc warnings

[tip-bot2 for Randy Dunlap]

The following commit has been merged into the x86/urgent branch of tip:

Commit-ID:     025d5ac978cc3b47874cc1c03ab096a78b49f278
Gitweb:        https://git.kernel.org/tip/025d5ac978cc3b47874cc1c03ab096a78b49f278
Author:        Randy Dunlap <rdunlap@infradead.org>
AuthorDate:    Fri, 06 Oct 2023 16:51:32 -07:00
Committer:     Ingo Molnar <mingo@kernel.org>
CommitterDate: Sun, 08 Oct 2023 11:45:16 +02:00

x86/resctrl: Fix kernel-doc warnings

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")
Reported-by: kernel test robot <lkp@intel.com>
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Link: https://lore.kernel.org/r/20231006235132.16227-1-rdunlap@infradead.org
---
 arch/x86/kernel/cpu/resctrl/monitor.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/arch/x86/kernel/cpu/resctrl/monitor.c b/arch/x86/kernel/cpu/resctrl/monitor.c
index ded1fc7..f136ac0 100644
--- 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;

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

[Reinette Chatre]

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@infradead.org>
> Reported-by: kernel test robot <lkp@intel.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@linux.intel.com>
> Cc: Tony Luck <tony.luck@intel.com>
> Cc: Thomas Gleixner <tglx@linutronix.de>
> Cc: Fenghua Yu <fenghua.yu@intel.com>
> Cc: Reinette Chatre <reinette.chatre@intel.com>
> Cc: Ingo Molnar <mingo@redhat.com>
> Cc: Borislav Petkov <bp@alien8.de>
> Cc: Dave Hansen <dave.hansen@linux.intel.com>
> Cc: x86@kernel.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@intel.com>

Reinette

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

[Reinette Chatre]

Hi Randy,

On 10/9/2023 10:07 AM, Reinette Chatre wrote:
> On 10/6/2023 4:51 PM, Randy Dunlap wrote:
>>
>> 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.
>>

I've been thinking more about this change and I would also
like to propose that you do not use "We" in the commit message.
I understand that you are not impersonating code but I think it
would be simpler to avoid any potential controversy by not using
"We". Perhaps something like "There is no syntax for documenting ...".

Reinette 

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

[Randy Dunlap]

On 10/9/23 10:07, Reinette Chatre wrote:
> 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@infradead.org>
>> Reported-by: kernel test robot <lkp@intel.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@linux.intel.com>
>> Cc: Tony Luck <tony.luck@intel.com>
>> Cc: Thomas Gleixner <tglx@linutronix.de>
>> Cc: Fenghua Yu <fenghua.yu@intel.com>
>> Cc: Reinette Chatre <reinette.chatre@intel.com>
>> Cc: Ingo Molnar <mingo@redhat.com>
>> Cc: Borislav Petkov <bp@alien8.de>
>> Cc: Dave Hansen <dave.hansen@linux.intel.com>
>> Cc: x86@kernel.org
>> ---
>> Not using Closes: since this patch only addresses some of the issues
>>   reported.

Hi Ingo,

Since you have already committed this patch, how would you like to handle
these requested changes?

The following commit has been merged into the x86/urgent branch of tip:

Commit-ID:     025d5ac978cc3b47874cc1c03ab096a78b49f278
Gitweb:        https://git.kernel.org/tip/025d5ac978cc3b47874cc1c03ab096a78b49f278
Author:        Randy Dunlap <rdunlap@infradead.org>
AuthorDate:    Fri, 06 Oct 2023 16:51:32 -07:00
Committer:     Ingo Molnar <mingo@kernel.org>
CommitterDate: Sun, 08 Oct 2023 11:45:16 +02:00

x86/resctrl: Fix kernel-doc warnings



Thanks.

> 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@intel.com>
> 
> Reinette

-- 
~Randy

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

[Reinette Chatre]

Hi Randy and Ingo,

On 10/10/2023 8:17 AM, Randy Dunlap wrote:
> 
> 
> On 10/9/23 10:07, Reinette Chatre wrote:
>> 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@infradead.org>
>>> Reported-by: kernel test robot <lkp@intel.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@linux.intel.com>
>>> Cc: Tony Luck <tony.luck@intel.com>
>>> Cc: Thomas Gleixner <tglx@linutronix.de>
>>> Cc: Fenghua Yu <fenghua.yu@intel.com>
>>> Cc: Reinette Chatre <reinette.chatre@intel.com>
>>> Cc: Ingo Molnar <mingo@redhat.com>
>>> Cc: Borislav Petkov <bp@alien8.de>
>>> Cc: Dave Hansen <dave.hansen@linux.intel.com>
>>> Cc: x86@kernel.org
>>> ---
>>> Not using Closes: since this patch only addresses some of the issues
>>>   reported.
> 
> Hi Ingo,
> 
> Since you have already committed this patch, how would you like to handle
> these requested changes?
> 

All my comments were related to my understanding of x86 customs with the goal
to make it acceptable to x86 maintainers. The change itself is good. If this
patch has already been merged by x86 maintainers then I surely will not object.

Reinette