Merge pull request #1209 from oleksiimoisieiev/hwconfig

config: Add Hardware description object to the VM configuration

Author: kolyshkin

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.
+* **`memory`** (int OPTIONAL) Maximum memory in bytes 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`** (int 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`** (int REQUIRED) Physical page number of iomem regions, see [Xen Config][xl-config-format] for the details.
+    * **`nrMFNs`** (int 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,
+        "memory": 4194304,
+        "dtdevs": [
+            "path/to/dev1_node",
+            "path/to/dev2_node"
+        ],
+        "iomems": [
+            {
+                "firstMFN": 12288,
+                "nrMFNs": 1
+            },
+            {
+                "firstGFN": 12544,
+                "firstMFN": 33024,
+                "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"
+                    },
+                    "memory": {
+                        "$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

@@ -688,6 +688,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,omitempty"`
+	// 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,omitempty"`
+	// Number of virtual cpus for the VM.
+	VCPUs *uint32 `json:"vcpus,omitempty"`
+	// Maximum memory in bytes allocated to the VM.
+	Memory *uint64 `json:"memory,omitempty"`
+	// Host device tree nodes to passthrough to the VM.
+	DtDevs []string `json:"dtdevs,omitempty"`
+	// Allow auto-translated domains to access specific hardware I/O memory pages.
+	IOMems []IOMems `json:"iomems,omitempty"`
+	// Allows VM to access specific physical IRQs.
+	Irqs []uint32 `json:"irqs,omitempty"`
+}
+
 // VM contains information for virtual-machine-based containers.
 type VM struct {
 	// Hypervisor specifies hypervisor-related configuration for virtual-machine-based containers.
@@ -696,6 +722,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,omitempty"`
 }
 
 // VMHypervisor contains information about the hypervisor to use for a virtual machine.