[PATCH 0/5] x86/sgx: Fix kernel-doc warnings

[PATCH 0/5] x86/sgx: Fix kernel-doc warnings

[Sean Christopherson]

Fix a pile of kernel-doc warnings in the SGX code that have been hiding for
years, and were discovered after recent fix for "make htmldocs"[*].

Note, processing arch/x86/include/asm/sgx.h will still generate several
warnings, but nothing actually processes arch/x86/include/asm/sgx.h today,
and documenting a bunch of reserved fields seems to be counter-productive.
(I found and fixed a few asm/sgx.h issues because I included the header in
an .rst file to figure out why htmldocs warned about SGX_PAGE_MEASURE not
being documented, but not all the other enums that used the same syntax).

  WARNING: ./arch/x86/include/asm/sgx.h:193 struct member 'reserved1' not described in 'sgx_secs'
  WARNING: ./arch/x86/include/asm/sgx.h:193 struct member 'reserved2' not described in 'sgx_secs'
  WARNING: ./arch/x86/include/asm/sgx.h:193 struct member 'reserved3' not described in 'sgx_secs'
  WARNING: ./arch/x86/include/asm/sgx.h:193 struct member 'reserved4' not described in 'sgx_secs'
  WARNING: ./arch/x86/include/asm/sgx.h:243 struct member 'reserved' not described in 'sgx_tcs'
  WARNING: ./arch/x86/include/asm/sgx.h:319 struct member 'reserved' not described in 'sgx_secinfo'
  WARNING: ./arch/x86/include/asm/sgx.h:338 struct member 'secinfo' not described in 'sgx_pcmd'
  WARNING: ./arch/x86/include/asm/sgx.h:338 struct member 'reserved' not described in 'sgx_pcmd'
  WARNING: ./arch/x86/include/asm/sgx.h:360 struct member 'reserved1' not described in 'sgx_sigstruct_header'
  WARNING: ./arch/x86/include/asm/sgx.h:386 struct member 'reserved2' not described in 'sgx_sigstruct_body'
  WARNING: ./arch/x86/include/asm/sgx.h:386 struct member 'reserved3' not described in 'sgx_sigstruct_body'
  WARNING: ./arch/x86/include/asm/sgx.h:410 struct member 'reserved4' not described in 'sgx_sigstruct'

https://lore.kernel.org/all/20251104215502.1049817-1-andriy.shevchenko@linux.intel.com

Sean Christopherson (5):
  x86/sgx: Add a missing colon in kernel-doc markup for "struct
    sgx_enclave_run"
  x86/sgx: Add kernel-doc descriptions for params passed to vDSO user
    handler
  x86/sgx: Document structs and enums with '@', not '%'
  x86/sgx: Remove superfluous asterisk from copyright comment in
    asm/sgx.h
  x86/sgx: Fix a typo in the kernel-doc comment for enum sgx_attribute

 arch/x86/include/asm/sgx.h      | 64 ++++++++++++++++-----------------
 arch/x86/include/uapi/asm/sgx.h | 10 ++++--
 2 files changed, 40 insertions(+), 34 deletions(-)


base-commit: 19e2126bba55df9de15d9100b922df1dad6d39a4
-- 
2.51.2.1041.gc1ab5b90ca-goog

[PATCH 1/5] x86/sgx: Add a missing colon in kernel-doc markup for "struct sgx_enclave_run"

[Sean Christopherson]

Add a missing ':' for the description of sgx_enclave_run.reserved so that
documentation for the member is correctly generated:

  WARNING: arch/x86/include/uapi/asm/sgx.h:184 struct member 'reserved' not
  described in 'sgx_enclave_run'

Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Closes: https://lore.kernel.org/all/20251106145506.145fc620@canb.auug.org.au
Signed-off-by: Sean Christopherson <seanjc@google.com>
---
 arch/x86/include/uapi/asm/sgx.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/arch/x86/include/uapi/asm/sgx.h b/arch/x86/include/uapi/asm/sgx.h
