mdevctl is a utility for managing and persisting devices in the mediated device device framework of the Linux kernel. Mediated devices are sub-devices of a parent device (ex. a vGPU) which can be dynamically created and potentially used by drivers like vfio-mdev for assignment to virtual machines.
Licensed under the GNU Lesser General Public License aka LGPL v2.1. See COPYING for details.
https://github.com/mdevctl/mdevctl
mdevctl is built with rust's cargo
tool. To build the executable, run cargo
build
. This will compile the code and also generate a Makefile that can be
used for installing the executable and all support files into your system. On
RPM based systems, you can run make rpm
then install the resulting package.
Otherwise, run make install
.
mdevctl stores defined mediated devices in /etc/mdevctl.d/ with directories matching the parent device name and config files named by the UUID of the mdev device itself. The format used is JSON; a configuration file for an mdev device looks like follows:
{
"mdev_type": "$VENDOR_TYPE",
"start": "auto|manual",
"attrs": [
...optional list of device-specific attributes...
]
}
When a known parent device add udev event occurs (or, for more recent kernels, change events with MDEV_STATE values), mdevctl is called by a udev rule to create defined devices with "start": "auto" configured.
mdevctl defines three classes of commands, those that manage device config files, those that manage the device itself, and listing commands for showing defined, active, or potential mdev devices.
Starting with the latter, mdevctl is able to manage mdev devices
created either with mdevctl or externally, such as through direct
sysfs interactions. Likewise, when generating a list of currently
active mdev devices via the list
command, all mdevs are included.
When provided with the --defined
option, the list command will show
mdev device configs defined on the system, regardless of whether they
are currently active. The types
command provides details of the
mdev types supported on the system, including the number of
instances of each that may be created, the API exposed for each, as
well as vendor provided name and description as available.
Mediated device definitions can be created with the define
command,
which not only accepts a fully specified configuration via options,
but can also create a config for a currently running mdev. Thus a
transient device created either through mdevctl or sysfs can be
promoted to a defined device. The undefine
command simply removes
the config definition without modifying the running device, while
the modify
command allows device config to be modified. Config
modifications to a running device to not take effect until the device
is stopped and restarted.
This leads to the final class of commands, which provides the start
and stop
functionality. The start command can operate either on
a previously defined mdev or the mdev can be fully specified via
options to create a transient device, ie. a running device with no
persistence.
List running mdev devices:
```
85006552-1b4b-45ef-ad62-de05be9171df 0000:00:02.0 i915-GVTgV44 83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTgV48 (defined) ```
List defined mdev devices:
```
83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTgV48 auto b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTgV48 auto 5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTgV44 manual ```
List mdev types supported on the host system:
```
0000:00:02.0 i915-GVTgV42 Available instances: 1 Device API: vfio-pci Description: lowgmsize: 256MB highgmsize: 1024MB fence: 4 resolution: 1920x1200 weight: 8 i915-GVTgV41 Available instances: 0 Device API: vfio-pci Description: lowgmsize: 512MB highgmsize: 2048MB fence: 4 resolution: 1920x1200 weight: 16 i915-GVTgV48 Available instances: 4 Device API: vfio-pci Description: lowgmsize: 64MB highgmsize: 384MB fence: 4 resolution: 1024x768 weight: 2 i915-GVTgV44 Available instances: 3 Device API: vfio-pci Description: lowgmsize: 128MB highgmsize: 512MB fence: 4 resolution: 1920x1200 weight: 4 ```
Modify a defined device from automatic start to manual:
```
83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTgV48 manual b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTgV48 auto 5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTgV44 manual ```
Stop a running mdev device:
```
```
Start an mdev device that is not defined
```
6eba5b41-176e-40db-b93e-7f18e04e0b93
85006552-1b4b-45ef-ad62-de05be9171df 0000:00:02.0 i915-GVTgV44 6eba5b41-176e-40db-b93e-7f18e04e0b93 0000:00:02.0 i915-GVTgV41 ```
Promote the new created mdev to a defined device:
```
83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTgV48 manual 6eba5b41-176e-40db-b93e-7f18e04e0b93 0000:00:02.0 i915-GVTgV41 manual b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTgV48 auto 5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTgV44 manual ```
mdevctl provides support for specifying additional configuration via device-specific attributes. It also provides support for inspecting and modifying its internal JSON representation of the configuration directly.
Example:
```
783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual ```
Add some attributes:
```
783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfioap-passthrough manual Attrs: @{0}: {"assignadapter":"5"} @{1}: {"assignadapter":"6"} @{2}: {"assigndomain":"0xab"} @{3}: {"assigncontroldomain":"0xab"} @{4}: {"assigndomain":"4"} @{5}: {"assigncontrol_domain":"4"} ```
Dump the JSON configuration:
```
{ "mdevtype": "vfioap-passthrough", "start": "manual", "attrs": [ { "assignadapter": "5" }, { "assignadapter": "6" }, { "assigndomain": "0xab" }, { "assigncontroldomain": "0xab" }, { "assigndomain": "4" }, { "assigncontroldomain": "4" } ] } ```
Remove some attributes:
```
783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfioap-passthrough manual Attrs: @{0}: {"assignadapter":"5"} @{1}: {"assignadapter":"6"} @{2}: {"assigndomain":"0xab"} @{3}: {"assigncontroldomain":"0xab"} ```
Define an mdev device from a file:
```
{ "mdevtype": "vfioap-passthrough", "start": "manual", "attrs": [ { "assignadapter": "5" }, { "assigndomain": "0x47" }, { "assign_domain": "0xff" } ] }
e2e73122-cc39-40ee-89eb-b0a47d334cae
783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfioap-passthrough manual Attrs: @{0}: {"assignadapter":"5"} @{1}: {"assignadapter":"6"} @{2}: {"assigndomain":"0xab"} @{3}: {"assigncontroldomain":"0xab"} e2e73122-cc39-40ee-89eb-b0a47d334cae matrix vfioap-passthrough manual Attrs: @{0}: {"assignadapter":"5"} @{1}: {"assigndomain":"0x47"} @{2}: {"assigndomain":"0xff"} ```
See mdevctl --help
or the manpage for more information.