[PATCH v9 05/13] resources: Add theory of operation for device resources

[Parav Pandit <parav@nvidia.com>]

The device may support device operation by means of resources.
The driver creates the device resources and operates the device
in a certain way.

These operations include create, query, modify, and destroy the device
resources.

Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179
Signed-off-by: Parav Pandit <parav@nvidia.com>
---
changelog:
v7->v8:
- added text about administration commands execution rate behavior
---
 content.tex   |  1 +
 resources.tex | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 resources.tex

diff --git a/content.tex b/content.tex
index 4938fc0..33d7169 100644
--- a/content.tex
+++ b/content.tex
@@ -503,6 +503,7 @@ \section{Exporting Objects}\label{sec:Basic Facilities of a Virtio Device / Expo
 UUIDs as specified by \hyperref[intro:rfc4122]{[RFC4122]}.
 
 \input{capabilities.tex}
+\input{resources.tex}
 \input{admin.tex}
 
 \chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation}
diff --git a/resources.tex b/resources.tex
new file mode 100644
index 0000000..307308c
--- /dev/null
+++ b/resources.tex
@@ -0,0 +1,70 @@
+\section{Device Resources}\label{sec:Basic Facilities of a Virtio Device / Device Resources}
+
+A device may support certain device functioning by means of a device
+resource. A device resource typically defines how the device should
+function. For example, a driver can instruct the virtio network
+device to forward or drop packets by using flow filter group and
+flow filter rule resources. The driver can create, query, modify, or
+destroy a resource using the administration commands. The driver
+sends the device resource related administration commands, thereby
+instructing the device to operate in a certain way.
+
+Each device resource is identified by a unique resource identifier. The driver
+assigns the resource identifier when creating a device resource. Once the resource
+successfully created, subsequent operations of modifying, querying or destroying
+the resource refers to this unique resource identifier. A device may support
+multiple types of resources. Resource identifiers are unique per resource type;
+in other words resources of two different resource types may have the same
+resource identifier.
+
+A resource of one type may be linked to the resource of other type. Such linking
+of resources is done by referring to the unique resource identifier in the
+administration commands. For example, a driver creates the resource identified
+by id A of one type, followed by creating another resource identified by id B
+of a different type linked to resource A. Such linked resources establish
+the dependencies in the life cycle of these resources. The driver which creates
+the linked resource, destroys the resources in exact reverse order of their
+creation. In this example, driver destroys the resource B before removing the
+resource A.
+
+Broadly there are two types of device resources. One type of resources
+which are common across all the device types. Other resources are specific
+to a device type.
+
+\begin{tabular}{|l|l|}
+\hline
+Type & Description \\
+\hline \hline
+0x000-0x1ff & Generic resource type common across all devices \\
+\hline
+0x200-0x4ff & Device type specific resource \\
+\hline
+0x500-0xffff & Reserved for future use  \\
+\hline
+\end{tabular}
+
+The device and the driver may publish a resource limit by using
+\field{struct virtio_resource_limit} as part of
+\field{Device and Driver Capabilities} described in
+\ref{sec:Basic Facilities of a Virtio Device / Device and Driver Capabilities}.
+
+\begin{lstlisting}
+struct virtio_resource_limit {
+        le32 max_limit; /* maximum resource identifier = max_limit - 1 */
+};
+\end{lstlisting}
+
+A valid resource identifier is \field{max_limit - 1}. For example, when a device
+reports a \field{max_limit = 10} capability for a resource, and driver writes
+\field{max_limit = 8}, the valid resource identifier range for the driver
+and device is 0 to 7 for all the resource operations. In this example,
+the driver can only create 8 resources of a specified type.
+
+When the device starts, device starts with zero resources; the driver creates
+the resource up to the published limit of \field{max_limit}, the driver can
+destroy the resource and recreate it one or multiple times. On the device reset,
+all the resources created by the driver are destroyed within the device.
+
+Managing resources using administration commands using administration virtqueues
+are assumed to be slower operations compared to data path operations such as
+handling tranmitq or receiveq.
-- 
2.34.1