1MDEVCTL(8) MDEVCTL(8)
2
6 mdevctl - Mediated device management utility
7
9 mdevctl {COMMAND} [OPTIONS...]
10 lsmdev [OPTIONS...]
12
14 mdevctl is a utility for managing and persisting devices in the medi‐
15 ated device device framework of the Linux kernel. Mediated devices are
16 sub-devices of a parent device (ex. a vGPU) which can be dynamically
17 created and potentially used by drivers like vfio-mdev for assignment
18 to virtual machines.
19 lsmdev is an alias for mdevctl list.
21
23 The following options are understood:
24 --addattr=ATTRIBUTE
26 Add an attribute ATTRIBUTE. Valid for the modify command.
27 -a|--auto
29 Automatically start the device on parent availability. Valid for
30 define and modify commands.
31 -d|--defined
33 List all defined devices, even if not active. Valid for the list
34 command.
35 --delattr
37 Delete an attribute entry. Valid for the modify command.
38 --dumpjson
40 Dump the configuration for a device in JSON format when filtered
41 to as single device and used with the list command. When used
42 with the types command, output machine readable type informa‐
43 tion.
44 -i|--index=INDEX
46 Act on the attribute INDEX. Valid for the modify command.
47 --jsonfile=FILE
49 Read the configuration for a device from a JSON file FILE.
50 Valid for the define and start commands.
51 -m|--manual
53 Do not start a device automatically on parent availability.
54 Valid for the modify command.
55 -p|--parent=PARENT
57 Specify or identify the device by its parent device. Note that
58 the parent device is specified by its kernel sysfs name and is
59 case-sensitive.
60 -t|--type=TYPE
62 Specify or identify the device by its type.
63 -u|--uuid=UUID
65 Specify or identify the device by its UUID.
66 --value=VALUE
68 Set an attribute to VALUE, in the format accepted by the attri‐
69 bute. Valid for the modify command.
70 -v|--verbose
72 Increase output verbosity, currently only adds attribute output
73 to the list command.
74 -V|--version
76 Print mdevctl version.
77
79 The following commands are understood:
80 define DEVICESPEC
82 Define a config for an mdev device, identified either by an UUID
83 (if the device already exists), or by the parent device and ei‐
84 ther the type or a JSON configuration file, and, optionally, the
85 UUID. If no UUID is specified, one is autogenerated and printed.
86 If no file is used, -a|--auto may be used to specify that the
87 device should be started automatically.
88 list List mdev devices. With no options, currently running devices
90 are listed. With -d|--defined, previously defined devices are
91 listed. Can be restricted to list only devices for a given par‐
92 ent or UUID. With --dumpjson output is provided in machine read‐
93 able JSON format. When a UUID is provided and the output re‐
94 sults in a single device, the JSON output format is compatible
95 with the configuration file format.
96 modify DEVICESPEC
98 Modify the configuration for an mdev device, identified via its
99 UUID and optionally its parent. Type and startup mode (auto or
100 manual) can be modified by this command. Attributes can be
101 added or deleted. Attributes to be deleted must be specified by
102 their index; if an attribute is specified without an index, it
103 is appended at the end of the attribute list. Running devices
104 are unaffected by this command; changes in the configuration are
105 applied the next time the device is started.
106 start DEVICESPEC
108 Start a mediated device. This command can be used to start ei‐
109 ther a previously-defined device or a newly-created transient
110 device.
111 If the UUID and optional parent argument matches an existing de‐
113 vice definition, then the existing device will be started. It is
114 an error to specify a device type that conflicts with the exist‐
115 ing device definition.
116 If the UUID argument is omitted or if the specified UUID and
118 parent does not match an existing device definition, a new tran‐
119 sient device will be started. If the UUID is omitted, a new
120 UUID will be automatically generated. When starting a new tran‐
121 sient device, the parent and device type must be specified. A
122 --jsonfile may replace the --type specification and also include
123 additional attributes in JSON format to be applied to the
124 started device.
125 stop DEVICESPEC
127 Stop an mdev device, specified via its UUID.
128 types List the mdev device types known to the system by parent device.
130 Output may be limited to a single parent device with the
131 -p|--parent option. JSON output format is used with the
132 --dumpjson option.
133 undefine DEVICESPEC
135 Undefine, or remove the configuration for an mdev device, speci‐
136 fied by its UUID and optionally its parent. If a UUID exists for
137 multiple parents, all of them will be removed unless restricted
138 to a single parent. Running devices are unaffected by this com‐
139 mand.
140
142 For a given UUID, only one device with that UUID may be running at the
143 same time. However, it is possible to define multiple devices with the
144 same UUID under different parent devices. Therefore, it is sometimes
145 necessary to specify the parent device alongside the UUID to uniquely
146 identify a device.
147
149 On success, 0 is returned, a non-zero failure code otherwise.
150
152 List running mdev devices:
153 # mdevctl list
155 85006552-1b4b-45ef-ad62-de05be9171df 0000:00:02.0 i915-GVTg_V4_4
156 83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 (defined)
157 List defined mdev devices:
159 # mdevctl list -d
161 83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 auto
162 b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
163 5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual
164 List mdev types supported on the host system:
166 # mdevctl types
168 0000:00:02.0
169 i915-GVTg_V4_2
170 Available instances: 1
171 Device API: vfio-pci
172 Description: low_gm_size: 256MB high_gm_size: 1024MB fence: 4 resolution: 1920x1200 weight: 8
173 i915-GVTg_V4_1
174 Available instances: 0
175 Device API: vfio-pci
176 Description: low_gm_size: 512MB high_gm_size: 2048MB fence: 4 resolution: 1920x1200 weight: 16
177 i915-GVTg_V4_8
178 Available instances: 4
179 Device API: vfio-pci
180 Description: low_gm_size: 64MB high_gm_size: 384MB fence: 4 resolution: 1024x768 weight: 2
181 i915-GVTg_V4_4
182 Available instances: 3
183 Device API: vfio-pci
184 Description: low_gm_size: 128MB high_gm_size: 512MB fence: 4 resolution: 1920x1200 weight: 4
185 Modify a defined device from automatic start to manual:
187 # mdevctl modify --uuid 83c32df7-d52e-4ec1-9668-1f3c7e4df107 --manual
189 # mdevctl list -d
190 83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 manual
191 b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
192 5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual
193 Stop a running mdev device:
195 # mdevctl stop -u 83c32df7-d52e-4ec1-9668-1f3c7e4df107
197 Start an mdev device that is not defined:
199 # uuidgen
201 6eba5b41-176e-40db-b93e-7f18e04e0b93
202 # mdevctl start -u 6eba5b41-176e-40db-b93e-7f18e04e0b93 -p 0000:00:02.0 --type i915-GVTg_V4_1
203 # mdevctl list
204 85006552-1b4b-45ef-ad62-de05be9171df 0000:00:02.0 i915-GVTg_V4_4
205 6eba5b41-176e-40db-b93e-7f18e04e0b93 0000:00:02.0 i915-GVTg_V4_1
206 Promote the new created mdev to a defined device:
208 # mdevctl define --uuid 6eba5b41-176e-40db-b93e-7f18e04e0b93
210 # mdevctl list -d
211 83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 manual
212 6eba5b41-176e-40db-b93e-7f18e04e0b93 0000:00:02.0 i915-GVTg_V4_1 manual
213 b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
214 5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual
215 ADVANCED EXAMPLES (ATTRIBUTES AND JSON)
217 # mdevctl list -d
218 783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
219 Add some attributes:
221 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_adapter --value=5
223 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_adapter --value=6
224 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_domain --value=0xab
225 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_control_domain --value=0xab
226 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_domain --value=4
227 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_control_domain --value=4
228 # mdevctl list -dv
229 783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
230 Attrs:
231 @{0}: {"assign_adapter":"5"}
232 @{1}: {"assign_adapter":"6"}
233 @{2}: {"assign_domain":"0xab"}
234 @{3}: {"assign_control_domain":"0xab"}
235 @{4}: {"assign_domain":"4"}
236 @{5}: {"assign_control_domain":"4"}
237 Dump the JSON configuration:
239 # mdevctl list -d -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --dumpjson
241 {
242 "mdev_type": "vfio_ap-passthrough",
243 "start": "manual",
244 "attrs": [
245 {
246 "assign_adapter": "5"
247 },
248 {
249 "assign_adapter": "6"
250 },
251 {
252 "assign_domain": "0xab"
253 },
254 {
255 "assign_control_domain": "0xab"
256 },
257 {
258 "assign_domain": "4"
259 },
260 {
261 "assign_control_domain": "4"
262 }
263 ]
264 }
265 Remove some attributes:
267 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --delattr --index=5
269 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --delattr --index=4
270 # mdevctl list -dv
271 783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
272 Attrs:
273 @{0}: {"assign_adapter":"5"}
274 @{1}: {"assign_adapter":"6"}
275 @{2}: {"assign_domain":"0xab"}
276 @{3}: {"assign_control_domain":"0xab"}
277 Define an mdev device from a file:
279 # cat vfio_ap_device.json
281 {
282 "mdev_type": "vfio_ap-passthrough",
283 "start": "manual",
284 "attrs": [
285 {
286 "assign_adapter": "5"
287 },
288 {
289 "assign_domain": "0x47"
290 },
291 {
292 "assign_domain": "0xff"
293 }
294 ]
295 }
296 # mdevctl define -p matrix --jsonfile vfio_ap_device.json
297 e2e73122-cc39-40ee-89eb-b0a47d334cae
298 # mdevctl list -dv
299 783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
300 Attrs:
301 @{0}: {"assign_adapter":"5"}
302 @{1}: {"assign_adapter":"6"}
303 @{2}: {"assign_domain":"0xab"}
304 @{3}: {"assign_control_domain":"0xab"}
305 e2e73122-cc39-40ee-89eb-b0a47d334cae matrix vfio_ap-passthrough manual
306 Attrs:
307 @{0}: {"assign_adapter":"5"}
308 @{1}: {"assign_domain":"0x47"}
309 @{2}: {"assign_domain":"0xff"}
310
312 Configuration files are in JSON. Attributes in "attrs" are optional.
313 {
315 "mdev_type": "TYPE",
316 "start": "auto|manual",
317 "attrs": [
318 {
319 "attribute0": "VALUE"
320 },
321 {
322 "attribute1": "VALUE"
323 }
324 ]
325 }
326
328 mdevctl supports invoking external scripts to handle additional device
329 type-specific configurations and to broadcast notifications regarding
330 changes or updates to a device. These scripts are invoked before, af‐
331 ter, and/or during mdevctl's "primary command execution" (e.g. writing
332 the device configuration file for define, or activating a device for
333 start).
334 Essentially, the procedure in mdevctl looks like this:
336 • command-line parsing & setup
338 • invoke pre-command call-out
340 • primary command execution [1]
342 • invoke post-command call-out [1]
344 • invoke notifier
346 [1] skipped if step 2 fails.
348 EVENT SCRIPTS
350 A call-out or notification event invokes a script along with a set of
351 parameters detailing the type of call-out, mdevctl's command execution
352 progress, and the mediated device. The parameters are as follows:
353 <CONFIG> | SCRIPT <-t=type -e=event -a=action -s=state -u=UUID -p=par‐
355 ent>
356 CONFIG The device's JSON configuration, provided via standard input.
358 -t=type
360 The device type.
361 -e=event
363 Event type of call-out that is invoked. For call-out scripts,
364 this may be pre, post, or get. For notification scripts, this
365 will always be notify.
366 -a=action
368 An action synonymous with an mdevctl command (e.g. define,
369 start).
370 -s=state
372 A trinary state of the mdevctl command execution. The possibili‐
373 ties are none if the mdevctl command has yet to execute, success
374 if the mdevctl command completed successfully, or failure if
375 there was a problem executing the mdevctl command.
376 -u=UUID
378 UUID of the mediated device.
379 -p=parent
381 Parent of the mediated the device.
382 CALL-OUT EVENT SCRIPTS
384 A call-out event script is invoked during a pre, post, or get event.
385 mdevctl will attempt each script stored in the mdevctl callouts direc‐
386 tory until either a script that satisfies the device type is found or
387 all scripts have been attempted. A device script must check the "TYPE"
388 parameter to ensure the specified device type is supported, otherwise
389 error code 2 should be returned. If no script is found for the speci‐
390 fied device type, then mdevctl will carry on as normal.
391 These scripts are stored in /etc/mdevctl.d/scripts.d/callouts. The same
393 script is invoked for pre, post, and get call-out events for the device
394 type.
395 Pre-Command
397 A pre-command call-out event is invoked once prior to primary com‐
398 mand execution. Event type is pre. Status will always be none.
399 Any non-zero return code (exempting 2) will prevent mdevctl from
401 performing the primary command execution and mdevctl will abort
402 early.
403 A notification event will follow only if an error code (exempting 2)
405 is observed.
406 This event is not supported for the list, types, or version com‐
408 mands.
409 Post-Command
411 A post-command call-out event is invoked once after primary command
412 execution. Event type is post. Status will be success if mdevctl
413 was able to finish primary command execution successfully, or fail‐
414 ure otherwise.
415 The same script used for the pre event is used for the post event.
417 Any return code is non-disruptive.
419 A notification event will always follow a post-command call-out.
421 This event is not supported for the list, types, or version com‐
423 mands.
424 Get-attributes
426 A get event is invoked during a define and list command to acquire
427 device attributes from an active device. Event type is get. Action
428 is attributes. Status is none. Note that, unlike other call-outs
429 events, get-attributes does not expect a device config on stdin, and
430 an array of JSON formatted device attributes is returned via stdout.
431 The same script used for the pre event is used for the get event. If
433 the script is not designed to support a get event, then the return
434 code is 0.
435 For define, a non-zero return code (exempting 2) will disrupt the
437 define command entirely.
438 For list, any return code is non-disruptive.
440 A script must return a JSON formatted array of device attributes on
442 standard output. Example:
443 [
445 {
446 "attribute0": "VALUE"
447 },
448 {
449 "attribute1": "VALUE"
450 }
451 ]
452 AUTO-START CALL-OUTS
454 For each device set to start automatically during system boot, mdevctl
455 will invoke the pre and post events. Action is the string start.
456 Return code and notification event behavior is the same as documented
458 for the pre and post events. Errors reported by a script will disrupt
459 the auto-start for that particular device and the message will be re‐
460 ported to the system log before attempting to the next auto-start de‐
461 vice.
462 Note that if a notification script is used to convey information to an‐
464 other program or daemon during the auto-start procedure, it is not
465 guaranteed that the program will already be active prior to mdevctl's
466 invocation (e.g. the auto-start event may occur before the libvirt dae‐
467 mon is activated).
468 NOTIFICATION EVENT SCRIPTS
470 Notification event scripts may be used to signal the state of the medi‐
471 ated device or the status of an mdevctl command to other programs or
472 loggers. Unlike call-out scripts, notifier scripts are device-type ag‐
473 nostic.
474 Notify
476 A notification event is invoked once either following a pre-command
477 call-out failure or after a post-command call-out. Event is notify.
478 If following a pre event, then status will be none. If following a
479 post event, then status will mirror the value passed to the
480 post-command call-out.
481 These scripts are stored in /etc/mdevctl.d/scripts.d/notifiers. All
483 notification scripts will be invoked during a notification event.
484 A non-zero return code is ignored.
486 This event is not supported for the list, types, or version com‐
488 mands.
489 SCRIPT RETURN VALUES
491 A call-out script should return one of the following values:
492 • 0 if OK,
494 • 1 if an error occurred,
496 • 2 if the script does not support the device type
498
500 /etc/mdevctl.d/*
501 Configuration files are in one subdirectory per parent device and named
503 by UUID.
504 /etc/mdevctl.d/scripts.d/callouts/*
506 Scripts for pre/post/get call-out events.
508 /etc/mdevctl.d/scripts.d/notifiers/*
510 Scripts for notification call-out events.
512
514 udev(7), udevadm(8), driverctl(8)
515 MDEVCTL(8)