Update mdev doc on new aggregration attribute and instances attribute
for mdev.

Cc: Kirti Wankhede <kwankhede@nvidia.com>
Cc: Alex Williamson <alex.williamson@redhat.com>
Cc: Kevin Tian <kevin.tian@intel.com>
Signed-off-by: Zhenyu Wang <zhenyuw@linux.intel.com>
---
 Documentation/vfio-mediated-device.txt | 39 ++++++++++++++++++++++----
 1 file changed, 33 insertions(+), 6 deletions(-)

diff --git a/Documentation/vfio-mediated-device.txt b/Documentation/vfio-mediated-device.txt
index c3f69bcaf96e..9ec9495dcbe7 100644
--- a/Documentation/vfio-mediated-device.txt
+++ b/Documentation/vfio-mediated-device.txt
@@ -211,12 +211,20 @@ Directories and files under the sysfs for Each Physical Device
   |     |   |--- description
   |     |   |--- [devices]
   |     |--- [<type-id>]
-  |          |--- create
-  |          |--- name
-  |          |--- available_instances
-  |          |--- device_api
-  |          |--- description
-  |          |--- [devices]
+  |     |    |--- create
+  |     |    |--- name
+  |     |    |--- available_instances
+  |     |    |--- device_api
+  |     |    |--- description
+  |     |    |--- [devices]
+  |     |--- [<type-id>]
+  |     |    |--- create
+  |     |    |--- name
+  |     |    |--- available_instances
+  |     |    |--- device_api
+  |     |    |--- description
+  |     |    |--- <aggregation>
+  |     |    |--- [devices]
 
 * [mdev_supported_types]
 
@@ -260,6 +268,19 @@ Directories and files under the sysfs for Each Physical Device
   This attribute should show brief features/description of the type. This is
   optional attribute.
 
+* <aggregation>
+
+  The description is to show feature for one instance of the type. <aggregation>
+  is an optional attributes to show that [<type-id>]'s instances can be
+  aggregated to be assigned for one mdev device. Set number of instances by
+  appending "instances=N" parameter for create. Instances number can't exceed
+  available_instances number. Without "instances=N" parameter will be default
+  one instance to create.
+
+Example::
+
+	# echo "<uuid>,instances=N" > create
+
 Directories and Files Under the sysfs for Each mdev Device
 ----------------------------------------------------------
 
@@ -268,6 +289,7 @@ Directories and Files Under the sysfs for Each mdev Device
   |- [parent phy device]
   |--- [$MDEV_UUID]
          |--- remove
+	 |--- instances
          |--- mdev_type {link to its type}
          |--- vendor-specific-attributes [optional]
 
@@ -281,6 +303,11 @@ Example::
 
 	# echo 1 > /sys/bus/mdev/devices/$mdev_UUID/remove
 
+* instances
+
+For aggregation type show number of instances assigned for this mdev. For normal
+type or default will just show one instance.
+
 Mediated device Hot plug
 ------------------------
 
-- 
2.18.0

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list

On Fri, 20 Jul 2018 10:19:28 +0800
Zhenyu Wang <zhenyuw@linux.intel.com> wrote:

> Update mdev doc on new aggregration attribute and instances attribute
> for mdev.
> 
> Cc: Kirti Wankhede <kwankhede@nvidia.com>
> Cc: Alex Williamson <alex.williamson@redhat.com>
> Cc: Kevin Tian <kevin.tian@intel.com>
> Signed-off-by: Zhenyu Wang <zhenyuw@linux.intel.com>
> ---
>  Documentation/vfio-mediated-device.txt | 39 ++++++++++++++++++++++----
>  1 file changed, 33 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/vfio-mediated-device.txt b/Documentation/vfio-mediated-device.txt
> index c3f69bcaf96e..9ec9495dcbe7 100644
> --- a/Documentation/vfio-mediated-device.txt
> +++ b/Documentation/vfio-mediated-device.txt
> @@ -211,12 +211,20 @@ Directories and files under the sysfs for Each Physical Device
>    |     |   |--- description
>    |     |   |--- [devices]
>    |     |--- [<type-id>]
> -  |          |--- create
> -  |          |--- name
> -  |          |--- available_instances
> -  |          |--- device_api
> -  |          |--- description
> -  |          |--- [devices]
> +  |     |    |--- create
> +  |     |    |--- name
> +  |     |    |--- available_instances
> +  |     |    |--- device_api
> +  |     |    |--- description
> +  |     |    |--- [devices]
> +  |     |--- [<type-id>]
> +  |     |    |--- create
> +  |     |    |--- name
> +  |     |    |--- available_instances
> +  |     |    |--- device_api
> +  |     |    |--- description
> +  |     |    |--- <aggregation>
> +  |     |    |--- [devices]
>  
>  * [mdev_supported_types]
>  
> @@ -260,6 +268,19 @@ Directories and files under the sysfs for Each Physical Device
>    This attribute should show brief features/description of the type. This is
>    optional attribute.
>  
> +* <aggregation>
> +
> +  The description is to show feature for one instance of the type. <aggregation>

