sdk/fidl/fuchsia.virtualization/realm.fidl

// Copyright 2018 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 fuchsia.sys;

/// 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;
};

const uint64 MAX_BLOCK_DEVICE_ID_SIZE = 20;

/// Properties describing a single block device in the system.
struct BlockDevice {
    /// A label used to identify the block device.
    string:MAX_BLOCK_DEVICE_ID_SIZE 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;
};

struct BlockSpec {
    string path;
    BlockFormat format;
    BlockMode mode;
};

enum Kernel {
    ZIRCON = 0;
    LINUX = 1;
};

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

struct MemorySpec {
    uint64 base;
    uint64 size;
    MemoryPolicy policy;
};

struct NetSpec {
    fuchsia.hardware.ethernet.MacAddress mac_address;
};

/// The configuration required to start up a guest.
table GuestConfig {
    /// Which kernel to use. Cannot be changed from the command-line.
    1: Kernel kernel;
    // TODO(fxb/42889): Make kernel_path, ramdisk_path, and block_devices into a fuchsia.io.File
    /// The path to load the kernel from. Cannot be changed from the command-line.
    2: string kernel_path;
    /// Load the ramdisk_path as an initial RAM disk. Cannot be changed from the command-line.
    3: string ramdisk_path;
    /// The file path to the dtb overlay for a linux kernel. Cannot be changed from the
    /// command-line.
    4: string dtb_overlay_path;
    /// A list of block devices to give the guest. Cannot be changed from the command-line.
    5: vector<BlockSpec> block_devices;

    /// The command to start the client with.
    6: string cmdline;
    /// Any additional arguments to add to the cmdline.
    7: vector<string> cmdline_add;
    /// The layout of memory to be mapped into the guest.
    8: vector<MemorySpec> memory;
    /// A list of interrupt vectors.
    9: vector<uint32> interrupts;
    /// The number of CPUs to provide to the guest.
    10: uint8 cpus;
    /// A list of specifications for network devices.
    11: vector<NetSpec> net_devices;
    /// Whether to add a default network device (default).
    12: bool default_net;
    /// Enable virtio-balloon (default).
    13: bool virtio_balloon;
    /// Enable virtio-console (default).
    14: bool virtio_console;
    /// Enable virtio-gpu (default).
    15: bool virtio_gpu;
    /// Enable virtio-magma (default).
    16: bool virtio_magma;
    /// Enable virtio-rng (default).
    17: bool virtio_rng;
    /// Enable virtio-vsock (default).
    18: bool virtio_vsock;
};

/// An interface that will 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(handle<channel> channel);
};

/// Properties describing a virtio_wl device.
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;
};

struct LaunchInfo {
    /// The URL of the package to launch.
    string url;

    // TODO(fxb/42888): pass the configuration to the guest launcher instead.
    /// Configuration that will be passed to the VMM binary when launching this guest.
    ///
    /// See //src/virtualization/bin/vmm/guest_config.cc for valid options.
    GuestConfig guest_config;

    /// A diagnostic string to associate with this instance.
    string? label;

    /// A flat namespace to be appended to the default namespace for the VMM
    /// process.
    fuchsia.sys.FlatNamespace? flat_namespace;

    /// A set of block devices to add to the virtual machine.
    vector<BlockDevice>? block_devices;

    /// An optional virtio_wl device.
    ///
    /// If not provided, no virtio_wl device will be created by the VMM.
    WaylandDevice? wayland_device;

    /// An optional virtio_magma device.
    ///
    /// If not provided, no virtio_magma device will be created by the VMM.
    MagmaDevice? magma_device;
};

protocol Realm {
    /// Launch a new guest instance into this environment. The `cid` of the
    /// instance is returned so that it can be uniquely identified.
    LaunchInstance(LaunchInfo launch_info,
                   request<Guest> controller)
        -> (uint32 cid);

    /// Query for guests running in this environment.
    ListInstances() -> (vector<InstanceInfo> instances);

    /// Connect to a currently running guest instance identified by `cid`. The
    /// `cid` can be found via the return value of `LaunchInstance` or a call to
    /// `ListInstances`.
    ConnectToInstance(uint32 cid, request<Guest> controller);

    /// Connect to the memory balloon of a currently running guest instance
    /// identified by `cid`.
    ConnectToBalloon(uint32 cid, request<BalloonController> controller);

    /// Returns an interface that can be used to access the host vsock endpoint.
    GetHostVsockEndpoint(request<HostVsockEndpoint> endpoint);
};