mirrors/crosvm
1
0
Fork 0
mirror of https://chromium.googlesource.com/crosvm/crosvm synced 2025-01-26 10:21:00 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: book: update architecture docs

Browse source 
This cleans up some of the more egregiously outdated information, but
it could probably use a more thorough rewrite at some point.

Change-Id: I6a1f440f9e9500ae85d0c93cb6b1123e3f1ba3c1
Reviewed-on: https://chromium-review.googlesource.com/c/crosvm/crosvm/+/4578297
Commit-Queue: Daniel Verkamp <dverkamp@chromium.org>
Reviewed-by: Zihan Chen <zihanchen@google.com>
This commit is contained in:
Daniel Verkamp 2023-05-31 16:19:43 -07:00 committed by crosvm LUCI
parent 929acf6534
commit c7813cb229
1 changed files with 22 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
ARCHITECTURE.md
View file

@ -2,20 +2,20 @@
The principle characteristics of crosvm are: The principle characteristics of crosvm are:
- A process per virtual device, made using fork - A process per virtual device, made using fork on Linux
- Each process is sandboxed using [minijail] - Each process is sandboxed using [minijail]
- Takes full advantage of KVM and low-level Linux syscalls, and so only runs on Linux - Support for several CPU architectures, operating systems, and [hypervisors]
- Written in Rust for security and safety - Written in Rust for security and safety
A typical session of crosvm starts in `main.rs` where command line parsing is done to build up a A typical session of crosvm starts in `main.rs` where command line parsing is done to build up a
`Config` structure. The `Config` is used by `run_config` in `linux/mod.rs` to setup and execute a `Config` structure. The `Config` is used by `run_config` in `src/crosvm/sys/unix.rs` to setup and
VM. Broken down into rough steps: execute a VM. Broken down into rough steps:
1. Load the linux kernel from an ELF file. 1. Load the Linux kernel from an ELF or bzImage file.
1. Create a handful of control sockets used by the virtual devices. 1. Create a handful of control sockets used by the virtual devices.
1. Invoke the architecture specific VM builder `Arch::build_vm` (located in `x86_64/src/lib.rs` or 1. Invoke the architecture-specific VM builder `Arch::build_vm` (located in `x86_64/src/lib.rs`,
`aarch64/src/lib.rs`). `aarch64/src/lib.rs`, or `riscv64/src/lib.rs`).
1. `Arch::build_vm` will itself invoke the provided `create_devices` function from `linux/mod.rs` 1. `Arch::build_vm` will create a `RunnableLinuxVm` to represent a virtual machine instance.
1. `create_devices` creates every PCI device, including the virtio devices, that were configured in 1. `create_devices` creates every PCI device, including the virtio devices, that were configured in
`Config`, along with matching [minijail] configs for each. `Config`, along with matching [minijail] configs for each.
1. `Arch::assign_pci_addresses` assigns an address to each PCI device, prioritizing devices that 1. `Arch::assign_pci_addresses` assigns an address to each PCI device, prioritizing devices that
@ -47,7 +47,7 @@ each supported architecture.
## The VM Control Sockets ## The VM Control Sockets
For the operations that devices need to perform on the global VM state, such as mapping into guest For the operations that devices need to perform on the global VM state, such as mapping into guest
memory address space, there are the vm control sockets. There are a few kinds, split by the type of memory address space, there are the VM control sockets. There are a few kinds, split by the type of
request and response that the socket will process. This also proves basic security privilege request and response that the socket will process. This also proves basic security privilege
separation in case a device becomes compromised by a malicious guest. For example, a rogue device separation in case a device becomes compromised by a malicious guest. For example, a rogue device
that is able to allocate MSI routes would not be able to use the same socket to (de)register guest that is able to allocate MSI routes would not be able to use the same socket to (de)register guest
@ -59,7 +59,7 @@ main process's control loop.
The socket exposed by crosvm with the `--socket` command line argument is another form of the VM The socket exposed by crosvm with the `--socket` command line argument is another form of the VM
control socket. Because the protocol of the control socket is internal and unstable, the only control socket. Because the protocol of the control socket is internal and unstable, the only
supported way of using that resulting named unix domain socket is via crosvm command line supported way of using that resulting named unix domain socket is via crosvm command line
subcommands such as `crosvm stop`. subcommands such as `crosvm stop` or programmatically via the [`crosvm_control`] library.
## GuestMemory ## GuestMemory
@ -202,10 +202,8 @@ receiving descriptors alongside the plain old bytes that serde consumes.
Source code is organized into crates, each with their own unit tests. Source code is organized into crates, each with their own unit tests.
- `./src/` - The top-level binary front-end for using crosvm. - `./src/` - The top-level binary front-end for using crosvm.
- `aarch64` - Support code specific to 64 bit ARM architectures. - `aarch64` - Support code specific to 64-bit ARM architectures.
- `base` - Safe wrappers for system facilities which provides cross-platform-compatible interfaces. - `base` - Safe wrappers for system facilities which provides cross-platform-compatible interfaces.
- `bin` - Scripts for code health such as wrappers of `rustfmt` and `clippy`.
- `ci` - Scripts for continuous integration.
- `cros_async` - Runtime for async/await programming. This crate provides a `Future` executor based - `cros_async` - Runtime for async/await programming. This crate provides a `Future` executor based
on `io_uring` and one based on `epoll`. on `io_uring` and one based on `epoll`.
- `devices` - Virtual devices exposed to the guest OS. - `devices` - Virtual devices exposed to the guest OS.
@ -213,7 +211,11 @@ Source code is organized into crates, each with their own unit tests.
- `hypervisor` - Abstract layer to interact with hypervisors. For Linux, this crate is a wrapper of - `hypervisor` - Abstract layer to interact with hypervisors. For Linux, this crate is a wrapper of
`kvm`. `kvm`.
- `e2e_tests` - End-to-end tests that run a crosvm VM. - `e2e_tests` - End-to-end tests that run a crosvm VM.
- `kernel_loader` - Loads elf64 kernel files to a slice of memory. - `infra` - Infrastructure recipes for continuous integration testing.
- `jail` - Sandboxing helper library for Linux.
- `jail/seccomp` - Contains minijail seccomp policy files for each sandboxed device. Because some
syscalls vary by architecture, the seccomp policies are split by architecture.
- `kernel_loader` - Loads kernel images in various formats to a slice of memory.
- `kvm_sys` - Low-level (mostly) auto-generated structures and constants for using KVM. - `kvm_sys` - Low-level (mostly) auto-generated structures and constants for using KVM.
- `kvm` - Unsafe, low-level wrapper code for using `kvm_sys`. - `kvm` - Unsafe, low-level wrapper code for using `kvm_sys`.
- `media/libvda` - Safe wrapper of [libvda], a ChromeOS HW-accelerated video decoding/encoding - `media/libvda` - Safe wrapper of [libvda], a ChromeOS HW-accelerated video decoding/encoding
@ -222,21 +224,22 @@ Source code is organized into crates, each with their own unit tests.
devices. devices.
- `net_util` - Wrapper for creating TUN/TAP devices. - `net_util` - Wrapper for creating TUN/TAP devices.
- `qcow_util` - A library and a binary to manipulate [qcow] disks. - `qcow_util` - A library and a binary to manipulate [qcow] disks.
- `seccomp` - Contains minijail seccomp policy files for each sandboxed device. Because some
syscalls vary by architecture, the seccomp policies are split by architecture.
- `sync` - Our version of `std::sync::Mutex` and `std::sync::Condvar`. - `sync` - Our version of `std::sync::Mutex` and `std::sync::Condvar`.
- `third_party` - Third-party libraries which we are maintaining on the ChromeOS tree or the AOSP - `third_party` - Third-party libraries which we are maintaining on the ChromeOS tree or the AOSP
tree. tree.
- `tools` - Scripts for code health such as wrappers of `rustfmt` and `clippy`.
- `vfio_sys` - Low-level (mostly) auto-generated structures, constants and ioctls for [VFIO]. - `vfio_sys` - Low-level (mostly) auto-generated structures, constants and ioctls for [VFIO].
- `vhost` - Wrappers for creating vhost based devices. - `vhost` - Wrappers for creating vhost based devices.
- `virtio_sys` - Low-level (mostly) auto-generated structures and constants for interfacing with - `virtio_sys` - Low-level (mostly) auto-generated structures and constants for interfacing with
kernel vhost support. kernel vhost support.
- `vm_control` - IPC for the VM. - `vm_control` - IPC for the VM.
- `vm_memory` - Vm-specific memory objects. - `vm_memory` - VM-specific memory objects.
- `x86_64` - Support code specific to 64 bit intel machines. - `x86_64` - Support code specific to 64-bit x86 machines.
[hypervisors]: https://crosvm.dev/book/hypervisors.html
[libvda]: https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/main/arc/vm/libvda/ [libvda]: https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/main/arc/vm/libvda/
[minijail]: https://android.googlesource.com/platform/external/minijail [minijail]: https://crosvm.dev/book/appendix/minijail.html
[qcow]: https://en.wikipedia.org/wiki/Qcow [qcow]: https://en.wikipedia.org/wiki/Qcow
[vfio]: https://www.kernel.org/doc/html/latest/driver-api/vfio.html [vfio]: https://www.kernel.org/doc/html/latest/driver-api/vfio.html
[`crosvm_control`]: https://crosvm.dev/book/running_crosvm/programmatic_interaction.html
[`waitcontext`]: https://crosvm.dev/doc/base/struct.WaitContext.html [`waitcontext`]: https://crosvm.dev/doc/base/struct.WaitContext.html