Skip to content

Commit af0d16d

Browse files
oleksiimoisieievoleksiimoisieiev
committed
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]>
1 parent 720792f commit af0d16d

File tree

5 files changed

+127
-0
lines changed

5 files changed

+127
-0
lines changed

‎config-vm.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,54 @@ This image contains the root filesystem that the virtual machine **`kernel`** wi
6161
}
6262
```
6363

64+
## <a name="HwConfigObject" /> HWConfig Object
65+
66+
**`hwConfig`** (object OPTIONAL) Specifies the hardware configuration that should be passed to the VM.
67+
* **`deviceTree`** (string OPTIONAL) Path to the container device-tree file that should be passed to the VM.
68+
* **`vcpus`** (int OPTIONAL) Number of virtual cpus for the VM.
69+
* **`memory`** (int OPTIONAL) Maximum memory in bytes allocated to the VM.
70+
* **`dtdevs`** (array OPTIONAL) Host device tree nodes to passthrough to the VM, see [Xen Config][xl-config-format] for the details.
71+
* **`iomems`** (array OPTIONAL) Allow auto-translated domains to access specific hardware I/O memory pages, see [Xen Config][xl-config-format].
72+
* **`firstGFN`** (int OPTIONAL) Guest Frame Number to map the iomem range.
73+
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.
74+
* **`firstMFN`** (int REQUIRED) Physical page number of iomem regions, see [Xen Config][xl-config-format] for the details.
75+
* **`nrMFNs`** (int REQUIRED) Number of pages to be mapped, see [Xen Config][xl-config-format] for the details.
76+
* **`irqs`** (array OPTIONAL) Allows VM to access specific physical IRQs, see [Xen Config][xl-config-format] for the details.
77+
78+
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.
79+
80+
### Example
81+
82+
```json
83+
"hwConfig": {
84+
"deviceTree": "/path/to/vm/devicetree.dtb",
85+
"vcpus": 1,
86+
"memory": 4194304,
87+
"dtdevs": [
88+
"path/to/dev1_node",
89+
"path/to/dev2_node"
90+
],
91+
"iomems": [
92+
{
93+
"firstMFN": 12288,
94+
"nrMFNs": 1
95+
},
96+
{
97+
"firstGFN": 12544,
98+
"firstMFN": 33024,
99+
"nrMFNs": 2
100+
}
101+
],
102+
"irqs": [
103+
11,
104+
22
105+
]
106+
}
107+
```
108+
64109
[raw-image-format]: https://en.wikipedia.org/wiki/IMG_(file_format)
65110
[qcow2-image-format]: https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/interop/qcow2.txt;hb=HEAD
66111
[vdi-image-format]: https://forensicswiki.org/wiki/Virtual_Disk_Image_(VDI)
67112
[vmdk-image-format]: http://www.vmware.com/app/vmdk/?src=vmdk
68113
[vhd-image-format]: https://github.com/libyal/libvhdi/blob/master/documentation/Virtual%20Hard%20Disk%20(VHD)%20image%20format.asciidoc
114+
[xl-config-format]: https://xenbits.xen.org/docs/4.10-testing/man/xl.cfg.5.html

‎schema/config-vm.json

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,35 @@
5454
"$ref": "defs-vm.json#/definitions/RootImageFormat"
5555
}
5656
}
57+
},
58+
"hwConfig": {
59+
"description": "hardware configuration for the VM image",
60+
"type": "object",
61+
"properties": {
62+
"deviceTree": {
63+
"$ref": "defs.json#/definitions/FilePath"
64+
},
65+
"vcpus": {
66+
"$ref": "defs.json#/definitions/uint32"
67+
},
68+
"memory": {
69+
"$ref": "defs.json#/definitions/uint64"
70+
},
71+
"dtdevs": {
72+
"$ref": "defs.json#/definitions/ArrayOfStrings"
73+
},
74+
"iomems": {
75+
"type": "array",
76+
"items": [
77+
{
78+
"$ref": "defs-vm.json#/definitions/IOMemEntryFormat"
79+
}
80+
]
81+
},
82+
"irqs": {
83+
"$ref": "defs.json#/definitions/ArrayOfUint32"
84+
}
85+
}
5786
}
5887
}
5988
}

‎schema/defs-vm.json

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,24 @@
99
"vmdk",
1010
"vhd"
1111
]
12+
},
13+
"IOMemEntryFormat": {
14+
"type": "object",
15+
"properties": {
16+
"firstGFN": {
17+
"$ref": "defs.json#/definitions/uint64"
18+
},
19+
"firstMFN": {
20+
"$ref": "defs.json#/definitions/uint64"
21+
},
22+
"nrMFNs": {
23+
"$ref": "defs.json#/definitions/uint64"
24+
}
25+
},
26+
"required": [
27+
"firstMFN",
28+
"nrMFNs"
29+
]
1230
}
1331
}
1432
}

‎schema/defs.json

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,12 @@
7575
"type": "string"
7676
}
7777
},
78+
"ArrayOfUint32": {
79+
"type": "array",
80+
"items": {
81+
"$ref": "#definitions/uint32"
82+
}
83+
},
7884
"FilePath": {
7985
"type": "string"
8086
},

‎specs-go/config.go

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -649,6 +649,32 @@ type WindowsHyperV struct {
649649
UtilityVMPath string `json:"utilityVMPath,omitempty"`
650650
}
651651

652+
// IOMems containes information about iomem addresses that should be passed to the VM.
653+
type IOMems struct {
654+
// 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.
655+
FirstGFN *uint64 `json:"firstGFN,omitempty"`
656+
// Physical page number of iomem regions.
657+
FirstMFN *uint64 `json:"firstMFN"`
658+
// Number of pages to be mapped.
659+
NrMFNs *uint64 `json:"nrMFNs"`
660+
}
661+
662+
// Hardware configuration for the VM image
663+
type HWConfig struct {
664+
// Path to the container device-tree file that should be passed to the VM configuration.
665+
DeviceTree string `json:"deviceTree,omitempty"`
666+
// Number of virtual cpus for the VM.
667+
VCPUs *uint32 `json:"vcpus,omitempty"`
668+
// Maximum memory in bytes allocated to the VM.
669+
Memory *uint64 `json:"memory,omitempty"`
670+
// Host device tree nodes to passthrough to the VM.
671+
DtDevs []string `json:"dtdevs,omitempty"`
672+
// Allow auto-translated domains to access specific hardware I/O memory pages.
673+
IOMems []IOMems `json:"iomems,omitempty"`
674+
// Allows VM to access specific physical IRQs.
675+
Irqs []uint32 `json:"irqs,omitempty"`
676+
}
677+
652678
// VM contains information for virtual-machine-based containers.
653679
type VM struct {
654680
// Hypervisor specifies hypervisor-related configuration for virtual-machine-based containers.
@@ -657,6 +683,8 @@ type VM struct {
657683
Kernel VMKernel `json:"kernel"`
658684
// Image specifies guest image related configuration for virtual-machine-based containers.
659685
Image VMImage `json:"image,omitempty"`
686+
// Hardware configuration that should be passed to the VM.
687+
HwConfig *HWConfig `json:"hwconfig,omitempty"`
660688
}
661689

662690
// VMHypervisor contains information about the hypervisor to use for a virtual machine.

0 commit comments

Comments
 (0)