@@ -18,39 +18,57 @@
* __vdso_sgx_enter_enclave() - Enter an SGX enclave
* @leaf: ENCLU leaf, must be EENTER or ERESUME
* @tcs: TCS, must be non-NULL
- * @ex_info: Optional struct sgx_enclave_exception instance
- * @callback: Optional callback function to be called on enclave exit or
- * exception
+ * @e: Optional struct sgx_enclave_exception instance
+ * @handler: Optional enclave exit handler
*
* **Important!** __vdso_sgx_enter_enclave() is **NOT** compliant with the
- * x86-64 ABI, i.e. cannot be called from standard C code. As noted above,
- * input parameters must be passed via ``%eax``, ``8(%rsp)``, ``0x10(%rsp)`` and
- * ``0x18(%rsp)``, with the return value passed via ``%eax``. All other
- * registers will be passed through to the enclave as is. All registers except
- * ``%rbp`` must be treated as volatile from the caller's perspective, including
- * but not limited to GPRs, EFLAGS.DF, MXCSR, FCW, etc... Conversely, the
- * enclave being run **must** preserve the untrusted ``%rbp``.
+ * x86-64 ABI, i.e. cannot be called from standard C code.
*
- * ``callback`` has the following signature:
- * int callback(long rdi, long rsi, long rdx,
- * struct sgx_enclave_exinfo *exinfo, long r8, long r9,
- * void *tcs, long ursp);
- * ``callback`` **shall** follow x86_64 ABI. All GPRs **except** ``%rax``,
- * ``%rbx`` and ``rcx`` are passed through to ``callback``. ``%rdi``, ``%rsi``,
- * ``%rdx``, ``%r8``, ``%r9``, along with the value of ``%rsp`` when the enclave
- * exited/excepted, can be accessed directly as input parameters, while other
- * GPRs can be accessed in assembly if needed. A positive value returned from
- * ``callback`` will be treated as an ENCLU leaf (e.g. EENTER/ERESUME) to
- * reenter the enclave (without popping the extra data pushed by the enclave off
- * the stack), while 0 (zero) or a negative return value will be passed back to
- * the caller of __vdso_sgx_enter_enclave(). It is also safe to leave
- * ``callback`` via ``longjmp()`` or by throwing a C++ exception.
+ * Input ABI:
+ * @leaf %eax
+ * @tcs 8(%rsp)
+ * @e 0x10(%rsp)
+ * @handler 0x18(%rsp)
+ *
+ * Output ABI:
+ * @ret %eax
+ *
+ * All general purpose registers except RAX, RBX and RCX are passed as-is to
+ * the enclave. RAX, RBX and RCX are consumed by EENTER and ERESUME and are
+ * loaded with @leaf, asynchronous exit pointer, and @tcs respectively.
+ *
+ * RBP and the stack are used to anchor __vdso_sgx_enter_enclave() to the
+ * pre-enclave state, e.g. to retrieve @e and @handler after an enclave exit.
+ * All other registers are available for use by the enclave and its runtime,
+ * e.g. an enclave can push additional data onto the stack (and modify RSP) to
+ * pass information to the optional exit handler (see below).
+ *
+ * Most exceptions reported on ENCLU, including those that occur within the
+ * enclave, are fixed up and reported synchronously instead of being delivered
+ * via a standard signal. Debug Exceptions (#DB) and Breakpoints (#BP) are
+ * never fixed up and are always delivered via standard signals. On synchrously
+ * reported exceptions, -EFAULT is returned and details about the exception are
+ * recorded in @e, the optional sgx_enclave_exception struct.
+
+ * If an exit handler is provided, the handler will be invoked on synchronous
+ * exits from the enclave and for all synchronously reported exceptions. In
+ * latter case, @e is filled prior to invoking the handler.
+ *
+ * The exit handler's return value is interpreted as follows:
+ * >0: continue, restart __vdso_sgx_enter_enclave() with @ret as @leaf
+ * 0: success, return @ret to the caller
+ * <0: error, return @ret to the caller
+ *
+ * The userspace exit handler is responsible for unwinding the stack, e.g. to
+ * pop @e, u_rsp and @tcs, prior to returning to __vdso_sgx_enter_enclave().
+ * The exit handler may also transfer control, e.g. via longjmp() or a C++
+ * exception, without returning to __vdso_sgx_enter_enclave().
*
* Return:
- * 0 on success,
- * -EINVAL if ENCLU leaf is not allowed,
- * -EFAULT if ENCL or the enclave faults or non-positive value is returned
- * from the callback.
+ * 0 on success,
+ * -EINVAL if ENCLU leaf is not allowed,
+ * -EFAULT if an exception occurs on ENCLU or within the enclave
+ * -errno for all other negative values returned by the userspace exit handler
*/
#ifdef SGX_KERNEL_DOC
/* C-style function prototype to coerce kernel-doc into parsing the comment. */
Rewrite the function comment for __vdso_sgx_enter_enclave() to eliminate dependencies on markup (which currently doesn't work correctly anyways), bring the comments up-to-date, and use phrasing and mood that is more consistent with the rest of the kernel. Signed-off-by: Sean Christopherson <sean.j.christopherson@intel.com> --- arch/x86/entry/vdso/vsgx_enter_enclave.S | 74 +++++++++++++++--------- 1 file changed, 46 insertions(+), 28 deletions(-)