[PATCH] KVM: PPC: Fix guest state buffer kernel-doc names and parameters

[PATCH] KVM: PPC: Fix guest state buffer kernel-doc names and parameters

[Karl Mehltretter]

Several guest state buffer comments use copied function or parameter
names. In particular, kvmppc_gsm_for_each() describes a parser and an
element argument, although it takes a message and yields IDs.
kvmppc_gsm_include_all() also describes an ID argument it does not take.

Match the headings and parameter descriptions to their declarations,
and describe the parser argument and vector output with their actual
roles.

Fixes: 6ccbbc33f06a ("KVM: PPC: Add helper library for Guest State Buffers")
Assisted-by: LLM
Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>
---
 arch/powerpc/include/asm/guest-state-buffer.h | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/arch/powerpc/include/asm/guest-state-buffer.h b/arch/powerpc/include/asm/guest-state-buffer.h
index acd61eb36d59..95d50ec7f2a9 100644
--- a/arch/powerpc/include/asm/guest-state-buffer.h
+++ b/arch/powerpc/include/asm/guest-state-buffer.h
@@ -224,7 +224,7 @@ struct kvmppc_gs_buff_info {
 
 /**
  * struct kvmppc_gs_header - serialized guest state buffer header
- * @nelem: count of guest state elements in the buffer
+ * @nelems: count of guest state elements in the buffer
  * @data: start of the stream of elements in the buffer
  */
 struct kvmppc_gs_header {
@@ -779,6 +779,7 @@ static inline u64 kvmppc_gse_get_u64(const struct kvmppc_gs_elem *gse)
 /**
  * kvmppc_gse_get_vector128() - return the data of a vector element
  * @gse: guest state element
+ * @v: output vector in host endianness
  */
 static inline void kvmppc_gse_get_vector128(const struct kvmppc_gs_elem *gse,
 					    vector128 *v)
@@ -849,7 +850,7 @@ struct kvmppc_gs_elem *kvmppc_gsp_lookup(struct kvmppc_gs_parser *gsp,
 /**
  * kvmppc_gsp_for_each - iterate the <guest state IDs, guest state element>
  * pairs
- * @gsp: guest state buffer bitmap
+ * @gsp: guest state parser
  * @iden: current guest state ID
  * @gse: guest state element
  */
@@ -866,9 +867,8 @@ struct kvmppc_gs_elem *kvmppc_gsp_lookup(struct kvmppc_gs_parser *gsp,
 /**
  * kvmppc_gsm_for_each - iterate the guest state IDs included in a guest state
  * message
- * @gsp: guest state buffer bitmap
+ * @gsm: guest state message
  * @iden: current guest state ID
- * @gse: guest state element
  */
 #define kvmppc_gsm_for_each(gsm, iden)                            \
 	for (iden = kvmppc_gsbm_next(&gsm->bitmap, 0); iden != 0; \
@@ -908,10 +908,9 @@ static inline bool kvmppc_gsm_includes(struct kvmppc_gs_msg *gsm, u16 iden)
 }
 
 /**
- * kvmppc_gsm_includes - indicate all guest state IDs should be included when
+ * kvmppc_gsm_include_all - indicate all guest state IDs should be included when
  * serializing
  * @gsm: guest state message
- * @iden: guest state ID
  */
 static inline void kvmppc_gsm_include_all(struct kvmppc_gs_msg *gsm)
 {
@@ -919,7 +918,7 @@ static inline void kvmppc_gsm_include_all(struct kvmppc_gs_msg *gsm)
 }
 
 /**
- * kvmppc_gsm_include - clear the guest state IDs that should be included when
+ * kvmppc_gsm_reset - clear the guest state IDs that should be included when
  * serializing
  * @gsm: guest state message
  */
@@ -958,7 +957,7 @@ static inline int kvmppc_gsb_receive_data(struct kvmppc_gs_buff *gsb,
 }
 
 /**
- * kvmppc_gsb_recv - receive a single guest state ID
+ * kvmppc_gsb_receive_datum - receive a single guest state ID
  * @gsb: guest state buffer
  * @gsm: guest state message
  * @iden: guest state identity
@@ -998,7 +997,7 @@ static inline int kvmppc_gsb_send_data(struct kvmppc_gs_buff *gsb,
 }
 
 /**
- * kvmppc_gsb_recv - send a single guest state ID
+ * kvmppc_gsb_send_datum - send a single guest state ID
  * @gsb: guest state buffer
  * @gsm: guest state message
  * @iden: guest state identity

base-commit: 50d05c7c76c96b90462f24debacca971d2e86713
-- 
2.39.5 (Apple Git-154)

Re: [PATCH] KVM: PPC: Fix guest state buffer kernel-doc names and parameters

[Gautam Menghani]

On Thu, Sep 10, 2026 at 05:36:55AM +0200, Karl Mehltretter wrote:
> Several guest state buffer comments use copied function or parameter
> names. In particular, kvmppc_gsm_for_each() describes a parser and an
> element argument, although it takes a message and yields IDs.
> kvmppc_gsm_include_all() also describes an ID argument it does not take.
> 
> Match the headings and parameter descriptions to their declarations,
> and describe the parser argument and vector output with their actual
> roles.
> 
> Fixes: 6ccbbc33f06a ("KVM: PPC: Add helper library for Guest State Buffers")
> Assisted-by: LLM
> Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>
> ---
>  arch/powerpc/include/asm/guest-state-buffer.h | 17 ++++++++---------
>  1 file changed, 8 insertions(+), 9 deletions(-)
> 
> diff --git a/arch/powerpc/include/asm/guest-state-buffer.h b/arch/powerpc/include/asm/guest-state-buffer.h
> index acd61eb36d59..95d50ec7f2a9 100644
> --- a/arch/powerpc/include/asm/guest-state-buffer.h
> +++ b/arch/powerpc/include/asm/guest-state-buffer.h
> @@ -224,7 +224,7 @@ struct kvmppc_gs_buff_info {
>  
>  /**
>   * struct kvmppc_gs_header - serialized guest state buffer header
> - * @nelem: count of guest state elements in the buffer
> + * @nelems: count of guest state elements in the buffer
>   * @data: start of the stream of elements in the buffer
>   */
>  struct kvmppc_gs_header {
> @@ -779,6 +779,7 @@ static inline u64 kvmppc_gse_get_u64(const struct kvmppc_gs_elem *gse)
>  /**
>   * kvmppc_gse_get_vector128() - return the data of a vector element
>   * @gse: guest state element
> + * @v: output vector in host endianness
>   */
>  static inline void kvmppc_gse_get_vector128(const struct kvmppc_gs_elem *gse,
>  					    vector128 *v)
> @@ -849,7 +850,7 @@ struct kvmppc_gs_elem *kvmppc_gsp_lookup(struct kvmppc_gs_parser *gsp,
>  /**
>   * kvmppc_gsp_for_each - iterate the <guest state IDs, guest state element>
>   * pairs
> - * @gsp: guest state buffer bitmap
> + * @gsp: guest state parser
>   * @iden: current guest state ID
>   * @gse: guest state element
>   */
> @@ -866,9 +867,8 @@ struct kvmppc_gs_elem *kvmppc_gsp_lookup(struct kvmppc_gs_parser *gsp,
>  /**
>   * kvmppc_gsm_for_each - iterate the guest state IDs included in a guest state
>   * message
> - * @gsp: guest state buffer bitmap
> + * @gsm: guest state message
>   * @iden: current guest state ID
> - * @gse: guest state element
>   */
>  #define kvmppc_gsm_for_each(gsm, iden)                            \
>  	for (iden = kvmppc_gsbm_next(&gsm->bitmap, 0); iden != 0; \
> @@ -908,10 +908,9 @@ static inline bool kvmppc_gsm_includes(struct kvmppc_gs_msg *gsm, u16 iden)
>  }
>  
>  /**
> - * kvmppc_gsm_includes - indicate all guest state IDs should be included when
> + * kvmppc_gsm_include_all - indicate all guest state IDs should be included when
>   * serializing
>   * @gsm: guest state message
> - * @iden: guest state ID
>   */
>  static inline void kvmppc_gsm_include_all(struct kvmppc_gs_msg *gsm)
>  {
> @@ -919,7 +918,7 @@ static inline void kvmppc_gsm_include_all(struct kvmppc_gs_msg *gsm)
>  }
>  
>  /**
> - * kvmppc_gsm_include - clear the guest state IDs that should be included when
> + * kvmppc_gsm_reset - clear the guest state IDs that should be included when
>   * serializing
>   * @gsm: guest state message
>   */
> @@ -958,7 +957,7 @@ static inline int kvmppc_gsb_receive_data(struct kvmppc_gs_buff *gsb,
>  }
>  
>  /**
> - * kvmppc_gsb_recv - receive a single guest state ID
> + * kvmppc_gsb_receive_datum - receive a single guest state ID
>   * @gsb: guest state buffer
>   * @gsm: guest state message
>   * @iden: guest state identity
> @@ -998,7 +997,7 @@ static inline int kvmppc_gsb_send_data(struct kvmppc_gs_buff *gsb,
>  }
>  
>  /**
> - * kvmppc_gsb_recv - send a single guest state ID
> + * kvmppc_gsb_send_datum - send a single guest state ID
>   * @gsb: guest state buffer
>   * @gsm: guest state message
>   * @iden: guest state identity
> 
> base-commit: 50d05c7c76c96b90462f24debacca971d2e86713
> -- 
> 2.39.5 (Apple Git-154)
> 
> 


Reviewed-by: Gautam Menghani <gautam@linux.ibm.com>

Re: [PATCH] KVM: PPC: Fix guest state buffer kernel-doc names and parameters

[Amit Machhiwal]

On 2026/09/10 05:36 AM, Karl Mehltretter wrote:
> Several guest state buffer comments use copied function or parameter
> names. In particular, kvmppc_gsm_for_each() describes a parser and an
> element argument, although it takes a message and yields IDs.
> kvmppc_gsm_include_all() also describes an ID argument it does not take.
> 
> Match the headings and parameter descriptions to their declarations,
> and describe the parser argument and vector output with their actual
> roles.
> 
> Fixes: 6ccbbc33f06a ("KVM: PPC: Add helper library for Guest State Buffers")
> Assisted-by: LLM
> Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>
> ---
>  arch/powerpc/include/asm/guest-state-buffer.h | 17 ++++++++---------
>  1 file changed, 8 insertions(+), 9 deletions(-)

The kernel-doc fixes are all accurate — heading names, parameter names, and
parameter lists now match their declarations. In particular, the
kvmppc_gsm_for_each / kvmppc_gsm_include_all / kvmppc_gsm_reset /
kvmppc_gsb_receive_datum / kvmppc_gsb_send_datum corrections are a clear
improvement over the copy-paste state left by the original commit.

Reviewed-by: Amit Machhiwal <amachhiw@linux.ibm.com>

> 
> diff --git a/arch/powerpc/include/asm/guest-state-buffer.h b/arch/powerpc/include/asm/guest-state-buffer.h
> index acd61eb36d59..95d50ec7f2a9 100644
> --- a/arch/powerpc/include/asm/guest-state-buffer.h
> +++ b/arch/powerpc/include/asm/guest-state-buffer.h
> @@ -224,7 +224,7 @@ struct kvmppc_gs_buff_info {
>  
>  /**
>   * struct kvmppc_gs_header - serialized guest state buffer header
> - * @nelem: count of guest state elements in the buffer
> + * @nelems: count of guest state elements in the buffer
>   * @data: start of the stream of elements in the buffer
>   */
>  struct kvmppc_gs_header {
> @@ -779,6 +779,7 @@ static inline u64 kvmppc_gse_get_u64(const struct kvmppc_gs_elem *gse)
>  /**
>   * kvmppc_gse_get_vector128() - return the data of a vector element
>   * @gse: guest state element
> + * @v: output vector in host endianness
>   */
>  static inline void kvmppc_gse_get_vector128(const struct kvmppc_gs_elem *gse,
>  					    vector128 *v)
> @@ -849,7 +850,7 @@ struct kvmppc_gs_elem *kvmppc_gsp_lookup(struct kvmppc_gs_parser *gsp,
>  /**
>   * kvmppc_gsp_for_each - iterate the <guest state IDs, guest state element>
>   * pairs
> - * @gsp: guest state buffer bitmap
> + * @gsp: guest state parser
>   * @iden: current guest state ID
>   * @gse: guest state element
>   */
> @@ -866,9 +867,8 @@ struct kvmppc_gs_elem *kvmppc_gsp_lookup(struct kvmppc_gs_parser *gsp,
>  /**
>   * kvmppc_gsm_for_each - iterate the guest state IDs included in a guest state
>   * message
> - * @gsp: guest state buffer bitmap
> + * @gsm: guest state message
>   * @iden: current guest state ID
> - * @gse: guest state element
>   */
>  #define kvmppc_gsm_for_each(gsm, iden)                            \
>  	for (iden = kvmppc_gsbm_next(&gsm->bitmap, 0); iden != 0; \
> @@ -908,10 +908,9 @@ static inline bool kvmppc_gsm_includes(struct kvmppc_gs_msg *gsm, u16 iden)
>  }
>  
>  /**
> - * kvmppc_gsm_includes - indicate all guest state IDs should be included when
> + * kvmppc_gsm_include_all - indicate all guest state IDs should be included when
>   * serializing
>   * @gsm: guest state message
> - * @iden: guest state ID
>   */
>  static inline void kvmppc_gsm_include_all(struct kvmppc_gs_msg *gsm)
>  {
> @@ -919,7 +918,7 @@ static inline void kvmppc_gsm_include_all(struct kvmppc_gs_msg *gsm)
>  }
>  
>  /**
> - * kvmppc_gsm_include - clear the guest state IDs that should be included when
> + * kvmppc_gsm_reset - clear the guest state IDs that should be included when
>   * serializing
>   * @gsm: guest state message
>   */
> @@ -958,7 +957,7 @@ static inline int kvmppc_gsb_receive_data(struct kvmppc_gs_buff *gsb,
>  }
>  
>  /**
> - * kvmppc_gsb_recv - receive a single guest state ID
> + * kvmppc_gsb_receive_datum - receive a single guest state ID
>   * @gsb: guest state buffer
>   * @gsm: guest state message
>   * @iden: guest state identity
> @@ -998,7 +997,7 @@ static inline int kvmppc_gsb_send_data(struct kvmppc_gs_buff *gsb,
>  }
>  
>  /**
> - * kvmppc_gsb_recv - send a single guest state ID
> + * kvmppc_gsb_send_datum - send a single guest state ID
>   * @gsb: guest state buffer
>   * @gsm: guest state message
>   * @iden: guest state identity
> 
> base-commit: 50d05c7c76c96b90462f24debacca971d2e86713
> -- 
> 2.39.5 (Apple Git-154)
>