Provided by: mdevctl_0.81-1_all bug

NAME

       mdevctl, lsmdev - Mediated device management utility

SYNOPSIS

       mdevctl {COMMAND} [OPTIONS...]

DESCRIPTION

       mdevctl  is  a  utility  for managing and persisting devices in the mediated device device
       framework of the Linux kernel.  Mediated devices are sub-devices of a parent device (ex. a
       vGPU)  which can be dynamically created and potentially used by drivers like vfio-mdev for
       assignment to virtual machines.

OPTIONS

       The following options are understood:

       --addattr=ATTRIBUTE
           Add an attribute ATTRIBUTE. Valid for the modify command.

       -a|--auto
           Automatically start the device on parent availability. Valid  for  define  and  modify
           commands.

       -d|--defined
           List all defined devices, even if not active. Valid for the list command.

       --delattr
           Delete an attribute entry. Valid for the modify command.

       --dumpjson
           Dump  the  configuration for a device in JSON format when filtered to as single device
           and used with the list command.  When used with  the  types  command,  output  machine
           readable type information.

       -i|--index=INDEX
           Act on the attribute INDEX. Valid for the modify command.

       --jsonfile=FILE
           Read  the  configuration for a device from a JSON file FILE.  Valid for the define and
           start commands.

       -m|--manual
           Do not start a device automatically on  parent  availability.  Valid  for  the  modify
           command.

       -p|--parent=PARENT
           Specify or identify the device by its parent device.

       -t|--type=TYPE
           Specify or identify the device by its type.

       -u|--uuid=UUID
           Specify or identify the device by its UUID.

       --value=VALUE
           Set  an  attribute  to  VALUE, in the format accepted by the attribute.  Valid for the
           modify command.

       -v|--verbose
           Increase output verbosity, currently only adds attribute output to the list command.

COMMANDS

       The following commands are understood:

       define DEVICESPEC
           Define a config for an mdev device, identified  either  by  an  UUID  (if  the  device
           already  exists),  or by the parent device and either the type or a JSON configuration
           file, and, optionally, the UUID. If no UUID is specified,  one  is  autogenerated  and
           printed.  If  no file is used, -a|--auto may be used to specify that the device should
           be started automatically.

       list
           List mdev devices. With no  options,  currently  running  devices  are  listed.   With
           -d|--defined,  previously  defined devices are listed.  Can be restricted to list only
           devices for a given parent or UUID. With --dumpjson  output  is  provided  in  machine
           readable  JSON  format.   When  a  UUID is provided and the output results in a single
           device, the JSON output format is compatible with the configuration file format.

       modify DEVICESPEC
           Modify the configuration for an mdev device, identified via its  UUID  and  optionally
           its  parent.   Type and startup mode (auto or manual) can be modified by this command.
           Attributes can be added or deleted. Attributes to be  deleted  must  be  specified  by
           their  index; if an attribute is specified without an index, it is appended at the end
           of the attribute list.  Running devices are unaffected by this command; changes in the
           configuration are applied the next time the device is started.

       start DEVICESPEC
           Start  an mdev device, identified by its UUID and optionally its parent, or its parent
           and type and optionally its UUID, which is generated if not given.  If  specified  via
           its  parent and optionally its UUID, the type may be specified in a JSON configuration
           file, alongside additional parameters.

       stop DEVICESPEC
           Stop an mdev device, specified via its UUID.

       types
           List the mdev device types known to the  system  by  parent  device.   Output  may  be
           limited  to a single parent device with the -p|--parent option.  JSON output format is
           used with the --dumpjson option.

       undefine DEVICESPEC
           Undefine, or remove the configuration for an mdev device, specified by  its  UUID  and
           optionally  its  parent.  If  a  UUID exists for multiple parents, all of them will be
           removed unless restricted to a single parent.  Running devices are unaffected by  this
           command.

       version
           Print mdevctl version.

NOTE ON DEVICE SPECIFICATION

       For a given UUID, only one device with that UUID may be running at the same time. However,
       it is possible to define multiple devices  with  the  same  UUID  under  different  parent
       devices.  Therefore,  it is sometimes necessary to specify the parent device alongside the
       UUID to uniquely identify a device.

EXIT STATUS

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

