Add helpful guiding messages to those who need to read them.

Explain some nuances about systrap in more detail.

PiperOrigin-RevId: 900439001

Author: konstantin-s-bogom

pkg/sentry/platform/systrap/sysmsg/syshandler_amd64.S

@@ -12,6 +12,21 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// This file contains the switch functionality of the systrap "syshandler" optimization.
+// It lets us avoid the signal frame setup overhead of the regular SIGSYS handler. These
+// switch routines save user state, and rely on having %gs point to this thread's sysmsg
+// state in order to have a region to actually save the state to.
+//
+// There are limitations to this optimization, and it can be disabled via the
+// systrap-disable-syscall-patching flag:
+// - If a user workload actually uses %gs and switches it (swapgs), this optimization will
+//   not work. Note that this is not an issue for other subprocesses, because
+//   gs overwrite will only affect the process doing it.
+// - If TF is set within RFLAGS (e.g. by debuggers), when the process enters
+//   __export_syshandler TF will still remain set, and user regs RIP will be discarded.
+//
+// Despite these limitations the speed up is significant, so it's ON by default.
+
 #include "sysmsg_offsets.h"
 #include "sysmsg_offsets_amd64.h"
 

pkg/sentry/platform/systrap/sysmsg/sysmsg.go

@@ -228,6 +228,14 @@ const (
 // ThreadContext contains the current context of the sysmsg thread. The struct
 // facilitates switching contexts by allowing the sentry to switch pointers to
 // this struct as it needs to.
+//
+// N.B ThreadContexts are shared between all sysmsg threads within a subprocess,
+// and are necessarily writeable by any thread within the subprocess. If a
+// subprocess really wants to (i.e. sandbox break-out attempts) it can find
+// where the TC region is mapped and use other threads to manipulate this data
+// for a thread doing a context switch into the sentry.
+// This is OK because as a rule we do not trust this data; if any funny business
+// is going on the sentry simply kills the subprocess.
 type ThreadContext struct {
 	// FPState is a region of memory where:
 	//   - syshandler saves FPU state to using xsave/fxsave