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

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

-t=type

-e=event

-a=action

-s=state

-u=UUID

-p=parent>

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

Post-Command

Get-attributes

[


    {


        "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

SCRIPT RETURN VALUES¶