You are talking about "one instance" here. Can this be different for
the same type with different physical devices?

> +  is an optional attributes to show that [<type-id>]'s instances can be
> +  aggregated to be assigned for one mdev device. Set number of instances by
> +  appending "instances=N" parameter for create. Instances number can't exceed
> +  available_instances number. Without "instances=N" parameter will be default
> +  one instance to create.

Could there be a case where available_instances is n, but aggregation
is only supported for a value m < n? If yes, should m be discoverable
via the "aggregation" attribute?

> +
> +Example::
> +
> +	# echo "<uuid>,instances=N" > create
> +
>  Directories and Files Under the sysfs for Each mdev Device
>  ----------------------------------------------------------
>  
> @@ -268,6 +289,7 @@ Directories and Files Under the sysfs for Each mdev Device
>    |- [parent phy device]
>    |--- [$MDEV_UUID]
>           |--- remove
> +	 |--- instances
>           |--- mdev_type {link to its type}
>           |--- vendor-specific-attributes [optional]
>  
> @@ -281,6 +303,11 @@ Example::
>  
>  	# echo 1 > /sys/bus/mdev/devices/$mdev_UUID/remove
>  
> +* instances
> +
> +For aggregation type show number of instances assigned for this mdev. For normal
> +type or default will just show one instance.
> +
>  Mediated device Hot plug
>  ------------------------
>  

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list

On 2018.07.26 17:46:40 +0200, Cornelia Huck wrote:
> On Fri, 20 Jul 2018 10:19:28 +0800
> Zhenyu Wang <zhenyuw@linux.intel.com> wrote:
> 
> > Update mdev doc on new aggregration attribute and instances attribute
> > for mdev.
> > 
> > Cc: Kirti Wankhede <kwankhede@nvidia.com>
> > Cc: Alex Williamson <alex.williamson@redhat.com>
> > Cc: Kevin Tian <kevin.tian@intel.com>
> > Signed-off-by: Zhenyu Wang <zhenyuw@linux.intel.com>
> > ---
> >  Documentation/vfio-mediated-device.txt | 39 ++++++++++++++++++++++----
> >  1 file changed, 33 insertions(+), 6 deletions(-)
> > 
> > diff --git a/Documentation/vfio-mediated-device.txt b/Documentation/vfio-mediated-device.txt
> > index c3f69bcaf96e..9ec9495dcbe7 100644
> > --- a/Documentation/vfio-mediated-device.txt
> > +++ b/Documentation/vfio-mediated-device.txt
> > @@ -211,12 +211,20 @@ Directories and files under the sysfs for Each Physical Device
> >    |     |   |--- description
> >    |     |   |--- [devices]
> >    |     |--- [<type-id>]
> > -  |          |--- create
> > -  |          |--- name
> > -  |          |--- available_instances
> > -  |          |--- device_api
> > -  |          |--- description
> > -  |          |--- [devices]
> > +  |     |    |--- create
> > +  |     |    |--- name
> > +  |     |    |--- available_instances
> > +  |     |    |--- device_api
> > +  |     |    |--- description
> > +  |     |    |--- [devices]
> > +  |     |--- [<type-id>]
> > +  |     |    |--- create
> > +  |     |    |--- name
> > +  |     |    |--- available_instances
> > +  |     |    |--- device_api
> > +  |     |    |--- description
> > +  |     |    |--- <aggregation>
> > +  |     |    |--- [devices]
> >  
> >  * [mdev_supported_types]
> >  
> > @@ -260,6 +268,19 @@ Directories and files under the sysfs for Each Physical Device
> >    This attribute should show brief features/description of the type. This is
> >    optional attribute.
> >  
> > +* <aggregation>
> > +
> > +  The description is to show feature for one instance of the type. <aggregation>
> 
> You are talking about "one instance" here. Can this be different for
> the same type with different physical devices?
>

I would expect for normal mdev types, driver might expose like x2, x4, x8 types
which split hw resource equally. But for type with aggregation feature, it can
set user wanted number of instances. Sorry maybe my use of word was not clear, how
about "one example of type"?

