gvisor.dev/gvisor@v0.0.0-20240520182842-f9d4d51c7e0f/pkg/sentry/platform/systrap/README.md (about)

     1  # The systrap platform
     2  
     3  This platform is similar with the ptrace platform but differs on how system
     4  calls, page-faults and other exceptions are handled.
     5  
     6  Linux allows setting seccomp filters with `SECCOMP_RET_TRAP`, such that when a
     7  thread tries to call a system call caught by the seccomp filter, this thread
     8  will receive the `SIGSYS` signal.
     9  
    10  gVisor's systrap platform uses this kernel feature to have all thread events
    11  that have to be handled in the sentry trigger signals.
    12  
    13  The systrap platform implements a stub signal handler (as part of the `sysmsg`
    14  module), and communication protocol between this stub signal handler and the
    15  Sentry.
    16  
    17  The initialization of a new stub thread involves:
    18  
    19  *   Installing seccomp filters to trap all user system calls.
    20  *   Setting up an alternate signal stack which is shared with the Sentry.
    21  *   Setting up the sysmsg signal handler for `SIGSYS`, `SIGSEGV`, `SIGBUS`,
    22      `SIGFPE`, `SIGTRAP`, and `SIGILL`.
    23  
    24  User code is executed in the context of a stub thread. When it calls a system
    25  call or triggers a page-fault, the stub signal handler code executes. It
    26  notifies the Sentry of this new signal. The Sentry handles this, and calls back
    27  the system thread so that it can resume running.
    28  
    29  When the kernel prepares to execute the signal handler, it generates a signal
    30  frame which contains the process state (registers, FPU state, etc). Then, when
    31  the kernel resumes the process, the process state is restored from this frame.
    32  The signal frame is saved on the signal handler stack. This memory region is
    33  shared with the Sentry process. This allows gVisor to read and modify the thread
    34  state from the Sentry.