[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [PATCH v8 04/13] admin-cmds-capabilities: Add capabilities admin commands
Add three capabilities related commands.
First to read the device and driver capabilities.
Second to write the driver capabilities.
Third for driver to discover which capabilities can be accessed.
Write capabilities by the owner driver is not currently supported.
It will be supported in future by the owner driver to write for
the member device.
Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179
Signed-off-by: Parav Pandit <parav@nvidia.com>
---
admin-cmds-capabilities.tex | 161 ++++++++++++++++++++++++++++++++++++
admin.tex | 9 +-
capabilities.tex | 3 +
conformance.tex | 2 +
4 files changed, 174 insertions(+), 1 deletion(-)
create mode 100644 admin-cmds-capabilities.tex
diff --git a/admin-cmds-capabilities.tex b/admin-cmds-capabilities.tex
new file mode 100644
index 0000000..47394c7
--- /dev/null
+++ b/admin-cmds-capabilities.tex
@@ -0,0 +1,161 @@
+\subsubsection{Device and Driver Capabilities}\label{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and Driver Capabilities}
+
+The device and driver capabilities commands are currently defined for self group type and for
+SR-IOV group type.
+
+\begin{enumerate}
+\item Device Capabilities Support Query Command
+\item Capabilities Read Command
+\item Capabilities Write Command
+\end{enumerate}
+
+\paragraph{Device Capabilities Support Query Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and Driver Capabilities / Device Capabilities Support Query Command}
+
+For the command VIRTIO_ADMIN_CMD_CAP_SUPPORT_QUERY, \field{opcode} is set to 0x7.
+
+This command queries the supported device capabilities identifiers bitmap in
+\field{supported_caps}. Each bit in \field{supported_caps} corresponds to the
+capability identifier. Thus, supported_caps[0] refers to the first 64-bit value
+in this array corresponding to identifiers 0 to 63, supported_caps[1]
+is the second 64-bit value corresponding to identifiers 64 to 127, etc.
+For example, with \field{num_caps = 2}, the array of size 2 including the values
+0x3 in supported_caps[0], and 0x1 in supported_caps[1] indicates that only
+identifiers 0, 1 and 64 are supported.
+
+The length of the array \field{supported_caps} depends on the supported
+identifiers - it is large enough to include bits set for all supported
+identifiers, that is the length is set by calculating by starting with the
+largest supported opcode adding one, dividing by 64 and rounding up.
+
+The array \field{supported_caps} is also allowed to be larger and to
+additionally include an arbitrary number of all-zero entries.
+
+For each identifier, the driver can read the device capabilities and write
+the driver capabilities. The driver can also read the written capabilities.
+
+This command has no command specific data.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_query_supported_cap_result {
+ le16 num_caps;
+ u8 reserved[6];
+ le64 supported_caps[];
+};
+\end{lstlisting}
+
+When the command completes successfully, \field{command_specific_result}
+is in the format \field{struct virtio_admin_cmd_query_supported_cap_result}
+returned by the device. The number of valid array entries of
+\field{supported_caps} are indicated in \field{num_caps}.
+
+\paragraph{Capabilities Read Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and Driver Capabilities / Capabilities Read Command}
+
+This command reads the device or driver capabilities. It either reads the
+capability of the own device or the owner device can read the capabilities of
+the member device.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_cap_read_data {
+ le16 cid;
+ u8 type; /* 0 = device cap, 1 = driver cap */
+ u8 reserved[5];
+};
+\end{lstlisting}
+
+For the command VIRTIO_ADMIN_CMD_CAP_READ, \field{opcode} is set to 0x8.
+
+\field{group_member_id} refers to the device itself or the member device to be accessed.
+\field{cid} refers to the capability identifier listed in
+\ref{sec:Basic Facilities of a Virtio Device / Device and Driver Capabilities}.
+When \field{type} is set to 0, it refers to the device capability, when
+\field{type} is set to 1, it refers to the driver capability, rest of the
+values are reserved.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_cap_read_result {
+ le16 length;
+ u8 reserved[6];
+ u8 cap_specific_data[];
+};
+\end{lstlisting}
+
+When the command completes successfully, \field{command_specific_result}
+is in the format \field{struct virtio_admin_cmd_cap_read_result} responded
+by the device. The \field{length} is set to the length of the
+\field{cap_specific_data}. Each capability uses different capability specific
+\field{cap_specific_data} and is described separately.
+
+\paragraph{Capabilities Write Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and Driver Capabilities / Capabilities Write Command}
+
+This command writes the driver capabilities indicating to the device which
+capabilities are used by the driver. The driver can write capabilities which
+are smaller or equal in value than the values published by the device
+capabilities.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_cap_write_data {
+ le16 cid;
+ u8 type; /* 1 = driver cap */
+ u8 reserved;
+ le16 length;
+ u8 reserved1[2];
+ u8 cap_specific_data[];
+};
+\end{lstlisting}
+
+For the command VIRTIO_ADMIN_CMD_CAP_WRITE, \field{opcode} is set to 0x9.
+
+\field{group_member_id} refers to the the device itself. Currently the owner
+device cannot write the member device's capabilities. This will be supported
+in the future.
+\field{cid} refers to the capability identifier listed in
+\ref{sec:Basic Facilities of a Virtio Device / Device and Driver Capabilities}.
+\field{type} is set to 1, refers to the driver capability, when
+\field{length} refers to the length of the \field{cap_specific_data}.
+
+There is no command specific result.
+When the command completes successfully the driver capabilities are
+updated to values supplied in \field{cap_specific_data}.
+
+\devicenormative{\paragraph}{Device and Driver Capabilities}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and Driver Capabilities}
+
+If the device supports capabilities, it MUST support
+VIRTIO_ADMIN_CMD_CAP_SUPPORT_QUERY, VIRTIO_ADMIN_CMD_CAP_WRITE and
+VIRTIO_ADMIN_CMD_CAP_READ commands.
+
+The device MUST support writing all the driver capabilities in
+VIRTIO_ADMIN_CMD_CAP_WRITE command to same or smaller value than what is reported
+in device capabilities in VIRTIO_ADMIN_CMD_CAP_READ command unless
+otherwise explicitly stated capability fields as non writeable fields.
+
+In VIRTIO_ADMIN_CMD_CAP_WRITE command, if any of the written capability
+field value is larger than the value reported by the device capability,
+the device MUST complete VIRTIO_ADMIN_CMD_CAP_WRITE command with \field{status}
+VIRTIO_ADMIN_STATUS_EINVAL.
+
+The device MUST support VIRTIO_ADMIN_CMD_CAP_READ command for the owner
+device to read capabilities for the member device.
+
+The device MUST complete VIRTIO_ADMIN_CMD_CAP_WRITE command with
+\field{status} VIRTIO_ADMIN_STATUS_EINVAL for the owner device to
+write the capabilities of the member device.
+
+The device MUST complete VIRTIO_ADMIN_CMD_CAP_WRITE command with \field{status}
+VIRTIO_ADMIN_STATUS_EBUSY if the command requested to disable a capability and
+the device has any valid resources related to the capability being disabled.
+
+On device reset, the device MUST reset all the driver capabilities.
+
+\drivernormative{\paragraph}{Device and Driver Capabilities}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and Driver Capabilities}
+
+The driver MUST send VIRTIO_ADMIN_CMD_CAP_WRITE command before using
+any resources related to such capabilities.
+
+The driver SHOULD NOT send VIRTIO_ADMIN_CMD_CAP_WRITE command
+containing values which is larger than
+the device capabilities reported by the device in
+VIRTIO_ADMIN_CMD_CAP_READ command.
+
+The driver SHOULD NOT disable any of the driver capabilities by sending
+VIRTIO_ADMIN_CMD_CAP_WRITE command when any functionality related
+to such capabilities is in use by the device.
diff --git a/admin.tex b/admin.tex
index fdf25c5..c0ba54e 100644
--- a/admin.tex
+++ b/admin.tex
@@ -133,7 +133,13 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti
\hline
0x0006 & VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO & Query the notification region information \\
\hline
-0x0007 - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd} \\
+0x0007 & VIRTIO_ADMIN_CMD_CAP_SUPPORT_QUERY & Query the supported device capabilities bitmap \\
+\hline
+0x0008 & VIRTIO_ADMIN_CMD_CAP_READ & Read the device and driver capabilities \\
+\hline
+0x0009 & VIRTIO_ADMIN_CMD_CAP_WRITE & Write the device and driver capabilities \\
+\hline
+0x000a - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd} \\
\hline
0x8000 - 0xFFFF & - & Reserved for future commands (possibly using a different structure) \\
\hline
@@ -311,6 +317,7 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti
might differ between different group types.
\input{admin-cmds-legacy-interface.tex}
+\input{admin-cmds-capabilities.tex}
\devicenormative{\subsubsection}{Group administration commands}{Basic Facilities of a Virtio Device / Device groups / Group administration commands}
diff --git a/capabilities.tex b/capabilities.tex
index c375089..77d4aa5 100644
--- a/capabilities.tex
+++ b/capabilities.tex
@@ -38,3 +38,6 @@ \section{Device and Driver Capabilities}\label{sec:Basic Facilities of a Virtio
Whichever device supports the device specific capabilities, such
capabilities are described in the respective \field{Device and Driver Capabilities}
section of the device.
+
+Device and driver capabilities related administration commands are listed in
+\ref{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and Driver Capabilities}.
diff --git a/conformance.tex b/conformance.tex
index 863f9c5..4782016 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -95,6 +95,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
\item \ref{drivernormative:General Initialization And Device Operation / Device Initialization}
\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}
\end{itemize}
\conformance{\subsection}{PCI Driver Conformance}\label{sec:Conformance / Driver Conformance / PCI Driver Conformance}
@@ -175,6 +176,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
\item \ref{devicenormative:Basic Facilities of a Virtio Device / Packed Virtqueues / Scatter-Gather Support}
\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}
\end{itemize}
\conformance{\subsection}{PCI Device Conformance}\label{sec:Conformance / Device Conformance / PCI Device Conformance}
--
2.34.1
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]