Skip to contentSkip to conversation

x86/resctrl: Fix kernel-doc in internal.h

PATCH Applied Fabio M. De Francesco 3 participants 3 messages Jun 18, 2021 – Jun 24, 2021

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH v4 1/1 x86/resctrl: Fix kernel-doc in internal.h

Add description of undocumented parameters. Issues detected by scripts/kernel-doc.

---

v3->v4: Make consistent use of spaces in the documentation of struct mon_data_bits.
v2->v3: Fix typo. Inherit the descriptions of membw and mbm_width from commit
https://lore.kernel.org/lkml/[email protected]/
to make it easier to merge both patches.
v1->v2: According to a first review by Reinette Chartre, remove changes unrelated to the subject of this patch and modify the descriptions of two parameters.

 arch/x86/kernel/cpu/resctrl/internal.h | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)
arch/x86/kernel/cpu/resctrl/internal.h +14 -7
index c4d320d02fd5..6a5f60a37219 100644
@@ -70,6 +70,7 @@ DECLARE_STATIC_KEY_FALSE(rdt_mon_enable_key);
  * struct mon_evt - Entry in the event list of a resource
  * @evtid:		event id
  * @name:		name of the event
+ * @list:		entry in &rdt_resource->evt_list
  */
 struct mon_evt {
 	u32			evtid;
@@ -78,10 +79,13 @@ struct mon_evt {
 };
 
 /**
- * struct mon_data_bits - Monitoring details for each event file
- * @rid:               Resource id associated with the event file.
+ * union mon_data_bits - Monitoring details for each event file
+ * @priv:              Used to store monitoring event data in @u
+ *                     as kernfs private data
+ * @rid:               Resource id associated with the event file
  * @evtid:             Event id associated with the event file
  * @domid:             The domain to which the event file belongs
+ * @u:                 Name of the bit fields struct
  */
 union mon_data_bits {
 	void *priv;
@@ -119,6 +123,7 @@ enum rdt_group_type {
  * @RDT_MODE_PSEUDO_LOCKSETUP: Resource group will be used for Pseudo-Locking
  * @RDT_MODE_PSEUDO_LOCKED: No sharing of this resource group's allocations
  *                          allowed AND the allocations are Cache Pseudo-Locked
+ * @RDT_NUM_MODES: Total number of modes
  *
  * The mode of a resource group enables control over the allowed overlap
  * between allocations associated with different resource groups (classes
@@ -142,7 +147,7 @@ enum rdtgrp_mode {
 
 /**
  * struct mongroup - store mon group's data in resctrl fs.
- * @mon_data_kn		kernlfs node for the mon_data directory
+ * @mon_data_kn:		kernfs node for the mon_data directory
  * @parent:			parent rdtgrp
  * @crdtgrp_list:		child rdtgroup node list
  * @rmid:			rmid for this rdtgroup
@@ -282,11 +287,11 @@ struct rftype {
 /**
  * struct mbm_state - status for each MBM counter in each domain
  * @chunks:	Total data moved (multiply by rdt_group.mon_scale to get bytes)
- * @prev_msr	Value of IA32_QM_CTR for this RMID last time we read it
+ * @prev_msr:	Value of IA32_QM_CTR for this RMID last time we read it
  * @prev_bw_msr:Value of previous IA32_QM_CTR for bandwidth counting
- * @prev_bw	The most recent bandwidth in MBps
- * @delta_bw	Difference between the current and previous bandwidth
- * @delta_comp	Indicates whether to compute the delta_bw
+ * @prev_bw:	The most recent bandwidth in MBps
+ * @delta_bw:	Difference between the current and previous bandwidth
+ * @delta_comp:	Indicates whether to compute the delta_bw
  */
 struct mbm_state {
 	u64	chunks;
@@ -456,11 +461,13 @@ struct rdt_parse_data {
  * @data_width:		Character width of data when displaying
  * @domains:		All domains for this resource
  * @cache:		Cache allocation related data
+ * @membw:		If the component has bandwidth controls, their properties.
  * @format_str:		Per resource format string to show domain value
  * @parse_ctrlval:	Per resource function pointer to parse control values
  * @evt_list:		List of monitoring events
  * @num_rmid:		Number of RMIDs available
  * @mon_scale:		cqm counter * mon_scale = occupancy in bytes
+ * @mbm_width:		Monitor width, to detect and correct for overflow.
  * @fflags:		flags to choose base and info files
  */
 struct rdt_resource {
Signature · 1 line
2.32.0
maintainer Reviewed-by on v4 1/1
#1 lore raw

Hi Fabio,

Quoted 5 lines · Fabio M. De Francesco

Add description of undocumented parameters. Issues detected by scripts/kernel-doc.

---

Before this patch:

$ scripts/kernel-doc -none arch/x86/kernel/cpu/resctrl/internal.h
arch/x86/kernel/cpu/resctrl/internal.h:78: warning: Function parameter or member 'list' not described in 'mon_evt'
arch/x86/kernel/cpu/resctrl/internal.h:93: warning: Function parameter or member 'priv' not described in 'mon_data_bits'
arch/x86/kernel/cpu/resctrl/internal.h:93: warning: Function parameter or member 'u' not described in 'mon_data_bits'
arch/x86/kernel/cpu/resctrl/internal.h:141: warning: Enum value 'RDT_NUM_MODES' not described in enum 'rdtgrp_mode'
arch/x86/kernel/cpu/resctrl/internal.h:155: warning: Function parameter or member 'mon_data_kn' not described in 'mongroup'
arch/x86/kernel/cpu/resctrl/internal.h:298: warning: Function parameter or member 'prev_msr' not described in 'mbm_state'
arch/x86/kernel/cpu/resctrl/internal.h:298: warning: Function parameter or member 'prev_bw' not described in 'mbm_state'
arch/x86/kernel/cpu/resctrl/internal.h:298: warning: Function parameter or member 'delta_bw' not described in 'mbm_state'
arch/x86/kernel/cpu/resctrl/internal.h:298: warning: Function parameter or member 'delta_comp' not described in 'mbm_state'
arch/x86/kernel/cpu/resctrl/internal.h:492: warning: Function parameter or member 'membw' not described in 'rdt_resource'
arch/x86/kernel/cpu/resctrl/internal.h:492: warning: Function parameter or member 'mbm_width' not described in 'rdt_resource'
$

After this patch:

$ scripts/kernel-doc -none arch/x86/kernel/cpu/resctrl/internal.h
$

Thank you very much.

Reinette

#2 lore raw
In reply to Fabio M. De Francesco
The following commit has been merged into the x86/cache branch of tip:

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

Commit-ID:     fd2afa70eff057fab57c9e06708b68677b261a0c
Gitweb:        https://git.kernel.org/tip/fd2afa70eff057fab57c9e06708b68677b261a0c
Author:        Fabio M. De Francesco <[email protected]>
AuthorDate:    Sat, 19 Jun 2021 00:32:06 +02:00
Committer:     Borislav Petkov <[email protected]>
CommitterDate: Thu, 24 Jun 2021 10:23:57 +02:00

x86/resctrl: Fix kernel-doc in internal.h

Add description of undocumented parameters. Issues detected by scripts/kernel-doc.

---
 arch/x86/kernel/cpu/resctrl/internal.h | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)
arch/x86/kernel/cpu/resctrl/internal.h +14 -7
index c4d320d..6a5f60a 100644
@@ -70,6 +70,7 @@ DECLARE_STATIC_KEY_FALSE(rdt_mon_enable_key);
  * struct mon_evt - Entry in the event list of a resource
  * @evtid:		event id
  * @name:		name of the event
+ * @list:		entry in &rdt_resource->evt_list
  */
 struct mon_evt {
 	u32			evtid;
@@ -78,10 +79,13 @@ struct mon_evt {
 };
 
 /**
- * struct mon_data_bits - Monitoring details for each event file
- * @rid:               Resource id associated with the event file.
+ * union mon_data_bits - Monitoring details for each event file
+ * @priv:              Used to store monitoring event data in @u
+ *                     as kernfs private data
+ * @rid:               Resource id associated with the event file
  * @evtid:             Event id associated with the event file
  * @domid:             The domain to which the event file belongs
+ * @u:                 Name of the bit fields struct
  */
 union mon_data_bits {
 	void *priv;
@@ -119,6 +123,7 @@ enum rdt_group_type {
  * @RDT_MODE_PSEUDO_LOCKSETUP: Resource group will be used for Pseudo-Locking
  * @RDT_MODE_PSEUDO_LOCKED: No sharing of this resource group's allocations
  *                          allowed AND the allocations are Cache Pseudo-Locked
+ * @RDT_NUM_MODES: Total number of modes
  *
  * The mode of a resource group enables control over the allowed overlap
  * between allocations associated with different resource groups (classes
@@ -142,7 +147,7 @@ enum rdtgrp_mode {
 
 /**
  * struct mongroup - store mon group's data in resctrl fs.
- * @mon_data_kn		kernlfs node for the mon_data directory
+ * @mon_data_kn:		kernfs node for the mon_data directory
  * @parent:			parent rdtgrp
  * @crdtgrp_list:		child rdtgroup node list
  * @rmid:			rmid for this rdtgroup
@@ -282,11 +287,11 @@ struct rftype {
 /**
  * struct mbm_state - status for each MBM counter in each domain
  * @chunks:	Total data moved (multiply by rdt_group.mon_scale to get bytes)
- * @prev_msr	Value of IA32_QM_CTR for this RMID last time we read it
+ * @prev_msr:	Value of IA32_QM_CTR for this RMID last time we read it
  * @prev_bw_msr:Value of previous IA32_QM_CTR for bandwidth counting
- * @prev_bw	The most recent bandwidth in MBps
- * @delta_bw	Difference between the current and previous bandwidth
- * @delta_comp	Indicates whether to compute the delta_bw
+ * @prev_bw:	The most recent bandwidth in MBps
+ * @delta_bw:	Difference between the current and previous bandwidth
+ * @delta_comp:	Indicates whether to compute the delta_bw
  */
 struct mbm_state {
 	u64	chunks;
@@ -456,11 +461,13 @@ struct rdt_parse_data {
  * @data_width:		Character width of data when displaying
  * @domains:		All domains for this resource
  * @cache:		Cache allocation related data
+ * @membw:		If the component has bandwidth controls, their properties.
  * @format_str:		Per resource format string to show domain value
  * @parse_ctrlval:	Per resource function pointer to parse control values
  * @evt_list:		List of monitoring events
  * @num_rmid:		Number of RMIDs available
  * @mon_scale:		cqm counter * mon_scale = occupancy in bytes
+ * @mbm_width:		Monitor width, to detect and correct for overflow.
  * @fflags:		flags to choose base and info files
  */
 struct rdt_resource {