diff --git a/config-vm.md b/config-vm.md index ff551d317..d528616db 100644 --- a/config-vm.md +++ b/config-vm.md @@ -61,8 +61,54 @@ This image contains the root filesystem that the virtual machine **`kernel`** wi } ``` +## 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`** (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, + "memKB": 4096, + "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 \ No newline at end of file diff --git a/schema/config-vm.json b/schema/config-vm.json index 6b1fb4baf..68358fa4e 100644 --- a/schema/config-vm.json +++ b/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" + } + } } } } diff --git a/schema/defs-vm.json b/schema/defs-vm.json index 4dae91506..4f817ca33 100644 --- a/schema/defs-vm.json +++ b/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" + ] } } } diff --git a/schema/defs.json b/schema/defs.json index a0bf846a1..688d20515 100644 --- a/schema/defs.json +++ b/schema/defs.json @@ -75,6 +75,12 @@ "type": "string" } }, + "ArrayOfUint32": { + "type": "array", + "items": { + "$ref": "#definitions/uint32" + } + }, "FilePath": { "type": "string" }, diff --git a/specs-go/config.go b/specs-go/config.go index 4e7717d53..5dbbef563 100644 --- a/specs-go/config.go +++ b/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,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 KB that VM can consume. + MemKB *uint64 `json:"memKB,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. @@ -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,omitempty"` } // VMHypervisor contains information about the hypervisor to use for a virtual machine.