> > +  is an optional attributes to show that [<type-id>]'s instances can be
> > +  aggregated to be assigned for one mdev device. Set number of instances by
> > +  appending "instances=N" parameter for create. Instances number can't exceed
> > +  available_instances number. Without "instances=N" parameter will be default
> > +  one instance to create.
> 
> Could there be a case where available_instances is n, but aggregation
> is only supported for a value m < n? If yes, should m be discoverable
> via the "aggregation" attribute?
>

I don't think there could be a case for that. As for aggregation type,
it represents minimal resource allocated for a singleton, I can't see
any reason for possible m < n.

Thanks.

> > +
> > +Example::
> > +
> > +	# echo "<uuid>,instances=N" > create
> > +
> >  Directories and Files Under the sysfs for Each mdev Device
> >  ----------------------------------------------------------
> >  
> > @@ -268,6 +289,7 @@ Directories and Files Under the sysfs for Each mdev Device
> >    |- [parent phy device]
> >    |--- [$MDEV_UUID]
> >           |--- remove
> > +	 |--- instances
> >           |--- mdev_type {link to its type}
> >           |--- vendor-specific-attributes [optional]
> >  
> > @@ -281,6 +303,11 @@ Example::
> >  
> >  	# echo 1 > /sys/bus/mdev/devices/$mdev_UUID/remove
> >  
> > +* instances
> > +
> > +For aggregation type show number of instances assigned for this mdev. For normal
> > +type or default will just show one instance.
> > +
> >  Mediated device Hot plug
> >  ------------------------
> >  
> 

-- 
Open Source Technology Center, Intel ltd.

$gpg --keyserver wwwkeys.pgp.net --recv-keys 4D781827
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list

On Fri, 27 Jul 2018 10:16:58 +0800
Zhenyu Wang <zhenyuw@linux.intel.com> wrote:

> On 2018.07.26 17:46:40 +0200, Cornelia Huck wrote:
> > On Fri, 20 Jul 2018 10:19:28 +0800
> > Zhenyu Wang <zhenyuw@linux.intel.com> wrote:
> >   
> > > Update mdev doc on new aggregration attribute and instances attribute
> > > for mdev.
> > > 
> > > Cc: Kirti Wankhede <kwankhede@nvidia.com>
> > > Cc: Alex Williamson <alex.williamson@redhat.com>
> > > Cc: Kevin Tian <kevin.tian@intel.com>
> > > Signed-off-by: Zhenyu Wang <zhenyuw@linux.intel.com>
> > > ---
> > >  Documentation/vfio-mediated-device.txt | 39 ++++++++++++++++++++++----
> > >  1 file changed, 33 insertions(+), 6 deletions(-)
> > > 
> > > diff --git a/Documentation/vfio-mediated-device.txt b/Documentation/vfio-mediated-device.txt
> > > index c3f69bcaf96e..9ec9495dcbe7 100644
> > > --- a/Documentation/vfio-mediated-device.txt
> > > +++ b/Documentation/vfio-mediated-device.txt
> > > @@ -211,12 +211,20 @@ Directories and files under the sysfs for Each Physical Device
> > >    |     |   |--- description
> > >    |     |   |--- [devices]
> > >    |     |--- [<type-id>]
> > > -  |          |--- create
> > > -  |          |--- name
> > > -  |          |--- available_instances
> > > -  |          |--- device_api
> > > -  |          |--- description
> > > -  |          |--- [devices]
> > > +  |     |    |--- create
> > > +  |     |    |--- name
> > > +  |     |    |--- available_instances
> > > +  |     |    |--- device_api
> > > +  |     |    |--- description
> > > +  |     |    |--- [devices]
> > > +  |     |--- [<type-id>]
> > > +  |     |    |--- create
> > > +  |     |    |--- name
> > > +  |     |    |--- available_instances
> > > +  |     |    |--- device_api
> > > +  |     |    |--- description
> > > +  |     |    |--- <aggregation>
> > > +  |     |    |--- [devices]
> > >  
> > >  * [mdev_supported_types]
> > >  
> > > @@ -260,6 +268,19 @@ Directories and files under the sysfs for Each Physical Device
> > >    This attribute should show brief features/description of the type. This is
> > >    optional attribute.
> > >  
> > > +* <aggregation>
> > > +
> > > +  The description is to show feature for one instance of the type. <aggregation>  
> > 
> > You are talking about "one instance" here. Can this be different for
> > the same type with different physical devices?
> >  
> 
> I would expect for normal mdev types, driver might expose like x2, x4, x8 types
> which split hw resource equally. But for type with aggregation feature, it can
> set user wanted number of instances. Sorry maybe my use of word was not clear, how
> about "one example of type"?
> 
> > > +  is an optional attributes to show that [<type-id>]'s instances can be
> > > +  aggregated to be assigned for one mdev device. Set number of instances by
> > > +  appending "instances=N" parameter for create. Instances number can't exceed
> > > +  available_instances number. Without "instances=N" parameter will be default
> > > +  one instance to create.  
> > 
> > Could there be a case where available_instances is n, but aggregation
> > is only supported for a value m < n? If yes, should m be discoverable
> > via the "aggregation" attribute?
> >  
> 
> I don't think there could be a case for that. As for aggregation type,
> it represents minimal resource allocated for a singleton, I can't see
> any reason for possible m < n.

