Re: [Qemu-devel] [PATCH v6 4/4] docs: Add Documentation for Mediated devices

[Tian, Kevin]

> From: Kirti Wankhede [mailto:address@hidden
> Sent: Thursday, August 04, 2016 3:04 AM
> 
> +
> +* mdev_supported_types: (read only)
> +    List the current supported mediated device types and its details.
> +
> +* mdev_create: (write only)
> +     Create a mediated device on target physical device.
> +     Input syntax: <UUID:idx:params>
> +     where,
> +             UUID: mediated device's UUID
> +             idx: mediated device index inside a VM

Is above description too specific to VM usage? mediated device can
be used by other user components too, e.g. an user space driver.
Better to make the description general (you can list above as one
example).

Also I think calling it idx a bit limited, which means only numbers
possible. Is it more flexible to call it 'handle' and then any string
can be used here?

> +             params: extra parameters required by driver
> +     Example:
> +     # echo "12345678-1234-1234-1234-123456789abc:0:0" >
> +                              /sys/bus/pci/devices/0000\:05\:00.0/mdev_create
> +
> +* mdev_destroy: (write only)
> +     Destroy a mediated device on a target physical device.
> +     Input syntax: <UUID:idx>
> +     where,
> +             UUID: mediated device's UUID
> +             idx: mediated device index inside a VM
> +     Example:
> +     # echo "12345678-1234-1234-1234-123456789abc:0" >
> +                            /sys/bus/pci/devices/0000\:05\:00.0/mdev_destroy
> +
> +Under mdev class sysfs /sys/class/mdev/:
> +----------------------------------------
> +
> +* mdev_start: (write only)
> +     This trigger the registration interface to notify the driver to
> +     commit mediated device resource for target VM.
> +     The mdev_start function is a synchronized call, successful return of
> +     this call will indicate all the requested mdev resource has been fully
> +     committed, the VMM should continue.
> +     Input syntax: <UUID>
> +     Example:
> +     # echo "12345678-1234-1234-1234-123456789abc" >
> +                                             /sys/class/mdev/mdev_start
> +
> +* mdev_stop: (write only)
> +     This trigger the registration interface to notify the driver to
> +     release resources of mediated device of target VM.
> +     Input syntax: <UUID>
> +     Example:
> +     # echo "12345678-1234-1234-1234-123456789abc" >
> +                                              /sys/class/mdev/mdev_stop

I think it's clearer to create a node per mdev under /sys/class/mdev,
and then move start/stop as attributes under each mdev node, e.g:

echo "0/1" > /sys/class/mdev/12345678-1234-1234-1234-123456789abc/start

Doing this way is more extensible to add more capabilities under
each mdev node, and different capability set may be implemented
for them.

> +
> +Mediated device Hotplug:
> +-----------------------
> +
> +To support mediated device hotplug, <mdev_create> and <mdev_destroy> can be
> +accessed during VM runtime, and the corresponding registration callback is
> +invoked to allow driver to support hotplug.

'hotplug' is an action on the mdev user (e.g. the VM), not on mdev itself.
You can always create a mdev as long as physical device has enough
available resource to support requested config. Destroying a mdev 
may fail if there is still user on target mdev.

Thanks
Kevin