Re: [PATCH v10 15/50] crypto: ccp: Provide API to issue SEV and SNP commands

[Borislav Petkov <bp@alien8.de>]

On Mon, Oct 16, 2023 at 08:27:44AM -0500, Michael Roth wrote:

> Subject: Re: [PATCH v10 15/50] crypto: ccp: Provide API to issue SEV and SNP commands

"...: Export sev_do_cmd() as a generic API..."

> From: Brijesh Singh <brijesh.singh@amd.com>
> 
> Make sev_do_cmd() a generic API interface for the hypervisor
> to issue commands to manage an SEV and SNP guest. The commands
> for SEV and SNP are defined in the SEV and SEV-SNP firmware
> specifications.
> 
> Signed-off-by: Brijesh Singh <brijesh.singh@amd.com>
> Signed-off-by: Ashish Kalra <ashish.kalra@amd.com>
> ---

...

> diff --git a/include/linux/psp-sev.h b/include/linux/psp-sev.h
> index a7f92e74564d..61bb5849ebf2 100644
> --- a/include/linux/psp-sev.h
> +++ b/include/linux/psp-sev.h
> @@ -883,6 +883,20 @@ int sev_guest_df_flush(int *error);
>   */
>  int sev_guest_decommission(struct sev_data_decommission *data, int *error);
>  
> +/**

See below for the output of

./scripts/kernel-doc -none include/linux/psp-sev.h

I understand that you want to kernel-doc stuff but you should do it
right.

> + * sev_do_cmd - perform SEV command

"Issue an SEV or an SEV-SNP command"

> + *
> + * @error: SEV command return code

That must be @psp_ret.

And to quote the abovementioned script:

include/linux/psp-sev.h:898: warning: Function parameter or member 'cmd' not described in 'sev_do_cmd'
include/linux/psp-sev.h:898: warning: Function parameter or member 'data' not described in 'sev_do_cmd'
include/linux/psp-sev.h:898: warning: Function parameter or member 'psp_ret' not described in 'sev_do_cmd'
include/linux/psp-sev.h:898: warning: Excess function parameter 'error' description in 'sev_do_cmd'

> + *
> + * Returns:
> + * 0 if the SEV successfully processed the command

"the SEV"?

You mean the "SEV device"?

> + * -%ENODEV    if the SEV device is not available
> + * -%ENOTSUPP  if the SEV does not support SEV
> + * -%ETIMEDOUT if the SEV command timed out
> + * -%EIO       if the SEV returned a non-zero return code
> + */
> +int sev_do_cmd(int cmd, void *data, int *psp_ret);
> +
>  void *psp_copy_user_blob(u64 uaddr, u32 len);
>  
>  #else	/* !CONFIG_CRYPTO_DEV_SP_PSP */
> @@ -898,6 +912,9 @@ sev_guest_deactivate(struct sev_data_deactivate *data, int *error) { return -ENO
>  static inline int
>  sev_guest_decommission(struct sev_data_decommission *data, int *error) { return -ENODEV; }
>  
> +static inline int
> +sev_do_cmd(int cmd, void *data, int *psp_ret) { return -ENODEV; }
> +
>  static inline int
>  sev_guest_activate(struct sev_data_activate *data, int *error) { return -ENODEV; }
>  

include/linux/psp-sev.h:20: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * SEV platform state
include/linux/psp-sev.h:31: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
 * SEV platform and guest management commands
include/linux/psp-sev.h:126: warning: Function parameter or member 'reserved' not described in 'sev_data_init'
include/linux/psp-sev.h:146: warning: Function parameter or member 'reserved' not described in 'sev_data_init_ex'
include/linux/psp-sev.h:175: warning: expecting prototype for struct sev_data_cert_import. Prototype was for struct sev_data_pek_cert_import instead
include/linux/psp-sev.h:212: warning: Function parameter or member 'pdh_cert_address' not described in 'sev_data_pdh_cert_export'
include/linux/psp-sev.h:212: warning: Function parameter or member 'pdh_cert_len' not described in 'sev_data_pdh_cert_export'
include/linux/psp-sev.h:212: warning: Function parameter or member 'reserved' not described in 'sev_data_pdh_cert_export'
include/linux/psp-sev.h:276: warning: Function parameter or member 'reserved' not described in 'sev_data_launch_start'
include/linux/psp-sev.h:290: warning: Function parameter or member 'reserved' not described in 'sev_data_launch_update_data'
include/linux/psp-sev.h:304: warning: Function parameter or member 'reserved' not described in 'sev_data_launch_update_vmsa'
include/linux/psp-sev.h:318: warning: Function parameter or member 'reserved' not described in 'sev_data_launch_measure'
include/linux/psp-sev.h:342: warning: Function parameter or member 'reserved1' not described in 'sev_data_launch_secret'
include/linux/psp-sev.h:342: warning: Function parameter or member 'reserved2' not described in 'sev_data_launch_secret'
include/linux/psp-sev.h:342: warning: Function parameter or member 'reserved3' not described in 'sev_data_launch_secret'
include/linux/psp-sev.h:381: warning: Function parameter or member 'reserved1' not described in 'sev_data_send_start'
include/linux/psp-sev.h:381: warning: Function parameter or member 'reserved2' not described in 'sev_data_send_start'
include/linux/psp-sev.h:381: warning: Function parameter or member 'reserved3' not described in 'sev_data_send_start'
include/linux/psp-sev.h:405: warning: expecting prototype for struct sev_data_send_update. Prototype was for struct sev_data_send_update_data instead
include/linux/psp-sev.h:428: warning: expecting prototype for struct sev_data_send_update. Prototype was for struct sev_data_send_update_vmsa instead
include/linux/psp-sev.h:465: warning: Function parameter or member 'policy' not described in 'sev_data_receive_start'
include/linux/psp-sev.h:465: warning: Function parameter or member 'reserved1' not described in 'sev_data_receive_start'
include/linux/psp-sev.h:489: warning: Function parameter or member 'reserved1' not described in 'sev_data_receive_update_data'
include/linux/psp-sev.h:489: warning: Function parameter or member 'reserved2' not described in 'sev_data_receive_update_data'
include/linux/psp-sev.h:489: warning: Function parameter or member 'reserved3' not described in 'sev_data_receive_update_data'
include/linux/psp-sev.h:513: warning: Function parameter or member 'reserved1' not described in 'sev_data_receive_update_vmsa'
include/linux/psp-sev.h:513: warning: Function parameter or member 'reserved2' not described in 'sev_data_receive_update_vmsa'
include/linux/psp-sev.h:513: warning: Function parameter or member 'reserved3' not described in 'sev_data_receive_update_vmsa'
include/linux/psp-sev.h:538: warning: Function parameter or member 'reserved' not described in 'sev_data_dbg'
include/linux/psp-sev.h:554: warning: Function parameter or member 'reserved' not described in 'sev_data_attestation_report'
include/linux/psp-sev.h:585: warning: Function parameter or member 'gctx_paddr' not described in 'sev_data_snp_addr'
include/linux/psp-sev.h:605: warning: Function parameter or member 'gctx_paddr' not described in 'sev_data_snp_launch_start'
include/linux/psp-sev.h:605: warning: Function parameter or member 'ma_gctx_paddr' not described in 'sev_data_snp_launch_start'
include/linux/psp-sev.h:605: warning: Function parameter or member 'rsvd' not described in 'sev_data_snp_launch_start'
include/linux/psp-sev.h:605: warning: Function parameter or member 'gosvw' not described in 'sev_data_snp_launch_start'
include/linux/psp-sev.h:644: warning: Function parameter or member 'gctx_paddr' not described in 'sev_data_snp_launch_update'
include/linux/psp-sev.h:644: warning: Function parameter or member 'rsvd' not described in 'sev_data_snp_launch_update'
include/linux/psp-sev.h:644: warning: Function parameter or member 'rsvd2' not described in 'sev_data_snp_launch_update'
include/linux/psp-sev.h:644: warning: Function parameter or member 'rsvd3' not described in 'sev_data_snp_launch_update'
include/linux/psp-sev.h:644: warning: Function parameter or member 'rsvd4' not described in 'sev_data_snp_launch_update'
include/linux/psp-sev.h:659: warning: Function parameter or member 'gctx_paddr' not described in 'sev_data_snp_launch_finish'
include/linux/psp-sev.h:659: warning: Function parameter or member 'id_block_paddr' not described in 'sev_data_snp_launch_finish'
include/linux/psp-sev.h:659: warning: Function parameter or member 'id_auth_paddr' not described in 'sev_data_snp_launch_finish'
include/linux/psp-sev.h:659: warning: Function parameter or member 'id_block_en' not described in 'sev_data_snp_launch_finish'
include/linux/psp-sev.h:659: warning: Function parameter or member 'auth_key_en' not described in 'sev_data_snp_launch_finish'
include/linux/psp-sev.h:659: warning: Function parameter or member 'rsvd' not described in 'sev_data_snp_launch_finish'
include/linux/psp-sev.h:659: warning: Function parameter or member 'host_data' not described in 'sev_data_snp_launch_finish'
include/linux/psp-sev.h:705: warning: expecting prototype for struct sev_data_dbg. Prototype was for struct sev_data_snp_dbg instead
include/linux/psp-sev.h:718: warning: expecting prototype for struct sev_snp_guest_request. Prototype was for struct sev_data_snp_guest_request instead
include/linux/psp-sev.h:734: warning: expecting prototype for struct sev_data_snp_init. Prototype was for struct sev_data_snp_init_ex instead
include/linux/psp-sev.h:746: warning: Function parameter or member 'rsvd' not described in 'sev_data_range'
include/linux/psp-sev.h:758: warning: Function parameter or member 'rsvd' not described in 'sev_data_range_list'
include/linux/psp-sev.h:770: warning: Function parameter or member 'rsvd1' not described in 'sev_data_snp_shutdown_ex'
include/linux/psp-sev.h:825: warning: Function parameter or member 'filep' not described in 'sev_issue_cmd_external_user'
include/linux/psp-sev.h:825: warning: Function parameter or member 'id' not described in 'sev_issue_cmd_external_user'
include/linux/psp-sev.h:825: warning: Function parameter or member 'data' not described in 'sev_issue_cmd_external_user'
include/linux/psp-sev.h:840: warning: Function parameter or member 'data' not described in 'sev_guest_deactivate'
include/linux/psp-sev.h:840: warning: Function parameter or member 'error' not described in 'sev_guest_deactivate'
include/linux/psp-sev.h:840: warning: Excess function parameter 'deactivate' description in 'sev_guest_deactivate'
include/linux/psp-sev.h:840: warning: Excess function parameter 'sev_ret' description in 'sev_guest_deactivate'
include/linux/psp-sev.h:855: warning: Function parameter or member 'data' not described in 'sev_guest_activate'
include/linux/psp-sev.h:855: warning: Function parameter or member 'error' not described in 'sev_guest_activate'
include/linux/psp-sev.h:855: warning: Excess function parameter 'activate' description in 'sev_guest_activate'
include/linux/psp-sev.h:855: warning: Excess function parameter 'sev_ret' description in 'sev_guest_activate'
include/linux/psp-sev.h:869: warning: Function parameter or member 'error' not described in 'sev_guest_df_flush'
include/linux/psp-sev.h:869: warning: Excess function parameter 'sev_ret' description in 'sev_guest_df_flush'
include/linux/psp-sev.h:884: warning: Function parameter or member 'data' not described in 'sev_guest_decommission'
include/linux/psp-sev.h:884: warning: Function parameter or member 'error' not described in 'sev_guest_decommission'
include/linux/psp-sev.h:884: warning: Excess function parameter 'decommission' description in 'sev_guest_decommission'
include/linux/psp-sev.h:884: warning: Excess function parameter 'sev_ret' description in 'sev_guest_decommission'
include/linux/psp-sev.h:898: warning: Function parameter or member 'cmd' not described in 'sev_do_cmd'
include/linux/psp-sev.h:898: warning: Function parameter or member 'data' not described in 'sev_do_cmd'
include/linux/psp-sev.h:898: warning: Function parameter or member 'psp_ret' not described in 'sev_do_cmd'
include/linux/psp-sev.h:898: warning: Excess function parameter 'error' description in 'sev_do_cmd'

-- 
Regards/Gruss,
    Boris.

https://people.kernel.org/tglx/notes-about-netiquette