Struct crosvm::crosvm::cmdline::RunCommand

pub struct RunCommand {

    pub ac_adapter: Option<bool>,
    pub acpi_table: Vec<PathBuf>,
    pub android_display_service: Option<String>,
    pub android_fstab: Option<PathBuf>,
    pub async_executor: Option<ExecutorKind>,
    pub balloon_bias_mib: Option<i64>,
    pub balloon_control: Option<PathBuf>,
    pub balloon_page_reporting: Option<bool>,
    pub balloon_ws_num_bins: Option<u8>,
    pub balloon_ws_reporting: Option<bool>,
    pub battery: Option<BatteryConfig>,
    pub bios: Option<PathBuf>,
    block: Vec<DiskOptionWithId>,
    pub boost_uclamp: Option<bool>,
    pub break_linux_pci_config_io: Option<bool>,
    pub bus_lock_ratelimit: Option<u64>,
    cfg: Vec<Self>,
    pub cid: Option<u64>,
    pub coiommu: Option<CoIommuParameters>,
    pub core_scheduling: bool,
    pub cpu_affinity: Option<VcpuAffinity>,
    pub cpu_capacity: Option<BTreeMap<usize, u32>>,
    pub cpu_cluster: Vec<CpuSet>,
    pub cpus: Option<CpuOptions>,
    pub crash_pipe_name: Option<String>,
    pub delay_rt: Option<bool>,
    pub device_tree_overlay: Vec<DtboOption>,
    pub disable_sandbox: Option<bool>,
    pub disable_virtio_intx: Option<bool>,
    disk: Vec<DiskOptionWithId>,
    pub display_window_keyboard: Option<bool>,
    pub display_window_mouse: Option<bool>,
    dump_cfg: Option<PathBuf>,
    pub dump_device_tree_blob: Option<PathBuf>,
    pub dynamic_power_coefficient: Option<BTreeMap<usize, u32>>,
    pub enable_fw_cfg: Option<bool>,
    pub enable_hwp: Option<bool>,
    pub evdev: Vec<PathBuf>,
    pub fdt_position: Option<FdtPosition>,
    pub file_backed_mapping: Vec<FileBackedMappingParameters>,
    pub force_calibrated_tsc_leaf: Option<bool>,
    pub fw_cfg: Vec<FwCfgParameters>,
    pub gdb: Option<u32>,
    pub gpu: Vec<FixedGpuParameters>,
    pub gpu_cgroup_path: Option<PathBuf>,
    pub gpu_display: Vec<FixedGpuDisplayParameters>,
    pub gpu_render_server: Option<GpuRenderServerParameters>,
    pub gpu_server_cgroup_path: Option<PathBuf>,
    pub host_cpu_topology: Option<bool>,
    pub host_ip: Option<Ipv4Addr>,
    pub hugepages: Option<bool>,
    pub hypervisor: Option<HypervisorKind>,
    pub init_mem: Option<u64>,
    pub initrd: Option<PathBuf>,
    pub input: Vec<InputDeviceOption>,
    pub irqchip: Option<IrqChipKind>,
    pub itmt: Option<bool>,
    pub kernel: Option<PathBuf>,
    pub keyboard: Vec<PathBuf>,
    pub kvm_device: Option<PathBuf>,
    pub lock_guest_memory: Option<bool>,
    pub mac_address: Option<MacAddress>,
    pub mem: Option<MemOptions>,
    pub mmio_address_range: Option<Vec<AddressRange>>,
    pub mouse: Vec<PathBuf>,
    pub multi_touch: Vec<TouchDeviceOption>,
    pub name: Option<String>,
    pub net: Vec<NetParameters>,
    pub net_vq_pairs: Option<u16>,
    pub netmask: Option<Ipv4Addr>,
    pub no_balloon: Option<bool>,
    pub no_i8042: Option<bool>,
    pub no_rng: Option<bool>,
    pub no_rtc: Option<bool>,
    pub no_smt: Option<bool>,
    pub no_usb: Option<bool>,
    pub oem_strings: Vec<String>,
    pub params: Vec<String>,
    pub pci: Option<PciConfig>,
    pub pci_hotplug_slots: Option<u8>,
    pub pci_start: Option<u64>,
    pub per_vm_core_scheduling: Option<bool>,
    pub pflash: Option<PflashParameters>,
    pub pivot_root: Option<PathBuf>,
    pub plugin: Option<PathBuf>,
    pub plugin_gid_map: Vec<GidMap>,
    pub plugin_gid_map_file: Option<PathBuf>,
    pub plugin_mount: Vec<BindMount>,
    pub plugin_mount_file: Option<PathBuf>,
    pub plugin_root: Option<PathBuf>,
    pub pmem: Vec<PmemOption>,
    pmem_device: Vec<DiskOption>,
    pub pmem_ext2: Vec<PmemExt2Option>,
    pub protected_vm: Option<bool>,
    pub protected_vm_with_firmware: Option<PathBuf>,
    protected_vm_without_firmware: Option<bool>,
    pub pstore: Option<Pstore>,
    pub pvclock: Option<bool>,
    pub restore: Option<PathBuf>,
    root: Option<DiskOptionWithId>,
    pub rotary: Vec<PathBuf>,
    pub rt_cpus: Option<CpuSet>,
    rw_pmem_device: Vec<DiskOption>,
    rwdisk: Vec<DiskOptionWithId>,
    rwroot: Option<DiskOptionWithId>,
    pub s2idle: Option<bool>,
    scsi_block: Vec<ScsiOption>,
    pub seccomp_log_failures: Option<bool>,
    pub seccomp_policy_dir: Option<PathBuf>,
    pub serial: Vec<SerialParameters>,
    pub shared_dir: Vec<SharedDir>,
    pub simple_media_device: Option<bool>,
    pub single_touch: Vec<TouchDeviceOption>,
    pub smbios: Option<SmbiosOptions>,
    pub socket: Option<PathBuf>,
    pub sound: Option<PathBuf>,
    pub split_irqchip: Option<bool>,
    pub stub_pci_device: Vec<StubPciParameters>,
    pub suspended: Option<bool>,
    pub swap_dir: Option<PathBuf>,
    pub swiotlb: Option<u64>,
    pub switches: Vec<PathBuf>,
    pub syslog_tag: Option<String>,
    pub tap_fd: Vec<RawDescriptor>,
    pub tap_name: Vec<String>,
    pub trackpad: Vec<TouchDeviceOption>,
    pub unmap_guest_memory_on_fork: Option<bool>,
    pub unprotected_vm_with_firmware: Option<PathBuf>,
    pub v4l2_proxy: Vec<PathBuf>,
    pub vcpu_cgroup_path: Option<PathBuf>,
    pub vfio: Vec<VfioOption>,
    pub vfio_isolate_hotplug: Option<bool>,
    pub vfio_platform: Vec<VfioOption>,
    pub vhost_net: Option<bool>,
    pub vhost_net_device: Option<PathBuf>,
    pub vhost_user: Vec<VhostUserFrontendOption>,
    pub vhost_user_blk: Vec<VhostUserOption>,
    pub vhost_user_connect_timeout_ms: Option<u64>,
    pub vhost_user_console: Vec<VhostUserOption>,
    pub vhost_user_fs: Vec<VhostUserFsOption>,
    pub vhost_user_gpu: Vec<VhostUserOption>,
    pub vhost_user_mac80211_hwsim: Option<VhostUserOption>,
    pub vhost_user_net: Vec<VhostUserOption>,
    pub vhost_user_snd: Vec<VhostUserOption>,
    pub vhost_user_video_decoder: Vec<VhostUserOption>,
    pub vhost_user_vsock: Vec<VhostUserOption>,
    pub vhost_user_wl: Option<VhostUserOption>,
    pub vhost_vsock_device: Option<PathBuf>,
    pub vhost_vsock_fd: Option<RawDescriptor>,
    pub video_decoder: Vec<VideoDeviceConfig>,
    pub video_encoder: Vec<VideoDeviceConfig>,
    pub virtio_snd: Vec<Parameters>,
    pub vsock: Option<VsockConfig>,
    pub vtpm_proxy: Option<bool>,
    pub wayland_sock: Vec<(String, PathBuf)>,
    pub x_display: Option<String>,
}

