x86/sgx: Fix kernel-doc warnings

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

Posted by Sean Christopherson 2 months, 4 weeks ago

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

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

Posted by Jarkko Sakkinen 2 months, 3 weeks ago

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 2/5] x86/sgx: Add kernel-doc descriptions for params passed to vDSO user handler

Posted by Huang, Kai 2 months, 3 weeks ago

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 2/5] x86/sgx: Add kernel-doc descriptions for params passed to vDSO user handler

Posted by Sean Christopherson 2 months, 3 weeks ago

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

Posted by Huang, Kai 2 months, 3 weeks ago

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