mdevctl(8)

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.

-V|--version
    Print mdevctl version.

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 a mediated device. This command can be used to start either a previously-defined device or a newly-created transient device. If the UUID and optional parent argument matches an existing device definition, then the existing device will be started. It is an error to specify a device type that conflicts with the existing device definition. If the UUID argument is omitted or if the specified UUID and parent does not match an existing device definition, a new transient device will be started. If the UUID is omitted, a new UUID will be automatically generated. When starting a new transient device, the parent and device type must be specified. A --jsonfile may replace the --type specification and also include additional attributes in JSON format to be applied to the started device.

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.

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"}

CONFIGURATION FILE FORMAT
Configuration files are in JSON. Attributes in "attrs" are optional.
    {
      "mdev_type": "TYPE",
      "start": "auto|manual",
      "attrs": [
        {
          "attribute0": "VALUE"
        },
        {
          "attribute1": "VALUE"
        }
      ]
    }

INVOKING EXTERNAL SCRIPTS FOR DEVICE EVENTS
mdevctl supports invoking external scripts to handle additional device type-specific configurations and to broadcast notifications regarding changes or updates to a device. These scripts are invoked before, after, and/or during mdevctl's "primary command execution" (e.g. writing the device configuration file for define, or activating a device for start). Essentially, the procedure in mdevctl looks like this:

    1. command-line parsing & setup

    2. invoke pre-command call-out

    3. primary command execution*

    4. invoke post-command call-out*

    5. invoke notifier

    * skipped if step 2 fails.

  EVENT SCRIPTS
A call-out or notification event invokes a script along with a set of parameters detailing the type of call-out, mdevctl's command execution progress, and the mediated device. The parameters are as follows: <CONFIG> | SCRIPT <-t=type -e=event -a=action -s=state -u=UUID -p=parent>

CONFIG
    The device's JSON configuration, provided via standard input.

-t=type
    The device type.

-e=event
    Event type of call-out that is invoked. For call-out scripts, this may be pre, post, or get. For notification scripts, this will always be notify.

-a=action
    An action synonymous with an mdevctl command (e.g. define, start).

-s=state
    A trinary state of the mdevctl command execution. The possibilities are none if the mdevctl command has yet to execute, success if the mdevctl command completed successfully, or failure if there was a problem executing the mdevctl command.

-u=UUID
    UUID of the mediated device.

-p=parent>
    Parent of the mediated the device.

  CALL-OUT EVENT SCRIPTS
A call-out event script is invoked during a pre, post, or get event. mdevctl will attempt each script stored in the mdevctl callouts directory until either a script that satisfies the device type is found or all scripts have been attempted. A device script must check the "TYPE" parameter to ensure the specified device type is supported, otherwise error code 2 should be returned. If no script is found for the specified device type, then mdevctl will carry on as normal. These scripts are stored in /etc/mdevctl.d/scripts.d/callouts. The same script is invoked for pre, post, and get call-out events for the device type.

Pre-Command
    A pre-command call-out event is invoked once prior to primary command execution. Event type is pre. Status will always be none. Any non-zero return code (exempting 2) will prevent mdevctl from performing the primary command execution and mdevctl will abort early. A notification event will follow only if an error code (exempting 2) is observed. This event is not supported for the list, types, or version commands.

Post-Command
    A post-command call-out event is invoked once after primary command execution. Event type is post. Status will be success if mdevctl was able to finish primary command execution successfully, or failure otherwise. The same script used for the pre event is used for the post event. Any return code is non-disruptive. A notification event will always follow a post-command call-out. This event is not supported for the list, types, or version commands.

Get-attributes
    A get event is invoked during a define and list command to acquire device attributes from an active device. Event type is get. Action is attributes. Status is none. Note that, unlike other call-outs events, get-attributes does not expect a device config on stdin, and an array of JSON formatted device attributes is returned via stdout. The same script used for the pre event is used for the get event. If the script is not designed to support a get event, then the return code is 0. For define, a non-zero return code (exempting 2) will disrupt the define command entirely. For list, any return code is non-disruptive. A script must return a JSON formatted array of device attributes on standard output. Example:
        [
            {
                "attribute0": "VALUE"
            },
            {
                "attribute1": "VALUE"
            }
        ]

  AUTO-START CALL-OUTS
For each device set to start automatically during system boot, mdevctl will invoke the pre and post events. Action is the string start. Return code and notification event behavior is the same as documented for the pre and post events. Errors reported by a script will disrupt the auto-start for that particular device and the message will be reported to the system log before attempting to the next auto-start device. Note that if a notification script is used to convey information to another program or daemon during the auto-start procedure, it is not guaranteed that the program will already be active prior to mdevctl's invocation (e.g. the auto-start event may occur before the libvirt daemon is activated).

  NOTIFICATION EVENT SCRIPTS
Notification event scripts may be used to signal the state of the mediated device or the status of an mdevctl command to other programs or loggers. Unlike call-out scripts, notifier scripts are device-type agnostic.

Notify
    A notification event is invoked once either following a pre-command call-out failure or after a post-command call-out. Event is notify. If following a pre event, then status will be none. If following a post event, then status will mirror the value passed to the post-command call-out. These scripts are stored in /etc/mdevctl.d/scripts.d/notifiers. All notification scripts will be invoked during a notification event. A non-zero return code is ignored. This event is not supported for the list, types, or version commands.

  SCRIPT RETURN VALUES

    0  if OK,

    1  if an error occurred,

    2  if the script does not support the device type

FILES
/etc/mdevctl.d/* Configuration files are in one subdirectory per parent device and named by UUID. /etc/mdevctl.d/scripts.d/callouts/* Scripts for pre/post/get call-out events. /etc/mdevctl.d/scripts.d/notifiers/* Scripts for notification call-out events.

SEE ALSO
udev(7) udevadm(8) driverctl(8)