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 -V|--version
85 Print mdevctl version.
86
89 The following commands are understood:
90 define DEVICESPEC
93 Define a config for an mdev device, identified either by an UUID
94 (if the device already exists), or by the parent device and either
95 the type or a JSON configuration file, and, optionally, the UUID.
96 If no UUID is specified, one is autogenerated and printed. If no
97 file is used, -a|--auto may be used to specify that the device
98 should be started automatically.
99 list
102 List mdev devices. With no options, currently running devices are
103 listed. With -d|--defined, previously defined devices are listed.
104 Can be restricted to list only devices for a given parent or UUID.
105 With --dumpjson output is provided in machine readable JSON format.
106 When a UUID is provided and the output results in a single device,
107 the JSON output format is compatible with the configuration file
108 format.
109 modify DEVICESPEC
112 Modify the configuration for an mdev device, identified via its
113 UUID and optionally its parent. Type and startup mode (auto or
114 manual) can be modified by this command. Attributes can be added
115 or deleted. Attributes to be deleted must be specified by their in‐
116 dex; if an attribute is specified without an index, it is appended
117 at the end of the attribute list. Running devices are unaffected
118 by this command; changes in the configuration are applied the next
119 time the device is started.
120 start DEVICESPEC
123 Start a mediated device. This command can be used to start either a
124 previously-defined device or a newly-created transient device.
125 If the UUID and optional parent argument matches an existing device
127 definition, then the existing device will be started. It is an er‐
128 ror to specify a device type that conflicts with the existing de‐
129 vice definition.
130 If the UUID argument is omitted or if the specified UUID and parent
132 does not match an existing device definition, a new transient de‐
133 vice will be started. If the UUID is omitted, a new UUID will be
134 automatically generated. When starting a new transient device, the
135 parent and device type must be specified. A --jsonfile may replace
136 the --type specification and also include additional attributes in
137 JSON format to be applied to the started device.
138 stop DEVICESPEC
141 Stop an mdev device, specified via its UUID.
142 types
145 List the mdev device types known to the system by parent device.
146 Output may be limited to a single parent device with the -p|--par‐
147 ent option. JSON output format is used with the --dumpjson option.
148 undefine DEVICESPEC
151 Undefine, or remove the configuration for an mdev device, specified
152 by its UUID and optionally its parent. If a UUID exists for multi‐
153 ple parents, all of them will be removed unless restricted to a
154 single parent. Running devices are unaffected by this command.
155
158 For a given UUID, only one device with that UUID may be running at the
159 same time. However, it is possible to define multiple devices with the
160 same UUID under different parent devices. Therefore, it is sometimes
161 necessary to specify the parent device alongside the UUID to uniquely
162 identify a device.
163
166 On success, 0 is returned, a non-zero failure code otherwise.
167
170 List running mdev devices:
171 # mdevctl list
173 85006552-1b4b-45ef-ad62-de05be9171df 0000:00:02.0 i915-GVTg_V4_4
174 83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 (defined)
175 List defined mdev devices:
177 # mdevctl list -d
179 83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 auto
180 b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
181 5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual
182 List mdev types supported on the host system:
184 # mdevctl types
186 0000:00:02.0
187 i915-GVTg_V4_2
188 Available instances: 1
189 Device API: vfio-pci
190 Description: low_gm_size: 256MB high_gm_size: 1024MB fence: 4 resolution: 1920x1200 weight: 8
191 i915-GVTg_V4_1
192 Available instances: 0
193 Device API: vfio-pci
194 Description: low_gm_size: 512MB high_gm_size: 2048MB fence: 4 resolution: 1920x1200 weight: 16
195 i915-GVTg_V4_8
196 Available instances: 4
197 Device API: vfio-pci
198 Description: low_gm_size: 64MB high_gm_size: 384MB fence: 4 resolution: 1024x768 weight: 2
199 i915-GVTg_V4_4
200 Available instances: 3
201 Device API: vfio-pci
202 Description: low_gm_size: 128MB high_gm_size: 512MB fence: 4 resolution: 1920x1200 weight: 4
203 Modify a defined device from automatic start to manual:
205 # mdevctl modify --uuid 83c32df7-d52e-4ec1-9668-1f3c7e4df107 --manual
207 # mdevctl list -d
208 83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 manual
209 b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
210 5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual
211 Stop a running mdev device:
213 # mdevctl stop -u 83c32df7-d52e-4ec1-9668-1f3c7e4df107
215 Start an mdev device that is not defined:
217 # uuidgen
219 6eba5b41-176e-40db-b93e-7f18e04e0b93
220 # mdevctl start -u 6eba5b41-176e-40db-b93e-7f18e04e0b93 -p 0000:00:02.0 --type i915-GVTg_V4_1
221 # mdevctl list
222 85006552-1b4b-45ef-ad62-de05be9171df 0000:00:02.0 i915-GVTg_V4_4
223 6eba5b41-176e-40db-b93e-7f18e04e0b93 0000:00:02.0 i915-GVTg_V4_1
224 Promote the new created mdev to a defined device:
226 # mdevctl define --uuid 6eba5b41-176e-40db-b93e-7f18e04e0b93
228 # mdevctl list -d
229 83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 manual
230 6eba5b41-176e-40db-b93e-7f18e04e0b93 0000:00:02.0 i915-GVTg_V4_1 manual
231 b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
232 5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual
233 ADVANCED EXAMPLES (ATTRIBUTES AND JSON)
236 # mdevctl list -d
237 783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
238 Add some attributes:
240 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_adapter --value=5
242 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_adapter --value=6
243 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_domain --value=0xab
244 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_control_domain --value=0xab
245 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_domain --value=4
246 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_control_domain --value=4
247 # mdevctl list -dv
248 783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
249 Attrs:
250 @{0}: {"assign_adapter":"5"}
251 @{1}: {"assign_adapter":"6"}
252 @{2}: {"assign_domain":"0xab"}
253 @{3}: {"assign_control_domain":"0xab"}
254 @{4}: {"assign_domain":"4"}
255 @{5}: {"assign_control_domain":"4"}
256 Dump the JSON configuration:
258 # mdevctl list -d -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --dumpjson
260 {
261 "mdev_type": "vfio_ap-passthrough",
262 "start": "manual",
263 "attrs": [
264 {
265 "assign_adapter": "5"
266 },
267 {
268 "assign_adapter": "6"
269 },
270 {
271 "assign_domain": "0xab"
272 },
273 {
274 "assign_control_domain": "0xab"
275 },
276 {
277 "assign_domain": "4"
278 },
279 {
280 "assign_control_domain": "4"
281 }
282 ]
283 }
284 Remove some attributes:
286 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --delattr --index=5
288 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --delattr --index=4
289 # mdevctl list -dv
290 783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
291 Attrs:
292 @{0}: {"assign_adapter":"5"}
293 @{1}: {"assign_adapter":"6"}
294 @{2}: {"assign_domain":"0xab"}
295 @{3}: {"assign_control_domain":"0xab"}
296 Define an mdev device from a file:
298 # cat vfio_ap_device.json
300 {
301 "mdev_type": "vfio_ap-passthrough",
302 "start": "manual",
303 "attrs": [
304 {
305 "assign_adapter": "5"
306 },
307 {
308 "assign_domain": "0x47"
309 },
310 {
311 "assign_domain": "0xff"
312 }
313 ]
314 }
315 # mdevctl define -p matrix --jsonfile vfio_ap_device.json
316 e2e73122-cc39-40ee-89eb-b0a47d334cae
317 # mdevctl list -dv
318 783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
319 Attrs:
320 @{0}: {"assign_adapter":"5"}
321 @{1}: {"assign_adapter":"6"}
322 @{2}: {"assign_domain":"0xab"}
323 @{3}: {"assign_control_domain":"0xab"}
324 e2e73122-cc39-40ee-89eb-b0a47d334cae matrix vfio_ap-passthrough manual
325 Attrs:
326 @{0}: {"assign_adapter":"5"}
327 @{1}: {"assign_domain":"0x47"}
328 @{2}: {"assign_domain":"0xff"}
329
332 Configuration files are in JSON. Attributes in "attrs" are optional.
333 {
335 "mdev_type": "TYPE",
336 "start": "auto|manual",
337 "attrs": [
338 {
339 "attribute0": "VALUE"
340 },
341 {
342 "attribute1": "VALUE"
343 }
344 ]
345 }
346
349 mdevctl supports invoking external scripts to handle additional device
350 type-specific configurations and to broadcast notifications regarding
351 changes or updates to a device. These scripts are invoked before, af‐
352 ter, and/or during mdevctl's "primary command execution" (e.g. writing
353 the device configuration file for define, or activating a device for
354 start).
355 Essentially, the procedure in mdevctl looks like this:
357 1. command-line parsing & setup
360 2. invoke pre-command call-out
362 3. primary command execution*
364 4. invoke post-command call-out*
366 5. invoke notifier
368 * skipped if step 2 fails.
370 EVENT SCRIPTS
373 A call-out or notification event invokes a script along with a set of
374 parameters detailing the type of call-out, mdevctl's command execution
375 progress, and the mediated device. The parameters are as follows:
376 <CONFIG> | SCRIPT <-t=type -e=event -a=action -s=state -u=UUID -p=par‐
378 ent>
379 CONFIG
382 The device's JSON configuration, provided via standard input.
383 -t=type
386 The device type.
387 -e=event
390 Event type of call-out that is invoked. For call-out scripts, this
391 may be pre, post, or get. For notification scripts, this will al‐
392 ways be notify.
393 -a=action
396 An action synonymous with an mdevctl command (e.g. define, start).
397 -s=state
400 A trinary state of the mdevctl command execution. The possibilities
401 are none if the mdevctl command has yet to execute, success if the
402 mdevctl command completed successfully, or failure if there was a
403 problem executing the mdevctl command.
404 -u=UUID
407 UUID of the mediated device.
408 -p=parent>
411 Parent of the mediated the device.
412 CALL-OUT EVENT SCRIPTS
415 A call-out event script is invoked during a pre, post, or get event.
416 mdevctl will attempt each script stored in the mdevctl callouts direc‐
417 tory until either a script that satisfies the device type is found or
418 all scripts have been attempted. A device script must check the "TYPE"
419 parameter to ensure the specified device type is supported, otherwise
420 error code 2 should be returned. If no script is found for the speci‐
421 fied device type, then mdevctl will carry on as normal.
422 These scripts are stored in /etc/mdevctl.d/scripts.d/callouts. The same
424 script is invoked for pre, post, and get call-out events for the device
425 type.
426 Pre-Command
429 A pre-command call-out event is invoked once prior to primary com‐
431 mand execution. Event type is pre. Status will always be none.
432 Any non-zero return code (exempting 2) will prevent mdevctl from
434 performing the primary command execution and mdevctl will abort
435 early.
436 A notification event will follow only if an error code (exempting
438 2) is observed.
439 This event is not supported for the list, types, or version com‐
441 mands.
442 Post-Command
445 A post-command call-out event is invoked once after primary command
447 execution. Event type is post. Status will be success if mdevctl
448 was able to finish primary command execution successfully, or fail‐
449 ure otherwise.
450 The same script used for the pre event is used for the post event.
452 Any return code is non-disruptive.
454 A notification event will always follow a post-command call-out.
456 This event is not supported for the list, types, or version com‐
458 mands.
459 Get-attributes
462 A get event is invoked during a define and list command to acquire
464 device attributes from an active device. Event type is get. Action
465 is attributes. Status is none. Note that, unlike other call-outs
466 events, get-attributes does not expect a device config on stdin,
467 and an array of JSON formatted device attributes is returned via
468 stdout.
469 The same script used for the pre event is used for the get event.
471 If the script is not designed to support a get event, then the re‐
472 turn code is 0.
473 For define, a non-zero return code (exempting 2) will disrupt the
475 define command entirely.
476 For list, any return code is non-disruptive.
478 A script must return a JSON formatted array of device attributes on
480 standard output. Example:
481 [
483 {
484 "attribute0": "VALUE"
485 },
486 {
487 "attribute1": "VALUE"
488 }
489 ]
490 AUTO-START CALL-OUTS
493 For each device set to start automatically during system boot, mdevctl
494 will invoke the pre and post events. Action is the string start.
495 Return code and notification event behavior is the same as documented
497 for the pre and post events. Errors reported by a script will disrupt
498 the auto-start for that particular device and the message will be re‐
499 ported to the system log before attempting to the next auto-start de‐
500 vice.
501 Note that if a notification script is used to convey information to an‐
503 other program or daemon during the auto-start procedure, it is not
504 guaranteed that the program will already be active prior to mdevctl's
505 invocation (e.g. the auto-start event may occur before the libvirt dae‐
506 mon is activated).
507 NOTIFICATION EVENT SCRIPTS
510 Notification event scripts may be used to signal the state of the medi‐
511 ated device or the status of an mdevctl command to other programs or
512 loggers. Unlike call-out scripts, notifier scripts are device-type ag‐
513 nostic.
514 Notify
517 A notification event is invoked once either following a pre-command
519 call-out failure or after a post-command call-out. Event is notify.
520 If following a pre event, then status will be none. If following a
521 post event, then status will mirror the value passed to the post-
522 command call-out.
523 These scripts are stored in /etc/mdevctl.d/scripts.d/notifiers. All
525 notification scripts will be invoked during a notification event.
526 A non-zero return code is ignored.
528 This event is not supported for the list, types, or version com‐
530 mands.
531 SCRIPT RETURN VALUES
534 0 if OK,
535 1 if an error occurred,
537 2 if the script does not support the device type
539
542 /etc/mdevctl.d/*
543 Configuration files are in one subdirectory per parent device and named
545 by UUID.
546 /etc/mdevctl.d/scripts.d/callouts/*
548 Scripts for pre/post/get call-out events.
550 /etc/mdevctl.d/scripts.d/notifiers/*
552 Scripts for notification call-out events.
554
557 udev(7) udevadm(8) driverctl(8)
558 mdevctl(8)