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@xxxxxxxxx>
> ---
>  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@xxxxxxxxxxxxx>

> 
> 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)
>