1mdevctl(8) System Manager's Manual mdevctl(8)
2
6 mdevctl, lsmdev - Mediated device management utility
7
9 mdevctl {COMMAND} [OPTIONS...]
10
13 mdevctl is a utility for managing and persisting devices in the medi‐
14 ated device device framework of the Linux kernel. Mediated devices are
15 sub-devices of a parent device (ex. a vGPU) which can be dynamically
16 created and potentially used by drivers like vfio-mdev for assignment
17 to virtual machines.
18
21 The following options are understood:
22 --addattr=ATTRIBUTE
25 Add an attribute ATTRIBUTE. Valid for the modify command.
26 -a|--auto
29 Automatically start the device on parent availability. Valid for
30 define and modify commands.
31 -d|--defined
34 List all defined devices, even if not active. Valid for the list
35 command.
36 --delattr
39 Delete an attribute entry. Valid for the modify command.
40 --dumpjson
43 Dump the configuration for a device in JSON format when filtered to
44 as single device and used with the list command. When used with
45 the types command, output machine readable type information.
46 -i|--index=INDEX
49 Act on the attribute INDEX. Valid for the modify command.
50 --jsonfile=FILE
53 Read the configuration for a device from a JSON file FILE. Valid
54 for the define and start commands.
55 -m|--manual
58 Do not start a device automatically on parent availability. Valid
59 for the modify command.
60 -p|--parent=PARENT
63 Specify or identify the device by its parent device.
64 -t|--type=TYPE
67 Specify or identify the device by its type.
68 -u|--uuid=UUID
71 Specify or identify the device by its UUID.
72 --value=VALUE
75 Set an attribute to VALUE, in the format accepted by the attribute.
76 Valid for the modify command.
77 -v|--verbose
80 Increase output verbosity, currently only adds attribute output to
81 the list command.
82
85 The following commands are understood:
86 define DEVICESPEC
89 Define a config for an mdev device, identified either by an UUID
90 (if the device already exists), or by the parent device and either
91 the type or a JSON configuration file, and, optionally, the UUID.
92 If no UUID is specified, one is autogenerated and printed. If no
93 file is used, -a|--auto may be used to specify that the device
94 should be started automatically.
95 list
98 List mdev devices. With no options, currently running devices are
99 listed. With -d|--defined, previously defined devices are listed.
100 Can be restricted to list only devices for a given parent or UUID.
101 With --dumpjson output is provided in machine readable JSON format.
102 When a UUID is provided and the output results in a single device,
103 the JSON output format is compatible with the configuration file
104 format.
105 modify DEVICESPEC
108 Modify the configuration for an mdev device, identified via its
109 UUID and optionally its parent. Type and startup mode (auto or
110 manual) can be modified by this command. Attributes can be added
111 or deleted. Attributes to be deleted must be specified by their
112 index; if an attribute is specified without an index, it is
113 appended at the end of the attribute list. Running devices are
114 unaffected by this command; changes in the configuration are
115 applied the next time the device is started.
116 start DEVICESPEC
119 Start an mdev device, identified by its UUID and optionally its
120 parent, or its parent and type and optionally its UUID, which is
121 generated if not given. If specified via its parent and optionally
122 its UUID, the type may be specified in a JSON configuration file,
123 alongside additional parameters.
124 stop DEVICESPEC
127 Stop an mdev device, specified via its UUID.
128 types
131 List the mdev device types known to the system by parent device.
132 Output may be limited to a single parent device with the -p|--par‐
133 ent option. JSON output format is used with the --dumpjson option.
134 undefine DEVICESPEC
137 Undefine, or remove the configuration for an mdev device, specified
138 by its UUID and optionally its parent. If a UUID exists for multi‐
139 ple parents, all of them will be removed unless restricted to a
140 single parent. Running devices are unaffected by this command.
141 version
144 Print mdevctl version.
145
148 For a given UUID, only one device with that UUID may be running at the
149 same time. However, it is possible to define multiple devices with the
150 same UUID under different parent devices. Therefore, it is sometimes
151 necessary to specify the parent device alongside the UUID to uniquely
152 identify a device.
153
156 On success, 0 is returned, a non-zero failure code otherwise.
157
160 List running mdev devices:
161 # mdevctl list
163 85006552-1b4b-45ef-ad62-de05be9171df 0000:00:02.0 i915-GVTg_V4_4
164 83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 (defined)
165 List defined mdev devices:
167 # mdevctl list -d
169 83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 auto
170 b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
171 5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual
172 List mdev types supported on the host system:
174 # mdevctl types
176 0000:00:02.0
177 i915-GVTg_V4_2
178 Available instances: 1
179 Device API: vfio-pci
180 Description: low_gm_size: 256MB high_gm_size: 1024MB fence: 4 resolution: 1920x1200 weight: 8
181 i915-GVTg_V4_1
182 Available instances: 0
183 Device API: vfio-pci
184 Description: low_gm_size: 512MB high_gm_size: 2048MB fence: 4 resolution: 1920x1200 weight: 16
185 i915-GVTg_V4_8
186 Available instances: 4
187 Device API: vfio-pci
188 Description: low_gm_size: 64MB high_gm_size: 384MB fence: 4 resolution: 1024x768 weight: 2
189 i915-GVTg_V4_4
190 Available instances: 3
191 Device API: vfio-pci
192 Description: low_gm_size: 128MB high_gm_size: 512MB fence: 4 resolution: 1920x1200 weight: 4
193 Modify a defined device from automatic start to manual:
195 # mdevctl modify --uuid 83c32df7-d52e-4ec1-9668-1f3c7e4df107 --manual
197 # mdevctl list -d
198 83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 manual
199 b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
200 5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual
201 Stop a running mdev device:
203 # mdevctl stop -u 83c32df7-d52e-4ec1-9668-1f3c7e4df107
205 Start an mdev device that is not defined:
207 # uuidgen
209 6eba5b41-176e-40db-b93e-7f18e04e0b93
210 # mdevctl start -u 6eba5b41-176e-40db-b93e-7f18e04e0b93 -p 0000:00:02.0 --type i915-GVTg_V4_1
211 # mdevctl list
212 85006552-1b4b-45ef-ad62-de05be9171df 0000:00:02.0 i915-GVTg_V4_4
213 6eba5b41-176e-40db-b93e-7f18e04e0b93 0000:00:02.0 i915-GVTg_V4_1
214 Promote the new created mdev to a defined device:
216 # mdevctl define --uuid 6eba5b41-176e-40db-b93e-7f18e04e0b93
218 # mdevctl list -d
219 83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 manual
220 6eba5b41-176e-40db-b93e-7f18e04e0b93 0000:00:02.0 i915-GVTg_V4_1 manual
221 b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
222 5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual
223 ADVANCED EXAMPLES (ATTRIBUTES AND JSON)
226 # mdevctl list -d
227 783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
228 Add some attributes:
230 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_adapter --value=5
232 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_adapter --value=6
233 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_domain --value=0xab
234 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_control_domain --value=0xab
235 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_domain --value=4
236 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_control_domain --value=4
237 # mdevctl list -dv
238 783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
239 Attrs:
240 @{0}: {"assign_adapter":"5"}
241 @{1}: {"assign_adapter":"6"}
242 @{2}: {"assign_domain":"0xab"}
243 @{3}: {"assign_control_domain":"0xab"}
244 @{4}: {"assign_domain":"4"}
245 @{5}: {"assign_control_domain":"4"}
246 Dump the JSON configuration:
248 # mdevctl list -d -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --dumpjson
250 {
251 "mdev_type": "vfio_ap-passthrough",
252 "start": "manual",
253 "attrs": [
254 {
255 "assign_adapter": "5"
256 },
257 {
258 "assign_adapter": "6"
259 },
260 {
261 "assign_domain": "0xab"
262 },
263 {
264 "assign_control_domain": "0xab"
265 },
266 {
267 "assign_domain": "4"
268 },
269 {
270 "assign_control_domain": "4"
271 }
272 ]
273 }
274 Remove some attributes:
276 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --delattr --index=5
278 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --delattr --index=4
279 # mdevctl list -dv
280 783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
281 Attrs:
282 @{0}: {"assign_adapter":"5"}
283 @{1}: {"assign_adapter":"6"}
284 @{2}: {"assign_domain":"0xab"}
285 @{3}: {"assign_control_domain":"0xab"}
286 Define an mdev device from a file:
288 # cat vfio_ap_device.json
290 {
291 "mdev_type": "vfio_ap-passthrough",
292 "start": "manual",
293 "attrs": [
294 {
295 "assign_adapter": "5"
296 },
297 {
298 "assign_domain": "0x47"
299 },
300 {
301 "assign_domain": "0xff"
302 }
303 ]
304 }
305 # mdevctl define -p matrix --jsonfile vfio_ap_device.json
306 e2e73122-cc39-40ee-89eb-b0a47d334cae
307 # mdevctl list -dv
308 783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
309 Attrs:
310 @{0}: {"assign_adapter":"5"}
311 @{1}: {"assign_adapter":"6"}
312 @{2}: {"assign_domain":"0xab"}
313 @{3}: {"assign_control_domain":"0xab"}
314 e2e73122-cc39-40ee-89eb-b0a47d334cae matrix vfio_ap-passthrough manual
315 Attrs:
316 @{0}: {"assign_adapter":"5"}
317 @{1}: {"assign_domain":"0x47"}
318 @{2}: {"assign_domain":"0xff"}
319
322 /etc/mdevctl.d/*
323 Configuration files are in one subdirectory per parent device and named
325 by UUID.
326
329 Configuration files are in JSON. Attributes in "attrs" are optional.
330 {
332 "mdev_type": "TYPE",
333 "start": "auto|manual",
334 "attrs": [
335 {
336 "attribute0": "VALUE"
337 },
338 {
339 "attribute1": "VALUE"
340 }
341 ]
342 }
343
346 udev(7) udevadm(8) driverctl(8)
347 mdevctl(8)