User-specified configuration for the crosvm run command.

All fields of this structure MUST be either an Option or a Vec of their type. Arguments of type Option can only be specified once, whereas Vec arguments can be specified several times.

Each field of this structure has a dual use:

1. As a command-line parameter, controlled by the #[argh] helper attribute.
2. As a configuration file parameter, controlled by the #[serde] helper attribute.

For consistency, field names should be the same and use kebab-case for both uses, so please refrain from using renaming directives and give the field the desired parameter name (it will automatically be converted to kebab-case).

For consistency and convenience, all parameters should be deserializable by serde_keyvalue, as this will automatically provide the same schema for both the command-line and configuration file. This is particularly important for fields that are enums or structs, for which extra parameters can be specified. Make sure to annotate your struct/enum with #[serde(deny_unknown_fields, rename_all = "kebab-case")] so invalid fields are properly rejected and all members are converted to kebab-case.

Each field should also have a #[merge] helper attribute, which defines the strategy to use when merging two configurations into one. This happens when e.g. the user has specified extra command-line arguments along with a configuration file. In this case, the RunCommand created from the command-line arguments will be merged into the RunCommand deserialized from the configuration file.

The rule of thumb for #[merge] attributes is that parameters that can only be specified once (of Option type) should be overridden (#[merge(strategy = overwrite_option)]), while parameters that can be specified several times (typically of Vec type) should be appended (#[merge(strategy = append)]), but there might also be exceptions.

The command-line is the root configuration source, but one or more configuration files can be specified for inclusion using the --cfg argument. Configuration files are applied in the order they are mentioned, overriding (for Option fields) or augmenting (for Vec fields) their fields, and the command-line options are finally applied last.

A configuration files can also include other configuration files by using cfg itself. Included configuration files are applied first, with the parent configuration file applied last.

The doccomment of the member will be displayed as its help message with --help.

Note that many parameters are marked with #[serde(skip)] and annotated with b/255223604. This is because we only want to enable parameters in the config file after they undergo a proper review to make sure they won’t be obsoleted.

Fields

ac_adapter: Option<bool>

enable AC adapter device
It purpose is to emulate ACPI ACPI0003 device, replicate and propagate the ac adapter status from the host to the guest.

acpi_table: Vec<PathBuf>

path to user provided ACPI table

android_display_service: Option<String>

name that the Android display backend will be registered to the service manager.

android_fstab: Option<PathBuf>

path to Android fstab

async_executor: Option<ExecutorKind>

configure async executor backend; “uring” or “epoll” on Linux, “handle” or “overlapped” on Windows. If this option is omitted on Linux, “epoll” is used by default.

balloon_bias_mib: Option<i64>

amount to bias balance of memory between host and guest as the balloon inflates, in mib.

balloon_control: Option<PathBuf>

path for balloon controller socket.

balloon_page_reporting: Option<bool>

enable page reporting in balloon.

balloon_ws_num_bins: Option<u8>

set number of WS bins to use (default = 4).

balloon_ws_reporting: Option<bool>

enable working set reporting in balloon.

battery: Option<BatteryConfig>

comma separated key=value pairs for setting up battery
device
Possible key values:
type=goldfish - type of battery emulation, defaults to
goldfish

bios: Option<PathBuf>

path to BIOS/firmware ROM

block: Vec<DiskOptionWithId>

