Re: [PATCH v9 13/13] newdevice: Extend informative guidance on capabilities, resources

[Peter Hilber <peter.hilber@opensynergy.com>]

On 07.02.24 08:23, Parav Pandit wrote:
> Add few informative guidance/notes about which use cases to use
> device capabilities, and device resources.
> 
> Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179
> Signed-off-by: Parav Pandit <parav@nvidia.com>
> ---
> changelog:
> v7->v8:
> - improved the examples and text for usage of device capabilities
>   and device resources
> - added more Q&A to clarify the resources and capabilities
> ---
>  newdevice.tex | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 52 insertions(+)
> 
> diff --git a/newdevice.tex b/newdevice.tex
> index 93feb71..02e79b5 100644
> --- a/newdevice.tex
> +++ b/newdevice.tex
> @@ -13,6 +13,46 @@ \section{How Many Virtqueues?}\label{sec:Creating New Device Types or Extending
>  receive input, and one which the driver places buffers to
>  transmit output.
>  
> +\section{When to use Device Resource?}\label{sec:Creating New Device Types or Extending the Device / When to use Device Resource?}
> +For a desired device functionality,
> +(a) if majority of fields are configured by the
> +driver, or
> +(b) if device sets majority of fields which are changing often and
> +driver wants to query them, in both of those cases, using a device
> +resource is preferred.
> +
> +Even if such functionality is limited to small count as small as one,
> +using a device resource can be helpful with large number of devices.
> +
> +Some examples of implicit device resources for network device are mac
> +and vlan table, rtc or PTP clock; examples of explicit resource is virtqueues or
> +crypto sessions for crypto device, flow filter counters for network device etc.
> +

As the author of the virtio-rtc device draft and PoC implementation, I
disagree with this advice. Please refer to the discussion about virtio-rtc
and resources [1] for more information.

> +\section{How to expose various Device Resource Limit?}\label{sec:Creating New Device Types or Extending the Device / How to expose various Device Resource Limit?}
> +If a device supports resource creation to the driver or if the device
> +has some implicit resource(s), and device wants to share such resource limits
> +to the driver, how should device expose these limits? The device, should
> +expose these resource limits using the device capabilities.

So implicit resources cannot be created (and removed)? This should be
described in the specification.

> +
> +\section{When to use the Capabilities?}\label{sec:Creating New Device Types or Extending the Device / When to use the Capabilities?}
> +Any field which is more than a bit that a device want to expose to the
> +driver, can be exposed as a device capability. Device and driver
> +capabilities are not constantly changing fields during the life cycle
> +of the driver and device; capabilities are rarely changing parameters
> +used during the life time of driver possibly dynamically. Sometimes a
> +system may have many similar devices, but each device may have different
> +attributes, it is better to use capabilities for such attributes as well.
> +Examples of capabilities are resource limits indicating number of RTC clocks
> +per device, number of flow filter groups, number of flow filter rules for net
> +device, number of data bytes that can be places inline instead of descriptors
> +for the transmitq for virtio net device, number of bytes in a header data split
> +receive virtqueue etc.

What would "number of RTC clocks" mean? Maximum number? Currently existing
resources?

> +
> +\section{Read only attributes as capabilities?}\label{sec:Creating New Device Types or Extending the Device / Read only attributes as capabilities?}
> +If there are one or more device attributes which are read only for the driver,
> +they can also be used as device capabilities. Such read only capabilities must
> +be documented as read only so that driver do not try to change them.
> +
>  \section{What Device Configuration Space Layout?}\label{sec:Creating New Device Types or Extending the Device / What Device Configuration Space Layout?}
>  
>  Device configuration space should only be used for initialization-time
> @@ -26,6 +66,18 @@ \section{What Device Configuration Space Layout?}\label{sec:Creating New Device
>  writable by the driver.  Therefore, no writeable field which triggers an
>  action ought to be wider than 32 bits.
>  
> +\section{When to use admin virtqueue vs control virtqueue?}\label{sec:Creating New Device Types or Extending the Device / When to use admin virtqueue vs control virtqueue?}
> +Any new device which can model its configuration using device capabilities,
> +and resources as either implicit or driver created resources, it is preferred
> +to use the admin commands using admin virtqueue. This is also helpful
> +to do multiple admin virtqueues in future if needed. Even for the existing
> +device if a control virtqueue may exist for the existing device, extending new
> +functionalities using administration commands is desired as it already
> +offers a generic infrastructure for configuration.

As the author of the virtio-rtc device draft and PoC implementation, I
disagree with this advice as well. Please again refer to the discussion
about virtio-rtc and resources [1] for more information.

> +
> +Administration virtqueue operations may be relatively slower than the
> +data path operations, hence it is not suitable for data path level commands.

What does "slower" mean? More latency? Less bandwidth? For RTC the latency
can be important for the device performance.

Best regards,

Peter

[1] 4e39177c-7bdb-4754-a170-5edbb89002e1@opensynergy.com/">https://lore.kernel.org/virtio-comment/4e39177c-7bdb-4754-a170-5edbb89002e1@opensynergy.com/