[PATCH v9 06/13] admin-cmds-resources: Add device resources admin commands

[Parav Pandit <parav@nvidia.com>]

Add generic administration commands create, modify, query and destroy
device resources.

Each resource defines resource specific attributes for the commands.
Once the resource is created by the driver, it can be query/modify or
destroyed by the driver.

Each resource is identified using a unique resource identifier per
resource type.

Administration commands for managing resources using administration
commands are relatively slower operations compared to data path
operations of transmitq and receiveq of the network device.

Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179
Signed-off-by: Parav Pandit <parav@nvidia.com>
---
changelog:
v8->v9:
- changed command name from read_data/read_result to query_data/query_result
  to match the opcode name and description
- added fields_bmap bitmap to support future support of optional fields
  in the resources without inventing new set of commands, for example
  multiple pages in the VQ, PASID in VQ, flow counter id in flow filter rule
  etc.
- fixed spelling from 'destroyd' to 'destroyed'
- fixed 'upto' to 'up to'
---
 admin-cmds-resources.tex | 207 +++++++++++++++++++++++++++++++++++++++
 admin.tex                |  11 ++-
 conformance.tex          |   2 +
 resources.tex            |   4 +
 4 files changed, 223 insertions(+), 1 deletion(-)
 create mode 100644 admin-cmds-resources.tex

