[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [PATCH v7 06/13] admin-cmds-resources: Add device resources admin commands
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.
Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179
Signed-off-by: Parav Pandit <parav@nvidia.com>
---
admin-cmds-resources.tex | 186 +++++++++++++++++++++++++++++++++++++++
admin.tex | 11 ++-
conformance.tex | 2 +
resources.tex | 4 +
4 files changed, 202 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..da4e576
--- /dev/null
+++ b/admin-cmds-resources.tex
@@ -0,0 +1,186 @@
+\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 */
+};
+\end{lstlisting}
+
+\field{type} refers to the device resource type.
+\field{rid} uniquely identifies the resource of a specified \field{type}.
+
+\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;
+ u8 reserved[6];
+ u8 resource_specific_data[];
+};
+\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 the \field{resource_specific_data}.
+\field{resource_specific_data} refers to the resource specific data. Each resource
+uses a different \field{resource_specific_data} and is described separately.
+
+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];
+ u8 resource_specific_data[];
+};
+\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{data}.
+
+When the command completes successfully, the resource is modified with
+updated \field{resource_specific_data}.
+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_read_data {
+ struct virtio_admin_cmd_resource_cmd_hdr hdr;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_admin_cmd_resource_read_result {
+ le16 length;
+ le16 reserved[6];
+ u8 resource_specific_data[];
+};
+\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{data}.
+
+When the command completes successfully, the resource information is returned
+to the driver in \field{resource_specific_data}.
+
+\paragraph{Device Resource Remove Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group
+administration commands / Device Resources / Device Resource Destroy Command}
+
+This command reads 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 destroyd.
+
+When the command completes successfully, the resource is destroyd 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 destroyd 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 upto 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 destroyd 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 587cc32..d4a7c7f 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]