Re: [PATCH V3 01/30] x86/sgx: Add short descriptions to ENCLS wrappers

[Jarkko Sakkinen <jarkko@kernel.org>]

On Mon, Apr 04, 2022 at 09:49:09AM -0700, Reinette Chatre wrote:
> The SGX ENCLS instruction uses EAX to specify an SGX function and
> may require additional registers, depending on the SGX function.
> ENCLS invokes the specified privileged SGX function for managing
> and debugging enclaves. Macros are used to wrap the ENCLS
> functionality and several wrappers are used to wrap the macros to
> make the different SGX functions accessible in the code.
> 
> The wrappers of the supported SGX functions are cryptic. Add short
> descriptions of each as a comment.
> 
> Suggested-by: Dave Hansen <dave.hansen@linux.intel.com>
> Signed-off-by: Reinette Chatre <reinette.chatre@intel.com>
> ---
> No changes since V2
> 
> Changes since V1:
> - Fix commit message and subject to not refer to descriptions as
> "changelog descriptions" or "shortlog descriptions" (Jarkko).
> - Improve all descriptions with guidance from Jarkko.
> 
>  arch/x86/kernel/cpu/sgx/encls.h | 15 +++++++++++++++
>  1 file changed, 15 insertions(+)
> 
> diff --git a/arch/x86/kernel/cpu/sgx/encls.h b/arch/x86/kernel/cpu/sgx/encls.h
> index fa04a73daf9c..0e22fa8f77c5 100644
> --- a/arch/x86/kernel/cpu/sgx/encls.h
> +++ b/arch/x86/kernel/cpu/sgx/encls.h
> @@ -136,57 +136,71 @@ static inline bool encls_failed(int ret)
>  	ret;						\
>  	})
>  
> +/* Initialize an EPC page into an SGX Enclave Control Structure (SECS) page. */
>  static inline int __ecreate(struct sgx_pageinfo *pginfo, void *secs)
>  {
>  	return __encls_2(ECREATE, pginfo, secs);
>  }
>  
> +/* Hash a 256 byte region of an enclave page to SECS:MRENCLAVE. */
>  static inline int __eextend(void *secs, void *addr)
>  {
>  	return __encls_2(EEXTEND, secs, addr);
>  }
>  
> +/*
> + * Associate an EPC page to an enclave either as a REG or TCS page
> + * populated with the provided data.
> + */
>  static inline int __eadd(struct sgx_pageinfo *pginfo, void *addr)
>  {
>  	return __encls_2(EADD, pginfo, addr);
>  }
>  
> +/* Finalize enclave build, initialize enclave for user code execution. */
>  static inline int __einit(void *sigstruct, void *token, void *secs)
>  {
>  	return __encls_ret_3(EINIT, sigstruct, secs, token);
>  }
>  
> +/* Disassociate EPC page from its enclave and mark it as unused. */
>  static inline int __eremove(void *addr)
>  {
>  	return __encls_ret_1(EREMOVE, addr);
>  }
>  
> +/* Copy data to an EPC page belonging to a debug enclave. */
>  static inline int __edbgwr(void *addr, unsigned long *data)
>  {
>  	return __encls_2(EDGBWR, *data, addr);
>  }
>  
> +/* Copy data from an EPC page belonging to a debug enclave. */
>  static inline int __edbgrd(void *addr, unsigned long *data)
>  {
>  	return __encls_1_1(EDGBRD, *data, addr);
>  }
>  
> +/* Track that software has completed the required TLB address clears. */
>  static inline int __etrack(void *addr)
>  {
>  	return __encls_ret_1(ETRACK, addr);
>  }
>  
> +/* Load, verify, and unblock an EPC page. */
>  static inline int __eldu(struct sgx_pageinfo *pginfo, void *addr,
>  			 void *va)
>  {
>  	return __encls_ret_3(ELDU, pginfo, addr, va);
>  }
>  
> +/* Make EPC page inaccessible to enclave, ready to be written to memory. */
>  static inline int __eblock(void *addr)
>  {
>  	return __encls_ret_1(EBLOCK, addr);
>  }
>  
> +/* Initialize an EPC page into a Version Array (VA) page. */
>  static inline int __epa(void *addr)
>  {
>  	unsigned long rbx = SGX_PAGE_TYPE_VA;
> @@ -194,6 +208,7 @@ static inline int __epa(void *addr)
>  	return __encls_2(EPA, rbx, addr);
>  }
>  
> +/* Invalidate an EPC page and write it out to main memory. */
>  static inline int __ewb(struct sgx_pageinfo *pginfo, void *addr,
>  			void *va)
>  {
> -- 
> 2.25.1
> 

Reviewed-by: Jarkko Sakkinen <jarkko@kernel.org>

BR, Jarkko