parameters for setting up a block device.
Valid keys:
path=PATH - Path to the disk image. Can be specified
without the key as the first argument.
ro=BOOL - Whether the block should be read-only.
(default: false)
root=BOOL - Whether the block device should be mounted
as the root filesystem. This will add the required
parameters to the kernel command-line. Can only be
specified once. (default: false)
sparse=BOOL - Indicates whether the disk should support the discard operation. (default: true)
block-size=BYTES - Set the reported block size of the
disk. (default: 512)
id=STRING - Set the block device identifier to an ASCII string, up to 20 characters. (default: no ID)
direct=BOOL - Use O_DIRECT mode to bypass page cache.
(default: false)
async-executor=epoll|uring - set the async executor kind to simulate the block device with. This takes
precedence over the global –async-executor option. multiple-workers=BOOL - (Experimental) run multiple
worker threads in parallel. this option is not
effective for vhost-user blk device.
(default: false)
packed-queue=BOOL - Use packed virtqueue
in block device. If false, use split virtqueue.
(default: false)
bootindex=NUM - An index dictating the order that the
firmware will consider devices to boot from.
For example, if bootindex=2, then the BIOS
will attempt to boot from the current device
after failing to boot from the device with
bootindex=1.
pci-address=ADDR - Preferred PCI address, e.g. “00:01.0”.

boost_uclamp: Option<bool>

set a minimum utilization for vCPU threads which will hint to the host scheduler to ramp up higher frequencies or place vCPU threads on larger cores.

break_linux_pci_config_io: Option<bool>

break linux PCI configuration space io probing, to force the use of mmio access to PCIe ECAM.

bus_lock_ratelimit: Option<u64>

ratelimit enforced on detected bus locks in guest.
The default value of the bus_lock_ratelimit is 0 per second, which means no limitation on the guest’s bus locks.

cfg: Vec<Self>

path to a JSON configuration file to load.

The options specified in the file can be overridden or augmented by subsequent uses of this argument, or other command-line parameters.

cid: Option<u64>

context ID for virtual sockets.

coiommu: Option<CoIommuParameters>

comma separated key=value pairs for setting up coiommu
devices.
Possible key values:
unpin_policy=lru - LRU unpin policy.
unpin_interval=NUM - Unpin interval time in seconds.
unpin_limit=NUM - Unpin limit for each unpin cycle, in
unit of page count. 0 is invalid.
unpin_gen_threshold=NUM - Number of unpin intervals a
pinned page must be busy for to be aged into the
older which is less frequently checked generation.

core_scheduling: bool

protect VM threads from hyperthreading-based attacks by scheduling them on different cores. Enabled by default, and required for per_vm_core_scheduling.

cpu_affinity: Option<VcpuAffinity>

comma-separated list of CPUs or CPU ranges to run VCPUs on (e.g. 0,1-3,5) or colon-separated list of assignments of guest to host CPU assignments (e.g. 0=0:1=1:2=2) (default: no mask)

cpu_capacity: Option<BTreeMap<usize, u32>>

set the relative capacity of the given CPU (default: no capacity)

cpu_cluster: Vec<CpuSet>

group the given CPUs into a cluster (default: no clusters)

cpus: Option<CpuOptions>

cpu parameters.
Possible key values:
num-cores=NUM - number of VCPUs. (default: 1)
clusters=[[CLUSTER],…] - CPU clusters (default: None) Each CLUSTER is a set containing a list of CPUs
that should belong to the same cluster. Individual
CPU ids or ranges can be specified, comma-separated.
Examples:
clusters=[[0],[1],[2],[3]] - creates 4 clusters, one
for each specified core.
clusters=[[0-3]] - creates a cluster for cores 0 to 3 included.
clusters=[[0,2],[1,3],[4-7,12]] - creates one cluster for cores 0 and 2, another one for cores 1 and 3,
and one last for cores 4, 5, 6, 7 and 12.
core-types=[atom=[CPUSET],core=[CPUSET]] - Hybrid core
types. (default: None)
Set the type of virtual hybrid CPUs. Currently
supports Intel Atom and Intel Core cpu types.
Examples:
core-types=[atom=[0,1],core=[2,3]] - set vCPU 0 and
vCPU 1 as intel Atom type, also set vCPU 2 and vCPU 3 as intel Core type.
boot-cpu=NUM - Select vCPU to boot from. (default: 0) (aarch64 only) freq_domains=[[FREQ_DOMAIN],…] - CPU freq_domains (default: None) (aarch64 only) Usage is identical to clusters, each FREQ_DOMAIN is a set containing a list of CPUs that should belong to the same freq_domain. Individual CPU ids or ranges can be specified, comma-separated.
Examples:
freq_domains=[[0],[1],[2],[3]] - creates 4 freq_domains, one for each specified core.
freq_domains=[[0-3]] - creates a freq_domain for cores 0 to 3 included.
freq_domains=[[0,2],[1,3],[4-7,12]] - creates one freq_domain for cores 0 and 2, another one for cores 1 and 3,
and one last for cores 4, 5, 6, 7 and 12.
sve=[enabled=bool] - SVE Config. (aarch64 only)
Examples:
sve=[enabled=true] - Enables SVE on device. Will fail is SVE unsupported. default value = false.

crash_pipe_name: Option<String>

the crash handler ipc pipe name.

delay_rt: Option<bool>

don’t set VCPUs real-time until make-rt command is run

device_tree_overlay: Vec<DtboOption>

path to device tree overlay binary which will be applied to the base guest device tree Parameters:
filter - only apply device tree nodes which belong to a VFIO device

disable_sandbox: Option<bool>

run all devices in one, non-sandboxed process

disable_virtio_intx: Option<bool>

disable INTx in virtio devices

disk: Vec<DiskOptionWithId>

path to a disk image followed by optional comma-separated
options.
Valid keys:
sparse=BOOL - Indicates whether the disk should support
the discard operation (default: true)
block_size=BYTES - Set the reported block size of the
disk (default: 512)
id=STRING - Set the block device identifier to an ASCII
string, up to 20 characters (default: no ID)
o_direct=BOOL - Use O_DIRECT mode to bypass page cache“

display_window_keyboard: Option<bool>

capture keyboard input from the display window

display_window_mouse: Option<bool>

capture keyboard input from the display window

dump_cfg: Option<PathBuf>

path to a JSON configuration file to write the current configuration.

dump_device_tree_blob: Option<PathBuf>

