Add undocumented parameters detected by scripts/kernel-doc.
Signed-off-by: Fabio M. De Francesco <[email protected]>
---
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
<[email protected]>, 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 | 13 ++++++++++---
1 file changed, 10 insertions(+), 3 deletions(-)
diff --git a/arch/x86/kernel/cpu/resctrl/pseudo_lock.c b/arch/x86/kernel/cpu/resctrl/pseudo_lock.c
index 05a89e33fde2..84b9bf4daa33 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,8 +163,9 @@ static struct rdtgroup *region_find_by_minor(unsigned int minor)
}
/**
- * pseudo_lock_pm_req - A power management QoS request list entry
- * @list: Entry within the @pm_reqs list for a pseudo-locked region
+ * struct pseudo_lock_pm_req - A power management QoS request list entry
+ * @list: Entry within the power management requests list for a
+ * pseudo-locked region
* @req: PM QoS request
*/
struct pseudo_lock_pm_req {
@@ -184,6 +186,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 +199,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 +525,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 +1145,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
Hi Fabio,
On 6/14/2021 8:09 AM, Fabio M. De Francesco wrote:
> Add undocumented parameters detected by scripts/kernel-doc.
>
> Signed-off-by: Fabio M. De Francesco <[email protected]>
> ---
...
> diff --git a/arch/x86/kernel/cpu/resctrl/pseudo_lock.c b/arch/x86/kernel/cpu/resctrl/pseudo_lock.c
> index 05a89e33fde2..84b9bf4daa33 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,8 +163,9 @@ static struct rdtgroup *region_find_by_minor(unsigned int minor)
> }
>
> /**
> - * pseudo_lock_pm_req - A power management QoS request list entry
> - * @list: Entry within the @pm_reqs list for a pseudo-locked region
> + * struct pseudo_lock_pm_req - A power management QoS request list entry
> + * @list: Entry within the power management requests list for a
> + * pseudo-locked region
Adding "struct" is surely needed.
Regarding the description of list I prefer the original text. Consider
the scenario where somebody is trying to understand this code and using
a source code browser ... the original description would enable a direct
transition to where pm_reqs is defined with more descriptions and
context to understand the code.
> @@ -184,6 +186,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 +199,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 +525,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 +1145,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.
>
The rest looks good, thank you very much.
Reinette