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

[Parav Pandit <parav@nvidia.com>]

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.
+
+\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.
+
+\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.
+
+\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.
+
+Administration virtqueue operations may be relatively slower than the
+data path operations, hence it is not suitable for data path level commands.
+
 \section{What Device Number?}\label{sec:Creating New Device Types or Extending the Device / What Device Number?}
 
 Device numbers for the new devices can be reserved by the OASIS committee: email
-- 
2.34.1