Provided by: mdevctl_1.2.0-3ubuntu1_amd64 bug

NAME

       mdevctl - Mediated device management utility

SYNOPSIS

       mdevctl {COMMAND} [OPTIONS...]

       lsmdev [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.

       lsmdev is an alias for mdevctl list.

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. Note that the parent device is
              specified by its kernel sysfs name and is case-sensitive.

       -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:

          • command-line parsing & setup

          • invoke pre-command call-out

          • primary command execution [1]

          • invoke post-command call-out [1]

          • invoke notifier

          [1]  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
       A call-out script should return one of the following 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)

                                                                                       MDEVCTL(8)