Provided by: mdevctl_0.59-1_all 
NAME
mdevctl, lsmdev - Mediated device management utility
SYNOPSIS
mdevctl {COMMAND} [OPTIONS...]
DESCRIPTION
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.
OPTIONS
The following options are understood:
--addattr=ATTRIBUTE
Add an attribute ATTRIBUTE. Valid for the modify command.
-a|--auto
Automatically start the device on parent availability. Valid for define and modify
commands.
-d|--defined
List all defined devices, even if not active. Valid for the list command.
--delattr
Delete an attribute entry. Valid for the modify command.
--dumpjson
Dump the configuration for a device in JSON format when filtered to as single device
and used with the list command. When used with the types command, output machine
readable type information.
-i|--index=INDEX
Act on the attribute INDEX. Valid for the modify command.
--jsonfile=FILE
Read the configuration for a device from a JSON file FILE. Valid for the define and
start commands.
-m|--manual
Do not start a device automatically on parent availability. Valid for the modify
command.
-p|--parent=PARENT
Specify or identify the device by its parent device.
-t|--type=TYPE
Specify or identify the device by its type.
-u|--uuid=UUID
Specify or identify the device by its UUID.
--value=VALUE
Set an attribute to VALUE, in the format accepted by the attribute. Valid for the
modify command.
-v|--verbose
Increase output verbosity, currently only adds attribute output to the types command.
COMMANDS
The following commands are understood:
define DEVICESPEC
Define a config for an mdev device, identified either by an UUID (if the device
already exists), or by the parent device and either the type or a JSON configuration
file, and, optionally, the UUID. If no UUID is specified, one is autogenerated and
printed. If no file is used, -a|--auto may be used to specify that the device should
be started automatically.
list
List mdev devices. With no options, currently running devices are listed. With
-d|--defined, previously defined devices are listed. Can be restricted to list only
devices for a given parent or UUID. With --dumpjson output is provided in machine
readable JSON format. When a UUID is provided and the output results in a single
device, the JSON output format is compatible with the configuration file format.
modify DEVICESPEC
Modify the configuration for an mdev device, identified via its UUID and optionally
its parent. Type and startup mode (auto or manual) can be modified by this command.
Attributes can be added or deleted. Attributes to be deleted must be specified by
their index; if an attribute is specified without an index, it is appended at the end
of the attribute list. Running devices are unaffected by this command; changes in the
configuration are applied the next time the device is started.
start DEVICESPEC
Start an mdev device, identified by its UUID and optionally its parent, or its parent
and type and optionally its UUID, which is generated if not given. If specified via
its parent and optionally its UUID, the type may be specified in a JSON configuration
file, alongside additional parameters.
stop DEVICESPEC
Stop an mdev device, specified via its UUID.
types
List the mdev device types known to the system by parent device. Output may be
limited to a single parent device with the -p|--parent option. JSON output format is
used with the --dumpjson option.
undefine DEVICESPEC
Undefine, or remove the configuration for an mdev device, specified by its UUID and
optionally its parent. If a UUID exists for multiple parents, all of them will be
removed unless restricted to a single parent. Running devices are unaffected by this
command.
NOTE ON DEVICE SPECIFICATION
For a given UUID, only one device with that UUID may be running at the same time. However,
it is possible to define multiple devices with the same UUID under different parent
devices. Therefore, it is sometimes necessary to specify the parent device alongside the
UUID to uniquely identify a device.
EXIT STATUS
On success, 0 is returned, a non-zero failure code otherwise.
EXAMPLES
List running mdev devices:
# mdevctl list
85006552-1b4b-45ef-ad62-de05be9171df 0000:00:02.0 i915-GVTg_V4_4
83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 (defined)
List defined mdev devices:
# mdevctl list -d
83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 auto
b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual
List mdev types supported on the host system:
# mdevctl types
0000:00:02.0
i915-GVTg_V4_2
Available instances: 1
Device API: vfio-pci
Description: low_gm_size: 256MB high_gm_size: 1024MB fence: 4 resolution: 1920x1200 weight: 8
i915-GVTg_V4_1
Available instances: 0
Device API: vfio-pci
Description: low_gm_size: 512MB high_gm_size: 2048MB fence: 4 resolution: 1920x1200 weight: 16
i915-GVTg_V4_8
Available instances: 4
Device API: vfio-pci
Description: low_gm_size: 64MB high_gm_size: 384MB fence: 4 resolution: 1024x768 weight: 2
i915-GVTg_V4_4
Available instances: 3
Device API: vfio-pci
Description: low_gm_size: 128MB high_gm_size: 512MB fence: 4 resolution: 1920x1200 weight: 4
Modify a defined device from automatic start to manual:
# mdevctl modify --uuid 83c32df7-d52e-4ec1-9668-1f3c7e4df107 --manual
# mdevctl list -d
83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 manual
b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual
Stop a running mdev device:
# mdevctl stop -u 83c32df7-d52e-4ec1-9668-1f3c7e4df107
Start an mdev device that is not defined:
# uuidgen
6eba5b41-176e-40db-b93e-7f18e04e0b93
# mdevctl start -u 6eba5b41-176e-40db-b93e-7f18e04e0b93 -p 0000:00:02.0 --type i915-GVTg_V4_1
# mdevctl list
85006552-1b4b-45ef-ad62-de05be9171df 0000:00:02.0 i915-GVTg_V4_4
6eba5b41-176e-40db-b93e-7f18e04e0b93 0000:00:02.0 i915-GVTg_V4_1
Promote the new created mdev to a defined device:
# mdevctl define --uuid 6eba5b41-176e-40db-b93e-7f18e04e0b93
# mdevctl list -d
83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 manual
6eba5b41-176e-40db-b93e-7f18e04e0b93 0000:00:02.0 i915-GVTg_V4_1 manual
b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual
ADVANCED EXAMPLES (ATTRIBUTES AND JSON)
# mdevctl list -d
783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
Add some attributes:
# mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_adapter --value=5
# mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_adapter --value=6
# mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_domain --value=0xab
# mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_control_domain --value=0xab
# mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_domain --value=4
# mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_control_domain --value=4
# mdevctl list -dv
783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
Attrs:
@{0}: {"assign_adapter":"5"}
@{1}: {"assign_adapter":"6"}
@{2}: {"assign_domain":"0xab"}
@{3}: {"assign_control_domain":"0xab"}
@{4}: {"assign_domain":"4"}
@{5}: {"assign_control_domain":"4"}
Dump the JSON configuration:
# mdevctl list -d -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --dumpjson
{
"mdev_type": "vfio_ap-passthrough",
"start": "manual",
"attrs": [
{
"assign_adapter": "5"
},
{
"assign_adapter": "6"
},
{
"assign_domain": "0xab"
},
{
"assign_control_domain": "0xab"
},
{
"assign_domain": "4"
},
{
"assign_control_domain": "4"
}
]
}
Remove some attributes:
# mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --delattr --index=5
# mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --delattr --index=4
# mdevctl list -dv
783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
Attrs:
@{0}: {"assign_adapter":"5"}
@{1}: {"assign_adapter":"6"}
@{2}: {"assign_domain":"0xab"}
@{3}: {"assign_control_domain":"0xab"}
Define an mdev device from a file:
# cat vfio_ap_device.json
{
"mdev_type": "vfio_ap-passthrough",
"start": "manual",
"attrs": [
{
"assign_adapter": "5"
},
{
"assign_domain": "0x47"
},
{
"assign_domain": "0xff"
}
]
}
# mdevctl define -p matrix --jsonfile vfio_ap_device.json
e2e73122-cc39-40ee-89eb-b0a47d334cae
# mdevctl list -dv
783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
Attrs:
@{0}: {"assign_adapter":"5"}
@{1}: {"assign_adapter":"6"}
@{2}: {"assign_domain":"0xab"}
@{3}: {"assign_control_domain":"0xab"}
e2e73122-cc39-40ee-89eb-b0a47d334cae matrix vfio_ap-passthrough manual
Attrs:
@{0}: {"assign_adapter":"5"}
@{1}: {"assign_domain":"0x47"}
@{2}: {"assign_domain":"0xff"}
FILES
/etc/mdevctl.d/*
Configuration files are in one subdirectory per parent device and named by UUID.
CONFIGURATION FILE FORMAT
Configuration files are in JSON. Attributes in "attrs" are optional.
{
"mdev_type": "TYPE",
"start": "auto|manual",
"attrs": [
{
"attribute0": "VALUE"
},
{
"attribute1": "VALUE"
}
]
}
SEE ALSO
udev(7) udevadm(8) driverctl(8)
mdevctl(8)