gvisor/g3doc/architecture_guide/platforms.md

Platform Guide

[TOC]

gVisor requires a platform to implement interception of syscalls, basic context switching, and memory mapping functionality. Internally, gVisor uses an abstraction sensibly called Platform. A simplified version of this interface looks like:

type Platform interface {
    NewAddressSpace() (AddressSpace, error)
    NewContext() Context
}

type Context interface {
    Switch(as AddressSpace, ac arch.Context) (..., error)
}

type AddressSpace interface {
    MapFile(addr hostarch.Addr, f File, fr FileRange, at hostarch.AccessType, ...) error
    Unmap(addr hostarch.Addr, length uint64)
}

There are a number of different ways to implement this interface that come with various trade-offs, generally around performance and hardware requirements.

Implementations

The choice of platform depends on the context in which runsc is executing. In general, virtualized platforms may be limited to platforms that do not require hardware virtualized support (since the hardware is already in use):

ptrace

The ptrace platform uses PTRACE_SYSEMU to execute user code without allowing it to execute host system calls. This platform can run anywhere that ptrace works (even VMs without nested virtualization), which is ubiquitous.

Unfortunately, the ptrace platform has high context switch overhead, so system call-heavy applications may pay a performance penalty.

KVM

The KVM platform uses the kernel's 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.

Changing Platforms

See Changing Platforms.