[PAL/Linux-SGX] Rename sgx_entry to sgx_do_host_ocall

The file `host_entry.S` contains low-level code that executes ECALL/OCALL/AEX flows in the untrusted runtime of Gramine. Previously, this file contained the label `sgx_entry` that has a misleading name -- it doesn't "enter the SGX enclave" but instead it "performs an OCALL on the host", i.e. executes the syscall on the host. This commit renames this label to avoid confusion. Also, some explanations are added. Signed-off-by: Dmitrii Kuvaiskii <[email protected]>
gramineproject · Aug 14, 2024 · 4a73025 · 4a73025
1 parent a717598
commit 4a73025
Show file tree

Hide file tree

Showing 2 changed files with 19 additions and 6 deletions.
diff --git a/pal/src/host/linux-sgx/enclave_entry.S b/pal/src/host/linux-sgx/enclave_entry.S
@@ -940,9 +940,9 @@ restore_xregs:
     # called __morestack.
     #
     # To make GDB backtrace work, we make sure that the first function outside of enclave
-    # (sgx_entry) has a return address on stack, pointing inside __morestack. We will not actually
-    # return to this function (sgx_entry performs EENTER to go back to enclave), but GDB will make a
-    # stack frame for it.
+    # (sgx_do_host_ocall) has a return address on stack, pointing inside __morestack. We will not
+    # actually return to this function (sgx_do_host_ocall performs EENTER to go back to enclave),
+    # but GDB will make a stack frame for it.
     #
     # The function contains CFI directives to make sure that all callee-saved registers can be
     # recovered. They should reflect the situation during EEXIT in code above.

diff --git a/pal/src/host/linux-sgx/host_entry.S b/pal/src/host/linux-sgx/host_entry.S
@@ -1,3 +1,15 @@
+# This file contains host-to-enclave and enclave-to-host flows, from the side of untrusted runtime:
+#
+#     - Host-to-enclave normal-context flow (ECALL) -- sgx_ecall() function.
+#
+#     - Host-to-enclave signal-handling flow (ECALL) -- sgx_raise() function.
+#
+#     - Enclave-to-host syscall-handling flow (OCALL) -- Lsgx_do_host_ocall label. The sgx_ecall()
+#       flow pushes the address of this label into RDX before calling EENTER, and the enclave code
+#       jumps to it when handling the OCALL, see enclave_entry.S:sgx_ocall().
+#
+#     - Enclave-to-host asynchronous enclave exit (AEX) -- async_exit_pointer() function.
+
 #include "sgx_arch.h"
 
 #include "asm-offsets.h"
@@ -11,8 +23,8 @@
 sgx_ecall:
     .cfi_startproc
 
-    # put entry address in RDX
-    leaq .Lsgx_entry(%rip), %rdx
+    # put host-OCALL target in RDX (enclave code will jump to it when handling the OCALL)
+    leaq .Lsgx_do_host_ocall(%rip), %rdx
 
     # other arguments: RDI - code, RSI - ms
 
@@ -126,7 +138,7 @@ sgx_raise:
     leaq .Lafter_resume(%rip), %rdx
     jmp .Ldo_ecall_callee_save
 
-.Lsgx_entry:
+.Lsgx_do_host_ocall:
     # arguments: RDI - code, RSI - ms
     .cfi_startproc
 
@@ -163,6 +175,7 @@ sgx_raise:
     andq $~0xF, %rsp  # Required by System V AMD64 ABI.
 #endif
 
+    # call one of the sgx_ocall_* functions defined in host_ocalls.c
     callq *%rbx
 
     movq %rbp, %rsp