[PATCH v4] x86/resctrl: Fix kernel-doc in pseudo_lock.c

[PATCH v4] x86/resctrl: Fix kernel-doc in pseudo_lock.c

[Fabio M. De Francesco]

Add undocumented parameters detected by scripts/kernel-doc.

Signed-off-by: Fabio M. De Francesco <fmdefrancesco@gmail.com>
---

v3->v4: Restore the description of a parameter to the original text
because it is preferred.
v2->v3: According to a second review by Reinette Chatre, drop many 
unrelated changes that should go in separate patches. Modify also the
patch log.
v1->v2: According to a first review by Reinette Chatre
<reinette.chatre@intel.com>, modify the 'Subject' to conform to x86
subsystem, modify a wrong description, and run 'scripts/kernel-doc'
to find out more warnings that 'sparse' didn't notice.

 arch/x86/kernel/cpu/resctrl/pseudo_lock.c | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/arch/x86/kernel/cpu/resctrl/pseudo_lock.c b/arch/x86/kernel/cpu/resctrl/pseudo_lock.c
index 05a89e33fde2..2207916cae65 100644
--- a/arch/x86/kernel/cpu/resctrl/pseudo_lock.c
+++ b/arch/x86/kernel/cpu/resctrl/pseudo_lock.c
@@ -49,6 +49,7 @@ static struct class *pseudo_lock_class;
 
 /**
  * get_prefetch_disable_bits - prefetch disable bits of supported platforms
+ * @void: It takes no parameters.
  *
  * Capture the list of platforms that have been validated to support
  * pseudo-locking. This includes testing to ensure pseudo-locked regions
@@ -162,7 +163,7 @@ static struct rdtgroup *region_find_by_minor(unsigned int minor)
 }
 
 /**
- * pseudo_lock_pm_req - A power management QoS request list entry
+ * struct pseudo_lock_pm_req - A power management QoS request list entry
  * @list:	Entry within the @pm_reqs list for a pseudo-locked region
  * @req:	PM QoS request
  */
