.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "MDEVCTL" 8 "" ""
.SH NAME
mdevctl \- Mediated device management utility
.SH SYNOPSIS
.sp
\fBmdevctl\fP {COMMAND} [OPTIONS...]
.sp
\fBlsmdev\fP [OPTIONS...]
.SH DESCRIPTION
.sp
\fBmdevctl\fP 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.
.sp
\fBlsmdev\fP is an alias for \fBmdevctl list\fP\&.
.SH OPTIONS
.sp
The following options are understood:
.INDENT 0.0
.TP
.B \fB\-\-addattr=ATTRIBUTE\fP
Add an attribute \fIATTRIBUTE\fP\&. Valid for the \fBmodify\fP
command.
.TP
.B \fB\-a|\-\-auto\fP
Automatically start the device on parent availability. Valid for
\fBdefine\fP and \fBmodify\fP commands.
.TP
.B \fB\-d|\-\-defined\fP
List all defined devices, even if not active. Valid for the \fBlist\fP
command. Modify the defined configuration of a device, even if the
device is active. Valid for the \fBmodify\fP command.
.TP
.B \fB\-\-delattr\fP
Delete an attribute entry. Valid for the \fBmodify\fP command.
.TP
.B \fB\-\-dumpjson\fP
Dump the configuration for a device in JSON format when filtered to
as single device and used with the \fBlist\fP command.  When used
with the \fBtypes\fP command, output machine readable type information.
.TP
.B \fB\-i|\-\-index=INDEX\fP
Act on the attribute \fIINDEX\fP\&. Valid for the \fBmodify\fP command.
.TP
.B \fB\-\-jsonfile=FILE\fP
Read the configuration for a device from a JSON file \fIFILE\fP\&.
Valid for the \fBdefine\fP and \fBstart\fP commands.
.TP
.B \fB\-l|\-\-live\fP
Modify active device without modifying the defined configuration of
the device. Valid for the \fBmodify\fP command.
.TP
.B \fB\-m|\-\-manual\fP
Do not start a device automatically on parent availability. Valid
for the \fBmodify\fP command.
.TP
.B \fB\-p|\-\-parent=PARENT\fP
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.
.TP
.B \fB\-t|\-\-type=TYPE\fP
Specify or identify the device by its type.
.TP
.B \fB\-u|\-\-uuid=UUID\fP
Specify or identify the device by its UUID.
.TP
.B \fB\-\-value=VALUE\fP
Set an attribute to \fIVALUE\fP, in the format accepted by the attribute.
Valid for the \fBmodify\fP command.
.TP
.B \fB\-v|\-\-verbose\fP
Increase output verbosity, currently only adds attribute output to the
\fBlist\fP command.
.TP
.B \fB\-V|\-\-version\fP
Print mdevctl version.
.UNINDENT
.SH COMMANDS
.sp
The following commands are understood:
.INDENT 0.0
.TP
.B \fBdefine\fP \fIDEVICESPEC\fP
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,
\fI\-a|\-\-auto\fP may be used to specify that the device should be started
automatically.
.TP
.B \fBlist\fP
List mdev devices. With no options, currently running devices are listed.
With \fB\-d|\-\-defined\fP, previously defined devices are listed.
Can be restricted to list only devices for a given parent or UUID. With
\fB\-\-dumpjson\fP 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.
.TP
.B \fBmodify\fP \fIDEVICESPEC\fP
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.
Active devices are unaffected by this command; changes in the configuration
are applied the next time the device is started. Depending on installed
callout scripts active devices can be modified. With \fB\-l|\-\-live\fP
modifications can be applied to active devices if a callout scripts supports
the event \fBlive\fP\&. The option \fB\-d|\-\-defined\fP also direct the modification
to the started device configuration.
.TP
.B \fBstart\fP \fIDEVICESPEC\fP
Start a mediated device. This command can be used to start either a
previously\-defined device or a newly\-created transient device.
.sp
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.
.sp
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 \fB\-\-jsonfile\fP may replace the \fB\-\-type\fP specification and also include
additional attributes in JSON format to be applied to the started device.
.TP
.B \fBstop\fP \fIDEVICESPEC\fP
Stop an mdev device, specified via its UUID.
.TP
.B \fBtypes\fP
List the mdev device types known to the system by parent device.  Output
may be limited to a single parent device with the \fB\-p|\-\-parent\fP option.
JSON output format is used with the \fB\-\-dumpjson\fP option.
.TP
.B \fBundefine\fP \fIDEVICESPEC\fP
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.
.UNINDENT
.SH NOTE ON DEVICE SPECIFICATION
.sp
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.
.SH EXIT STATUS
.sp
On success, 0 is returned, a non\-zero failure code otherwise.
.SH EXAMPLES
.sp
List running mdev devices:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# 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)
.EE
.UNINDENT
.UNINDENT
.sp
List defined mdev devices:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# 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
.EE
.UNINDENT
.UNINDENT
.sp
List mdev types supported on the host system:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# 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
.EE
.UNINDENT
.UNINDENT
.sp
Modify a defined device from automatic start to manual:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# 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
.EE
.UNINDENT
.UNINDENT
.sp
Stop a running mdev device:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# mdevctl stop \-u 83c32df7\-d52e\-4ec1\-9668\-1f3c7e4df107
.EE
.UNINDENT
.UNINDENT
.sp
Start an mdev device that is not defined:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# 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
.EE
.UNINDENT
.UNINDENT
.sp
Promote the new created mdev to a defined device:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# 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
.EE
.UNINDENT
.UNINDENT
.SS ADVANCED EXAMPLES (ATTRIBUTES AND JSON)
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# mdevctl list \-d
783e6dbb\-ea0e\-411f\-94e2\-717eaad438bf matrix vfio_ap\-passthrough manual
.EE
.UNINDENT
.UNINDENT
.sp
Add some attributes:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# 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}: {\(dqassign_adapter\(dq:\(dq5\(dq}
    @{1}: {\(dqassign_adapter\(dq:\(dq6\(dq}
    @{2}: {\(dqassign_domain\(dq:\(dq0xab\(dq}
    @{3}: {\(dqassign_control_domain\(dq:\(dq0xab\(dq}
    @{4}: {\(dqassign_domain\(dq:\(dq4\(dq}
    @{5}: {\(dqassign_control_domain\(dq:\(dq4\(dq}
.EE
.UNINDENT
.UNINDENT
.sp
Dump the JSON configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# mdevctl list \-d \-u 783e6dbb\-ea0e\-411f\-94e2\-717eaad438bf \-\-dumpjson
{
  \(dqmdev_type\(dq: \(dqvfio_ap\-passthrough\(dq,
  \(dqstart\(dq: \(dqmanual\(dq,
  \(dqattrs\(dq: [
    {
      \(dqassign_adapter\(dq: \(dq5\(dq
    },
    {
      \(dqassign_adapter\(dq: \(dq6\(dq
    },
    {
      \(dqassign_domain\(dq: \(dq0xab\(dq
    },
    {
      \(dqassign_control_domain\(dq: \(dq0xab\(dq
    },
    {
      \(dqassign_domain\(dq: \(dq4\(dq
    },
    {
      \(dqassign_control_domain\(dq: \(dq4\(dq
    }
  ]
}
.EE
.UNINDENT
.UNINDENT
.sp
Remove some attributes:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# 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}: {\(dqassign_adapter\(dq:\(dq5\(dq}
    @{1}: {\(dqassign_adapter\(dq:\(dq6\(dq}
    @{2}: {\(dqassign_domain\(dq:\(dq0xab\(dq}
    @{3}: {\(dqassign_control_domain\(dq:\(dq0xab\(dq}
.EE
.UNINDENT
.UNINDENT
.sp
Define an mdev device from a file:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# cat vfio_ap_device.json
{
  \(dqmdev_type\(dq: \(dqvfio_ap\-passthrough\(dq,
  \(dqstart\(dq: \(dqmanual\(dq,
  \(dqattrs\(dq: [
    {
      \(dqassign_adapter\(dq: \(dq5\(dq
    },
    {
      \(dqassign_domain\(dq: \(dq0x47\(dq
    },
    {
      \(dqassign_domain\(dq: \(dq0xff\(dq
    }
  ]
}
# 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}: {\(dqassign_adapter\(dq:\(dq5\(dq}
    @{1}: {\(dqassign_adapter\(dq:\(dq6\(dq}
    @{2}: {\(dqassign_domain\(dq:\(dq0xab\(dq}
    @{3}: {\(dqassign_control_domain\(dq:\(dq0xab\(dq}
e2e73122\-cc39\-40ee\-89eb\-b0a47d334cae matrix vfio_ap\-passthrough manual
  Attrs:
    @{0}: {\(dqassign_adapter\(dq:\(dq5\(dq}
    @{1}: {\(dqassign_domain\(dq:\(dq0x47\(dq}
    @{2}: {\(dqassign_domain\(dq:\(dq0xff\(dq}
.EE
.UNINDENT
.UNINDENT
.SH CONFIGURATION FILE FORMAT
.sp
Configuration files are in JSON. Attributes in \(dq\fBattrs\fP\(dq are optional.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{
  \(dqmdev_type\(dq: \(dqTYPE\(dq,
  \(dqstart\(dq: \(dqauto|manual\(dq,
  \(dqattrs\(dq: [
    {
      \(dqattribute0\(dq: \(dqVALUE\(dq
    },
    {
      \(dqattribute1\(dq: \(dqVALUE\(dq
    }
  ]
}
.EE
.UNINDENT
.UNINDENT
.SH INVOKING EXTERNAL SCRIPTS FOR DEVICE EVENTS
.sp
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\(aqs \(dqprimary command execution\(dq (e.g. writing the device configuration
file for define, or activating a device for start).
.sp
Essentially, the procedure in mdevctl looks like this:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
command\-line parsing & setup
.IP \(bu 2
invoke live\-command call\-out [1]
.IP \(bu 2
invoke pre\-command call\-out
.IP \(bu 2
primary command execution [2]
.IP \(bu 2
invoke post\-command call\-out [2]
.IP \(bu 2
invoke notifier
.UNINDENT
.IP [1] 5
executed only if live update is requested.
.IP [2] 5
skipped if step \fBinvoke pre\-command call\-out\fP fails.
.UNINDENT
.UNINDENT
.SS EVENT SCRIPTS
.sp
A call\-out or notification event invokes a script along with a set of
parameters detailing the type of call\-out, mdevctl\(aqs command execution
progress, and the mediated device. The parameters are as follows:
.sp
<CONFIG> | SCRIPT <\fB\-t=\fP\fItype\fP \fB\-e=\fP\fIevent\fP
\fB\-a=\fP\fIaction\fP \fB\-s=\fP\fIstate\fP \fB\-u=\fP\fIUUID\fP
\fB\-p=\fP\fIparent\fP>
.INDENT 0.0
.TP
.B \fBCONFIG\fP
The device\(aqs JSON configuration, provided via standard input.
.TP
.B \fB\-t=\fP\fItype\fP
The device type.
.TP
.B \fB\-e=\fP\fIevent\fP
Event type of call\-out that is invoked. For call\-out scripts, this may be
\fBpre\fP, \fBlive\fP, \fBpost\fP, or \fBget\fP\&. For notification scripts, this will
always be \fBnotify\fP\&.
.TP
.B \fB\-a=\fP\fIaction\fP
An action synonymous with an mdevctl command (e.g. define, start).
.TP
.B \fB\-s=\fP\fIstate\fP
A trinary state of the mdevctl command execution. The possibilities are
\fBnone\fP if the mdevctl command has yet to execute, \fBsuccess\fP
if the mdevctl command completed successfully, or \fBfailure\fP if there
was a problem executing the mdevctl command.
.TP
.B \fB\-u=\fP\fIUUID\fP
UUID of the mediated device.
.TP
.B \fB\-p=\fP\fIparent\fP
Parent of the mediated the device.
.UNINDENT
.SS CALL\-OUT EVENT SCRIPTS
.sp
A call\-out event script is invoked during a \fBlive\fP, \fBpre\fP, \fBpost\fP or
\fBget\fP 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 \(dqTYPE\(dq 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.
.sp
These scripts are stored in \fI/usr/lib/mdevctl/scripts.d/callouts\fP\&. The same
script is invoked for \fBlive\fP, \fBpre\fP, \fBpost\fP, and \fBget\fP call\-out events
for the device type.
.sp
\fBLive\-Command\fP
.INDENT 0.0
.INDENT 3.5
A live\-command call\-out event is invoked once before the pre\-command call\-out
event execution. This only occurs if the \fBlive\fP option is specified on the
\fBmodify\fP command and the device modified is active.
Event type is \fBlive\fP\&. State will always be \fBnone\fP\&.
.sp
If the \fBlive\fP command line option is specified any non\-zero return code results in
a live modification failure except for all call\-outs return with return code 2
resulting in a \fBlive update not supported\fP information.
The return code is disruptive if also the option \fBdefined\fP is provided and will
prevent the update of the defined device configuration.
.sp
A notification event will follow if the \fBlive\fP command line option is specified.
.sp
This event is only supported for the \fBmodify\fP command.
.UNINDENT
.UNINDENT
.sp
\fBPre\-Command\fP
.INDENT 0.0
.INDENT 3.5
A pre\-command call\-out event is invoked once prior to primary command execution.
Event type is \fBpre\fP\&. State will always be \fBnone\fP\&.
.sp
Any non\-zero return code (exempting 2) will prevent mdevctl from performing
the primary command execution and mdevctl will abort early.
.sp
A notification event will follow only if an error code (exempting 2) is
observed.
.sp
This event is not supported for the \fBlist\fP, \fBtypes\fP, or \fBversion\fP
commands.
.UNINDENT
.UNINDENT
.sp
\fBPost\-Command\fP
.INDENT 0.0
.INDENT 3.5
A post\-command call\-out event is invoked once after primary command execution.
Event type is \fBpost\fP\&. State will be \fBsuccess\fP if mdevctl was able to
finish primary command execution successfully, or \fBfailure\fP otherwise.
.sp
The same script used for the pre event is used for the post event.
.sp
Any return code is non\-disruptive.
.sp
A notification event will always follow a post\-command call\-out.
.sp
This event is not supported for the \fBlist\fP, \fBtypes\fP, or \fBversion\fP
commands.
.UNINDENT
.UNINDENT
.sp
\fBGet\-attributes\fP
.INDENT 0.0
.INDENT 3.5
A get event is invoked during a \fBdefine\fP and \fBlist\fP command to
acquire device attributes from an active device. Event type is \fBget\fP\&. Action
is \fBattributes\fP\&. State is \fBnone\fP\&. Note that, unlike other call\-outs
events, \fBget\-attributes does not expect a device config on stdin, and an
array of JSON formatted device attributes is returned via stdout\fP\&.
.sp
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.
.sp
For \fBdefine\fP, a non\-zero return code (exempting 2) will disrupt the define
command entirely.
.sp
For \fBlist\fP, any return code is non\-disruptive.
.sp
A script must return a JSON formatted array of device attributes on standard
output. Example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
[
    {
        \(dqattribute0\(dq: \(dqVALUE\(dq
    },
    {
        \(dqattribute1\(dq: \(dqVALUE\(dq
    }
]
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBGet\-capabilities\fP
.INDENT 0.0
.INDENT 3.5
A get event is invoked on every new mdevctl execution to find a matching script
supporting versioning for the device type.
Event type is \fBget\fP\&. Action is \fBcapabilities\fP\&. State is \fBnone\fP\&.
Note that, unlike other call\-outs events, \fBget\-capabilities provides a
versioning JSON on stdin, and expects a versioning JSON is returned via
stdout\fP\&.
The provided JSON on stdin explains in \fBprovides\fP which \fBactions\fP and
\fBevents\fP mdevctl supports. The information is offered to the script to
derive its supported \fBactions\fP and \fBevents\fP from but it there is no
obligation for scripts to follow this pattern.
A valid versioning JSON response provides in \fBsupports\fP the supported
actions in \fBactions\fP and the supported events in \fBevents\fP\&.
.sp
If a valid versioning JSON is returned on stdout by the script and the
return code is NOT 2 the script is considered a positive match for the
provided device type. A script providing versioning is the primary choice
for a device type when mdevctl is executing callouts or in other words if
a script which supports versioning is found the script is used for every
event and action for the device type. Should no versioning supporting
script be found the none versioning search pattern is used.
.sp
A script is provided on standard in with a versioning JSON describing the mdevctl
supported version, actions and events. Example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{
  \(dqprovides\(dq: {
    \(dqversion\(dq: 1,
    \(dqactions\(dq: [
      \(dqstart\(dq,
      \(dqstop\(dq,
      \(dqdefine\(dq,
      \(dqundefine\(dq,
      \(dqmodify\(dq,
      \(dqattributes\(dq,
      \(dqcapabilities\(dq
    ],
    \(dqevents\(dq: [
      \(dqpre\(dq,
      \(dqpost\(dq,
      \(dqnotify\(dq,
      \(dqget\(dq
    ]
  }
}
.EE
.UNINDENT
.UNINDENT
.sp
A script that wants to support versioning must return a versioning JSON on standard
output. The script should list all supported actions in the actions array and all
supported events in the events array. It is possible to add additional actions or
events in the array but if mdevctl did not have these in the arrays in provides
they are ignored. Example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{
  \(dqsupports\(dq: {
    \(dqversion\(dq: 1,
    \(dqactions\(dq: [
      \(dqstart\(dq,
      \(dqstop\(dq,
      \(dqdefine\(dq,
      \(dqundefine\(dq,
      \(dqmodify\(dq,
      \(dqattributes\(dq,
      \(dqcapabilities\(dq
    ],
    \(dqevents\(dq: [
      \(dqpre\(dq,
      \(dqpost\(dq,
      \(dqnotify\(dq,
      \(dqget\(dq
    ]
  }
}
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS AUTO\-START CALL\-OUTS
.sp
For each device set to start automatically during system boot, mdevctl will
invoke the pre and post events. Action is the string \fBstart\fP\&.
.sp
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.
.sp
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\(aqs invocation (e.g. the
auto\-start event may occur before the libvirt daemon is activated).
.SS NOTIFICATION EVENT SCRIPTS
.sp
Notification event scripts may be used to signal the state of the mediated
device or the state of an mdevctl command to other programs or loggers. Unlike
call\-out scripts, notifier scripts are device\-type agnostic.
.sp
\fBNotify\fP
.INDENT 0.0
.INDENT 3.5
A notification event is invoked once either following a pre\-command call\-out
failure or after a post\-command call\-out. Event is \fBnotify\fP\&. If following a
pre event, then state will be \fBnone\fP\&. If following a post event, then
state will mirror the value passed to the post\-command call\-out.
.sp
These scripts are stored in \fI/usr/lib/mdevctl/scripts.d/notifiers\fP\&. \fBAll
notification scripts will be invoked during a notification event\fP\&.
.sp
A non\-zero return code is ignored.
.sp
This event is not supported for the \fBlist\fP, \fBtypes\fP, or \fBversion\fP
commands.
.UNINDENT
.UNINDENT
.SS SCRIPT RETURN VALUES
.sp
A call\-out script should return one of the following values:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
0  if OK,
.IP \(bu 2
1  if an error occurred,
.IP \(bu 2
2  if the script does not support the device type
.UNINDENT
.UNINDENT
.UNINDENT
.SH FILES
.sp
\fI/etc/mdevctl.d/*\fP
.sp
Configuration files are in one subdirectory per parent device and named
by UUID.
.sp
\fI/usr/lib/mdevctl/scripts.d/callouts/*\fP
.sp
Scripts for pre/post/get call\-out events. \fBNOTE\fP: these scripts were
previously located at \fI/etc/mdevctl.d/scripts.d/callouts/*\fP, but that location
is now deprecated.
.sp
\fI/usr/lib/mdevctl/scripts.d/notifiers/*\fP
.sp
Scripts for notification call\-out events. \fBNOTE\fP: these scripts were
previously located at \fI/etc/mdevctl.d/scripts.d/notifiers/*\fP, but that location
is now deprecated.
.SH SEE ALSO
.sp
udev(7), udevadm(8), driverctl(8)
.\" Generated by docutils manpage writer.
.