index 2dd35bbdc822..a438ea43bfd1 100644
--- a/arch/x86/include/uapi/asm/sgx.h
+++ b/arch/x86/include/uapi/asm/sgx.h
@@ -166,7 +166,7 @@ typedef int (*sgx_enclave_user_handler_t)(long rdi, long rsi, long rdx,
  * @exception_addr:		The address that triggered the exception
  * @user_handler:		User provided callback run on exception
  * @user_data:			Data passed to the user handler
- * @reserved			Reserved for future extensions
+ * @reserved:			Reserved for future extensions
  *
  * If @user_handler is provided, the handler will be invoked on all return paths
  * of the normal flow.  The user handler may transfer control, e.g. via a
-- 
2.51.2.1041.gc1ab5b90ca-goog

[PATCH 2/5] x86/sgx: Add kernel-doc descriptions for params passed to vDSO user handler

[Sean Christopherson]

Add kernel-doc markup for the register parameters passed by the vDSO blob
to the user handler to suppress build warnings, e.g.

  WARNING: arch/x86/include/uapi/asm/sgx.h:157 function parameter 'r8' not
           described in 'sgx_enclave_user_handler_t'

Call out that except for RSP, the registers are undefined on asynchronous
exits as far as the vDSO ABI is concerned.  E.g. the vDSO's exception
handler clobbers RDX, RDI, and RSI, and the kernel doesn't guarantee that
R8 or R9 will be zero (the synthetic value loaded by the CPU).

Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Closes: https://lore.kernel.org/all/20251106145506.145fc620@canb.auug.org.au
Signed-off-by: Sean Christopherson <seanjc@google.com>
---
 arch/x86/include/uapi/asm/sgx.h | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/arch/x86/include/uapi/asm/sgx.h b/arch/x86/include/uapi/asm/sgx.h
index a438ea43bfd1..0d408f001ac6 100644
--- a/arch/x86/include/uapi/asm/sgx.h
+++ b/arch/x86/include/uapi/asm/sgx.h
@@ -143,6 +143,12 @@ struct sgx_enclave_run;
 /**
  * typedef sgx_enclave_user_handler_t - Exit handler function accepted by
  *					__vdso_sgx_enter_enclave()
+ * @rdi:	RDI at the time of EEXIT, undefined on AEX
+ * @rsi:	RSI at the time of EEXIT, undefined on AEX
+ * @rdx:	RDX at the time of EEXIT, undefined on AEX
+ * @rsp:	RSP (untrusted) at the time of EEXIT or AEX
+ * @r8:		R8 at the time of EEXIT, undefined on AEX
+ * @r9:		R9 at the time of EEXIT, undefined on AEX
  * @run:	The run instance given by the caller
  *
  * The register parameters contain the snapshot of their values at enclave
-- 
2.51.2.1041.gc1ab5b90ca-goog

[PATCH 3/5] x86/sgx: Document structs and enums with '@', not '%'

[Sean Christopherson]

Use '@' to document structure members and enum values in kernel-doc markup,
as per Documentation/doc-guide/kernel-doc.rst and flagged by make htmldocs.

  WARNING: arch/x86/include/uapi/asm/sgx.h:17 Enum value 'SGX_PAGE_MEASURE'
           not described in enum 'sgx_page_flags'

Opportunistically add a missing ':' for SGX_CHILD_PRESENT.

Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Closes: https://lore.kernel.org/all/20251106145506.145fc620@canb.auug.org.au
Signed-off-by: Sean Christopherson <seanjc@google.com>
---
 arch/x86/include/asm/sgx.h      | 60 ++++++++++++++++-----------------
 arch/x86/include/uapi/asm/sgx.h |  2 +-
 2 files changed, 31 insertions(+), 31 deletions(-)

diff --git a/arch/x86/include/asm/sgx.h b/arch/x86/include/asm/sgx.h
index c2c4c0d22ca4..a88c4ab95edd 100644
--- a/arch/x86/include/asm/sgx.h
+++ b/arch/x86/include/asm/sgx.h
@@ -66,19 +66,19 @@ enum sgx_encls_function {
 
 /**
  * enum sgx_return_code - The return code type for ENCLS, ENCLU and ENCLV
- * %SGX_EPC_PAGE_CONFLICT:	Page is being written by other ENCLS function.
- * %SGX_NOT_TRACKED:		Previous ETRACK's shootdown sequence has not
+ * @SGX_EPC_PAGE_CONFLICT:	Page is being written by other ENCLS function.
+ * @SGX_NOT_TRACKED:		Previous ETRACK's shootdown sequence has not
  *				been completed yet.
- * %SGX_CHILD_PRESENT		SECS has child pages present in the EPC.
- * %SGX_INVALID_EINITTOKEN:	EINITTOKEN is invalid and enclave signer's
+ * @SGX_CHILD_PRESENT:		SECS has child pages present in the EPC.
+ * @SGX_INVALID_EINITTOKEN:	EINITTOKEN is invalid and enclave signer's
  *				public key does not match IA32_SGXLEPUBKEYHASH.
- * %SGX_PAGE_NOT_MODIFIABLE:	The EPC page cannot be modified because it
+ * @SGX_PAGE_NOT_MODIFIABLE:	The EPC page cannot be modified because it
  *				is in the PENDING or MODIFIED state.
- * %SGX_INSUFFICIENT_ENTROPY:	Insufficient entropy in RNG.
- * %SGX_NO_UPDATE:		EUPDATESVN could not update the CPUSVN because the
+ * @SGX_INSUFFICIENT_ENTROPY:	Insufficient entropy in RNG.
+ * @SGX_NO_UPDATE:		EUPDATESVN could not update the CPUSVN because the
  *				current SVN was not newer than CPUSVN. This is the most
  *				common error code returned by EUPDATESVN.
- * %SGX_UNMASKED_EVENT:		An unmasked event, e.g. INTR, was received
+ * @SGX_UNMASKED_EVENT:		An unmasked event, e.g. INTR, was received
  */
 enum sgx_return_code {
 	SGX_EPC_PAGE_CONFLICT		= 7,
@@ -96,7 +96,7 @@ enum sgx_return_code {
 
 /**
  * enum sgx_miscselect - additional information to an SSA frame
- * %SGX_MISC_EXINFO:	Report #PF or #GP to the SSA frame.
+ * @SGX_MISC_EXINFO:	Report #PF or #GP to the SSA frame.
  *
  * Save State Area (SSA) is a stack inside the enclave used to store processor
  * state when an exception or interrupt occurs. This enum defines additional
@@ -113,16 +113,16 @@ enum sgx_miscselect {
 
 /**
  * enum sgx_attributes - the attributes field in &struct sgx_secs
- * %SGX_ATTR_INIT:		Enclave can be entered (is initialized).
- * %SGX_ATTR_DEBUG:		Allow ENCLS(EDBGRD) and ENCLS(EDBGWR).
- * %SGX_ATTR_MODE64BIT:		Tell that this a 64-bit enclave.
- * %SGX_ATTR_PROVISIONKEY:      Allow to use provisioning keys for remote
+ * @SGX_ATTR_INIT:		Enclave can be entered (is initialized).
+ * @SGX_ATTR_DEBUG:		Allow ENCLS(EDBGRD) and ENCLS(EDBGWR).
+ * @SGX_ATTR_MODE64BIT:		Tell that this a 64-bit enclave.
+ * @SGX_ATTR_PROVISIONKEY:      Allow to use provisioning keys for remote
  *				attestation.
- * %SGX_ATTR_KSS:		Allow to use key separation and sharing (KSS).
- * %SGX_ATTR_EINITTOKENKEY:	Allow to use token signing key that is used to
+ * @SGX_ATTR_KSS:		Allow to use key separation and sharing (KSS).
+ * @SGX_ATTR_EINITTOKENKEY:	Allow to use token signing key that is used to
  *				sign cryptographic tokens that can be passed to
  *				EINIT as an authorization to run an enclave.
- * %SGX_ATTR_ASYNC_EXIT_NOTIFY:	Allow enclaves to be notified after an
+ * @SGX_ATTR_ASYNC_EXIT_NOTIFY:	Allow enclaves to be notified after an
  *				asynchronous exit has occurred.
  */
 enum sgx_attribute {
@@ -195,7 +195,7 @@ struct sgx_secs {
 
 /**
  * enum sgx_tcs_flags - execution flags for TCS
- * %SGX_TCS_DBGOPTIN:	If enabled allows single-stepping and breakpoints
+ * @SGX_TCS_DBGOPTIN:	If enabled allows single-stepping and breakpoints
  *			inside an enclave. It is cleared by EADD but can
  *			be set later with EDBGWR.
  */
@@ -260,11 +260,11 @@ struct sgx_pageinfo {
 
 /**
  * enum sgx_page_type - bits in the SECINFO flags defining the page type
- * %SGX_PAGE_TYPE_SECS:	a SECS page
- * %SGX_PAGE_TYPE_TCS:	a TCS page
- * %SGX_PAGE_TYPE_REG:	a regular page
- * %SGX_PAGE_TYPE_VA:	a VA page
- * %SGX_PAGE_TYPE_TRIM:	a page in trimmed state
+ * @SGX_PAGE_TYPE_SECS:	a SECS page
+ * @SGX_PAGE_TYPE_TCS:	a TCS page
+ * @SGX_PAGE_TYPE_REG:	a regular page
+ * @SGX_PAGE_TYPE_VA:	a VA page
+ * @SGX_PAGE_TYPE_TRIM:	a page in trimmed state
  *
  * Make sure when making changes to this enum that its values can still fit
  * in the bitfield within &struct sgx_encl_page
@@ -282,14 +282,14 @@ enum sgx_page_type {
 
 /**
  * enum sgx_secinfo_flags - the flags field in &struct sgx_secinfo
- * %SGX_SECINFO_R:	allow read
- * %SGX_SECINFO_W:	allow write
- * %SGX_SECINFO_X:	allow execution
- * %SGX_SECINFO_SECS:	a SECS page
- * %SGX_SECINFO_TCS:	a TCS page
- * %SGX_SECINFO_REG:	a regular page
- * %SGX_SECINFO_VA:	a VA page
- * %SGX_SECINFO_TRIM:	a page in trimmed state
+ * @SGX_SECINFO_R:	allow read
+ * @SGX_SECINFO_W:	allow write
+ * @SGX_SECINFO_X:	allow execution
+ * @SGX_SECINFO_SECS:	a SECS page
+ * @SGX_SECINFO_TCS:	a TCS page
+ * @SGX_SECINFO_REG:	a regular page
+ * @SGX_SECINFO_VA:	a VA page
+ * @SGX_SECINFO_TRIM:	a page in trimmed state
  */
 enum sgx_secinfo_flags {
 	SGX_SECINFO_R			= BIT(0),
diff --git a/arch/x86/include/uapi/asm/sgx.h b/arch/x86/include/uapi/asm/sgx.h
index 0d408f001ac6..3c4d52072189 100644
--- a/arch/x86/include/uapi/asm/sgx.h
+++ b/arch/x86/include/uapi/asm/sgx.h
@@ -10,7 +10,7 @@
 
 /**
  * enum sgx_page_flags - page control flags
- * %SGX_PAGE_MEASURE:	Measure the page contents with a sequence of
+ * @SGX_PAGE_MEASURE:	Measure the page contents with a sequence of
  *			ENCLS[EEXTEND] operations.
  */
 enum sgx_page_flags {
-- 
2.51.2.1041.gc1ab5b90ca-goog

[PATCH 4/5] x86/sgx: Remove superfluous asterisk from copyright comment in asm/sgx.h

[Sean Christopherson]

Drop an asterisk from a file-level copyright comment so that the comment
isn't intrepeted as a kernel-doc comment.

E.g. if arch/x86/include/asm/sgx.h is fed into kernel-doc processing:

  WARNING: ./arch/x86/include/asm/sgx.h:2 This comment starts with '/**',
  but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst

Signed-off-by: Sean Christopherson <seanjc@google.com>
---
 arch/x86/include/asm/sgx.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/arch/x86/include/asm/sgx.h b/arch/x86/include/asm/sgx.h
index a88c4ab95edd..3c90cae04e1d 100644
--- a/arch/x86/include/asm/sgx.h
+++ b/arch/x86/include/asm/sgx.h
@@ -1,5 +1,5 @@
 /* SPDX-License-Identifier: GPL-2.0 */
-/**
+/*
  * Copyright(c) 2016-20 Intel Corporation.
  *
  * Intel Software Guard Extensions (SGX) support.
-- 
2.51.2.1041.gc1ab5b90ca-goog

[PATCH 5/5] x86/sgx: Fix a typo in the kernel-doc comment for enum sgx_attribute

[Sean Christopherson]

Use the exact enum name when documenting "enum sgx_attribute" to fix a
warning if the file is fed into kernel-doc processing:

  WARNING: ./arch/x86/include/asm/sgx.h:139 expecting prototype for enum
           sgx_attributes. Prototype was for enum sgx_attribute instead

Signed-off-by: Sean Christopherson <seanjc@google.com>
---
 arch/x86/include/asm/sgx.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/arch/x86/include/asm/sgx.h b/arch/x86/include/asm/sgx.h
index 3c90cae04e1d..04958459a7ca 100644
--- a/arch/x86/include/asm/sgx.h
+++ b/arch/x86/include/asm/sgx.h
@@ -112,7 +112,7 @@ enum sgx_miscselect {
 #define SGX_SSA_MISC_EXINFO_SIZE	16
 
 /**
- * enum sgx_attributes - the attributes field in &struct sgx_secs
+ * enum sgx_attribute - the attributes field in &struct sgx_secs
  * @SGX_ATTR_INIT:		Enclave can be entered (is initialized).
  * @SGX_ATTR_DEBUG:		Allow ENCLS(EDBGRD) and ENCLS(EDBGWR).
  * @SGX_ATTR_MODE64BIT:		Tell that this a 64-bit enclave.
-- 
2.51.2.1041.gc1ab5b90ca-goog

Re: [PATCH 4/5] x86/sgx: Remove superfluous asterisk from copyright comment in asm/sgx.h

[Huang, Kai]

On Wed, 2025-11-12 at 08:07 -0800, Sean Christopherson wrote:
> Drop an asterisk from a file-level copyright comment so that the comment
> isn't intrepeted as a kernel-doc comment.
	^
	interpreted

Re: [PATCH 2/5] x86/sgx: Add kernel-doc descriptions for params passed to vDSO user handler

[Huang, Kai]

On Wed, 2025-11-12 at 08:07 -0800, Sean Christopherson wrote:
> Add kernel-doc markup for the register parameters passed by the vDSO blob
> to the user handler to suppress build warnings, e.g.
> 
>   WARNING: arch/x86/include/uapi/asm/sgx.h:157 function parameter 'r8' not
>            described in 'sgx_enclave_user_handler_t'
> 
> Call out that except for RSP, the registers are undefined on asynchronous
> exits as far as the vDSO ABI is concerned.  E.g. the vDSO's exception
> handler clobbers RDX, RDI, and RSI, and the kernel doesn't guarantee that
> R8 or R9 will be zero (the synthetic value loaded by the CPU).

Perhaps a nit:

I am not that familiar with this part, but AFAICT the kernel always sets
RDI/RSI/RDX to exception vector/error code/addr before invoking the user
handler, after the vDSO's exception handler clobbers them.

Since you are adding description to them, should we somehow call this out in
the comment, if I didn't miss anything?

> 
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Closes: https://lore.kernel.org/all/20251106145506.145fc620@canb.auug.org.au
> Signed-off-by: Sean Christopherson <seanjc@google.com>
> ---
>  arch/x86/include/uapi/asm/sgx.h | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/arch/x86/include/uapi/asm/sgx.h b/arch/x86/include/uapi/asm/sgx.h
> index a438ea43bfd1..0d408f001ac6 100644
> --- a/arch/x86/include/uapi/asm/sgx.h
> +++ b/arch/x86/include/uapi/asm/sgx.h
> @@ -143,6 +143,12 @@ struct sgx_enclave_run;
>  /**
>   * typedef sgx_enclave_user_handler_t - Exit handler function accepted by
>   *					__vdso_sgx_enter_enclave()
> + * @rdi:	RDI at the time of EEXIT, undefined on AEX
> + * @rsi:	RSI at the time of EEXIT, undefined on AEX
> + * @rdx:	RDX at the time of EEXIT, undefined on AEX
> + * @rsp:	RSP (untrusted) at the time of EEXIT or AEX
> + * @r8:		R8 at the time of EEXIT, undefined on AEX
> + * @r9:		R9 at the time of EEXIT, undefined on AEX
>   * @run:	The run instance given by the caller
>   *
>   * The register parameters contain the snapshot of their values at enclave

Re: [PATCH 0/5] x86/sgx: Fix kernel-doc warnings

[Huang, Kai]

On Wed, 2025-11-12 at 08:07 -0800, Sean Christopherson wrote:
> Fix a pile of kernel-doc warnings in the SGX code that have been hiding for
> years, and were discovered after recent fix for "make htmldocs"[*].
> 

For this series,

Reviewed-by: Kai Huang <kai.huang@intel.com>

Re: [PATCH 2/5] x86/sgx: Add kernel-doc descriptions for params passed to vDSO user handler

[Sean Christopherson]

On Thu, Nov 13, 2025, Kai Huang wrote:
> On Wed, 2025-11-12 at 08:07 -0800, Sean Christopherson wrote:
> > Add kernel-doc markup for the register parameters passed by the vDSO blob
> > to the user handler to suppress build warnings, e.g.
> > 
> >   WARNING: arch/x86/include/uapi/asm/sgx.h:157 function parameter 'r8' not
> >            described in 'sgx_enclave_user_handler_t'
> > 
> > Call out that except for RSP, the registers are undefined on asynchronous
> > exits as far as the vDSO ABI is concerned.  E.g. the vDSO's exception
> > handler clobbers RDX, RDI, and RSI, and the kernel doesn't guarantee that
> > R8 or R9 will be zero (the synthetic value loaded by the CPU).
> 
> Perhaps a nit:
> 
> I am not that familiar with this part, but AFAICT the kernel always sets
> RDI/RSI/RDX to exception vector/error code/addr before invoking the user
> handler, after the vDSO's exception handler clobbers them.
> 
> Since you are adding description to them, should we somehow call this out in
> the comment, if I didn't miss anything?

I don't think we want to commit to that as ABI for the vDSO interface, which is
why I documented the values as being "undefined".  Maybe were already stuck with
that ABI, e.g. if some funky userspace is looking at the register params instead
of its run structure, but IMO we should at least discourage relying on the values.

E.g. if the kernel ever changed its exception fixup to use different registers,
then RDI/RSI/RDX might not hold the same values.  In hindsight, we probably should
have scrambled those registers after propagating the exception information to the
run structure.

RE: [PATCH 2/5] x86/sgx: Add kernel-doc descriptions for params passed to vDSO user handler

[Huang, Kai]

> > > Call out that except for RSP, the registers are undefined on
> > > asynchronous exits as far as the vDSO ABI is concerned.  E.g. the
> > > vDSO's exception handler clobbers RDX, RDI, and RSI, and the kernel
> > > doesn't guarantee that
> > > R8 or R9 will be zero (the synthetic value loaded by the CPU).
> >
> > Perhaps a nit:
> >
> > I am not that familiar with this part, but AFAICT the kernel always
> > sets RDI/RSI/RDX to exception vector/error code/addr before invoking
> > the user handler, after the vDSO's exception handler clobbers them.
> >
> > Since you are adding description to them, should we somehow call this
> > out in the comment, if I didn't miss anything?
> 
> I don't think we want to commit to that as ABI for the vDSO interface, which is
> why I documented the values as being "undefined".  Maybe were already stuck
> with that ABI, e.g. if some funky userspace is looking at the register params
> instead of its run structure, but IMO we should at least discourage relying on the
> values.
> 
> E.g. if the kernel ever changed its exception fixup to use different registers, then
> RDI/RSI/RDX might not hold the same values.  In hindsight, we probably should
> have scrambled those registers after propagating the exception information to the
> run structure.

Yeah makes sense to me.  Thanks for explaining. 

Re: [PATCH 0/5] x86/sgx: Fix kernel-doc warnings

[Dave Hansen]

On 11/12/25 08:07, Sean Christopherson wrote:
> Fix a pile of kernel-doc warnings in the SGX code that have been hiding for
> years, and were discovered after recent fix for "make htmldocs"[*].

Thanks for these! I've applied them to x86/sgx.

Re: [PATCH 1/5] x86/sgx: Add a missing colon in kernel-doc markup for "struct sgx_enclave_run"

[Jarkko Sakkinen]

On Wed, Nov 12, 2025 at 08:07:04AM -0800, Sean Christopherson wrote:
> Add a missing ':' for the description of sgx_enclave_run.reserved so that
> documentation for the member is correctly generated:
> 
>   WARNING: arch/x86/include/uapi/asm/sgx.h:184 struct member 'reserved' not
>   described in 'sgx_enclave_run'
> 
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Closes: https://lore.kernel.org/all/20251106145506.145fc620@canb.auug.org.au
> Signed-off-by: Sean Christopherson <seanjc@google.com>
> ---
>  arch/x86/include/uapi/asm/sgx.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/arch/x86/include/uapi/asm/sgx.h b/arch/x86/include/uapi/asm/sgx.h
> index 2dd35bbdc822..a438ea43bfd1 100644
> --- a/arch/x86/include/uapi/asm/sgx.h
> +++ b/arch/x86/include/uapi/asm/sgx.h
> @@ -166,7 +166,7 @@ typedef int (*sgx_enclave_user_handler_t)(long rdi, long rsi, long rdx,
>   * @exception_addr:		The address that triggered the exception
>   * @user_handler:		User provided callback run on exception
>   * @user_data:			Data passed to the user handler
> - * @reserved			Reserved for future extensions
> + * @reserved:			Reserved for future extensions
>   *
>   * If @user_handler is provided, the handler will be invoked on all return paths
>   * of the normal flow.  The user handler may transfer control, e.g. via a
> -- 
> 2.51.2.1041.gc1ab5b90ca-goog
> 

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

BR, Jarkko

Re: [PATCH 2/5] x86/sgx: Add kernel-doc descriptions for params passed to vDSO user handler

[Jarkko Sakkinen]

On Wed, Nov 12, 2025 at 08:07:05AM -0800, Sean Christopherson wrote:
> Add kernel-doc markup for the register parameters passed by the vDSO blob
> to the user handler to suppress build warnings, e.g.
> 
>   WARNING: arch/x86/include/uapi/asm/sgx.h:157 function parameter 'r8' not
>            described in 'sgx_enclave_user_handler_t'
> 
> Call out that except for RSP, the registers are undefined on asynchronous
> exits as far as the vDSO ABI is concerned.  E.g. the vDSO's exception
> handler clobbers RDX, RDI, and RSI, and the kernel doesn't guarantee that
> R8 or R9 will be zero (the synthetic value loaded by the CPU).
> 
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Closes: https://lore.kernel.org/all/20251106145506.145fc620@canb.auug.org.au
> Signed-off-by: Sean Christopherson <seanjc@google.com>
> ---
>  arch/x86/include/uapi/asm/sgx.h | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/arch/x86/include/uapi/asm/sgx.h b/arch/x86/include/uapi/asm/sgx.h
> index a438ea43bfd1..0d408f001ac6 100644
> --- a/arch/x86/include/uapi/asm/sgx.h
> +++ b/arch/x86/include/uapi/asm/sgx.h
> @@ -143,6 +143,12 @@ struct sgx_enclave_run;
>  /**
>   * typedef sgx_enclave_user_handler_t - Exit handler function accepted by
>   *					__vdso_sgx_enter_enclave()
> + * @rdi:	RDI at the time of EEXIT, undefined on AEX
> + * @rsi:	RSI at the time of EEXIT, undefined on AEX
> + * @rdx:	RDX at the time of EEXIT, undefined on AEX
> + * @rsp:	RSP (untrusted) at the time of EEXIT or AEX
> + * @r8:		R8 at the time of EEXIT, undefined on AEX
> + * @r9:		R9 at the time of EEXIT, undefined on AEX
>   * @run:	The run instance given by the caller
>   *
>   * The register parameters contain the snapshot of their values at enclave
> -- 
> 2.51.2.1041.gc1ab5b90ca-goog
> 

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

BR, Jarkko

Re: [PATCH 4/5] x86/sgx: Remove superfluous asterisk from copyright comment in asm/sgx.h

[Jarkko Sakkinen]

On Wed, Nov 12, 2025 at 08:07:07AM -0800, Sean Christopherson wrote:
> Drop an asterisk from a file-level copyright comment so that the comment
> isn't intrepeted as a kernel-doc comment.
> 
> E.g. if arch/x86/include/asm/sgx.h is fed into kernel-doc processing:
> 
>   WARNING: ./arch/x86/include/asm/sgx.h:2 This comment starts with '/**',
>   but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> 
> Signed-off-by: Sean Christopherson <seanjc@google.com>
> ---
>  arch/x86/include/asm/sgx.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/arch/x86/include/asm/sgx.h b/arch/x86/include/asm/sgx.h
> index a88c4ab95edd..3c90cae04e1d 100644
> --- a/arch/x86/include/asm/sgx.h
> +++ b/arch/x86/include/asm/sgx.h
> @@ -1,5 +1,5 @@
>  /* SPDX-License-Identifier: GPL-2.0 */
> -/**
> +/*
>   * Copyright(c) 2016-20 Intel Corporation.
>   *
>   * Intel Software Guard Extensions (SGX) support.
> -- 
> 2.51.2.1041.gc1ab5b90ca-goog
> 

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

BR, Jarkko

Re: [PATCH 5/5] x86/sgx: Fix a typo in the kernel-doc comment for enum sgx_attribute

[Jarkko Sakkinen]

On Wed, Nov 12, 2025 at 08:07:08AM -0800, Sean Christopherson wrote:
> Use the exact enum name when documenting "enum sgx_attribute" to fix a
> warning if the file is fed into kernel-doc processing:
> 
>   WARNING: ./arch/x86/include/asm/sgx.h:139 expecting prototype for enum
>            sgx_attributes. Prototype was for enum sgx_attribute instead
> 
> Signed-off-by: Sean Christopherson <seanjc@google.com>
> ---
>  arch/x86/include/asm/sgx.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/arch/x86/include/asm/sgx.h b/arch/x86/include/asm/sgx.h
> index 3c90cae04e1d..04958459a7ca 100644
> --- a/arch/x86/include/asm/sgx.h
> +++ b/arch/x86/include/asm/sgx.h
> @@ -112,7 +112,7 @@ enum sgx_miscselect {
>  #define SGX_SSA_MISC_EXINFO_SIZE	16
>  
>  /**
> - * enum sgx_attributes - the attributes field in &struct sgx_secs
> + * enum sgx_attribute - the attributes field in &struct sgx_secs
>   * @SGX_ATTR_INIT:		Enclave can be entered (is initialized).
>   * @SGX_ATTR_DEBUG:		Allow ENCLS(EDBGRD) and ENCLS(EDBGWR).
>   * @SGX_ATTR_MODE64BIT:		Tell that this a 64-bit enclave.
> -- 
> 2.51.2.1041.gc1ab5b90ca-goog
> 

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

BR, Jarkko