@@ -184,6 +185,7 @@ static void pseudo_lock_cstates_relax(struct pseudo_lock_region *plr)
 
 /**
  * pseudo_lock_cstates_constrain - Restrict cores from entering C6
+ * @plr: Pseudo-locked region
  *
  * To prevent the cache from being affected by power management entering
  * C6 has to be avoided. This is accomplished by requesting a latency
@@ -196,6 +198,8 @@ static void pseudo_lock_cstates_relax(struct pseudo_lock_region *plr)
  * the ACPI latencies need to be considered while keeping in mind that C2
  * may be set to map to deeper sleep states. In this case the latency
  * requirement needs to prevent entering C2 also.
+ *
+ * Return: 0 on success, <0 on failure
  */
 static int pseudo_lock_cstates_constrain(struct pseudo_lock_region *plr)
 {
@@ -520,7 +524,7 @@ static int pseudo_lock_fn(void *_rdtgrp)
 
 /**
  * rdtgroup_monitor_in_progress - Test if monitoring in progress
- * @r: resource group being queried
+ * @rdtgrp: resource group being queried
  *
  * Return: 1 if monitor groups have been created for this resource
  * group, 0 otherwise.
@@ -1140,6 +1144,8 @@ static int measure_l3_residency(void *_plr)
 
 /**
  * pseudo_lock_measure_cycles - Trigger latency measure to pseudo-locked region
+ * @rdtgrp: Resource group to which the pseudo-locked region belongs.
+ * @sel: Selector of which measurement to perform on a pseudo-locked region.
  *
  * The measurement of latency to access a pseudo-locked region should be
  * done from a cpu that is associated with that pseudo-locked region.
-- 
2.32.0

Re: [PATCH v4] x86/resctrl: Fix kernel-doc in pseudo_lock.c

[Reinette Chatre]

Hi Fabio,

On 6/16/2021 11:15 AM, Fabio M. De Francesco wrote:
> Add undocumented parameters detected by scripts/kernel-doc.
> 
> Signed-off-by: Fabio M. De Francesco <fmdefrancesco@gmail.com>

Before this patch:
$ scripts/kernel-doc -none arch/x86/kernel/cpu/resctrl/pseudo_lock.c
arch/x86/kernel/cpu/resctrl/pseudo_lock.c:169: warning: cannot 
understand function prototype: 'struct pseudo_lock_pm_req '
arch/x86/kernel/cpu/resctrl/pseudo_lock.c:201: warning: Function 
parameter or member 'plr' not described in 'pseudo_lock_cstates_constrain'
arch/x86/kernel/cpu/resctrl/pseudo_lock.c:529: warning: Function 
parameter or member 'rdtgrp' not described in 'rdtgroup_monitor_in_progress'
arch/x86/kernel/cpu/resctrl/pseudo_lock.c:529: warning: Excess function 
parameter 'r' description in 'rdtgroup_monitor_in_progress'
arch/x86/kernel/cpu/resctrl/pseudo_lock.c:1152: warning: Function 
parameter or member 'rdtgrp' not described in 'pseudo_lock_measure_cycles'
arch/x86/kernel/cpu/resctrl/pseudo_lock.c:1152: warning: Function 
parameter or member 'sel' not described in 'pseudo_lock_measure_cycles'
$

After this patch:
$ scripts/kernel-doc -none arch/x86/kernel/cpu/resctrl/pseudo_lock.c
$

Thank you very much.

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

Reinette

[tip: x86/cache] x86/resctrl: Fix kernel-doc in pseudo_lock.c

[tip-bot2 for Fabio M. De Francesco]

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

Commit-ID:     f9b871c89ae61d5a4c0b81659fa6819c50d4ced2
Gitweb:        https://git.kernel.org/tip/f9b871c89ae61d5a4c0b81659fa6819c50d4ced2
Author:        Fabio M. De Francesco <fmdefrancesco@gmail.com>
AuthorDate:    Wed, 16 Jun 2021 20:15:30 +02:00
Committer:     Borislav Petkov <bp@suse.de>
CommitterDate: Thu, 24 Jun 2021 10:21:05 +02:00

x86/resctrl: Fix kernel-doc in pseudo_lock.c

Add undocumented parameters detected by scripts/kernel-doc.

Signed-off-by: Fabio M. De Francesco <fmdefrancesco@gmail.com>
Signed-off-by: Borislav Petkov <bp@suse.de>
Reviewed-by: Reinette Chatre <reinette.chatre@intel.com>
Link: https://lkml.kernel.org/r/20210616181530.4094-1-fmdefrancesco@gmail.com
---
 arch/x86/kernel/cpu/resctrl/pseudo_lock.c | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/arch/x86/kernel/cpu/resctrl/pseudo_lock.c b/arch/x86/kernel/cpu/resctrl/pseudo_lock.c
index 05a89e3..2207916 100644
--- a/arch/x86/kernel/cpu/resctrl/pseudo_lock.c
+++ b/arch/x86/kernel/cpu/resctrl/pseudo_lock.c
@@ -49,6 +49,7 @@ static struct class *pseudo_lock_class;
 
 /**
  * get_prefetch_disable_bits - prefetch disable bits of supported platforms
+ * @void: It takes no parameters.
  *
  * Capture the list of platforms that have been validated to support
  * pseudo-locking. This includes testing to ensure pseudo-locked regions
@@ -162,7 +163,7 @@ static struct rdtgroup *region_find_by_minor(unsigned int minor)
 }
 
 /**
- * pseudo_lock_pm_req - A power management QoS request list entry
+ * struct pseudo_lock_pm_req - A power management QoS request list entry
  * @list:	Entry within the @pm_reqs list for a pseudo-locked region
  * @req:	PM QoS request
  */
@@ -184,6 +185,7 @@ static void pseudo_lock_cstates_relax(struct pseudo_lock_region *plr)
 
 /**
  * pseudo_lock_cstates_constrain - Restrict cores from entering C6
+ * @plr: Pseudo-locked region
  *
  * To prevent the cache from being affected by power management entering
  * C6 has to be avoided. This is accomplished by requesting a latency
@@ -196,6 +198,8 @@ static void pseudo_lock_cstates_relax(struct pseudo_lock_region *plr)
  * the ACPI latencies need to be considered while keeping in mind that C2
  * may be set to map to deeper sleep states. In this case the latency
  * requirement needs to prevent entering C2 also.
+ *
+ * Return: 0 on success, <0 on failure
  */
 static int pseudo_lock_cstates_constrain(struct pseudo_lock_region *plr)
 {
@@ -520,7 +524,7 @@ static int pseudo_lock_fn(void *_rdtgrp)
 
 /**
  * rdtgroup_monitor_in_progress - Test if monitoring in progress
- * @r: resource group being queried
+ * @rdtgrp: resource group being queried
  *
  * Return: 1 if monitor groups have been created for this resource
  * group, 0 otherwise.
@@ -1140,6 +1144,8 @@ out:
 
 /**
  * pseudo_lock_measure_cycles - Trigger latency measure to pseudo-locked region
+ * @rdtgrp: Resource group to which the pseudo-locked region belongs.
+ * @sel: Selector of which measurement to perform on a pseudo-locked region.
  *
  * The measurement of latency to access a pseudo-locked region should be
  * done from a cpu that is associated with that pseudo-locked region.