From f07267b2b201aa2974b3925ac0afe5a6b50892f2 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..cdad7f249 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`** (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 \ 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..a4cae88bb 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"` + // 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.