dump generated device tree as a DTB file

dynamic_power_coefficient: Option<BTreeMap<usize, u32>>

pass power modeling param from to guest OS; scalar coefficient used in conjuction with voltage and frequency for calculating power; in units of uW/MHz/^2

enable_fw_cfg: Option<bool>

enable the fw_cfg device. If enabled, fw_cfg will automatically produce firmware configuration files containing such information as bootorder and the memory location of rsdp. If –fw-cfg is specified (see below), there is no need for this argument.

enable_hwp: Option<bool>

expose HWP feature to the guest

evdev: Vec<PathBuf>

path to an event device node. The device will be grabbed (unusable from the host) and made available to the guest with the same configuration it shows on the host

fdt_position: Option<FdtPosition>

where the FDT is placed in memory.

On x86_64, no effect.

On aarch64, defaults to end for kernel payloads and to start for BIOS payloads.

On riscv64, defaults to after-payload.

file_backed_mapping: Vec<FileBackedMappingParameters>

map the given file into guest memory at the specified
address.
Parameters (addr, size, path are required):
addr=NUM - guest physical address to map at
size=NUM - amount of memory to map
path=PATH - path to backing file/device to map
offset=NUM - offset in backing file (default 0)
rw - make the mapping writable (default readonly)
sync - open backing file with O_SYNC
align - whether to adjust addr and size to page
boundaries implicitly

force_calibrated_tsc_leaf: Option<bool>

force use of a calibrated TSC cpuid leaf (0x15) even if the hypervisor doesn’t require one.

fw_cfg: Vec<FwCfgParameters>

comma separated key=value pairs to specify data to pass to
fw_cfg.
Possible key values:
name - Name of the file in fw_cfg that will
be associated with provided data
path - Path to data that will be included in
fw_cfg under name
string - Alternative to path, data to be
included in fw_cfg under name

gdb: Option<u32>

(EXPERIMENTAL) gdb on the given port

gpu: Vec<FixedGpuParameters>

(EXPERIMENTAL) Comma separated key=value pairs for setting
up a virtio-gpu device
Possible key values:
backend=(2d|virglrenderer|gfxstream) - Which backend to use for virtio-gpu (determining rendering protocol)
max-num-displays=INT - The maximum number of concurrent virtual displays in this VM. This must not exceed
VIRTIO_GPU_MAX_SCANOUTS (i.e. 16).
displays=[GpuDisplayParameters] - The list of virtual displays to create when booting this VM. Displays may be hotplugged after booting. See the possible key
values for GpuDisplayParameters in the section below. context-types=LIST - The list of supported context
types, separated by ‘:’ (default: no contexts enabled) width=INT - The width of the virtual display connected
to the virtio-gpu.
Deprecated - use displays instead.
height=INT - The height of the virtual display
connected to the virtio-gpu.
Deprecated - use displays instead.
egl[=true|=false] - If the backend should use a EGL
context for rendering.
glx[=true|=false] - If the backend should use a GLX
context for rendering.
surfaceless[=true|=false] - If the backend should use a surfaceless context for rendering.
angle[=true|=false] - If the gfxstream backend should
use ANGLE (OpenGL on Vulkan) as its native OpenGL
driver.
vulkan[=true|=false] - If the backend should support
vulkan
wsi=vk - If the gfxstream backend should use the Vulkan swapchain to draw on a window
cache-path=PATH - The path to the virtio-gpu device
shader cache.
cache-size=SIZE - The maximum size of the shader cache. pci-address=ADDR - The PCI bus, device, and function
numbers, e.g. “00:01.0”
pci-bar-size=SIZE - The size for the PCI BAR in bytes
(default 8gb).
implicit-render-server[=true|=false] - If the render
server process should be allowed to autostart
(ignored when sandboxing is enabled)
fixed-blob-mapping[=true|=false] - if gpu memory blobs
should use fixed address mapping.

Possible key values for GpuDisplayParameters:
mode=(borderless_full_screen|windowed[width,height]) -
Whether to show the window on the host in full
screen or windowed mode. If not specified, windowed
mode is used by default. “windowed” can also be
specified explicitly to use a window size different
from the default one.
hidden[=true|=false] - If the display window is
initially hidden (default: false).
refresh-rate=INT - Force a specific vsync generation
rate in hertz on the guest (default: 60)
dpi=[INT,INT] - The horizontal and vertical DPI of the
display (default: [320,320])
horizontal-dpi=INT - The horizontal DPI of the display
(default: 320)
Deprecated - use dpi instead.
vertical-dpi=INT - The vertical DPI of the display
(default: 320)
Deprecated - use dpi instead.

gpu_cgroup_path: Option<PathBuf>

move all vGPU threads to this Cgroup (default: nothing moves)

gpu_display: Vec<FixedGpuDisplayParameters>

(EXPERIMENTAL) Comma separated key=value pairs for setting
up a display on the virtio-gpu device. See comments for gpu for possible key values of GpuDisplayParameters.

gpu_render_server: Option<GpuRenderServerParameters>

(EXPERIMENTAL) Comma separated key=value pairs for setting
up a render server for the virtio-gpu device
Possible key values:
path=PATH - The path to the render server executable.
cache-path=PATH - The path to the render server shader
cache.
cache-size=SIZE - The maximum size of the shader cache
foz-db-list-path=PATH - The path to GPU foz db list
file for dynamically loading RO caches.

gpu_server_cgroup_path: Option<PathBuf>

move all vGPU server threads to this Cgroup (default: nothing moves)

host_cpu_topology: Option<bool>

use mirror cpu topology of Host for Guest VM, also copy some cpu feature to Guest VM

host_ip: Option<Ipv4Addr>

IP address to assign to host tap interface

hugepages: Option<bool>

advise the kernel to use Huge Pages for guest memory mappings

hypervisor: Option<HypervisorKind>

hypervisor backend

init_mem: Option<u64>

amount of guest memory outside the balloon at boot in MiB. (default: –mem)

initrd: Option<PathBuf>

initial ramdisk to load

