[PATCH v11 13/13] newdevice: Extend informative guidance on capability, resource objects

[Parav Pandit <parav@nvidia.com>]

Add few informative guidance/notes about which use cases to use
device and driver capabilities and device resource objects.

Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179
Signed-off-by: Parav Pandit <parav@nvidia.com>
---
internal changelog:
- only sending last patch-12 to avoid the flood
- added back resource limit sentence along with resource object
- replaced administrative -> administration
- replaced admin virtqueue -> administration virtqueue
- replaced admin -> administration
- replaced utilize -> use
changelog:
v9->v10:
- updated examples
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 | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/newdevice.tex b/newdevice.tex
index 4f43554..c18689f 100644
--- a/newdevice.tex
+++ b/newdevice.tex
@@ -26,6 +26,27 @@ \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 device resource object?}\label{sec:Creating New Device Types or Extending the Device / When to use device resource object?}
+Device resource objects are best suited to represent device resources used
+dynamically by the driver. Limits on resource usage appear as limit
+fields in a device capability.
+
+\section{When to use the capabilities?}\label{sec:Creating New Device Types or Extending the Device / When to use the capabilities?}
+Capabilities allow the device and the driver to negotiate support and resources
+used for specific functionality. For example, for a networking device, a
+capability can represent the limit on the number of flow filter groups. In
+another example, a capability can represent the allowed flow filter classifiers.
+
+\section{When to use administration virtqueue vs control virtqueue?}\label{sec:Creating New Device Types or Extending the Device / When to use administration virtqueue vs control virtqueue?}
+Any new device configuration, through device capabilities and resources as
+either implicit or driver-created resource objects, should preferably use
+administration commands via the administration virtqueue. Furthermore, even for devices with a
+control virtqueue for configuration, implementing new functionality using
+administration commands that leverage generic infrastructure is desirable.
+
+Future enhancements may involve provisioning member devices using
+standardized administration commands that reuse existing capability structures.
+
 \section{What Device Number?}\label{sec:Creating New Device Types or Extending the Device / What Device Number?}
 
 Device numbers can be reserved by the OASIS committee: email
-- 
2.34.1