gvisor/pkg/sentry/kernel
Adin Scannell c0f89eba6e Import and structure cleanup.
PiperOrigin-RevId: 281795269
2019-11-21 11:41:30 -08:00
..
auth Import and structure cleanup. 2019-11-21 11:41:30 -08:00
contexttest Reorder BUILD license and load functions in gvisor. 2019-10-16 16:40:30 -07:00
epoll Reorder BUILD license and load functions in gvisor. 2019-10-16 16:40:30 -07:00
eventfd Reorder BUILD license and load functions in gvisor. 2019-10-16 16:40:30 -07:00
fasync Reorder BUILD license and load functions in gvisor. 2019-10-16 16:40:30 -07:00
futex Import and structure cleanup. 2019-11-21 11:41:30 -08:00
g3doc Use png for the run states diagram 2018-05-02 03:43:41 -07:00
memevent internal BUILD file cleanup. 2019-09-23 08:25:13 -07:00
pipe Add support for pipes in VFS2. 2019-10-19 11:49:38 -07:00
sched Remove go_test from go_stateify and go_marshal 2019-09-12 15:10:17 -07:00
semaphore Reorder BUILD license and load functions in gvisor. 2019-10-16 16:40:30 -07:00
shm Reorder BUILD license and load functions in gvisor. 2019-10-16 16:40:30 -07:00
signalfd Import and structure cleanup. 2019-11-21 11:41:30 -08:00
time Reorder BUILD license and load functions in gvisor. 2019-10-16 16:40:30 -07:00
BUILD Import and structure cleanup. 2019-11-21 11:41:30 -08:00
README.md Format documentation 2018-07-12 10:37:21 -07:00
abstract_socket_namespace.go Update canonical repository. 2019-06-13 16:50:15 -07:00
context.go Add context to state. 2019-10-31 18:03:24 -07:00
fd_table.go Keep minimal available fd to accelerate fd allocation 2019-10-23 14:27:53 -07:00
fd_table_test.go Keep minimal available fd to accelerate fd allocation 2019-10-23 14:27:53 -07:00
fd_table_unsafe.go Remove map from fd_map, change to fd_table. 2019-07-02 19:28:59 -07:00
fs_context.go Add finalizer on AtomicRefCount to check for leaks. 2019-06-28 20:07:52 -07:00
ipc_namespace.go Fix various spelling issues in the documentation 2019-06-27 14:25:50 -07:00
kernel.go Add context to state. 2019-10-31 18:03:24 -07:00
kernel_state.go Update canonical repository. 2019-06-13 16:50:15 -07:00
pending_signals.go Update canonical repository. 2019-06-13 16:50:15 -07:00
pending_signals_state.go Update canonical repository. 2019-06-13 16:50:15 -07:00
posixtimer.go Disable cpuClockTicker when app is idle 2019-10-01 12:21:01 -07:00
ptrace.go Update canonical repository. 2019-06-13 16:50:15 -07:00
ptrace_amd64.go Update canonical repository. 2019-06-13 16:50:15 -07:00
ptrace_arm64.go Fix some build errors on arm64. 2019-11-13 06:46:02 +00:00
rseq.go Update canonical repository. 2019-06-13 16:50:15 -07:00
seccomp.go Update canonical repository. 2019-06-13 16:50:15 -07:00
sessions.go Job control: controlling TTYs and foreground process groups. 2019-09-19 11:36:47 -07:00
signal.go Update canonical repository. 2019-06-13 16:50:15 -07:00
signal_handlers.go Update canonical repository. 2019-06-13 16:50:15 -07:00
syscalls.go Update canonical repository. 2019-06-13 16:50:15 -07:00
syscalls_state.go Change copyright notice to "The gVisor Authors" 2019-04-29 14:26:23 -07:00
syslog.go sentry/kernel: add syslog message 2019-07-02 12:05:41 -07:00
table_test.go Update canonical repository. 2019-06-13 16:50:15 -07:00
task.go Import and structure cleanup. 2019-11-21 11:41:30 -08:00
task_acct.go Update canonical repository. 2019-06-13 16:50:15 -07:00
task_block.go Ensure yield-equivalent with an already-expired timeout. 2019-08-22 14:34:33 -07:00
task_clone.go Remove map from fd_map, change to fd_table. 2019-07-02 19:28:59 -07:00
task_context.go Aggregate arguments for loading executables into a single struct. 2019-10-25 22:44:19 -07:00
task_exec.go Remove map from fd_map, change to fd_table. 2019-07-02 19:28:59 -07:00
task_exit.go Remove map from fd_map, change to fd_table. 2019-07-02 19:28:59 -07:00
task_futex.go Fix various spelling issues in the documentation 2019-06-27 14:25:50 -07:00
task_identity.go Include AT_SECURE in the aux vector 2019-10-01 15:43:14 -07:00
task_log.go Remove map from fd_map, change to fd_table. 2019-07-02 19:28:59 -07:00
task_net.go Update canonical repository. 2019-06-13 16:50:15 -07:00
task_run.go Update canonical repository. 2019-06-13 16:50:15 -07:00
task_sched.go Disable cpuClockTicker when app is idle 2019-10-01 12:21:01 -07:00
task_signals.go Signalfd support 2019-09-18 15:16:42 -07:00
task_start.go Job control: controlling TTYs and foreground process groups. 2019-09-19 11:36:47 -07:00
task_stop.go Fix various spelling issues in the documentation 2019-06-27 14:25:50 -07:00
task_syscall.go Update canonical repository. 2019-06-13 16:50:15 -07:00
task_test.go Update canonical repository. 2019-06-13 16:50:15 -07:00
task_usermem.go Update canonical repository. 2019-06-13 16:50:15 -07:00
thread_group.go Disable cpuClockTicker when app is idle 2019-10-01 12:21:01 -07:00
threads.go Merge pull request #452 from zhangningdlut:chris_test_pidns 2019-07-26 15:00:51 -07:00
timekeeper.go Fix various spelling issues in the documentation 2019-06-27 14:25:50 -07:00
timekeeper_state.go Update canonical repository. 2019-06-13 16:50:15 -07:00
timekeeper_test.go Update canonical repository. 2019-06-13 16:50:15 -07:00
tty.go Job control: controlling TTYs and foreground process groups. 2019-09-19 11:36:47 -07:00
uncaught_signal.proto Change copyright notice to "The gVisor Authors" 2019-04-29 14:26:23 -07:00
uts_namespace.go Update canonical repository. 2019-06-13 16:50:15 -07:00
vdso.go Update canonical repository. 2019-06-13 16:50:15 -07:00
version.go Change copyright notice to "The gVisor Authors" 2019-04-29 14:26:23 -07:00

