2020-04-28 05:24:58 +00:00
|
|
|
# Platform Guide
|
2019-11-18 21:40:27 +00:00
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
[TOC]
|
2019-03-30 02:40:11 +00:00
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
gVisor requires a platform to implement interception of syscalls, basic context
|
|
|
|
switching, and memory mapping functionality. Internally, gVisor uses an
|
|
|
|
abstraction sensibly called [Platform][platform]. A simplified version of this
|
|
|
|
interface looks like:
|
2019-03-30 02:40:11 +00:00
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
```golang
|
|
|
|
type Platform interface {
|
|
|
|
NewAddressSpace() (AddressSpace, error)
|
|
|
|
NewContext() Context
|
|
|
|
}
|
2019-03-30 02:40:11 +00:00
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
type Context interface {
|
|
|
|
Switch(as AddressSpace, ac arch.Context) (..., error)
|
|
|
|
}
|
2019-03-30 02:40:11 +00:00
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
type AddressSpace interface {
|
|
|
|
MapFile(addr usermem.Addr, f File, fr FileRange, at usermem.AccessType, ...) error
|
|
|
|
Unmap(addr usermem.Addr, length uint64)
|
|
|
|
}
|
|
|
|
```
|
2019-03-30 02:40:11 +00:00
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
There are a number of different ways to implement this interface that come with
|
|
|
|
various trade-offs, generally around performance and hardware requirements.
|
2019-03-30 02:40:11 +00:00
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
## Implementations
|
2019-03-30 02:40:11 +00:00
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
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):
|
2019-03-30 02:40:11 +00:00
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
![Platforms](platforms.png "Platform examples.")
|
2019-03-30 02:40:11 +00:00
|
|
|
|
|
|
|
### ptrace
|
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
The ptrace platform uses [PTRACE_SYSEMU][ptrace] 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.
|
2019-03-30 02:40:11 +00:00
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
Unfortunately, the ptrace platform has high context switch overhead, so system
|
|
|
|
call-heavy applications may pay a [performance penalty](./performance.md).
|
2019-03-30 02:40:11 +00:00
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
### KVM
|
2019-03-30 02:40:11 +00:00
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
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.
|
2019-03-30 02:40:11 +00:00
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
## Changing Platforms
|
2019-03-30 02:40:11 +00:00
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
See [Changing Platforms](../user_guide/platforms.md).
|
2019-03-30 02:40:11 +00:00
|
|
|
|
2020-05-16 03:03:54 +00:00
|
|
|
[kvm]: https://www.kernel.org/doc/Documentation/virtual/kvm/api.txt
|
|
|
|
[platform]: https://cs.opensource.google/gvisor/gvisor/+/release-20190304.1:pkg/sentry/platform/platform.go;l=33
|
|
|
|
[ptrace]: http://man7.org/linux/man-pages/man2/ptrace.2.html
|