Skip to contentSkip to conversation

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

PATCH Superseded Fabio M. De Francesco 2 participants 4 messages Jun 8, 2021 – Jun 15, 2021

Subsystems (2)

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

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

Added undocumented parameters, rewrote some phrases, and fixed some formatting issues. Most of the warnings detected by scripts/kernel-doc.

---

v1 -> v2: According to a first review by Reinette Chatre <[email protected]>, modified the 'Subject' to conform to x86 subsystem, modified 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 | 74 ++++++++++++-----------
 1 file changed, 39 insertions(+), 35 deletions(-)
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +39 -35
index 05a89e33fde2..7fb3998b1deb 100644
@@ -48,7 +48,8 @@ static unsigned long pseudo_lock_minor_avail = GENMASK(MINORBITS, 0);
 static struct class *pseudo_lock_class;
 
 /**
- * get_prefetch_disable_bits - prefetch disable bits of supported platforms
+ * 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
@@ -61,11 +62,10 @@ static struct class *pseudo_lock_class;
  * in the SDM.
  *
  * When adding a platform here also add support for its cache events to
- * measure_cycles_perf_fn()
+ * measure_cycles_perf_fn().
  *
- * Return:
- * If platform is supported, the bits to disable hardware prefetchers, 0
- * if platform is not supported.
+ * Return: The bits to disable hardware prefetchers, if platform is
+ * supported; 0, if it is not.
  */
 static u64 get_prefetch_disable_bits(void)
 {
@@ -126,7 +126,7 @@ static int pseudo_lock_minor_get(unsigned int *minor)
 }
 
 /**
- * pseudo_lock_minor_release - Return minor number to available
+ * pseudo_lock_minor_release - Set minor number to available
  * @minor: The minor number made available
  */
 static void pseudo_lock_minor_release(unsigned int minor)