input: Vec<InputDeviceOption>

virtio-input device
TYPE is an input device type, and OPTIONS are key=value
pairs specific to the device type:
evdev[path=PATH]
keyboard[path=PATH]
mouse[path=PATH]
multi-touch[path=PATH,width=W,height=H,name=N]
rotary[path=PATH]
single-touch[path=PATH,width=W,height=H,name=N]
switches[path=PATH]
trackpad[path=PATH,width=W,height=H,name=N]
multi-touch-trackpad[path=PATH,width=W,height=H,name=N] See https://crosvm.dev/book/devices/input.html for more
information.

irqchip: Option<IrqChipKind>

type of interrupt controller emulation. “split” is only available for x86 KVM.

itmt: Option<bool>

allow to enable ITMT scheduling feature in VM. The success of enabling depends on HWP and ACPI CPPC support on hardware

kernel: Option<PathBuf>

bzImage of kernel to run

keyboard: Vec<PathBuf>

path to a socket from where to read keyboard input events and write status updates to

kvm_device: Option<PathBuf>

path to the KVM device. (default /dev/kvm)

lock_guest_memory: Option<bool>

disable host swap on guest VM pages.

mac_address: Option<MacAddress>

MAC address for VM

mem: Option<MemOptions>

memory parameters.
Possible key values:
size=NUM - amount of guest memory in MiB. (default: 256)

mmio_address_range: Option<Vec<AddressRange>>

MMIO address ranges

mouse: Vec<PathBuf>

path to a socket from where to read mouse input events and write status updates to

multi_touch: Vec<TouchDeviceOption>

path to a socket from where to read multi touch input events (such as those from a touchscreen) and write status updates to, optionally followed by width and height (defaults to 800x1280) and a name for the input device

name: Option<String>

optional name for the VM. This is used as the name of the crosvm process which is helpful to distinguish multiple crosvm processes. A name longer than 15 bytes is truncated on Linux-like OSes. This is no-op on Windows and MacOS at the moment.

net: Vec<NetParameters>

comma separated key=value pairs for setting up a network
device.
Possible key values:
(
tap-name=STRING - name of a configured persistent TAP
interface to use for networking.
mac=STRING - MAC address for VM. [Optional]
OR
tap-fd=INT - File descriptor for configured tap
device.
mac=STRING - MAC address for VM. [Optional]
OR
(
host-ip=STRING - IP address to assign to host tap
interface.
AND
netmask=STRING - Netmask for VM subnet.
AND
mac=STRING - MAC address for VM.
)
)
AND
vhost-net
OR
vhost-net=[device=/vhost_net/device] - use vhost_net.
If the device path is not the default /dev/vhost-net, it can also be
specified.
Default: false. [Optional]
vq-pairs=N - number of rx/tx queue pairs.
Default: 1. [Optional]
packed-queue - use packed queue.
If not set or set to false, it will
use split virtqueue.
Default: false. [Optional]
pci-address - preferred PCI address, e.g. “00:01.0”
Default: automatic PCI address assignment. [Optional]

Either one tap_name, one tap_fd or a triplet of host_ip,
netmask and mac must be specified.

net_vq_pairs: Option<u16>

virtio net virtual queue pairs. (default: 1)

netmask: Option<Ipv4Addr>

netmask for VM subnet

no_balloon: Option<bool>

don’t use virtio-balloon device in the guest

no_i8042: Option<bool>

don’t use legacy KBD devices emulation

no_rng: Option<bool>

don’t create RNG device in the guest

no_rtc: Option<bool>

don’t use legacy RTC devices emulation

no_smt: Option<bool>

don’t use SMT in the guest

no_usb: Option<bool>

don’t use usb devices in the guest

oem_strings: Vec<String>

SMBIOS OEM string values to add to the DMI tables

params: Vec<String>

extra kernel or plugin command line arguments. Can be given more than once

pci: Option<PciConfig>

PCI parameters.

Possible key values:
mem=[start=INT,size=INT] - region for non-prefetchable
PCI device memory below 4G

Possible key values (aarch64 only):
cam=[start=INT,size=INT] - region for PCI Configuration Access Mechanism

Possible key values (x86_64 only):
ecam=[start=INT,size=INT] - region for PCIe Enhanced
Configuration Access Mechanism

pci_hotplug_slots: Option<u8>

number of hotplug slot count (default: None)

pci_start: Option<u64>

the pci mmio start address below 4G

per_vm_core_scheduling: Option<bool>

enable per-VM core scheduling intead of the default one (per-vCPU core scheduing) by making all vCPU threads share same cookie for core scheduling. This option is no-op on devices that have neither MDS nor L1TF vulnerability

pflash: Option<PflashParameters>

comma-seperated key-value pair for setting up the pflash device, which provides space to store UEFI variables. block_size defaults to 4K.
[–pflash <path=PATH,[block_size=SIZE]>]

pivot_root: Option<PathBuf>

path to empty directory to use for sandbox pivot root

plugin: Option<PathBuf>

absolute path to plugin process to run under crosvm

plugin_gid_map: Vec<GidMap>

supplemental GIDs that should be mapped in plugin jail. Can be given more than once

plugin_gid_map_file: Option<PathBuf>

path to the file listing supplemental GIDs that should be mapped in plugin jail. Can be given more than once

plugin_mount: Vec<BindMount>

path to be mounted into the plugin’s root filesystem. Can be given more than once

plugin_mount_file: Option<PathBuf>

path to the file listing paths be mounted into the plugin’s root filesystem. Can be given more than once

plugin_root: Option<PathBuf>

absolute path to a directory that will become root filesystem for the plugin process.

pmem: Vec<PmemOption>

parameters for setting up a virtio-pmem device.
Valid keys:
path=PATH - Path to the disk image. Can be specified
without the key as the first argument.
ro=BOOL - Whether the pmem device should be read-only.
(default: false)
vma-size=BYTES - (Experimental) Size in bytes
of an anonymous virtual memory area that is
created to back this device. When this
option is specified, the disk image path
is used to name the memory area
swap-interval-ms=NUM - (Experimental) Interval
in milliseconds for periodic swap out of
memory mapping created by this device. 0
means the memory mapping won’t be swapped
out by crosvm

