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.ethernet;
using fuchsia.io;
using zx;

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

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

/// Memory policy for a MemorySpec.
enum MemoryPolicy {
    /// Map a VMO as cached memory into a guest physical address space.
    GUEST_CACHED = 0;
    /// Map a VMO with 1:1 correspondence with host memory as cached memory into
    /// a guest physical address space.
    HOST_CACHED = 1;
    /// Map a VMO with 1:1 correspondence with host memory as device memory into
    /// a guest physical address space.
    HOST_DEVICE = 2;
};

/// Properties describing a region of guest physical address space.
struct MemorySpec {
    /// Base address of a region of guest physical address space.
    zx.gpaddr base;
    /// Size of a region of guest physical address space.
    uint64 size;
    /// Memory policy of a region of guest physical address space.
    MemoryPolicy policy;
};

/// Mode of the file backing a block device.
enum BlockMode {
    /// 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;
};

/// Data format of the file backing a block device.
enum BlockFormat {
    /// Raw IO. All reads and writes go directly to disk as a flat file.
    RAW = 0;
    /// QCOW image. All reads and writes go to a QCOW image.
    QCOW = 1;
};

/// Properties describing a block device.
resource struct BlockSpec {
    /// A label used to identify the block device.
    string:MAX_BLOCK_DEVICE_ID id;
    /// The access mode for the block backing file.
    BlockMode mode;
    /// The data format of the backing file.
    BlockFormat format;
    /// The underlying file that stores the drive contents.
    fuchsia.io.File file;
};

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

/// Protocol to receive channels for Wayland connections.
[Discoverable]
protocol WaylandDispatcher {
    /// Inform dispatcher of new connection.
    ///
    /// When a client opens a new connection to the virtio_wl device, a new
    /// zx::channel will be created for that connection. The virtio_wl device
    /// will retain one endpoint of that channel and the other endpoint will be
    /// provided to this method. The messages on the channel will be Wayland
    /// protocol messages as sent by the client. Each channel datagram will
    /// contain 1 or more complete Wayland messages.
    OnNewConnection(zx.handle:CHANNEL channel);
};

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

    /// The dispatcher for new virtio_wl connections.
    WaylandDispatcher dispatcher;
};

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

/// The configuration required to start up a guest.
resource table GuestConfig {
    /// Type of kernel to load. Cannot be changed from the command-line.
    1: KernelType kernel_type;
    /// File to load the kernel from. Cannot be changed from the command-line.
    2: fuchsia.io.File kernel;
    /// File to load the initial RAM disk from. Cannot be changed from the
    /// command-line.
    3: fuchsia.io.File ramdisk;
    /// File to load the dtb overlay for a Linux kernel from. Cannot be changed
    /// from the command-line.
    4: fuchsia.io.File dtb_overlay;
    /// Kernel command-line to use. Cannot be changed from the command-line.
    5: string:MAX cmdline;
    /// Additional kernel command-lines to append to the main command-line.
    6: vector<string:MAX>:MAX cmdline_add;

    /// The number of CPUs to provide to a guest.
    7: uint8 cpus;
    /// The layout of memory to be mapped into a guest.
    8: vector<MemorySpec>:MAX_MEMORY memory;
    /// A list of physical interrupts to bind to.
    9: vector<uint32>:MAX_INTERRUPTS interrupts;
    /// A list of block devices to give a guest. Cannot be changed from the
    /// command-line.
    10: vector<BlockSpec>:MAX_BLOCK_DEVICES block_devices;
    /// A list of specifications for network devices.
    11: vector<NetSpec>:MAX_NET_DEVICES net_devices;
    /// Optional virtio-wl device.
    12: WaylandDevice wayland_device;
    /// Optional virtio-magma device.
    13: MagmaDevice magma_device;

    /// Whether to add a default network device (default).
    14: bool default_net;
    /// Enable virtio-balloon (default).
    15: bool virtio_balloon;
    /// Enable virtio-console (default).
    16: bool virtio_console;
    /// Enable virtio-gpu (default).
    17: bool virtio_gpu;
    /// Enable virtio-rng (default).
    18: bool virtio_rng;
    /// Enable virtio-vsock (default).
    19: bool virtio_vsock;
};

/// Protocol to provide a guest's configuration.
[Discoverable]
protocol GuestConfigProvider {
    /// Get the |guest_config|.
    Get() -> (GuestConfig guest_config);
};