README.md

This package contains:

  • A (partial) emulation of the "core Linux kernel", which governs task execution and scheduling, system call dispatch, and signal handling. See below for details.

  • The top-level interface for the sentry's Linux kernel emulation in general, used by the main function of all versions of the sentry. This interface revolves around the Env type (defined in kernel.go).

Background

In Linux, each schedulable context is referred to interchangeably as a "task" or "thread". Tasks can be divided into userspace and kernel tasks. In the sentry, scheduling is managed by the Go runtime, so each schedulable context is a goroutine; only "userspace" (application) contexts are referred to as tasks, and represented by Task objects. (From this point forward, "task" refers to the sentry's notion of a task unless otherwise specified.)

At a high level, Linux application threads can be thought of as repeating a "run loop":

  • Some amount of application code is executed in userspace.

  • A trap (explicit syscall invocation, hardware interrupt or exception, etc.) causes control flow to switch to the kernel.

  • Some amount of kernel code is executed in kernelspace, e.g. to handle the cause of the trap.

  • The kernel "returns from the trap" into application code.

Analogously, each task in the sentry is associated with a task goroutine that executes that task's run loop (Task.run in task_run.go). However, the sentry's task run loop differs in structure in order to support saving execution state to, and resuming execution from, checkpoints.

While in kernelspace, a Linux thread can be descheduled (cease execution) in a variety of ways:

  • It can yield or be preempted, becoming temporarily descheduled but still runnable. At present, the sentry delegates scheduling of runnable threads to the Go runtime.

  • It can exit, becoming permanently descheduled. The sentry's equivalent is returning from Task.run, terminating the task goroutine.

  • It can enter interruptible sleep, a state in which it can be woken by a caller-defined wakeup or the receipt of a signal. In the sentry, interruptible sleep (which is ambiguously referred to as blocking) is implemented by making all events that can end blocking (including signal notifications) communicated via Go channels and using select to multiplex wakeup sources; see task_block.go.

  • It can enter uninterruptible sleep, a state in which it can only be woken by a caller-defined wakeup. Killable sleep is a closely related variant in which the task can also be woken by SIGKILL. (These definitions also include Linux's "group-stopped" (TASK_STOPPED) and "ptrace-stopped" (TASK_TRACED) states.)

To maximize compatibility with Linux, sentry checkpointing appears as a spurious signal-delivery interrupt on all tasks; interrupted system calls return EINTR or are automatically restarted as usual. However, these semantics require that uninterruptible and killable sleeps do not appear to be interrupted. In other words, the state of the task, including its progress through the interrupted operation, must be preserved by checkpointing. For many such sleeps, the wakeup condition is application-controlled, making it infeasible to wait for the sleep to end before checkpointing. Instead, we must support checkpointing progress through sleeping operations.

Implementation

We break the task's control flow graph into states, delimited by:

  1. Points where uninterruptible and killable sleeps may occur. For example, there exists a state boundary between signal dequeueing and signal delivery because there may be an intervening ptrace signal-delivery-stop.

  2. Points where sleep-induced branches may "rejoin" normal execution. For example, the syscall exit state exists because it can be reached immediately following a synchronous syscall, or after a task that is sleeping in execve() or vfork() resumes execution.

  3. Points containing large branches. This is strictly for organizational purposes. For example, the state that processes interrupt-signaled conditions is kept separate from the main "app" state to reduce the size of the latter.

  4. SyscallReinvoke, which does not correspond to anything in Linux, and exists solely to serve the autosave feature.

dot -Tpng -Goverlap=false -orun_states.png run_states.dot

States before which a stop may occur are represented as implementations of the taskRunState interface named run(state), allowing them to be saved and restored. States that cannot be immediately preceded by a stop are simply Task methods named do(state).

Conditions that can require task goroutines to cease execution for unknown lengths of time are called stops. Stops are divided into internal stops, which are stops whose start and end conditions are implemented within the sentry, and external stops, which are stops whose start and end conditions are not known to the sentry. Hence all uninterruptible and killable sleeps are internal stops, and the existence of a pending checkpoint operation is an external stop. Internal stops are reified into instances of the TaskStop type, while external stops are merely counted. The task run loop alternates between checking for stops and advancing the task's state. This allows checkpointing to hold tasks in a stopped state while waiting for all tasks in the system to stop.