pmem_device: Vec<DiskOption>

(DEPRECATED): Use –pmem instead.
path to a disk image

pmem_ext2: Vec<PmemExt2Option>

(EXPERIMENTAL): construct an ext2 file system on a pmem
device from the given directory. The argument is the form of “PATH[,key=value[,key=value[,…]]]”.
Valid keys:
blocks_per_group=NUM - Number of blocks in a block
group. (default: 4096)
inodes_per_group=NUM - Number of inodes in a block
group. (default: 1024)
size=BYTES - Size of the memory region allocated by this device. A file system will be built on the region. If the filesystem doesn’t fit within this size, crosvm
will fail to start with an error.
The number of block groups in the file system is
calculated from this value and other given parameters. The value of size must be larger than (4096 *
blocks_per_group.) (default: 16777216)
uid=UID - uid of the mkfs process in the user
namespace created by minijail. (default: 0)
gid=GID - gid of the mkfs process in the user
namespace created by minijail. (default: 0)
uidmap=UIDMAP - a uid map in the format
“inner outer count[,inner outer count]”. This format
is same as one for minijail.
(default: “0 1”)
gidmap=GIDMAP - a gid map in the same format as uidmap
(default: “0 1”)

protected_vm: Option<bool>

prevent host access to guest memory

protected_vm_with_firmware: Option<PathBuf>

(EXPERIMENTAL/FOR DEBUGGING) Use custom VM firmware to run in protected mode

protected_vm_without_firmware: Option<bool>

(EXPERIMENTAL) prevent host access to guest memory, but don’t use protected VM firmware

pstore: Option<Pstore>

path to pstore buffer backend file followed by size
[–pstore <path=PATH,size=SIZE>]

pvclock: Option<bool>

enable virtio-pvclock.
Only available when crosvm is built with feature ‘pvclock’.

restore: Option<PathBuf>

path of the snapshot that is used to restore the VM on startup.

root: Option<DiskOptionWithId>

path to a disk image followed by optional comma-separated
options.
Valid keys:
sparse=BOOL - Indicates whether the disk should support the discard operation (default: true)
block_size=BYTES - Set the reported block size of the
disk (default: 512)
id=STRING - Set the block device identifier to an ASCII string, up to 20 characters (default: no ID)
o_direct=BOOL - Use O_DIRECT mode to bypass page cache

rotary: Vec<PathBuf>

path to a socket from where to read rotary input events and write status updates to

rt_cpus: Option<CpuSet>

comma-separated list of CPUs or CPU ranges to run VCPUs on. (e.g. 0,1-3,5) (default: none)

rw_pmem_device: Vec<DiskOption>

(DEPRECATED): Use –pmem instead.
path to a writable disk image

rwdisk: Vec<DiskOptionWithId>

path to a read-write disk image followed by optional
comma-separated options.
Valid keys:
sparse=BOOL - Indicates whether the disk should support the discard operation (default: true)
block_size=BYTES - Set the reported block size of the
disk (default: 512)
id=STRING - Set the block device identifier to an ASCII string, up to 20 characters (default: no ID)
o_direct=BOOL - Use O_DIRECT mode to bypass page cache

rwroot: Option<DiskOptionWithId>

path to a read-write root disk image followed by optional
comma-separated options.
Valid keys:
sparse=BOOL - Indicates whether the disk should support the discard operation (default: true)
block_size=BYTES - Set the reported block size of the
disk (default: 512)
id=STRING - Set the block device identifier to an ASCII string, up to 20 characters (default: no ID)
o_direct=BOOL - Use O_DIRECT mode to bypass page cache

s2idle: Option<bool>

set Low Power S0 Idle Capable Flag for guest Fixed ACPI
Description Table, additionally use enhanced crosvm suspend and resume routines to perform full guest suspension/resumption

scsi_block: Vec<ScsiOption>

(EXPERIMENTAL) parameters for setting up a SCSI disk.
Valid keys:
path=PATH - Path to the disk image. Can be specified
without the key as the first argument.
block_size=BYTES - Set the reported block size of the
disk (default: 512)
ro=BOOL - Whether the block should be read-only.
(default: false)
root=BOOL - Whether the scsi device should be mounted
as the root filesystem. This will add the required
parameters to the kernel command-line. Can only be
specified once. (default: false)

seccomp_log_failures: Option<bool>

instead of seccomp filter failures being fatal, they will be logged instead

seccomp_policy_dir: Option<PathBuf>

path to seccomp .policy files

serial: Vec<SerialParameters>

comma separated key=value pairs for setting up serial
devices. Can be given more than once.
Possible key values:
type=(stdout,syslog,sink,file) - Where to route the
serial device.
Platform-specific options:
On Unix: ‘unix’ (datagram) and ‘unix-stream’ (stream) On Windows: ‘namedpipe’
hardware=(serial,virtio-console,debugcon,
legacy-virtio-console) - Which type of
serial hardware to emulate. Defaults to 8250 UART
(serial).
name=NAME - Console Port Name, used for virtio-console
as a tag for identification within the guest.
num=(1,2,3,4) - Serial Device Number. If not provided,
num will default to 1.
debugcon_port=PORT - Port for the debugcon device to
listen to. Defaults to 0x402, which is what OVMF
expects.
path=PATH - The path to the file to write to when
type=file
input=PATH - The path to the file to read from when not stdin
input-unix-stream - (Unix-only) Whether to use the given Unix stream socket for input as well as output.
This flag is only valid when type=unix-stream and
the socket path is specified with path=.
Can’t be passed when input is specified.
console - Use this serial device as the guest console.
Will default to first serial port if not provided.
earlycon - Use this serial device as the early console. Can only be given once.
stdin - Direct standard input to this serial device.
Can only be given once. Will default to first serial port if not provided.
pci-address - Preferred PCI address, e.g. “00:01.0”.

