Minor formatting updates for gvisor.dev.

* Aggregate architecture Overview in "What is gVisor?" as it makes more sense
  in one place.

* Drop "user-space kernel" and use "application kernel". The term "user-space
  kernel" is confusing when some platform implementation do not run in
  user-space (instead running in guest ring zero).

* Clear up the relationship between the Platform page in the user guide and the
  Platform page in the architecture guide, and ensure they are cross-linked.

* Restore the call-to-action quick start link in the main page, and drop the
  GitHub link (which also appears in the top-right).

* Improve image formatting by centering all doc and blog images, and move the
  image captions to the alt text.

PiperOrigin-RevId: 311845158

1 files changed, 42 insertions, 67 deletions

diff --git a/g3doc/architecture_guide/platforms.md b/g3doc/architecture_guide/platforms.md
index 6e63da8ce..d112c9a28 100644
--- a/g3doc/architecture_guide/platforms.md
+++ b/g3doc/architecture_guide/platforms.md
@@ -1,86 +1,61 @@
 # Platform Guide
 
-A gVisor sandbox consists of multiple processes when running. These processes
-collectively comprise a shared environment in which one or more containers can
-be run.
+[TOC]
 
-Each sandbox has its own isolated instance of:
-
-*   The **Sentry**, A user-space kernel that runs the container and intercepts
-    and responds to system calls made by the application.
-
-Each container running in the sandbox has its own isolated instance of:
-
-*   A **Gofer** which provides file system access to the container.
-
-![gVisor architecture diagram](Sentry-Gofer.png "gVisor architecture diagram")
-
-## runsc
-
-The entrypoint to running a sandboxed container is the `runsc` executable.
-`runsc` implements the [Open Container Initiative (OCI)][oci] runtime
-specification. This means that OCI compatible _filesystem bundles_ can be run by
-`runsc`. Filesystem bundles are comprised of a `config.json` file containing
-container configuration, and a root filesystem for the container. Please see the
-[OCI runtime spec][runtime-spec] for more information on filesystem bundles.
-`runsc` implements multiple commands that perform various functions such as
-starting, stopping, listing, and querying the status of containers.
+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:
 
-## Sentry
+```golang
+type Platform interface {
+    NewAddressSpace() (AddressSpace, error)
+    NewContext() Context
+}
 
-The Sentry is the largest component of gVisor. It can be thought of as a
-userspace OS kernel. The Sentry implements all the kernel functionality needed
-by the untrusted application. It implements all of the supported system calls,
-signal delivery, memory management and page faulting logic, the threading model,
-and more.
+type Context interface {
+    Switch(as AddressSpace, ac arch.Context) (..., error)
+}
 
-When the untrusted application makes a system call, the currently used platform
-redirects the call to the Sentry, which will do the necessary work to service
-it. It is important to note that the Sentry will not simply pass through system
-calls to the host kernel. As a userspace application, the Sentry will make some
-host system calls to support its operation, but it will not allow the
-application to directly control the system calls it makes.
+type AddressSpace interface {
+    MapFile(addr usermem.Addr, f File, fr FileRange, at usermem.AccessType, ...) error
+    Unmap(addr usermem.Addr, length uint64)
+}
+```
 
-The Sentry aims to present an equivalent environment to (upstream) Linux v4.4.
+There are a number of different ways to implement this interface that come with
+various trade-offs, generally around performance and hardware requirements.
 
-File system operations that extend beyond the sandbox (not internal /proc files,
-pipes, etc) are sent to the Gofer, described below.
+## Implementations
 
-## Platforms
+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):
 
-gVisor requires a platform to implement interception of syscalls, basic context
-switching, and memory mapping functionality.
+![Platforms](platforms.png "Platform examples.")
 
 ### 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).
-
-### KVM (experimental)
+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.
 
-The KVM platform allows the Sentry to act as both guest OS and VMM, switching
-back and forth between the two worlds seamlessly. 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.
+Unfortunately, the ptrace platform has high context switch overhead, so system
+call-heavy applications may pay a [performance penalty](./performance.md).
 
-## Gofer
+### KVM
 
-The Gofer is a normal host Linux process. The Gofer is started with each sandbox
-and connected to the Sentry. The Sentry process is started in a restricted
-seccomp container without access to file system resources. The Gofer provides
-the Sentry access to file system resources via the 9P protocol and provides an
-additional level of isolation.
+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.
 
-## Application
+## Changing Platforms
 
-The application (aka the untrusted application) is a normal Linux binary
-provided to gVisor in an OCI runtime bundle. gVisor aims to provide an
-environment equivalent to Linux v4.4, so applications should be able to run
-unmodified. However, gVisor does not presently implement every system call,
-/proc file, or /sys file so some incompatibilities may occur.
+See [Changing Platforms](../user_guide/platforms.md).
 
-[oci]: https://www.opencontainers.org
-[runtime-spec]: https://github.com/opencontainers/runtime-spec
+[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