Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

config: Add Hardware description object to the VM configuration #1209

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

config: Add Hardware description object to the VM configuration #1209

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions config-vm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's several references here to Xen specifically -- are these all applicable to other implementations too, or are these mostly Xen-specific fields?

I'm trying to understand how this helps improve interoperability between runtimes, so another way to put this question is whether you envision more than one runtime will implement support for this?

* **`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
29 changes: 29 additions & 0 deletions schema/config-vm.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
}
}
}
}
Expand Down
18 changes: 18 additions & 0 deletions schema/defs-vm.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
]
}
}
}
6 changes: 6 additions & 0 deletions schema/defs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,12 @@
"type": "string"
}
},
"ArrayOfUint32": {
"type": "array",
"items": {
"$ref": "#definitions/uint32"
}
},
"FilePath": {
"type": "string"
},
Expand Down
28 changes: 28 additions & 0 deletions specs-go/config.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand Down