diff --git a/admin-cmds-resources.tex b/admin-cmds-resources.tex
new file mode 100644
index 0000000..5068bcc
--- /dev/null
+++ b/admin-cmds-resources.tex
@@ -0,0 +1,207 @@
+\subsubsection{Device Resources}\label{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device Resources}
+
+The device resource operates the device as described in
+\ref{sec:Basic Facilities of a Virtio Device / Device Resources}.
+
+Following device resource commands are currently defined only for the self
+group type:
+
+\begin{enumerate}
+\item Device Resource Create Command
+\item Device Resource Modify Command
+\item Device Resource Query Command
+\item Device Resource Destroy Command
+\end{enumerate}
+
+\begin{lstlisting}
+struct virtio_admin_cmd_resource_cmd_hdr {
+        le16 type;
+        u8 reserved[2];
+        le32 rid; /* Indicates unique resource id per resource type */
+};
+
+struct virtio_admin_cmd_resource_attr {
+        le64 fields_bmap;
+        u8 resource_specific_data[];
+};
+
+\end{lstlisting}
+
+\field{type} refers to the device resource type.
+\field{rid} uniquely identifies the resource of a specified \field{type}.
+\field{resource_specific_data} refers to the resource specific data. Each resource
+uses a different \field{resource_specific_data} and is described separately.
+\field{fields_bmap} is a bitmap which refers to optional fields of
+\field{resource_specific_data}; each bit in the \field{fields_bmap} when set
+indicates a specific field of \field{resource_specific_data} is valid.
+\field{fields_bmap} does not influence the length of the
+\field{resource_specific_data}. Each resource uses a different value for
+\field{fields_bmap} and it is described separately.
+
+\paragraph{Device Resource Create Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device Resources / Device Resource Create Command}
+
+This command creates the specified resource of \field{type} identified by the
+resource identifier \field{rid}. The valid range of \field{rid} is defined by the
+device in the related device capabilities. The driver assigns the unique \field{rid}
+for the resource for the specified \field{type}.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_resource_create_data {
+        struct virtio_admin_cmd_resource_cmd_hdr hdr;
+        le16 length;
+        le16 reserved[6];
+        struct virtio_admin_cmd_resource_attr attr;
+};
+\end{lstlisting}
+
+For the command VIRTIO_ADMIN_CMD_RESOURCE_CREATE, \field{opcode} is set to 0xa.
+
+\field{group_member_id} refers to the device itself to be accessed.
+\field{length} refers to the length of \field{attr}.
+When driver wants to set the optional fields of
+\field{resource_specific_data}, for each such field a respective
+resource defined \field{fields_bmap} is set by the driver along with fields
+in the \field{resource_specific_data}.
+
+When the command completes successfully, the resource is created in the
+device and in use by the device. This command has no command specific result.
+
+\paragraph{Device Resource Modify Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device Resources / Device Resource Modify Command}
+
+This command modifies the existing resource of \field{type} identified
+by \field{rid}, which is previously created using command
+VIRTIO_ADMIN_CMD_RESOURCE_CREATE.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_resource_modify_data {
+        struct virtio_admin_cmd_resource_cmd_hdr hdr;
+        le16 length;
+        le16 reserved[6];
+        struct virtio_admin_cmd_resource_attr attr;
+};
+\end{lstlisting}
+
+For the command VIRTIO_ADMIN_CMD_RESOURCE_MODIFY, \field{opcode} is set to 0xb.
+
+\field{group_member_id} refers to the device itself to be accessed.
+\field{type} refers to the device resource type.
+\field{rid} uniquely identifies the resource of type \field{type} to be created.
+\field{length} refers to the length of the \field{attr}.
+When driver wants to modify the optional fields of
+\field{resource_specific_data}, for each such field a respective
+resource defined \field{fields_bmap} is set by the driver along with fields
+in the \field{resource_specific_data}.
+When the command completes successfully, the resource is modified as set in
+\field{attr}.
+This command has no command specific result.
+
+\paragraph{Device Resource Query Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group
+administration commands / Device Resources / Device Resource Query Command}
+
+This command reads the existing resource of \field{type} identified
+by \field{rid}, which is previously created using command
+VIRTIO_ADMIN_CMD_RESOURCE_CREATE.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_resource_query_data {
+        struct virtio_admin_cmd_resource_cmd_hdr hdr;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_admin_cmd_resource_query_result {
+        le16 length;
+        le16 reserved[6];
+        struct virtio_admin_cmd_resource_attr attr;
+};
+\end{lstlisting}
+
+For the command VIRTIO_ADMIN_CMD_RESOURCE_QUERY, \field{opcode} is set to 0xc.
+
+\field{group_member_id} refers to the device itself to be accessed.
+\field{type} refers to the device resource type.
+\field{rid} identifies the existing resource of type \field{type}.
+\field{length} refers to the length of the \field{attr}.
+
+When the command completes successfully, the resource information is returned
+to the driver in \field{attr}. When the optional fields of the
+\field{resource_specific_data} are valid, for each such field a respective
+resource defined \field{fields_bmap} is set by the device.
+
+\paragraph{Device Resource Destroy Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group
+administration commands / Device Resources / Device Resource Destroy Command}
+
+This command destroys the specified resource of \field{type} identified
+by \field{rid}, which is previously created using command
+VIRTIO_ADMIN_CMD_RESOURCE_CREATE.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_resource_destroy_data {
+        struct virtio_admin_cmd_resource_cmd_hdr hdr;
+};
+\end{lstlisting}
+
+For the command VIRTIO_ADMIN_CMD_RESOURCE_DESTROY, \field{opcode} is set to 0xd.
+
+\field{group_member_id} refers to the device itself to be accessed.
+\field{type} refers to the device resource type.
+\field{rid} identifies the existing resource of type \field{type} to be destroyed.
+
+When the command completes successfully, the resource is destroyed from the device.
+This command has no command specific result.
+
+\devicenormative{\paragraph}{Device Resources}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device Resources}
+
+The device MUST set VIRTIO_ADMIN_STATUS_EEXIST for the command
+VIRTIO_ADMIN_CMD_RESOURCE_CREATE if a resource already exists with supplied
+resource \field{rid} for the specified \field{type}.
+
+The device MUST complete the command with status \field{status}
+VIRTIO_ADMIN_STATUS_ENXIO for the commands
+VIRTIO_ADMIN_CMD_RESOURCE_MODIFY, VIRTIO_ADMIN_CMD_RESOURCE_QUERY and
+VIRTIO_ADMIN_CMD_RESOURCE_DESTROY if the specified resource does not exist.
+
+The device MUST set \field{status} to VIRTIO_ADMIN_STATUS_ENOSPC for the command
+VIRTIO_ADMIN_CMD_RESOURCE_CREATE if the device fail to create the
+resource.
+
+The device MUST complete the command with \field{status}
+VIRTIO_ADMIN_STATUS_EBUSY if the resource
+modified or destroyed is linked to other resource and if the device cannot perform
+the requested VIRTIO_ADMIN_CMD_RESOURCE_MODIFY or VIRTIO_ADMIN_CMD_RESOURCE_DESTROY
+commands.
+
+The device MUST allow recreating the resource using
+VIRTIO_ADMIN_CMD_RESOURCE_CREATE command which was previously created
+and destroyed using VIRTIO_ADMIN_CMD_RESOURCE_CREATE and
+VIRTIO_ADMIN_CMD_RESOURCE_DESTROY command respectively without undergoing
+a device reset.
+
+The device MUST allow creating the resource using
+VIRTIO_ADMIN_CMD_RESOURCE_CREATE command with any resource
+identifier as long as the resource does not exist and if the resource
+identifier is less than the device and driver capabilities published resource
+limit \field{max_limit}.
+
+The device MAY fail VIRTIO_ADMIN_CMD_RESOURCE_CREATE command even if the
+resources within the device have not reached up to the \field{max_limit}
+but the device MAY have reached an internal limit.
+
+On device reset, the device MUST destroy all the resources which driver MAY
+have created.
+
+\drivernormative{\paragraph}{Device Resources}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device Resources}
+
+The driver SHOULD NOT create the resource with the \field{rid} which is
+already created previously by the driver.
+
+The driver SHOULD NOT create the resource using command
+VIRTIO_ADMIN_CMD_RESOURCE_CREATE when maximum resource limit has reached.
+
+The driver SHOULD NOT modify, read and destroy the resource which is
+already destroyed previously by the driver.
+
+The driver MUST NOT destroy the resource which is in use by other
+linked resource; the driver MUST destroy all the linked resources before
+removing the resource which is used by the linked resources by using
+command VIRTIO_ADMIN_CMD_RESOURCE_DESTROY.
diff --git a/admin.tex b/admin.tex
index c0ba54e..aa4ff59 100644
--- a/admin.tex
+++ b/admin.tex
@@ -139,7 +139,15 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti
 \hline
 0x0009 & VIRTIO_ADMIN_CMD_CAP_WRITE & Write the device and driver capabilities \\
 \hline
