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

[Kirti Wankhede]

On 8/4/2016 1:01 PM, Tian, Kevin wrote:
>> 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).
>
Ok. I'll change it to VM or user space component.

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

Index is integer, it is to keep track of mediated device instance number
created for a user space component or VM.

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

To support multiple mdev devices in one VM or user space driver, process
is to create or configure all mdev devices for that VM or user space
driver and then have a single 'start' which means all requested mdev
resources are committed.

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

You can add extra capabilities for each mdev device node using
'mdev_attr_groups' of 'struct parent_ops' from vendor driver.


>> +
>> +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.
>

Here point is: user need to pass UUID to mdev_create and device will be
created even if VM or user space driver is running.

Thanks,
Kirti

> Thanks
> Kevin
>