gvisor.dev/gvisor@v0.0.0-20240520182842-f9d4d51c7e0f/g3doc/architecture_guide/platforms.md (about)

     1  # Platform Guide
     2  
     3  [TOC]
     4  
     5  gVisor requires a platform to implement interception of syscalls, basic context
     6  switching, and memory mapping functionality. Internally, gVisor uses an
     7  abstraction sensibly called [`Platform`][platform]. A simplified version of this
     8  interface looks like:
     9  
    10  ```golang
    11  type Platform interface {
    12      NewAddressSpace() (AddressSpace, error)
    13      NewContext() Context
    14  }
    15  
    16  type Context interface {
    17      Switch(as AddressSpace, ac arch.Context) (..., error)
    18  }
    19  
    20  type AddressSpace interface {
    21      MapFile(addr hostarch.Addr, f File, fr FileRange, at hostarch.AccessType, ...) error
    22      Unmap(addr hostarch.Addr, length uint64)
    23  }
    24  ```
    25  
    26  There are a number of different ways to implement this interface that come with
    27  various trade-offs, generally around performance and hardware requirements.
    28  
    29  ## Implementations
    30  
    31  The choice of platform depends on the context in which `runsc` is executing. In
    32  general, when running on bare-metal (not inside a VM), the KVM platform will
    33  provide the best performance. The `systrap` platform is a better choice when
    34  running inside a VM, or on a machine without virtualization support.
    35  
    36  ![Platforms](platforms.png "Platform examples.")
    37  
    38  ### KVM
    39  
    40  The KVM platform uses the kernel's [KVM][kvm] functionality to allow the Sentry
    41  to act as both guest OS and VMM. The KVM platform runs best on bare-metal
    42  setups. While there is no virtualized hardware layer -- the sandbox retains a
    43  process model -- gVisor leverages virtualization extensions available on modern
    44  processors in order to improve isolation and performance of address space
    45  switches.
    46  
    47  Note that while running within a nested VM is feasible with the KVM platform,
    48  the `systrap` platform will often provide better performance in such a setup,
    49  due to the overhead of nested virtualization.
    50  
    51  ### systrap
    52  
    53  The `systrap` platform relies `seccomp`'s `SECCOMP_RET_TRAP` feature in order to
    54  intercept system calls. This makes the kernel send `SIGSYS` to the triggering
    55  thread, which hands over control to gVisor to handle the system call. For more
    56  details, please see
    57  [the systrap `README` file](https://github.com/google/gvisor/blob/master/pkg/sentry/platform/systrap/README.md).
    58  
    59  `systrap` replaced `ptrace` as the default gVisor platform in mid-2023. If you
    60  depend on `ptrace`, and `systrap` doesn't fulfill your needs, please
    61  [voice your feedback](../community.md).
    62  
    63  ### ptrace
    64  
    65  The ptrace platform uses [`PTRACE_SYSEMU`][ptrace] to execute user code without
    66  allowing it to execute host system calls. This platform can run anywhere that
    67  `ptrace` works (even VMs without nested virtualization), which is ubiquitous.
    68  
    69  Unfortunately, the ptrace platform has high context switch overhead, so system
    70  call-heavy applications may pay a [performance penalty](./performance.md). For
    71  this reason, `systrap` is almost always the better choice.
    72  
    73  `systrap` replaced `ptrace` as the default gVisor platform in mid-2023. While
    74  `ptrace` continues to exist in the codebase, it is no longer supported and is
    75  expected to eventually be removed entirely. If you depend on `ptrace`, and
    76  `systrap` doesn't fulfill your needs, please
    77  [voice your feedback](../community.md).
    78  
    79  ## Changing Platforms
    80  
    81  See [Changing Platforms](../user_guide/platforms.md).
    82  
    83  [kvm]: https://www.kernel.org/doc/Documentation/virtual/kvm/api.txt
    84  [platform]: https://cs.opensource.google/gvisor/gvisor/+/release-20190304.1:pkg/sentry/platform/platform.go;l=33
    85  [ptrace]: http://man7.org/linux/man-pages/man2/ptrace.2.html
    86  [GKE Sandbox]: https://cloud.google.com/kubernetes-engine/docs/concepts/sandbox-pods