-0x000a - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd}    \\
+0x000a & VIRTIO_ADMIN_CMD_RESOURCE_CREATE & Create a device resource \\
+\hline
+0x000c & VIRTIO_ADMIN_CMD_RESOURCE_MODIFY & Modify a device resource \\
+\hline
+0x000b & VIRTIO_ADMIN_CMD_RESOURCE_QUERY & Query a device resource \\
+\hline
+0x000d & VIRTIO_ADMIN_CMD_RESOURCE_DESTROY & Destroy a device resource \\
+\hline
+0x000e - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd}    \\
 \hline
 0x8000 - 0xFFFF & - & Reserved for future commands (possibly using a different structure)    \\
 \hline
@@ -318,6 +326,7 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti
 
 \input{admin-cmds-legacy-interface.tex}
 \input{admin-cmds-capabilities.tex}
+\input{admin-cmds-resources.tex}
 
 \devicenormative{\subsubsection}{Group administration commands}{Basic Facilities of a Virtio Device / Device groups / Group administration commands}
 
diff --git a/conformance.tex b/conformance.tex
index 4782016..fbf63e3 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -96,6 +96,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \item \ref{drivernormative:General Initialization And Device Operation / Device Cleanup}
 \item \ref{drivernormative:Reserved Feature Bits}
 \item \ref{drivernormative:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and Driver Capabilities}
+\item \ref{drivernormative:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device Resources}
 \end{itemize}
 
 \conformance{\subsection}{PCI Driver Conformance}\label{sec:Conformance / Driver Conformance / PCI Driver Conformance}
@@ -177,6 +178,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \item \ref{devicenormative:Basic Facilities of a Virtio Device / Shared Memory Regions}
 \item \ref{devicenormative:Reserved Feature Bits}
 \item \ref{devicenormative:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and Driver Capabilities}
+\item \ref{devicenormative:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device Resources}
 \end{itemize}
 
 \conformance{\subsection}{PCI Device Conformance}\label{sec:Conformance / Device Conformance / PCI Device Conformance}
diff --git a/resources.tex b/resources.tex
index 307308c..4b0efb6 100644
--- a/resources.tex
+++ b/resources.tex
@@ -9,6 +9,10 @@ \section{Device Resources}\label{sec:Basic Facilities of a Virtio Device / Devic
 sends the device resource related administration commands, thereby
 instructing the device to operate in a certain way.
 
+The device supports resource control using the administration commands
+described in
+\ref{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device Resources}.
+
 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
-- 
2.34.1