@@ -135,7 +135,7 @@ static void pseudo_lock_minor_release(unsigned int minor)
 }
 
 /**
- * region_find_by_minor - Locate a pseudo-lock region by inode minor number
+ * region_find_by_minor - Locate a pseudo-locked region by inode minor number
  * @minor: The minor number of the device representing pseudo-locked region
  *
  * When the character device is accessed we need to determine which
@@ -146,7 +146,7 @@ static void pseudo_lock_minor_release(unsigned int minor)
  * with a cache instance.
  *
  * Return: On success return pointer to resource group owning the pseudo-locked
- *         region, NULL on failure.
+ * region, NULL on failure.
  */
 static struct rdtgroup *region_find_by_minor(unsigned int minor)
 {
@@ -162,9 +162,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
- * @req:	PM QoS request
+ * 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
  */
 struct pseudo_lock_pm_req {
 	struct list_head list;
@@ -184,6 +184,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 +197,9 @@ 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, -ENOMEM if there's not enough memory for data
+ * structure, otherwise -ENODEV or -EINVAL
  */
 static int pseudo_lock_cstates_constrain(struct pseudo_lock_region *plr)
 {
@@ -232,8 +236,8 @@ static int pseudo_lock_cstates_constrain(struct pseudo_lock_region *plr)
 }
 
 /**
- * pseudo_lock_region_clear - Reset pseudo-lock region data
- * @plr: pseudo-lock region
+ * pseudo_lock_region_clear - Reset pseudo-locked region data
+ * @plr: Pseudo-locked region
  *
  * All content of the pseudo-locked region is reset - any memory allocated
  * freed.
@@ -255,19 +259,19 @@ static void pseudo_lock_region_clear(struct pseudo_lock_region *plr)
 }
 
 /**
- * pseudo_lock_region_init - Initialize pseudo-lock region information
- * @plr: pseudo-lock region
+ * pseudo_lock_region_init - Initialize pseudo-locked region information
+ * @plr: Pseudo-locked region
  *
  * Called after user provided a schemata to be pseudo-locked. From the
  * schemata the &struct pseudo_lock_region is on entry already initialized
  * with the resource, domain, and capacity bitmask. Here the information
  * required for pseudo-locking is deduced from this data and &struct
  * pseudo_lock_region initialized further. This information includes:
- * - size in bytes of the region to be pseudo-locked
+ * - size in bytes of the region to be pseudo-locked;
  * - cache line size to know the stride with which data needs to be accessed
- *   to be pseudo-locked
+ *   to be pseudo-locked;
  * - a cpu associated with the cache instance on which the pseudo-locking
- *   flow can be executed
+ *   flow can be executed.
  *
  * Return: 0 on success, <0 on failure. Descriptive error will be written
  * to last_cmd_status buffer.
@@ -307,8 +311,8 @@ static int pseudo_lock_region_init(struct pseudo_lock_region *plr)
 }
 
 /**
- * pseudo_lock_init - Initialize a pseudo-lock region
- * @rdtgrp: resource group to which new pseudo-locked region will belong
+ * pseudo_lock_init - Initialize a pseudo-locked region
+ * @rdtgrp: Resource group to which a new pseudo-locked region will belong
  *
  * A pseudo-locked region is associated with a resource group. When this
  * association is created the pseudo-locked region is initialized. The
@@ -333,12 +337,12 @@ static int pseudo_lock_init(struct rdtgroup *rdtgrp)
 
 /**
  * pseudo_lock_region_alloc - Allocate kernel memory that will be pseudo-locked
- * @plr: pseudo-lock region
+ * @plr: Pseudo-locked region
  *
  * Initialize the details required to set up the pseudo-locked region and
  * allocate the contiguous memory that will be pseudo-locked to the cache.
  *
- * Return: 0 on success, <0 on failure.  Descriptive error will be written
+ * Return: 0 on success, <0 on failure. Descriptive error will be written
  * to last_cmd_status buffer.
  */
 static int pseudo_lock_region_alloc(struct pseudo_lock_region *plr)
@@ -376,13 +380,11 @@ static int pseudo_lock_region_alloc(struct pseudo_lock_region *plr)
 
 /**
  * pseudo_lock_free - Free a pseudo-locked region
- * @rdtgrp: resource group to which pseudo-locked region belonged
+ * @rdtgrp: Resource group to which pseudo-locked region belonged
  *
  * The pseudo-locked region's resources have already been released, or not
  * yet created at this point. Now it can be freed and disassociated from the
  * resource group.
- *
- * Return: void
  */
 static void pseudo_lock_free(struct rdtgroup *rdtgrp)
 {
@@ -393,7 +395,7 @@ static void pseudo_lock_free(struct rdtgroup *rdtgrp)
 
 /**
  * pseudo_lock_fn - Load kernel memory into cache
- * @_rdtgrp: resource group to which pseudo-lock region belongs
+ * @_rdtgrp: Resource group to which pseudo-locked region belongs
  *
  * This is the core pseudo-locking flow.
  *
@@ -401,7 +403,7 @@ static void pseudo_lock_free(struct rdtgroup *rdtgrp)
  * Then, while taking care that there will be as little interference as
  * possible, the memory to be loaded is accessed while core is running
  * with class of service set to the bitmask of the pseudo-locked region.
- * After this is complete no future CAT allocations will be allowed to
+ * After this is complete, no future CAT allocations will be allowed to
  * overlap with this bitmask.
  *
  * Local register variables are utilized to ensure that the memory region
@@ -520,7 +522,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.
@@ -532,7 +534,7 @@ static int rdtgroup_monitor_in_progress(struct rdtgroup *rdtgrp)
 
 /**
  * rdtgroup_locksetup_user_restrict - Restrict user access to group
- * @rdtgrp: resource group needing access restricted
+ * @rdtgrp: Resource group needing access restricted
  *
  * A resource group used for cache pseudo-locking cannot have cpus or tasks
  * assigned to it. This is communicated to the user by restricting access
@@ -582,7 +584,7 @@ static int rdtgroup_locksetup_user_restrict(struct rdtgroup *rdtgrp)
 
 /**
  * rdtgroup_locksetup_user_restore - Restore user access to group
- * @rdtgrp: resource group needing access restored
+ * @rdtgrp: Resource group needing access restored
  *
  * Restore all file access previously removed using
  * rdtgroup_locksetup_user_restrict()
@@ -629,7 +631,7 @@ static int rdtgroup_locksetup_user_restore(struct rdtgroup *rdtgrp)
 
 /**
  * rdtgroup_locksetup_enter - Resource group enters locksetup mode
- * @rdtgrp: resource group requested to enter locksetup mode
+ * @rdtgrp: Resource group requested to enter locksetup mode
  *
  * A resource group enters locksetup mode to reflect that it would be used
  * to represent a pseudo-locked region and is in the process of being set
@@ -744,8 +746,8 @@ int rdtgroup_locksetup_enter(struct rdtgroup *rdtgrp)
 }
 
 /**
- * rdtgroup_locksetup_exit - resource group exist locksetup mode
- * @rdtgrp: resource group
+ * rdtgroup_locksetup_exit - Resource group exits locksetup mode
+ * @rdtgrp: Resource group
  *
  * When a resource group exits locksetup mode the earlier restrictions are
  * lifted.
@@ -1140,6 +1142,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.
@@ -1254,7 +1258,7 @@ static const struct file_operations pseudo_measure_fops = {
 
 /**
  * rdtgroup_pseudo_lock_create - Create a pseudo-locked region
- * @rdtgrp: resource group to which pseudo-lock region belongs
+ * @rdtgrp: Resource group to which pseudo-locked region belongs
  *
  * Called when a resource group in the pseudo-locksetup mode receives a
  * valid schemata that should be pseudo-locked. Since the resource group is
@@ -1385,7 +1389,7 @@ int rdtgroup_pseudo_lock_create(struct rdtgroup *rdtgrp)
 
 /**
  * rdtgroup_pseudo_lock_remove - Remove a pseudo-locked region
- * @rdtgrp: resource group to which the pseudo-locked region belongs
+ * @rdtgrp: Resource group to which the pseudo-locked region belongs
  *
  * The removal of a pseudo-locked region can be initiated when the resource
  * group is removed from user space via a "rmdir" from userspace or the
Signature · 1 line
2.31.1
maintainer
#1 lore raw

Hi Fabio,

Quoted 2 lines · Fabio M. De Francesco

Added undocumented parameters, rewrote some phrases, and fixed some formatting issues. Most of the warnings detected by scripts/kernel-doc.

Please write commit message in imperative tone ... eg, "Add undocumented parameters ..."

Also, please refrain from making changes that are not related to the goal. The goal according to the subject of the patch is to fix kernel-doc issues - the "rewrote some phrases" is not related to this goal.

The "rewrote some phrases" really is not clear to me ... you do not mention this in your commit message but you seem to also capitalize each kernel-doc description? This is not a kernel-doc warning but something you chose to do. Please be specific in your commit message about any things that are not kernel-doc warnings that you do to warrant it to be classified as "Fix kernel-doc". For example, if indeed one of your goals are to capitalize all kernel-doc descriptions, add that as a goal to the commit log to help reader understand the changes. I think this will also help you to consider what is actually an issue and what is your preference.

When you say "Most of the warnings detected ... " - which warnings did it miss? How were other issues detected?

This patch is unclear regarding its goal - the subject and commit message indicate that this is about fixing kernel-doc issue while the patch does much more.

Quoted 16 lines

---

v1 -> v2: According to a first review by Reinette Chatre <[email protected]>, modified the 'Subject' to conform to x86 subsystem, modified 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 | 74 ++++++++++++-----------
  1 file changed, 39 insertions(+), 35 deletions(-)
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +0 -0
index 05a89e33fde2..7fb3998b1deb 100644

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static unsigned long pseudo_lock_minor_avail = GENMASK(MINORBITS, 0); · line 51

Quoted 5 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +1 -1
@@ -48,7 +48,8 @@ static unsigned long pseudo_lock_minor_avail = GENMASK(MINORBITS, 0);
  static struct class *pseudo_lock_class;
 
  /**
- * get_prefetch_disable_bits - prefetch disable bits of supported platforms
+ * get_prefetch_disable_bits - Prefetch disable bits of supported platforms

Did kernel-doc really complain about prefetch not being capitalized?

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static unsigned long pseudo_lock_minor_avail = GENMASK(MINORBITS, 0); · line 52

Quoted 1 line
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +1 -0
+ * @void: It takes no parameters.

ok, if this makes kernel-doc happy

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static struct class *pseudo_lock_class; · line 66

Quoted 10 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +1 -1
   *
   * Capture the list of platforms that have been validated to support
   * pseudo-locking. This includes testing to ensure pseudo-locked regions
@@ -61,11 +62,10 @@ static struct class *pseudo_lock_class;
   * in the SDM.
   *
   * When adding a platform here also add support for its cache events to
- * measure_cycles_perf_fn()
+ * measure_cycles_perf_fn().
   *

What kernel-doc problem is being fixed?

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static struct class *pseudo_lock_class; · line 68

Quoted 5 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +2 -3
- * Return:
- * If platform is supported, the bits to disable hardware prefetchers, 0
- * if platform is not supported.
+ * Return: The bits to disable hardware prefetchers, if platform is
+ * supported; 0, if it is not.

Did kernel-doc complain about this?

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static int pseudo_lock_minor_get(unsigned int *minor) · line 129

Quoted 9 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +1 -1
   */
  static u64 get_prefetch_disable_bits(void)
  {
@@ -126,7 +126,7 @@ static int pseudo_lock_minor_get(unsigned int *minor)
  }
 
  /**
- * pseudo_lock_minor_release - Return minor number to available
+ * pseudo_lock_minor_release - Set minor number to available

no. You may now verbatim document what the code does but you removed what it means when the code does that.

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static void pseudo_lock_minor_release(unsigned int minor) · line 138

Quoted 9 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +1 -1
   * @minor: The minor number made available
   */
  static void pseudo_lock_minor_release(unsigned int minor)
@@ -135,7 +135,7 @@ static void pseudo_lock_minor_release(unsigned int minor)
  }
 
  /**
- * region_find_by_minor - Locate a pseudo-lock region by inode minor number
+ * region_find_by_minor - Locate a pseudo-locked region by inode minor number

kernel-doc issue?

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static void pseudo_lock_minor_release(unsigned int minor) · line 149

Quoted 9 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +1 -1
   * @minor: The minor number of the device representing pseudo-locked region
   *
   * When the character device is accessed we need to determine which
@@ -146,7 +146,7 @@ static void pseudo_lock_minor_release(unsigned int minor)
   * with a cache instance.
   *
   * Return: On success return pointer to resource group owning the pseudo-locked
- *         region, NULL on failure.
+ * region, NULL on failure.

Please keep the spacing as it is.

Quoted 4 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +0 -0
   */
  static struct rdtgroup *region_find_by_minor(unsigned int minor)
  {

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static struct rdtgroup *region_find_by_minor(unsigned int minor) · line 168

Quoted 10 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +3 -3
@@ -162,9 +162,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
- * @req:	PM QoS request
+ * 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
   */

Only the missing "struct" is a kernel-doc issue?

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static void pseudo_lock_cstates_relax(struct pseudo_lock_region *plr) · line 188

Quoted 8 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +1 -0
  struct pseudo_lock_pm_req {
  	struct list_head list;
@@ -184,6 +184,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
   *

ok

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static void pseudo_lock_cstates_relax(struct pseudo_lock_region *plr) · line 202

Quoted 9 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +3 -0
   * 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 +197,9 @@ 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, -ENOMEM if there's not enough memory for data
+ * structure, otherwise -ENODEV or -EINVAL

This function passes some error codes through so being too specific may not be accurate when those functions change. You can follow the pattern in other functions like:

"Return: 0 on success, <0 on failure"

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static int pseudo_lock_cstates_constrain(struct pseudo_lock_region *plr) · line 241

Quoted 12 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +2 -2
   */
  static int pseudo_lock_cstates_constrain(struct pseudo_lock_region *plr)
  {
@@ -232,8 +236,8 @@ static int pseudo_lock_cstates_constrain(struct pseudo_lock_region *plr)
  }
 
  /**
- * pseudo_lock_region_clear - Reset pseudo-lock region data
- * @plr: pseudo-lock region
+ * pseudo_lock_region_clear - Reset pseudo-locked region data
+ * @plr: Pseudo-locked region
   *

No kernel-doc issue here?

Quoted 17 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +2 -3
   * All content of the pseudo-locked region is reset - any memory allocated
   * freed.
@@ -255,19 +259,19 @@ static void pseudo_lock_region_clear(struct pseudo_lock_region *plr)
  }
 
  /**
- * pseudo_lock_region_init - Initialize pseudo-lock region information
- * @plr: pseudo-lock region
+ * pseudo_lock_region_init - Initialize pseudo-locked region information
+ * @plr: Pseudo-locked region
   *
   * Called after user provided a schemata to be pseudo-locked. From the
   * schemata the &struct pseudo_lock_region is on entry already initialized
   * with the resource, domain, and capacity bitmask. Here the information
   * required for pseudo-locking is deduced from this data and &struct
   * pseudo_lock_region initialized further. This information includes:
- * - size in bytes of the region to be pseudo-locked

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static void pseudo_lock_region_clear(struct pseudo_lock_region *plr) · line 277

Quoted 10 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +3 -2
+ * - size in bytes of the region to be pseudo-locked;
   * - cache line size to know the stride with which data needs to be accessed
- *   to be pseudo-locked
+ *   to be pseudo-locked;
   * - a cpu associated with the cache instance on which the pseudo-locking
- *   flow can be executed
+ *   flow can be executed.
   *
   * Return: 0 on success, <0 on failure. Descriptive error will be written
   * to last_cmd_status buffer.

What kernel-doc issue is fixed in this snippet?

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static int pseudo_lock_region_init(struct pseudo_lock_region *plr) · line 318

Quoted 11 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +2 -2
@@ -307,8 +311,8 @@ static int pseudo_lock_region_init(struct pseudo_lock_region *plr)
  }
 
  /**
- * pseudo_lock_init - Initialize a pseudo-lock region
- * @rdtgrp: resource group to which new pseudo-locked region will belong
+ * pseudo_lock_init - Initialize a pseudo-locked region
+ * @rdtgrp: Resource group to which a new pseudo-locked region will belong
   *
   * A pseudo-locked region is associated with a resource group. When this
   * association is created the pseudo-locked region is initialized. The

same

Quoted 5 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +0 -1
@@ -333,12 +337,12 @@ static int pseudo_lock_init(struct rdtgroup *rdtgrp)
 
  /**
   * pseudo_lock_region_alloc - Allocate kernel memory that will be pseudo-locked
- * @plr: pseudo-lock region

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static int pseudo_lock_init(struct rdtgroup *rdtgrp) · line 348

Quoted 10 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +2 -1
+ * @plr: Pseudo-locked region
   *
   * Initialize the details required to set up the pseudo-locked region and
   * allocate the contiguous memory that will be pseudo-locked to the cache.
   *
- * Return: 0 on success, <0 on failure.  Descriptive error will be written
+ * Return: 0 on success, <0 on failure. Descriptive error will be written
   * to last_cmd_status buffer.
   */
  static int pseudo_lock_region_alloc(struct pseudo_lock_region *plr)

same

Quoted 5 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +0 -1
@@ -376,13 +380,11 @@ static int pseudo_lock_region_alloc(struct pseudo_lock_region *plr)
 
  /**
   * pseudo_lock_free - Free a pseudo-locked region
- * @rdtgrp: resource group to which pseudo-locked region belonged

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static int pseudo_lock_region_alloc(struct pseudo_lock_region *plr) · line 390

Quoted 10 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +1 -2
+ * @rdtgrp: Resource group to which pseudo-locked region belonged
   *
   * The pseudo-locked region's resources have already been released, or not
   * yet created at this point. Now it can be freed and disassociated from the
   * resource group.
- *
- * Return: void
   */
  static void pseudo_lock_free(struct rdtgroup *rdtgrp)
  {

same

Quoted 10 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +1 -1
@@ -393,7 +395,7 @@ static void pseudo_lock_free(struct rdtgroup *rdtgrp)
 
  /**
   * pseudo_lock_fn - Load kernel memory into cache
- * @_rdtgrp: resource group to which pseudo-lock region belongs
+ * @_rdtgrp: Resource group to which pseudo-locked region belongs
   *
   * This is the core pseudo-locking flow.
   *

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static void pseudo_lock_free(struct rdtgroup *rdtgrp) · line 409

Quoted 8 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +1 -1
@@ -401,7 +403,7 @@ static void pseudo_lock_free(struct rdtgroup *rdtgrp)
   * Then, while taking care that there will be as little interference as
   * possible, the memory to be loaded is accessed while core is running
   * with class of service set to the bitmask of the pseudo-locked region.
- * After this is complete no future CAT allocations will be allowed to
+ * After this is complete, no future CAT allocations will be allowed to
   * overlap with this bitmask.
   *
   * Local register variables are utilized to ensure that the memory region

same

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static int pseudo_lock_fn(void *_rdtgrp) · line 528

Quoted 9 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +1 -1
@@ -520,7 +522,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.

ok

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static int rdtgroup_monitor_in_progress(struct rdtgroup *rdtgrp) · line 540

Quoted 9 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +1 -1
@@ -532,7 +534,7 @@ static int rdtgroup_monitor_in_progress(struct rdtgroup *rdtgrp)
 
  /**
   * rdtgroup_locksetup_user_restrict - Restrict user access to group
- * @rdtgrp: resource group needing access restricted
+ * @rdtgrp: Resource group needing access restricted
   *
   * A resource group used for cache pseudo-locking cannot have cpus or tasks
   * assigned to it. This is communicated to the user by restricting access

same

Quoted 19 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +2 -2
@@ -582,7 +584,7 @@ static int rdtgroup_locksetup_user_restrict(struct rdtgroup *rdtgrp)
 
  /**
   * rdtgroup_locksetup_user_restore - Restore user access to group
- * @rdtgrp: resource group needing access restored
+ * @rdtgrp: Resource group needing access restored
   *
   * Restore all file access previously removed using
   * rdtgroup_locksetup_user_restrict()
@@ -629,7 +631,7 @@ static int rdtgroup_locksetup_user_restore(struct rdtgroup *rdtgrp)
 
  /**
   * rdtgroup_locksetup_enter - Resource group enters locksetup mode
- * @rdtgrp: resource group requested to enter locksetup mode
+ * @rdtgrp: Resource group requested to enter locksetup mode
   *
   * A resource group enters locksetup mode to reflect that it would be used
   * to represent a pseudo-locked region and is in the process of being set

arch/x86/kernel/cpu/resctrl/pseudo_lock.c int rdtgroup_locksetup_enter(struct rdtgroup *rdtgrp) · line 753

Quoted 10 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +2 -2
@@ -744,8 +746,8 @@ int rdtgroup_locksetup_enter(struct rdtgroup *rdtgrp)
  }
 
  /**
- * rdtgroup_locksetup_exit - resource group exist locksetup mode
- * @rdtgrp: resource group
+ * rdtgroup_locksetup_exit - Resource group exits locksetup mode
+ * @rdtgrp: Resource group
   *
   * When a resource group exits locksetup mode the earlier restrictions are
   * lifted.

same

arch/x86/kernel/cpu/resctrl/pseudo_lock.c static int measure_l3_residency(void *_plr) · line 1149

Quoted 9 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +2 -0
@@ -1140,6 +1142,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.

ok

Quoted 11 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +1 -1
@@ -1254,7 +1258,7 @@ static const struct file_operations pseudo_measure_fops = {
 
  /**
   * rdtgroup_pseudo_lock_create - Create a pseudo-locked region
- * @rdtgrp: resource group to which pseudo-lock region belongs
+ * @rdtgrp: Resource group to which pseudo-locked region belongs
   *
   * Called when a resource group in the pseudo-locksetup mode receives a
   * valid schemata that should be pseudo-locked. Since the resource group is

arch/x86/kernel/cpu/resctrl/pseudo_lock.c int rdtgroup_pseudo_lock_create(struct rdtgroup *rdtgrp) · line 1395

Quoted 8 lines
arch/x86/kernel/cpu/resctrl/pseudo_lock.c +1 -1
@@ -1385,7 +1389,7 @@ int rdtgroup_pseudo_lock_create(struct rdtgroup *rdtgrp)
 
  /**
   * rdtgroup_pseudo_lock_remove - Remove a pseudo-locked region
- * @rdtgrp: resource group to which the pseudo-locked region belongs
+ * @rdtgrp: Resource group to which the pseudo-locked region belongs
   *
   * The removal of a pseudo-locked region can be initiated when the resource
   * group is removed from user space via a "rmdir" from userspace or the

same

Reinette

#2 lore raw
Quoted 2 lines · CEST Reinette Chatre

Hi Fabio,

Hi Reinette,

Quoted 22 lines · Fabio M. De Francesco
Quoted 2 lines

Added undocumented parameters, rewrote some phrases, and fixed some formatting issues. Most of the warnings detected by scripts/kernel-doc.

Please write commit message in imperative tone ... eg, "Add undocumented parameters ..."

Also, please refrain from making changes that are not related to the goal. The goal according to the subject of the patch is to fix kernel-doc issues - the "rewrote some phrases" is not related to this goal.

The "rewrote some phrases" really is not clear to me ... you do not mention this in your commit message but you seem to also capitalize each kernel-doc description? This is not a kernel-doc warning but something you chose to do. Please be specific in your commit message about any things that are not kernel-doc warnings that you do to warrant it to be classified as "Fix kernel-doc". For example, if indeed one of your goals are to capitalize all kernel-doc descriptions, add that as a goal to the commit log to help reader understand the changes. I think this will also help you to consider what is actually an issue and what is your preference.

Quoted 7 lines

When you say "Most of the warnings detected ... " - which warnings did it miss? How were other issues detected?

This patch is unclear regarding its goal - the subject and commit message indicate that this is about fixing kernel-doc issue while the patch does much more.

I agree with you: I went too far and then I made changes that are not related to the goal as stated in the subject: "Fix kernel-doc issues". Obviously the same is valid for the patch to internal.h.

I've already removed everything from the pseudo_lock.c patch that should not be there and I'm about to send a new version. Soon after this one I'll also send a v2 patch to internal.h.

For what is related to style, if you agree with me, I'd like to have it
consistent: always capitalize the first word which describes a parameter, and always use consistent punctuation among different lines and comments, so I'd prepare a patch (or a series) to the files in resctrl. I could called them "Make consistent use of capitalization and punctuation". What about it?

I've also noticed some minor grammar issues (e.g., exist -> exits (in pseudo_lock.c, line 752 - pseudo-lock -> pseudo-locked in many other lines). What do you think if I make a "Fix English grammar" patch? So what about this other too?

[cut]

Thanks very much for your review,

Fabio

Quoted 2 lines

Reinette

maintainer
#3 lore raw

Hi Fabio

Quoted 5 lines · Fabio M. De Francesco

For what is related to style, if you agree with me, I'd like to have it
consistent: always capitalize the first word which describes a parameter, and always use consistent punctuation among different lines and comments, so I'd prepare a patch (or a series) to the files in resctrl. I could called them "Make consistent use of capitalization and punctuation". What about it?

While I surely would consider such a submission I wonder if your energy may not be better spent on other areas where there are higher priority work needed? What is your goal with this work? I understand that you are new to Linux kernel development and want to learn but it is not clear to me fixing capitalization and punctuation would be a good use of your energy.

Quoted 4 lines

I've also noticed some minor grammar issues (e.g., exist -> exits (in pseudo_lock.c, line 752 - pseudo-lock -> pseudo-locked in many other lines). What do you think if I make a "Fix English grammar" patch? So what about this other too?

This work would make the comments easier to read and a welcome addition. Please consider this a lower priority if you come across functional issues that could benefit your attention.

Thank you very much

Reinette