RE: [PATCH v2 5/6] mdev: Update sysfs documentation

Parav Pandit
2019-08-30T13:11:11Z

> -----Original Message-----
> From: Cornelia Huck <cohuck@redhat.com>
> Sent: Friday, August 30, 2019 6:19 PM
> To: Parav Pandit <parav@mellanox.com>
> Cc: alex.williamson@redhat.com; Jiri Pirko <jiri@mellanox.com>;
> kwankhede@nvidia.com; davem@davemloft.net; kvm@vger.kernel.org; linux-
> kernel@vger.kernel.org; netdev@vger.kernel.org
> Subject: Re: [PATCH v2 5/6] mdev: Update sysfs documentation
>
> On Thu, 29 Aug 2019 06:19:03 -0500
> Parav Pandit <parav@mellanox.com> wrote:
>
> > Updated documentation for optional read only sysfs attribute.
>
> I'd probably merge this into the patch introducing the attribute.
>
Ok. I will spin v3.

> >
> > Signed-off-by: Parav Pandit <parav@mellanox.com>
> > ---
> > Documentation/driver-api/vfio-mediated-device.rst | 5 +++++
> > 1 file changed, 5 insertions(+)
> >
> > diff --git a/Documentation/driver-api/vfio-mediated-device.rst
> > b/Documentation/driver-api/vfio-mediated-device.rst
> > index 25eb7d5b834b..0ab03d3f5629 100644
> > --- a/Documentation/driver-api/vfio-mediated-device.rst
> > +++ b/Documentation/driver-api/vfio-mediated-device.rst
> > @@ -270,6 +270,7 @@ Directories and Files Under the sysfs for Each mdev
> Device
> > |--- remove
> > |--- mdev_type {link to its type}
> > |--- vendor-specific-attributes [optional]
> > + |--- alias [optional]
>
> "optional" implies "not always present" to me, not "might return a read error if
> not available". Don't know if there's a better way to tag this? Or make it really
> optional? :)

May be write it as,

alias [ optional when requested by parent ]

>
> >
> > * remove (write only)
> >
> > @@ -281,6 +282,10 @@ Example::
> >
> > # echo 1 > /sys/bus/mdev/devices/$mdev_UUID/remove
> >
> > +* alias (read only)
> > +Whenever a parent requested to generate an alias, each mdev is
> > +assigned a unique alias by the mdev core. This file shows the alias of the
> mdev device.
>
> It's not really the parent, but the vendor driver requesting this, right? Also,
At mdev level, it only knows parent->ops structure, whether parent is registered by vendor driver or something else.

> "each mdev" is a bit ambiguous,
It is in context of the parent. Sentence is not starting with "each mdev".
But may be more verbosely written as,

Whenever a parent requested to generate an alias, Each mdev device of such parent is assigned
unique alias by the mdev core. This file shows the alias of the mdev device.

> created via that driver. Lastly, if we stick with the "returns an error if not
> implemented" approach, that should also be mentioned here.
Ok. Will spin v3 to describe it.

>
> > +
> > Mediated device Hot plug
> > ------------------------
> >