From af0d16d78169204104eedd586e3c89bba6fe7544 Mon Sep 17 00:00:00 2001 From: Oleksii Moisieiev Date: Thu, 1 Jun 2023 16:52:14 +0300 Subject: [PATCH] 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 --- config-vm.md | 46 +++++++++++++++++++++++++++++++++++++++++++ schema/config-vm.json | 29 +++++++++++++++++++++++++++ schema/defs-vm.json | 18 +++++++++++++++++ schema/defs.json | 6 ++++++ specs-go/config.go | 28 ++++++++++++++++++++++++++ 5 files changed, 127 insertions(+) diff --git a/config-vm.md b/config-vm.md index ff551d317..4fd80742d 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. +* **`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 \ No newline at end of file diff --git a/schema/config-vm.json b/schema/config-vm.json index 6b1fb4baf..54fae7af0 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" + }, + "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" + } + } } } } 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..5b8afe5ca 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 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. @@ -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.