EXAMPLES

       List running mdev devices:

       # mdevctl list
       85006552-1b4b-45ef-ad62-de05be9171df 0000:00:02.0 i915-GVTg_V4_4
       83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 (defined)

       List defined mdev devices:

       # mdevctl list -d
       83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 auto
       b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
       5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual

       List mdev types supported on the host system:

       # mdevctl types
       0000:00:02.0
         i915-GVTg_V4_2
           Available instances: 1
           Device API: vfio-pci
           Description: low_gm_size: 256MB high_gm_size: 1024MB fence: 4 resolution: 1920x1200 weight: 8
         i915-GVTg_V4_1
           Available instances: 0
           Device API: vfio-pci
           Description: low_gm_size: 512MB high_gm_size: 2048MB fence: 4 resolution: 1920x1200 weight: 16
         i915-GVTg_V4_8
           Available instances: 4
           Device API: vfio-pci
           Description: low_gm_size: 64MB high_gm_size: 384MB fence: 4 resolution: 1024x768 weight: 2
         i915-GVTg_V4_4
           Available instances: 3
           Device API: vfio-pci
           Description: low_gm_size: 128MB high_gm_size: 512MB fence: 4 resolution: 1920x1200 weight: 4

       Modify a defined device from automatic start to manual:

       # mdevctl modify --uuid 83c32df7-d52e-4ec1-9668-1f3c7e4df107 --manual
       # mdevctl list -d
       83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 manual
       b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
       5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual

       Stop a running mdev device:

       # mdevctl stop -u 83c32df7-d52e-4ec1-9668-1f3c7e4df107

       Start an mdev device that is not defined:

       # uuidgen
       6eba5b41-176e-40db-b93e-7f18e04e0b93
       # mdevctl start -u 6eba5b41-176e-40db-b93e-7f18e04e0b93 -p 0000:00:02.0 --type i915-GVTg_V4_1
       # mdevctl list
       85006552-1b4b-45ef-ad62-de05be9171df 0000:00:02.0 i915-GVTg_V4_4
       6eba5b41-176e-40db-b93e-7f18e04e0b93 0000:00:02.0 i915-GVTg_V4_1

       Promote the new created mdev to a defined device:

       # mdevctl define --uuid 6eba5b41-176e-40db-b93e-7f18e04e0b93
       # mdevctl list -d
       83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 manual
       6eba5b41-176e-40db-b93e-7f18e04e0b93 0000:00:02.0 i915-GVTg_V4_1 manual
       b0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto
       5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual

   ADVANCED EXAMPLES (ATTRIBUTES AND JSON)
       # mdevctl list -d
       783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual

       Add some attributes:

       # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_adapter --value=5
       # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_adapter --value=6
       # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_domain --value=0xab
       # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_control_domain --value=0xab
       # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_domain --value=4
       # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_control_domain --value=4
       # mdevctl list -dv
       783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
         Attrs:
           @{0}: {"assign_adapter":"5"}
           @{1}: {"assign_adapter":"6"}
           @{2}: {"assign_domain":"0xab"}
           @{3}: {"assign_control_domain":"0xab"}
           @{4}: {"assign_domain":"4"}
           @{5}: {"assign_control_domain":"4"}

       Dump the JSON configuration:

       # mdevctl list -d -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --dumpjson
       {
         "mdev_type": "vfio_ap-passthrough",
         "start": "manual",
         "attrs": [
           {
             "assign_adapter": "5"
           },
           {
             "assign_adapter": "6"
           },
           {
             "assign_domain": "0xab"
           },
           {
             "assign_control_domain": "0xab"
           },
           {
             "assign_domain": "4"
           },
           {
             "assign_control_domain": "4"
           }
         ]
       }

       Remove some attributes:

       # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --delattr --index=5
       # mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --delattr --index=4
       # mdevctl list -dv
       783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
         Attrs:
           @{0}: {"assign_adapter":"5"}
           @{1}: {"assign_adapter":"6"}
           @{2}: {"assign_domain":"0xab"}
           @{3}: {"assign_control_domain":"0xab"}

       Define an mdev device from a file:

       # cat vfio_ap_device.json
       {
         "mdev_type": "vfio_ap-passthrough",
         "start": "manual",
         "attrs": [
           {
             "assign_adapter": "5"
           },
           {
             "assign_domain": "0x47"
           },
           {
             "assign_domain": "0xff"
           }
         ]
       }
       # mdevctl define -p matrix --jsonfile vfio_ap_device.json
       e2e73122-cc39-40ee-89eb-b0a47d334cae
       # mdevctl list -dv
       783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual
         Attrs:
           @{0}: {"assign_adapter":"5"}
           @{1}: {"assign_adapter":"6"}
           @{2}: {"assign_domain":"0xab"}
           @{3}: {"assign_control_domain":"0xab"}
       e2e73122-cc39-40ee-89eb-b0a47d334cae matrix vfio_ap-passthrough manual
         Attrs:
           @{0}: {"assign_adapter":"5"}
           @{1}: {"assign_domain":"0x47"}
           @{2}: {"assign_domain":"0xff"}

FILES

       /etc/mdevctl.d/*

       Configuration files are in one subdirectory per parent device and named by UUID.

CONFIGURATION FILE FORMAT

       Configuration files are in JSON. Attributes in "attrs" are optional.

       {
         "mdev_type": "TYPE",
         "start": "auto|manual",
         "attrs": [
           {
             "attribute0": "VALUE"
           },
           {
             "attribute1": "VALUE"
           }
         ]
       }

SEE ALSO

       udev(7) udevadm(8) driverctl(8)

                                                                                       mdevctl(8)