shared_dir: Vec<SharedDir>

colon-separated options for configuring a directory to be
shared with the VM. The first field is the directory to be
shared and the second field is the tag that the VM can use
to identify the device. The remaining fields are key=value
pairs that may appear in any order.
Valid keys are:
type=(p9, fs) - Indicates whether the directory should
be shared via virtio-9p or virtio-fs (default: p9).
uidmap=UIDMAP - The uid map to use for the device’s
jail in the format “inner outer
count[,inner outer count]”
(default: 0 1).
gidmap=GIDMAP - The gid map to use for the device’s
jail in the format “inner outer
count[,inner outer count]”
(default: 0 1).
cache=(never, auto, always) - Indicates whether the VM
can cache the contents of the shared directory
(default: auto). When set to “auto” and the type
is “fs”, the VM will use close-to-open consistency
for file contents.
timeout=SECONDS - How long the VM should consider file
attributes and directory entries to be valid
(default: 5). If the VM has exclusive access to the directory, then this should be a large value. If
the directory can be modified by other processes,
then this should be 0.
writeback=BOOL - Enables writeback caching
(default: false). This is only safe to do when the
VM has exclusive access to the files in a directory. Additionally, the server should have read
permission for all files as the VM may issue read
requests even for files that are opened write-only.
dax=BOOL - Enables DAX support. Enabling DAX can
improve performance for frequently accessed files
by mapping regions of the file directly into the
VM’s memory. There is a cost of slightly increased
latency the first time the file is accessed. Since
the mapping is shared directly from the host kernel’s file cache, enabling DAX can improve performance even when the guest cache policy is “Never”. The default value for this option is “false”.
posix_acl=BOOL - Indicates whether the shared directory supports POSIX ACLs. This should only be enabled
when the underlying file system supports POSIX ACLs. The default value for this option is “true”.
uid=UID - uid of the device process in the user
namespace created by minijail. (default: 0)
gid=GID - gid of the device process in the user
namespace created by minijail. (default: 0)
max_dynamic_perm=uint - Indicates maximum number of
dynamic permissions that the shared directory allows. (default: 0). The fuse server will return EPERM
Error when FS_IOC_SETPERMISSION ioctl is called
in the device if current dyamic permission path is
lager or equal to this value.
max_dynamic_xattr=uint - Indicates maximum number of
dynamic xattrs that the shared directory allows.
(default: 0). The fuse server will return EPERM
Error when FS_IOC_SETPATHXATTR ioctl is called
in the device if current dyamic permission path is
lager or equal to this value.
security_ctx=BOOL - Enables FUSE_SECURITY_CONTEXT
feature(default: true). This should be set to false
in case the when the host not allowing write to
/proc//attr/fscreate, or guest directory does
not care about the security context.
Options uid and gid are useful when the crosvm process
has no CAP_SETGID/CAP_SETUID but an identity mapping of the current user/group between the VM and the host is
required. Say the current user and the crosvm process
has uid 5000, a user can use “uid=5000” and
“uidmap=5000 5000 1” such that files owned by user
5000 still appear to be owned by user 5000 in the VM.
These 2 options are useful only when there is 1 user
in the VM accessing shared files. If multiple users
want to access the shared file, gid/uid options are
useless. It’d be better to create a new user namespace
and give CAP_SETUID/CAP_SETGID to the crosvm.

simple_media_device: Option<bool>

enable the simple virtio-media device, a virtual capture device generating a fixed pattern for testing purposes.

single_touch: Vec<TouchDeviceOption>

path to a socket from where to read single touch input events (such as those from a touchscreen) and write status updates to, optionally followed by width and height (defaults to 800x1280) and a name for the input device

smbios: Option<SmbiosOptions>

SMBIOS table configuration (DMI)
The fields are key=value pairs.
Valid keys are:
bios-vendor=STRING - BIOS vendor name.
bios-version=STRING - BIOS version number (free-form string). manufacturer=STRING - System manufacturer name.
product-name=STRING - System product name.
serial-number=STRING - System serial number.
uuid=UUID - System UUID.
oem-strings=[…] - Free-form OEM strings (SMBIOS type 11).

socket: Option<PathBuf>

path to put the control socket. If PATH is a directory, a name will be generated

sound: Option<PathBuf>

path to the VioS server socket for setting up virtio-snd devices

split_irqchip: Option<bool>

(EXPERIMENTAL) enable split-irqchip support

stub_pci_device: Vec<StubPciParameters>

comma-separated key=value pairs for setting up a stub PCI
device that just enumerates. The first option in the list
must specify a PCI address to claim.
Optional further parameters
vendor=NUM - PCI vendor ID
device=NUM - PCI device ID
class=NUM - PCI class (including class code, subclass,
and programming interface)
subsystem_vendor=NUM - PCI subsystem vendor ID
subsystem_device=NUM - PCI subsystem device ID
revision=NUM - revision

suspended: Option<bool>

start a VM with vCPUs and devices suspended

swap_dir: Option<PathBuf>

enable vmm-swap via an unnamed temporary file on the filesystem which contains the specified directory.

swiotlb: Option<u64>

(EXPERIMENTAL) Size of virtio swiotlb buffer in MiB (default: 64 if --protected-vm or --protected-vm-without-firmware is present)

switches: Vec<PathBuf>

path to a socket from where to read switch input events and write status updates to

syslog_tag: Option<String>

when logging to syslog, use the provided tag

tap_fd: Vec<RawDescriptor>

file descriptor for configured tap device. A different virtual network card will be added each time this argument is given

tap_name: Vec<String>

name of a configured persistent TAP interface to use for networking. A different virtual network card will be added each time this argument is given

trackpad: Vec<TouchDeviceOption>

path to a socket from where to read trackpad input events and write status updates to, optionally followed by screen width and height (defaults to 800x1280) and a name for the input device

unmap_guest_memory_on_fork: Option<bool>

set MADV_DONTFORK on guest memory

