[PATCH v2 1/2] Documentation/driver-api/vfio-mediated-device.rst: update for aggregation support

[Tian, Kevin]

> From: Zhenyu Wang <zhenyuw at linux.intel.com>
> Sent: Thursday, March 26, 2020 1:42 PM
> 
> Update doc for mdev aggregation support. Describe mdev generic
> parameter directory under mdev device directory.
> 
> Cc: Kevin Tian <kevin.tian at intel.com>
> Cc: "Jiang, Dave" <dave.jiang at intel.com>
> Signed-off-by: Zhenyu Wang <zhenyuw at linux.intel.com>
> ---
>  .../driver-api/vfio-mediated-device.rst       | 19 +++++++++++++++++++
>  1 file changed, 19 insertions(+)
> 
> diff --git a/Documentation/driver-api/vfio-mediated-device.rst
> b/Documentation/driver-api/vfio-mediated-device.rst
> index 25eb7d5b834b..29c29432a847 100644
> --- a/Documentation/driver-api/vfio-mediated-device.rst
> +++ b/Documentation/driver-api/vfio-mediated-device.rst
> @@ -269,6 +269,9 @@ Directories and Files Under the sysfs for Each mdev
> Device
>    |--- [$MDEV_UUID]
>           |--- remove
>           |--- mdev_type {link to its type}
> +         |--- mdev [optional]
> +	     |--- aggregated_instances [optional]
> +	     |--- max_aggregation [optional]
>           |--- vendor-specific-attributes [optional]
> 
>  * remove (write only)
> @@ -281,6 +284,22 @@ Example::
> 
>  	# echo 1 > /sys/bus/mdev/devices/$mdev_UUID/remove
> 
> +* mdev directory (optional)

It sounds confusing to me when seeing a 'mdev' directory under a
mdev instance. How could one tell which attribute should put inside
or outside of 'mdev'?

> +
> +Vendor driver could create mdev directory to specify extra generic
> parameters
> +on mdev device by its type. Currently aggregation parameters are defined.
> +Vendor driver should provide both items to support.
> +
> +1) aggregated_instances (read/write)
> +
> +Set target aggregated instances for device. Reading will show current
> +count of aggregated instances. Writing value larger than max_aggregation
> +would fail and return error.

Can one write a value multiple-times and at any time? 

> +
> +2) max_aggregation (read only)
> +
> +Show maxium instances for aggregation.
> +

"show maximum-allowed instances which can be aggregated for this device". is
this value static or dynamic? if dynamic then the user is expected to read this
field before every write. worthy of some clarification here.

>  Mediated device Hot plug
>  ------------------------
> 
> --
> 2.25.1