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

[Cornelia Huck]

On Thu, 29 Aug 2019 06:19:03 -0500
Parav Pandit <parav@xxxxxxxxxxxx> wrote:

> Updated documentation for optional read only sysfs attribute.

I'd probably merge this into the patch introducing the attribute.

> 
> Signed-off-by: Parav Pandit <parav@xxxxxxxxxxxx>
> ---
>  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? :)

>  
>  * 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, "each mdev" is a bit ambiguous, as this is only true for
the subset of mdevs created via that driver. Lastly, if we stick with
the "returns an error if not implemented" approach, that should also be
mentioned here.

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