Intended for use in combination with –protected-vm, where the guest memory can be dangerous to access. Some systems, e.g. Android, have tools that fork processes and examine their memory. This flag effectively hides the guest memory from those tools.

Not compatible with sandboxing.

unprotected_vm_with_firmware: Option<PathBuf>

(EXPERIMENTAL/FOR DEBUGGING) Use VM firmware, but allow host access to guest memory

v4l2_proxy: Vec<PathBuf>

path to a V4L2 device to expose to the guest using the virtio-media protocol.

vcpu_cgroup_path: Option<PathBuf>

move all vCPU threads to this CGroup (default: nothing moves)

vfio: Vec<VfioOption>

path to sysfs of VFIO device.
guest-address=BUS:DEVICE.FUNCTION - PCI address
that the device will be assigned in the guest.
If not specified, the device will be assigned an
address that mirrors its address in the host.
Only valid for PCI devices.
iommu=viommu|coiommu|pkvm-iommu|off - indicates which type of IOMMU to use for this device.
dt-symbol= - the symbol that labels the device tree node in the device tree overlay file.

vfio_isolate_hotplug: Option<bool>

isolate all hotplugged passthrough vfio device behind virtio-iommu

vfio_platform: Vec<VfioOption>

path to sysfs of platform pass through

vhost_net: Option<bool>

use vhost for networking

vhost_net_device: Option<PathBuf>

path to the vhost-net device. (default /dev/vhost-net)

vhost_user: Vec<VhostUserFrontendOption>

comma separated key=value pairs for connecting to a
vhost-user backend.
Possible key values:
type=TYPE - Virtio device type (net, block, etc.)
socket=SOCKET_PATH - Path to vhost-user socket.
max-queue-size=NUM - Limit maximum queue size (must be a power of two). pci-address=ADDR - Preferred PCI address, e.g. “00:01.0”.

vhost_user_blk: Vec<VhostUserOption>

path to a socket for vhost-user block

vhost_user_connect_timeout_ms: Option<u64>

number of milliseconds to retry if the socket path is missing or has no listener. Defaults to no retries.

vhost_user_console: Vec<VhostUserOption>

path to a socket for vhost-user console

vhost_user_fs: Vec<VhostUserFsOption>

path to a socket path for vhost-user fs, and tag for the shared dir

vhost_user_gpu: Vec<VhostUserOption>

paths to a vhost-user socket for gpu

vhost_user_mac80211_hwsim: Option<VhostUserOption>

path to a socket for vhost-user mac80211_hwsim

vhost_user_net: Vec<VhostUserOption>

path to a socket for vhost-user net

vhost_user_snd: Vec<VhostUserOption>

path to a socket for vhost-user snd

vhost_user_video_decoder: Vec<VhostUserOption>

path to a socket for vhost-user video decoder

vhost_user_vsock: Vec<VhostUserOption>

path to a socket for vhost-user vsock

vhost_user_wl: Option<VhostUserOption>

path to a vhost-user socket for wayland

vhost_vsock_device: Option<PathBuf>

path to the vhost-vsock device. (default /dev/vhost-vsock)

vhost_vsock_fd: Option<RawDescriptor>

open FD to the vhost-vsock device, mutually exclusive with vhost-vsock-device

video_decoder: Vec<VideoDeviceConfig>

(EXPERIMENTAL) enable virtio-video decoder device
Possible backend values: libvda, ffmpeg, vaapi

video_encoder: Vec<VideoDeviceConfig>

(EXPERIMENTAL) enable virtio-video encoder device
Possible backend values: libvda

virtio_snd: Vec<Parameters>

comma separated key=value pairs for setting up virtio snd
devices.
Possible key values:
capture=(false,true) - Disable/enable audio capture.
Default is false.
backend=(null,file,[cras]) - Which backend to use for
virtio-snd.
client_type=(crosvm,arcvm,borealis) - Set specific
client type for cras backend. Default is crosvm.
socket_type=(legacy,unified) Set specific socket type
for cras backend. Default is unified.
playback_path=STR - Set directory of output streams
for file backend.
playback_size=INT - Set size of the output streams
from file backend.
num_output_devices=INT - Set number of output PCM
devices.
num_input_devices=INT - Set number of input PCM devices. num_output_streams=INT - Set number of output PCM
streams per device.
num_input_streams=INT - Set number of input PCM streams per device.

vsock: Option<VsockConfig>

add a vsock device. Since a guest can only have one CID,
this option can only be specified once.
cid=CID - CID to use for the device.
device=VHOST_DEVICE - path to the vhost-vsock device to use (Linux only). Defaults to /dev/vhost-vsock.

vtpm_proxy: Option<bool>

enable the virtio-tpm connection to vtpm daemon

wayland_sock: Vec<(String, PathBuf)>

path to the Wayland socket to use. The unnamed one is used for displaying virtual screens. Named ones are only for IPC

x_display: Option<String>

X11 display name to use

Implementations

impl RunCommand

pub fn squash(self) -> Self

Merge the content of self into self.cfg if it exists, and return the merged configuration in which self.cfg is empty.

Trait Implementations

impl Default for RunCommand

fn default() -> RunCommand

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for RunCommand

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl FromArgs for RunCommand

fn from_args(__cmd_name: &[&str], __args: &[&str]) -> Result<Self, EarlyExit>

Construct the type from an input set of arguments.

fn redact_arg_values( __cmd_name: &[&str], __args: &[&str] ) -> Result<Vec<String>, EarlyExit>

Get a String with just the argument names, e.g., options, flags, subcommands, etc, but without the values of the options and arguments. This can be useful as a means to capture anonymous usage statistics without revealing the content entered by the end user.

impl Merge for RunCommand

fn merge(&mut self, other: Self)

Merge another object into this object.

impl Serialize for RunCommand

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl SubCommand for RunCommand

const COMMAND: &'static CommandInfo = _

Information about the subcommand.

impl TryFrom<RunCommand> for Config

type Error = String

The type returned in the event of a conversion error.

fn try_from(cmd: RunCommand) -> Result<Self, Self::Error>

Performs the conversion.