sdk/fidl/fuchsia.virtualization/guest_config.fidl

// Copyright 2020 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.virtualization;

using fuchsia.hardware.block;
using fuchsia.net;
using fuchsia.io;
using fuchsia.wayland;
using zx;

const MAX_BLOCK_DEVICE_ID uint8 = 20;
const MAX_MEMORY uint8 = 32;
const MAX_BLOCK_DEVICES uint8 = 32;
const MAX_NET_DEVICES uint8 = 32;

/// Type of kernel used by a guest.
type KernelType = strict enum {
    ZIRCON = 0;
    LINUX = 1;
};

/// Properties describing a block device.
type BlockSpec = resource struct {
    /// The ID used to identify the block device.
    id string:MAX_BLOCK_DEVICE_ID;
    /// The access mode for the block device.
    mode @generated_name("BlockMode") strict enum {
        /// Reads and writes are allowed.
        READ_WRITE = 0;
        /// Only reads are allowed.
        READ_ONLY = 1;
        /// Writes are allowed, but are stored in memory, not to disk.
        VOLATILE_WRITE = 2;
    };
    /// The data format of the block device.
    format @generated_name("BlockFormat") strict resource union {
        /// File IO. All reads and writes go directly to disk as a flat file.
        1: file client_end:fuchsia.io.File;
        /// QCOW image. All reads and writes go to a QCOW image.
        2: qcow zx.Handle:CHANNEL;
        /// Block IO. All reads and writes go to a block server.
        3: block client_end:fuchsia.hardware.block.Block;
    };
};

/// Properites describing a network device.
type NetSpec = struct {
    /// MAC address for the network device.
    mac_address fuchsia.net.MacAddress;
    /// Whether to bridge the network device with the host network device.
    enable_bridge bool;
};

/// Properties describing a virtio_wl device.
type WaylandDevice = resource struct {
    /// The amount of guest-physical address space to allocate for virtio_wl
    /// buffers.
    ///
    /// Default to a 1GiB allocation.
    @allow_deprecated_struct_defaults
    memory uint64 = 1073741824;

    /// The server for new virtio_wl connections.
    server client_end:<fuchsia.wayland.Server, optional>;
};

/// Properties describing a virtio_magma device.
type MagmaDevice = struct {
    /// The amount of guest-physical address space to allocate for virtio_magma
    /// buffers.
    ///
    /// Default to a 16GiB allocation.
    @allow_deprecated_struct_defaults
    memory uint64 = 17179869184;
};

/// The configuration required to start up a guest. When adding a new field, consider updating
/// fuchsia.virtualization.GuestDescriptor which is an informational snapshot of this table.
type GuestConfig = resource table {
    /// Type of kernel to load. Cannot be changed from the command-line.
    1: kernel_type KernelType;
    /// File to load the kernel from. Cannot be changed from the command-line.
    2: kernel client_end:fuchsia.io.File;
    /// File to load the initial RAM disk from. Cannot be changed from the
    /// command-line.
    3: ramdisk client_end:fuchsia.io.File;
    /// File to load the dtb overlay for a Linux kernel from. Cannot be changed
    /// from the command-line.
    4: dtb_overlay client_end:fuchsia.io.File;
    /// Kernel command-line to use. Cannot be changed from the command-line.
    5: cmdline string:MAX;
    /// Additional kernel command-lines to append to the main command-line.
    6: cmdline_add vector<string:MAX>:MAX;

    /// The number of CPUs to provide to a guest.
    7: cpus uint8;
    /// Amount of guest memory required, in bytes. This value may be rounded up depending on
    /// the system configuration.
    8: guest_memory uint64;
    /// A list of block devices to give a guest. Cannot be changed from the
    /// command-line.
    9: block_devices vector<BlockSpec>:MAX_BLOCK_DEVICES;
    /// A list of specifications for network devices.
    10: net_devices vector<NetSpec>:MAX_NET_DEVICES;
    /// Optional virtio-wl device.
    11: wayland_device WaylandDevice;
    /// Optional virtio-magma device.
    12: magma_device MagmaDevice;

    /// Whether to add a default network device.
    13: default_net bool;
    /// Enable virtio-balloon.
    14: virtio_balloon bool;
    /// Enable virtio-console.
    15: virtio_console bool;
    /// Enable virtio-gpu.
    16: virtio_gpu bool;
    /// Enable virtio-rng.
    17: virtio_rng bool;
    /// Enable virtio-vsock.
    18: virtio_vsock bool;
    /// Enable virtio-sound.
    19: virtio_sound bool;
    /// Enable input streams (capture) for virtio-sound.
    20: virtio_sound_input bool;

    /// Host ports to listen for guest initiated vsock connections on. This can be used for
    /// simplicity if a Listener is known at config creation time, or if a Listener must be
    /// available at the moment of guest creation for timing reasons.
    ///
    /// To add a Listener after a guest starts, see HostVsockEndpoint::Listen.
    21: vsock_listeners vector<Listener>:MAX;
    // TODO(https://fxbug.dev/42051237): Model this similar to the MagmaDevice by using
    // the resource table to bundle all of the virtio-mem parameters into a
    // single resource table
    /// Enable virtio-mem
    22: virtio_mem bool;
    /// Size of the dynamically (un)pluggable memory block.
    /// Memory can be (un)plugged at this granularity.
    /// Smaller block size increases changes of successful unplug at the cost of increasing
    /// the size of tracking bitmap.
    23: virtio_mem_block_size uint64;
    /// Size of the entire dynamically pluggable memory region
    24: virtio_mem_region_size uint64;
    /// Required alignment of the dynamically pluggable memory region
    25: virtio_mem_region_alignment uint64;
};