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 types 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
144 For a given UUID, only one device with that UUID may be running at the
145 same time. However, it is possible to define multiple devices with the
146 same UUID under different parent devices. Therefore, it is sometimes
147 necessary to specify the parent device alongside the UUID to uniquely
148 identify a device.
149
152 On success, 0 is returned, a non-zero failure code otherwise.
153
156 List running mdev devices:
157 # mdevctl list
159 85006552-1b4b-45ef-ad62-de05be9171df 0000:00:02.0 i915-GVTg_V4_4
160 83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 (defined)
161 List defined mdev devices:
163 # mdevctl list -d
165 83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 auto
166 b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
167 5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual
168 List mdev types supported on the host system:
170 # mdevctl types
172 0000:00:02.0
173 i915-GVTg_V4_2
174 Available instances: 1
175 Device API: vfio-pci
176 Description: low_gm_size: 256MB high_gm_size: 1024MB fence: 4 resolution: 1920x1200 weight: 8
177 i915-GVTg_V4_1
178 Available instances: 0
179 Device API: vfio-pci
180 Description: low_gm_size: 512MB high_gm_size: 2048MB fence: 4 resolution: 1920x1200 weight: 16
181 i915-GVTg_V4_8
182 Available instances: 4
183 Device API: vfio-pci
184 Description: low_gm_size: 64MB high_gm_size: 384MB fence: 4 resolution: 1024x768 weight: 2
185 i915-GVTg_V4_4
186 Available instances: 3
187 Device API: vfio-pci
188 Description: low_gm_size: 128MB high_gm_size: 512MB fence: 4 resolution: 1920x1200 weight: 4
189 Modify a defined device from automatic start to manual:
191 # mdevctl modify --uuid 83c32df7-d52e-4ec1-9668-1f3c7e4df107 --manual
193 # mdevctl list -d
194 83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 manual
195 b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
196 5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual
197 Stop a running mdev device:
199 # mdevctl stop -u 83c32df7-d52e-4ec1-9668-1f3c7e4df107
201 Start an mdev device that is not defined:
203 # uuidgen
205 6eba5b41-176e-40db-b93e-7f18e04e0b93
206 # mdevctl start -u 6eba5b41-176e-40db-b93e-7f18e04e0b93 -p 0000:00:02.0 --type i915-GVTg_V4_1
207 # mdevctl list
208 85006552-1b4b-45ef-ad62-de05be9171df 0000:00:02.0 i915-GVTg_V4_4
209 6eba5b41-176e-40db-b93e-7f18e04e0b93 0000:00:02.0 i915-GVTg_V4_1
210 Promote the new created mdev to a defined device:
212 # mdevctl define --uuid 6eba5b41-176e-40db-b93e-7f18e04e0b93
214 # mdevctl list -d
215 83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 manual
216 6eba5b41-176e-40db-b93e-7f18e04e0b93 0000:00:02.0 i915-GVTg_V4_1 manual
217 b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
218 5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual
219 ADVANCED EXAMPLES (ATTRIBUTES AND JSON)
222 # mdevctl list -d
223 783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
224 Add some attributes:
226 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_adapter --value=5
228 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_adapter --value=6
229 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_domain --value=0xab
230 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_control_domain --value=0xab
231 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_domain --value=4
232 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_control_domain --value=4
233 # mdevctl list -dv
234 783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
235 Attrs:
236 @{0}: {"assign_adapter":"5"}
237 @{1}: {"assign_adapter":"6"}
238 @{2}: {"assign_domain":"0xab"}
239 @{3}: {"assign_control_domain":"0xab"}
240 @{4}: {"assign_domain":"4"}
241 @{5}: {"assign_control_domain":"4"}
242 Dump the JSON configuration:
244 # mdevctl list -d -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --dumpjson
246 {
247 "mdev_type": "vfio_ap-passthrough",
248 "start": "manual",
249 "attrs": [
250 {
251 "assign_adapter": "5"
252 },
253 {
254 "assign_adapter": "6"
255 },
256 {
257 "assign_domain": "0xab"
258 },
259 {
260 "assign_control_domain": "0xab"
261 },
262 {
263 "assign_domain": "4"
264 },
265 {
266 "assign_control_domain": "4"
267 }
268 ]
269 }
270 Remove some attributes:
272 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --delattr --index=5
274 # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --delattr --index=4
275 # mdevctl list -dv
276 783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
277 Attrs:
278 @{0}: {"assign_adapter":"5"}
279 @{1}: {"assign_adapter":"6"}
280 @{2}: {"assign_domain":"0xab"}
281 @{3}: {"assign_control_domain":"0xab"}
282 Define an mdev device from a file:
284 # cat vfio_ap_device.json
286 {
287 "mdev_type": "vfio_ap-passthrough",
288 "start": "manual",
289 "attrs": [
290 {
291 "assign_adapter": "5"
292 },
293 {
294 "assign_domain": "0x47"
295 },
296 {
297 "assign_domain": "0xff"
298 }
299 ]
300 }
301 # mdevctl define -p matrix --jsonfile vfio_ap_device.json
302 e2e73122-cc39-40ee-89eb-b0a47d334cae
303 # mdevctl list -dv
304 783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
305 Attrs:
306 @{0}: {"assign_adapter":"5"}
307 @{1}: {"assign_adapter":"6"}
308 @{2}: {"assign_domain":"0xab"}
309 @{3}: {"assign_control_domain":"0xab"}
310 e2e73122-cc39-40ee-89eb-b0a47d334cae matrix vfio_ap-passthrough manual
311 Attrs:
312 @{0}: {"assign_adapter":"5"}
313 @{1}: {"assign_domain":"0x47"}
314 @{2}: {"assign_domain":"0xff"}
315
318 /etc/mdevctl.d/*
319 Configuration files are in one subdirectory per parent device and named
321 by UUID.
322
325 Configuration files are in JSON. Attributes in "attrs" are optional.
326 {
328 "mdev_type": "TYPE",
329 "start": "auto|manual",
330 "attrs": [
331 {
332 "attribute0": "VALUE"
333 },
334 {
335 "attribute1": "VALUE"
336 }
337 ]
338 }
339
342 udev(7) udevadm(8) driverctl(8)
343 mdevctl(8)