config: Add Hardware description object to the VM configuration

This adds section to describe HW that should be passed through to the
VM. This enables Hardware-level isolation provided by XEN for
e.g. functional safety use cases.

Adds hwConfig object to the VM section which is apt to describe the
initial configuration for the VM, sush as number of vcpus and memory,
provided to the VM.
Hardware description includes path to the device-tree, that should be
passed to the VM and the hardware configuration parameters which
provides all needed data for VM to use the devices, such as:
  - dtdevs: host device tree nodes to passthrough to the VM;
  - iomems: allow auto-translated domains to access specific hardware
  I/O memory pages;
  - irqs: allows VM to access specific physical IRQs.

Signed-off-by: Oleksii Moisieiev <[email protected]>

config-vm.md

@@ -61,8 +61,54 @@ This image contains the root filesystem that the virtual machine **`kernel`** wi
  }
 ```
 
+## <a name="HwConfigObject" /> HWConfig Object
+
+**`hwConfig`** (object OPTIONAL) Specifies the hardware configuration that should be passed to the VM.
+* **`deviceTree`** (string OPTIONAL) Path to the container device-tree file that should be passed to the VM.
+* **`vcpus`** (int OPTIONAL) Number of virtual cpus for the VM.
+* **`memKB`** (int OPTIONAL) Maximum memory in KB allocated to the VM.
+* **`dtdevs`** (array OPTIONAL) Host device tree nodes to passthrough to the VM, see [Xen Config][xl-config-format] for the details.
+* **`iomems`** (array OPTIONAL) Allow auto-translated domains to access specific hardware I/O memory pages, see [Xen Config][xl-config-format].
+ * **`firstGFN`** (number OPTIONAL) Guest Frame Number to map the iomem range.
+ If GFN is not specified, the mapping will be done to the same Frame Number as was provided in firstMFN, see [Xen Config][xl-config-format] for the details.
+ * **`firstMFN`** (nubmer REQUIRED) Physical page number of iomem regions, see [Xen Config][xl-config-format] for the details.
+ * **`nrMFNs`** (number REQUIRED) Number of pages to be mapped, see [Xen Config][xl-config-format] for the details.
+* **`irqs`** (array OPTIONAL) Allows VM to access specific physical IRQs, see [Xen Config][xl-config-format] for the details.
+
+This hwConfig object contains the description of the hardware that can be safely passed through to the VM. Where **`deviceTree`** is the path to the device-tree blob, which conains description of the isolated hardware and paravirtualized hardware that should be used by VM. **`dtdevs`**, **`iomems`** and **`irqs`** parameters describing the minimun set of the parameters, needed for VM to access the hardware.
+
+### Example
+
+```json
+ "hwConfig": {
+ "deviceTree": "/path/to/vm/devicetree.dtb",
+ "vcpus": 1,
+ "memKB": 4096,
+ "dtdevs": [
+ "path/to/dev1_node",
+ "path/to/dev2_node"
+ ],
+ "iomems": [
+ {
+ "firstMFN": 0x3000,
+ "nrMFNs": 1
+ },
+ {
+ "firstGFN": 0x3100,
+ "firstMFN": 0x8100,
+ "nrMFNs": 2
+ }
+ ],
+ "irqs": [
+ 11,
+ 22
+ ]
+ }
+```
+
 [raw-image-format]: https://en.wikipedia.org/wiki/IMG_(file_format)
 [qcow2-image-format]: https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/interop/qcow2.txt;hb=HEAD
 [vdi-image-format]: https://forensicswiki.org/wiki/Virtual_Disk_Image_(VDI)
 [vmdk-image-format]: http://www.vmware.com/app/vmdk/?src=vmdk
 [vhd-image-format]: https://github.com/libyal/libvhdi/blob/master/documentation/Virtual%20Hard%20Disk%20(VHD)%20image%20format.asciidoc
+[xl-config-format]: https://xenbits.xen.org/docs/4.10-testing/man/xl.cfg.5.html

schema/config-vm.json

@@ -54,6 +54,35 @@
  "$ref": "defs-vm.json#/definitions/RootImageFormat"
  }
  }
+ },
+ "hwConfig": {
+ "description": "hardware configuration for the VM image",
+ "type": "object",
+ "properties": {
+ "deviceTree": {
+ "$ref": "defs.json#/definitions/FilePath"
+ },
+ "vcpus": {
+ "$ref": "defs.json#/definitions/uint32"
+ },
+ "memKB": {
+ "$ref": "defs.json#/definitions/uint64"
+ },
+ "dtdevs": {
+ "$ref": "defs.json#/definitions/ArrayOfStrings"
+ },
+ "iomems": {
+ "type": "array",
+ "items": [
+ {
+ "$ref": "defs-vm.json#/definitions/IOMemEntryFormat"
+ }
+ ]
+ },
+ "irqs": {
+ "$ref": "defs.json#/definitions/ArrayOfUint32"
+ }
+ }
  }
  }
  }

schema/defs-vm.json

@@ -9,6 +9,24 @@
  "vmdk",
  "vhd"
  ]
+ },
+ "IOMemEntryFormat": {
+ "type": "object",
+ "properties": {
+ "firstGFN": {
+ "$ref": "defs.json#/definitions/uint64"
+ },
+ "firstMFN": {
+ "$ref": "defs.json#/definitions/uint64"
+ },
+ "nrMFNs": {
+ "$ref": "defs.json#/definitions/uint64"
+ }
+ },
+ "required": [
+ "firstMFN",
+ "nrMFNs"
+ ]
  }
  }
 }

schema/defs.json

@@ -75,6 +75,12 @@
  "type": "string"
  }
  },
+ "ArrayOfUint32": {
+ "type": "array",
+ "items": {
+ "$ref": "#definitions/uint32"
+ }
+ },
  "FilePath": {
  "type": "string"
  },

specs-go/config.go

@@ -649,6 +649,32 @@ type WindowsHyperV struct {
  UtilityVMPath string `json:"utilityVMPath,omitempty"`
 }
 
+// IOMems containes information about iomem addresses that should be passed to the VM.
+type IOMems struct {
+ // Guest Frame Number to map the iomem range. If GFN is not specified, the mapping will be done to the same Frame Number as was provided in FirstMFN.
+ FirstGFN uint64 `json:"firstGFN"`
+ // Physical page number of iomem regions.
+ FirstMFN uint64 `json:"firstMFN"`
+ // Number of pages to be mapped.
+ NrMFNs uint64 `json:"nrMFNs"`
+}
+
+// Hardware configuration for the VM image
+type HWConfig struct {
+ // Path to the container device-tree file that should be passed to the VM configuration.
+ DeviceTree string `json:"deviceTree"`
+ // Number of virtual cpus for the VM.
+ VCPUs uint32 `json:"vcpus"`
+ // Maximum memory in KB that VM can consume.
+ MemKB uint64 `json:"memKB"`
+ // Host device tree nodes to passthrough to the VM.
+ DtDevs []string `json:"dtdevs"`
+ // Allow auto-translated domains to access specific hardware I/O memory pages.
+ IOMems []IOMems `json:"iomems"`
+ // Allows VM to access specific physical IRQs.
+ Irqs []uint32 `json:"irqs"`
+}
+
 // VM contains information for virtual-machine-based containers.
 type VM struct {
  // Hypervisor specifies hypervisor-related configuration for virtual-machine-based containers.
@@ -657,6 +683,8 @@ type VM struct {
  Kernel VMKernel `json:"kernel"`
  // Image specifies guest image related configuration for virtual-machine-based containers.
  Image VMImage `json:"image,omitempty"`
+ // Hardware configuration that should be passed to the VM.
+ HwConfig HWConfig `json:"hwconfig"`
 }
 
 // VMHypervisor contains information about the hypervisor to use for a virtual machine.