x86/resctrl: Fix kernel-doc in pseudo_lock.c
Subsystems (2)
PATCH v3 1/1 x86/resctrl: Fix kernel-doc in pseudo_lock.c
Add undocumented parameters detected by scripts/kernel-doc.
---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(-)
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +10 -3
@@ -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.
Signature · 1 line
2.32.0
Reinette Chatre
maintainerHi Fabio,
Quoted 4 lines · Fabio M. De Francesco
Add undocumented parameters detected by
scripts/kernel-doc.Signed-off-by Fabio M. De Francesco <[email protected]>---
...
Quoted 13 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +1
-0@@ -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
arch/x86/kernel/cpu/resctrl/pseudo_lock.c static struct rdtgroup *region_find_by_minor(unsigned int minor) · line 168
Quoted 8 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +3
-2@@ -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.
Quoted 28 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +4
-1@@ -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.
arch/x86/kernel/cpu/resctrl/pseudo_lock.c static int measure_l3_residency(void *_plr) · line 1152
Quoted 8 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +2
-0@@ -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