tools/virtual_device/proto/virtual_device.proto

// 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.

syntax = "proto3";

package virtual_device;

option go_package = "go.fuchsia.dev/fuchsia/tools/virtual_device/proto";

// VirtualDevice describes how to run Fuchsia using a vm or emulator.
//
// This message should capture the set of system images necessary to boot the
// device, as well as the hardware characteristics of the device.
//
// Its primary purpose is to carry virtualization options across system
// boundaries. For example, Fuchsia infra may pass a file containing this
// message from the build to a tool that runs Fuchsia in QEMU, without
// inspecting the message itself.
message VirtualDevice {
  // The name of this virtual device.
  //
  // This is meant to help humans identify this device.
  string name = 1;

  // Metadata indicating how to run QEMU.
  QEMU qemu = 2;

  // The name of the system kernel image in images.json.
  string kernel = 3;

  // The name of the initial ramdisk image in images.json.
  string initrd = 4;

  // Optional. The primary disk drive for this device.
  Drive drive = 5;

  // The device characterics.
  HardwareProfile hw = 6;

  // Kernel command line arguments.
  repeated string kernel_args = 7;
}

// QEMU describes how to run a VirtualDevice in QEMU.
message QEMU {
  // The maximum supported QEMU version.
  string max_version = 1;

  // The minimum supported QEMU version.
  string min_version = 2;
}

// A PCI disk drive.
message Drive {
  // The name of the drive.
  string id = 1;

  // A pointer to the image to use as a basis for the drive.
  string image = 2;

  // If true, image is the name of a file to use for this drive. This is useful
  // if the drive is, for example, a MinFS image. The path may be relative or
  // absolute, depending on the use case.
  //
  // If false, image is the name of an image in images.json whose path attribute
  // points to the file backing this device.
  //
  // Defaults to false.
  bool is_filename = 3;

  // DEPRECATED: Use device instead.
  // TODO(kjharland): Refactor //tools/qemu.go to use device and remove this.
  //
  // The PCI address for the device.
  //
  // Defaults to the empty string.
  string pci_address = 4;

  Device device = 5;
}

message HardwareProfile {
  // The CPU architecture.
  //
  // This must be one of:
  // - arm64
  // - x64
  string arch = 1;

  // The number of CPUs.
  //
  // Defaults to 1.
  uint32 cpu_count = 2;

  // The amount of RAM expressed as a string like "5M".
  //
  // The number must be a positive 64-bit integer in base 10.
  // The unit must be any of:
  // - b|B for bytes
  // - k|K for kilobytes
  // - m|M for megabytes
  // - g|G for gigabytes.
  string ram = 3;

  // The MAC address to use for the device.
  string mac = 4;

  // Optional networking devices.
  //
  // If unset, networking is disabled.
  repeated Netdev network_devices = 5;

  // Optional list of drives to mount.
  //
  // If any drive is a USB, remember to specify a USB host controller.
  repeated Drive drives = 6;

  // Optional USB host controller interface.
  //
  // This must be set if USB drives are specified. The only supported value is
  // 'xhci'.
  string hci = 7;

  // Whether to enable KVM.
  //
  // Defaults to false.
  bool enable_kvm = 8;
}

message Netdev {
  Device device = 1;
  string id = 2;

  // One of "user" or "tap".
  string kind = 3;
}

message Device {
  string model = 1;

  // Named fields that and can be added to `-device` options.
  repeated string options = 2;
}