Let's think about the interface beyond the immediate needs.  It seems
perfectly reasonable to me to think that a vendor driver might have a
large number of resources available, the ability to aggregate resources
beyond what's practical to enumerate with discrete types, yet have an
upper bound of how many resources can be aggregated for a single
instance.  Thanks,

Alex

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list

On Fri, 27 Jul 2018 10:16:58 +0800
Zhenyu Wang <zhenyuw@linux.intel.com> wrote:

> On 2018.07.26 17:46:40 +0200, Cornelia Huck wrote:
> > On Fri, 20 Jul 2018 10:19:28 +0800
> > Zhenyu Wang <zhenyuw@linux.intel.com> wrote:
> >   
> > > Update mdev doc on new aggregration attribute and instances attribute
> > > for mdev.
> > > 
> > > Cc: Kirti Wankhede <kwankhede@nvidia.com>
> > > Cc: Alex Williamson <alex.williamson@redhat.com>
> > > Cc: Kevin Tian <kevin.tian@intel.com>
> > > Signed-off-by: Zhenyu Wang <zhenyuw@linux.intel.com>
> > > ---
> > >  Documentation/vfio-mediated-device.txt | 39 ++++++++++++++++++++++----
> > >  1 file changed, 33 insertions(+), 6 deletions(-)
> > > 
> > > diff --git a/Documentation/vfio-mediated-device.txt b/Documentation/vfio-mediated-device.txt
> > > index c3f69bcaf96e..9ec9495dcbe7 100644
> > > --- a/Documentation/vfio-mediated-device.txt
> > > +++ b/Documentation/vfio-mediated-device.txt
> > > @@ -211,12 +211,20 @@ Directories and files under the sysfs for Each Physical Device
> > >    |     |   |--- description
> > >    |     |   |--- [devices]
> > >    |     |--- [<type-id>]
> > > -  |          |--- create
> > > -  |          |--- name
> > > -  |          |--- available_instances
> > > -  |          |--- device_api
> > > -  |          |--- description
> > > -  |          |--- [devices]
> > > +  |     |    |--- create
> > > +  |     |    |--- name
> > > +  |     |    |--- available_instances
> > > +  |     |    |--- device_api
> > > +  |     |    |--- description
> > > +  |     |    |--- [devices]
> > > +  |     |--- [<type-id>]
> > > +  |     |    |--- create
> > > +  |     |    |--- name
> > > +  |     |    |--- available_instances
> > > +  |     |    |--- device_api
> > > +  |     |    |--- description
> > > +  |     |    |--- <aggregation>
> > > +  |     |    |--- [devices]
> > >  
> > >  * [mdev_supported_types]
> > >  
> > > @@ -260,6 +268,19 @@ Directories and files under the sysfs for Each Physical Device
> > >    This attribute should show brief features/description of the type. This is
> > >    optional attribute.
> > >  
> > > +* <aggregation>
> > > +
> > > +  The description is to show feature for one instance of the type. <aggregation>  
> > 
> > You are talking about "one instance" here. Can this be different for
> > the same type with different physical devices?
> >  
> 
> I would expect for normal mdev types, driver might expose like x2, x4, x8 types
> which split hw resource equally. But for type with aggregation feature, it can
> set user wanted number of instances. Sorry maybe my use of word was not clear, how
> about "one example of type"?


Maybe my question was confusing as well...

<aggregation> is an attribute that is exposed for a particular type
under a particular physical device.

- If <aggregation> is always the same for that particular type,
  regardless of which physical device we're dealing with, let's just
  drop the "one instance" sentence.
- If it instead depends on what physical device we're handling, I'd
  write something like "The contents of this attribute depend both on
  the type and on the particular instance."

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list