gvisor.dev: Add information about the systrap platform.

If you're interested in gVisor to the extent of reading this commit message,
please try out this platform and report about your experience!
gvisor-users@googlegroups.com

This change also rewords Systrap's README file slightly.

PiperOrigin-RevId: 513042723

g3doc/architecture_guide/platforms.md

@@ -44,14 +44,27 @@ allowing it to execute host system calls. This platform can run anywhere that
 Unfortunately, the ptrace platform has high context switch overhead, so system
 call-heavy applications may pay a [performance penalty](./performance.md).
 
+### systrap
+
+The systrap platform is an **experimental, non-production-ready** platform aimed
+at replacing the ptrace platform (i.e. in VMs without nested virtualization). It
+relies `seccomp`'s `SECCOMP_RET_TRAP` feature in order to intercept system
+calls. This makes the kernel send `SIGSYS` to the triggering thread, which hands
+over control to gVisor to handle the system call. For more details, please see
+[the systrap `README` file](https://github.com/google/gvisor/blob/master/pkg/sentry/platform/systrap/README.md).
+
+As of 2023-03, this platform has not been battle-tested as `ptrace`, and is not
+recommended for production use. Users are encouraged to try it out in
+non-production environments and [report bugs and feedback](../community.md).
+
 ### KVM
 
 The KVM platform uses the kernel's [KVM][kvm] functionality to allow the Sentry
-to act as both guest OS and VMM. The KVM platform can run on bare-metal, or in a
-VM with nested virtualization enabled. While there is no virtualized hardware
-layer -- the sandbox retains a process model -- gVisor leverages virtualization
-extensions available on modern processors in order to improve isolation and
-performance of address space switches.
+to act as both guest OS and VMM. The KVM platform runs best on bare-metal
+setups. While there is no virtualized hardware layer -- the sandbox retains a
+process model -- gVisor leverages virtualization extensions available on modern
+processors in order to improve isolation and performance of address space
+switches.
 
 Note that while running within a nested VM is feasible with the KVM platform,
 the `ptrace` platform will often provide better performance in such a setup, due

g3doc/user_guide/platforms.md

@@ -45,6 +45,11 @@ cause of security issues (e.g.
 [CVE-2018-12904](https://nvd.nist.gov/vuln/detail/CVE-2018-12904)). It is not
 recommended for production.***
 
+A third platform, `systrap`, is expected to eventually replace the `ptrace`
+platform. As of this writing (2023-03), **this platform is not
+production-ready**, but we encourage `ptrace` users to try it out in
+non-production settings and [report bugs and feedback](../community.md).
+
 ## Configuring Docker
 
 The platform is selected by the `--platform` command line flag passed to
@@ -90,6 +95,12 @@ for the KVM platform:
             "runtimeArgs": [
                 "--platform=kvm"
             ]
+        },
+        "runsc-systrap": {
+            "path": "/usr/local/bin/runsc",
+            "runtimeArgs": [
+                "--platform=systrap"
+            ]
         }
     }
 }

pkg/sentry/platform/systrap/README.md

@@ -1,33 +1,34 @@
 # The systrap platform
 
-This platform is similar with the ptrace platform with the difference how system
-calls, page-faults and other exceptions handled.
+This platform is similar with the ptrace platform but differs on how system
+calls, page-faults and other exceptions are handled.
 
-The kernel allows setting seccomp filters (SECCOMP_RET_TRAP), so that each time
-when a thread tries to call a filtered system call, it will receive the SIGSYS
-signal.
+Linux allows setting seccomp filters with `SECCOMP_RET_TRAP`, such that when a
+thread tries to call a system call caught by the seccomp filter, this thread
+will receive the `SIGSYS` signal.
 
-With this kernel feature, all stub thread events what have to be handled in the
-sentry triggers signals. This means that they can be handled from a signal
-handler.
+gVisor's systrap platform uses this kernel feature to have all thread events
+that have to be handled in the sentry trigger signals.
 
-The systrap platform includes the sysmsg module which implements a stub signal
-handler and a protocol of communications of stub threads and the Sentry.
+The systrap platform implements a stub signal handler (as part of the `sysmsg`
+module), and communication protocol between this stub signal handler and the
+Sentry.
 
-The initializations of a new stub thread includes next steps:
+The initialization of a new stub thread involves:
 
-*   installing seccomp filters to trap all user system calls.
-*   setting an alternate signal stack which is shared with the Sentry.
-*   setting the sysmsg signal handler for SIGSYS, SIGSEGV, SIGBUS, SIGFPE,
-    SIGTRAP, SIGILL.
+*   Installing seccomp filters to trap all user system calls.
+*   Setting up an alternate signal stack which is shared with the Sentry.
+*   Setting up the sysmsg signal handler for `SIGSYS`, `SIGSEGV`, `SIGBUS`,
+    `SIGFPE`, `SIGTRAP`, and `SIGILL`.
 
-User code is executed in context of a stub thread. When it calls a system call
-or triggers page-fault, the signal handler is started. It notifies the Sentry
-about a new signal, then the Sentry handles this event and notifies the system
-thread back that it can continue running.
+User code is executed in the context of a stub thread. When it calls a system
+call or triggers a page-fault, the stub signal handler code executes. It
+notifies the Sentry of this new signal. The Sentry handles this, and calls back
+the system thread so that it can resume running.
 
 When the kernel prepares to execute the signal handler, it generates a signal
-frame which contains a process state (registers, FPU state, etc). Then when the
-kernel resumes a process, the process state is restored from this frame. The
-signal frame is saved on a signal handler stack which is shared with the Sentry.
-This allows us to read and modify the thread state from the Sentry.
+frame which contains the process state (registers, FPU state, etc). Then, when
+the kernel resumes the process, the process state is restored from this frame.
+The signal frame is saved on the signal handler stack. This memory region is
+shared with the Sentry process. This allows gVisor to read and modify the thread
+state from the Sentry.