1mdevctl(8)                  System Manager's Manual                 mdevctl(8)
2
3
4

NAME

6       mdevctl, lsmdev - Mediated device management utility
7

SYNOPSIS

9       mdevctl {COMMAND} [OPTIONS...]
10
11

DESCRIPTION

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
19

OPTIONS

21       The following options are understood:
22
23
24       --addattr=ATTRIBUTE
25           Add an attribute ATTRIBUTE. Valid for the modify command.
26
27
28       -a|--auto
29           Automatically  start  the  device on parent availability. Valid for
30           define and modify commands.
31
32
33       -d|--defined
34           List all defined devices, even if not active. Valid  for  the  list
35           command.
36
37
38       --delattr
39           Delete an attribute entry. Valid for the modify command.
40
41
42       --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
47
48       -i|--index=INDEX
49           Act on the attribute INDEX. Valid for the modify command.
50
51
52       --jsonfile=FILE
53           Read  the  configuration for a device from a JSON file FILE.  Valid
54           for the define and start commands.
55
56
57       -m|--manual
58           Do not start a device automatically on parent  availability.  Valid
59           for the modify command.
60
61
62       -p|--parent=PARENT
63           Specify or identify the device by its parent device.
64
65
66       -t|--type=TYPE
67           Specify or identify the device by its type.
68
69
70       -u|--uuid=UUID
71           Specify or identify the device by its UUID.
72
73
74       --value=VALUE
75           Set an attribute to VALUE, in the format accepted by the attribute.
76           Valid for the modify command.
77
78
79       -v|--verbose
80           Increase output verbosity, currently only adds attribute output  to
81           the types command.
82
83

COMMANDS

85       The following commands are understood:
86
87
88       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
96
97       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
106
107       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
117
118       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
125
126       stop DEVICESPEC
127           Stop an mdev device, specified via its UUID.
128
129
130       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
135
136       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
142

NOTE ON DEVICE SPECIFICATION

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
150

EXIT STATUS

152       On success, 0 is returned, a non-zero failure code otherwise.
153
154

EXAMPLES

156       List running mdev devices:
157
158       # 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
162       List defined mdev devices:
163
164       # 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
169       List mdev types supported on the host system:
170
171       # 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
190       Modify a defined device from automatic start to manual:
191
192       # 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
198       Stop a running mdev device:
199
200       # mdevctl stop -u 83c32df7-d52e-4ec1-9668-1f3c7e4df107
201
202       Start an mdev device that is not defined:
203
204       # 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
211       Promote the new created mdev to a defined device:
212
213       # 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
220
221   ADVANCED EXAMPLES (ATTRIBUTES AND JSON)
222       # mdevctl list -d
223       783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
224
225       Add some attributes:
226
227       # 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
243       Dump the JSON configuration:
244
245       # 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
271       Remove some attributes:
272
273       # 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
283       Define an mdev device from a file:
284
285       # 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
316

FILES

318       /etc/mdevctl.d/*
319
320       Configuration files are in one subdirectory per parent device and named
321       by UUID.
322
323

CONFIGURATION FILE FORMAT

325       Configuration files are in JSON. Attributes in "attrs" are optional.
326
327       {
328         "mdev_type": "TYPE",
329         "start": "auto|manual",
330         "attrs": [
331           {
332             "attribute0": "VALUE"
333           },
334           {
335             "attribute1": "VALUE"
336           }
337         ]
338       }
339
340

SEE ALSO

342       udev(7) udevadm(8) driverctl(8)
343
344
345
346                                                                    mdevctl(8)
Impressum