admin: Define common device parts

Define common device parts that represents the state of the device. The driver can get and set these device parts using administration commands. Fixes: oasis-tcs#176 Signed-off-by: Parav Pandit <[email protected]>
paravmellanox · Jul 11, 2024 · 2f8cdb5 · 2f8cdb5
1 parent 7b8ec05
commit 2f8cdb5
Show file tree

Hide file tree

Showing 4 changed files with 293 additions and 0 deletions.
diff --git a/admin-cmds-device-parts.tex b/admin-cmds-device-parts.tex
@@ -282,3 +282,40 @@ \subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Dev
 When the command completes successfully and if the \field{flags} field
 is set to zero, the device resumes its operation. If the command completes
 with an error, it does not produce any side effects on the device.
+
+\paragraph{Device parts order}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts order}
+
+Device parts are usually captured and restored using get and set administration
+commands respectively; when multiple device parts are captured or restored,
+they are arranged in the specific order listed:
+
+Some of the device parts do not need to be written to the device when restored, such
+device parts are listed as \field{O}. When a such an optional device part is
+exchanged using \field{struct virtio_dev_part}, it is marked as optional by
+setting VIRTIO_DEV_PART_F_OPTIONAL(bit 0) in the \field{flags}.
+
+\begin{table}[H]
+\caption{Device parts order}
+\label{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts order/ Device parts order}
+\begin{xltabular}{\textwidth}{ |l|l|X| }
+\hline
+Part name & Optional & Mandatory preceding parts \\
+\hline \hline
+\hline
+VIRTIO_DEV_PART_DEV_FEATURES & O & Nil \\
+\hline
+VIRTIO_DEV_PART_DRV_FEATURES & - & Nil \\
+\hline
+VIRTIO_DEV_PART_PCI_COMMON_CFG & - & VIRTIO_DEV_PART_DEV_FEATURES, VIRTIO_DEV_PART_DRV_FEATURES \\
+\hline
+VIRTIO_DEV_PART_DEVICE_STATUS & - & VIRTIO_DEV_PART_DEV_FEATURES, VIRTIO_DEV_PART_DRV_FEATURES, VIRTIO_DEV_PART_PCI_COMMON_CFG \\
+\hline
+VIRTIO_DEV_PART_VQ_CFG & - & VIRTIO_DEV_PART_DEV_FEATURES, VIRTIO_DEV_PART_DRV_FEATURES, VIRTIO_DEV_PART_PCI_COMMON_CFG,
+                             VIRTIO_DEV_PART_DEVICE_STATUS \\
+\hline
+VIRTIO_DEV_PART_VQ_NOTIFY_CFG & - & VIRTIO_DEV_PART_DEV_FEATURES, VIRTIO_DEV_PART_DRV_FEATURES, VIRTIO_DEV_PART_PCI_COMMON_CFG,
+                             VIRTIO_DEV_PART_DEVICE_STATUS, VIRTIO_DEV_PART_VQ_CFG \\
+\hline
+\hline
+\end{xltabular}
+\end{table}
diff --git 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{admin.tex}
+\input{device-parts.tex}
 
 \chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation}
 

diff --git a/device-parts.tex b/device-parts.tex
@@ -0,0 +1,231 @@
+\section{Device parts}\label{sec:Basic Facilities of a Virtio Device / Device parts}
+
+Device parts represent the device state, with parts for basic
+device facilities such as driver features, as well as transport specific
+and device type specific parts. In memory, each device part consists
+of a header \field{struct virtio_dev_part_hdr} followed by
+the device part data in \field{value}. The driver can get and set
+these device parts using administration commands.
+
+\begin{lstlisting}
+struct virtio_dev_part_hdr {
+        le16 part_type;
+        u8 flags;
+        u8 reserved;
+        union {
+                struct {
+                        le32 offset;
+                        le32 reserved;
+                } pci_common_cfg;
+                struct  {
+                        le16 index;
+                        u8 reserved[6];
+                } vq_index;
+        } selector;
+        le32 length;
+};
+
+#define VIRTIO_DEV_PART_F_OPTIONAL 0
+
+struct virtio_dev_part {
+        struct virtio_dev_part_hdr hdr;
+        u8 value[];
+};
+
+\end{lstlisting}
+
+Each device part consists of a fixed size \field{hdr} followed by optional
+part data in field \field{value}. The device parts are divided into
+two categories and identified by \field{part_type}. The common device parts are
+independent of the device type and, are in the range \field{0x0000 - 0x01FF}. Common
+device parts are listed in
+\ref{table:Basic Facilities of a Virtio Device / Device parts / Common device parts}
+The device parts in the range \field{0x0200 - 0x05FF} are specific to a device type
+such as a network or console device.
+The device part is identified by the \field{part_type} field as listed:
+
+\begin{description}
+\item[0x0000 - 0x01FF] - common part - used to describe a part of the device that
+                         is independent of the device type
+\item[0x0200 - 0x05FF] - device type specific part - used to indicate parts
+                         that are device type specific
+\item[0x0600 - 0xFFFF] - reserved
+\end{description}
+
+Some device parts are optional, the device can function without them.
+For example, such parts can help improve performance, with the device working
+slower, yet still correctly, even without the parts. In another example,
+optional parts can be used for validation, with the device being able to deduce
+the part itself, the part being helpful to detect driver or user errors.
+Such device parts are marked optional by setting bit 0
+(VIRTIO_DEV_PART_F_OPTIONAL) in the \field{flags}.
+
+\field{reserved} is reserved and set to zero.
+
+\field{length} indicates the length of the \field{value} in bytes. The length
+of the device part depends on the device part itself and is described separately.
+The device part data is in \field{value} and is \field{part_type} specific.
+
+\field{selector} further specifies the part. It is only used for some
+\field{part_type} values.
+
+\field{selector.pci_common_cfg.offset} is the offset of the
+field in the \hyperref[sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout]{Virtio PCI common config space}. It is valid only when the \field{part_type} is set to VIRTIO_DEV_PART_PCI_COMMON_CFG,
+otherwise it is reserved and set to 0.
+
+\field{selector.vq_index.index} is the index of the virtqueue. It is valid
+only when the \field{part_type} is VIRTIO_DEV_PART_VQ_CFG or
+VIRTIO_DEV_PART_VQ_CFG.
+
+\subsection{Common device parts}\label{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts}
+
+Common parts are independent of the device type.
+\field{part_type} and \field{value} for each part are documented as follows:
+
+\begin{table}
+\caption{Common device parts}
+\label{table:Basic Facilities of a Virtio Device / Device parts / Common device parts}
+\begin{xltabular}{\textwidth}{ |l||l|X| }
+\hline
+Type & Name & Description \\
+\hline \hline
+0x100 & \hyperref[sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_DEV_FEATURES]{VIRTIO_DEV_PART_DEV_FEATURES} & Device features \\
+\hline
+0x101 & \hyperref[sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_DRV_FEATURES]{VIRTIO_DEV_PART_DRV_FEATURES} & Driver features \\
+\hline
+0x102 & \hyperref[sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_PCI_COMMON_CFG]{VIRTIO_DEV_PART_PCI_COMMON_CFG} & PCI common configuration \\
+\hline
+0x103 & \hyperref[sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_DEVICE_STATUS]{VIRTIO_DEV_PART_DEVICE_STATUS} & Device status \\
+\hline
+0x104 & \hyperref[sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_VQ_CFG]{VIRTIO_DEV_PART_VQ_CFG} & Virtqueue configuration \\
+\hline
+0x105 & \hyperref[sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_VQ_NOTIFY_CFG]{VIRTIO_DEV_PART_VQ_NOTIFY_CFG} & Virtqueue notification configuration \\
+\hline
+0x106 - 0x2FF & - & Common device parts range reserved for future \\
+\hline
+\hline
+\end{xltabular}
+\end{table}
+
+\subsubsection{VIRTIO_DEV_PART_DEV_FEATURES}
+\label{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_DEV_FEATURES}
+
+For VIRTIO_DEV_PART_DEV_FEATURES, \field{part_type} is set to 0x100.
+The VIRTIO_DEV_PART_DEV_FEATURES field indicates features offered by the device.
+\field{value} is in the format of \field{struct virtio_dev_part_features}.
+\field{feature_bits} is in the format listed in
+\ref{sec:Basic Facilities of a Virtio Device / Feature Bits}.
+\field{length} is the length of the \field{struct virtio_dev_part_features}.
+
+If the VIRTIO_DEV_PART_DEV_FEATURES device part is present, there is exactly
+one instance of it in the get or set commands.
+
+The VIRTIO_DEV_PART_DEV_FEATURES part is optional for which
+the VIRTIO_DEV_PART_F_OPTIONAL (bit 0) \field{flags} is set.
+
+\begin{lstlisting}
+struct virtio_dev_part_features {
+        le64 feature_bits[];
+};
+\end{lstlisting}
+
+\subsubsection{VIRTIO_DEV_PART_DRV_FEATURES}
+\label{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_DRV_FEATURES}
+
+For VIRTIO_DEV_PART_DRV_FEATURES, \field{part_type} is set to 0x101.
+The VIRTIO_DEV_PART_DRV_FEATURES field indicates features set by the driver.
+\field{value} is in the format of \field{struct virtio_dev_part_features}.
+\field{feature_bits} is in the format listed in
+\ref{sec:Basic Facilities of a Virtio Device / Feature Bits}.
+\field{length} is the length of the \field{struct virtio_dev_part_features}.
+
+If the VIRTIO_DEV_PART_DEV_FEATURES device part present, there is exactly
+one instance of it in the get or set commands.
+
+\subsubsection{VIRTIO_DEV_PART_PCI_COMMON_CFG}
+\label{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_PCI_COMMON_CFG}
+
+For VIRTIO_DEV_PART_PCI_COMMON_CFG, \field{part_type} is set to 0x102.
+VIRTIO_DEV_PART_PCI_COMMON_CFG refers to the common device configuration
+fields. \field{offset} refers to the
+byte offset of single field in the common configuration layout described in
+\field{struct virtio_pci_common_cfg}. \field{value} is in the format depending on
+the \field{offset}, for example when \field{cfg_offset = 18}, \field{value}
+is in the format of \field{num_queues}. \field{length} is the length of
+\field{value} in bytes of a single structure field whose offset is \field{offset}.
+
+One or multiple VIRTIO_DEV_PART_PCI_COMMON_CFG parts may exist in the
+get or set commands; each such part corresponds to a unique \field{offset}.
+
+\subsubsection{VIRTIO_DEV_PART_DEVICE_STATUS}\label{par:VIRTIO_DEV_PART_DEVICE_STATUS}
+
+For VIRTIO_DEV_PART_DEVICE_STATUS, \field{part_type} is set to 0x103.
+The VIRTIO_DEV_PART_DEVICE_STATUS field indicates the device status as listed in
+\ref{sec:Basic Facilities of a Virtio Device / Device Status Field}.
+\field{value} is in the format \field{device_status} of
+\field{struct virtio_pci_common_cfg}.
+
+If the VIRTIO_DEV_PART_DEV_FEATURES device part is present, there is exactly
+one instance of it in the get or set commands.
+
+There is exactly one part may exist in the get or set
+commands.
+
+\subsubsection{VIRTIO_DEV_PART_VQ_CFG}
+\label{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_VQ_CFG}
+
+For VIRTIO_DEV_PART_VQ_CFG, \field{part_type} is set to 0x104.
+\field{value} is in the format \field{struct virtio_dev_part_vq_cfg}.
+\field{length} is the length of \field{struct virtio_dev_part_vq_cfg}.
+
+\begin{lstlisting}
+struct virtio_dev_part_vq_cfg {
+        le16 queue_size;
+        le16 vector;
+        le16 enabled;
+        le16 reserved;
+        le64 queue_desc;
+        le64 queue_driver;
+        le64 queue_device;
+};
+\end{lstlisting}
+
+\field{queue_size}, \field{vector}, \field{queue_desc},
+\field{queue_driver} and \field{queue_device} correspond to the
+fields of \field{struct virtio_pci_common_cfg} when used for PCI transport.
+
+One or multiple instances of the device part VIRTIO_DEV_PART_VQ_CFG may exist in
+the get and set commands. Each such device part corresponds to a unique virtqueue identified
+by the \field{vq_index.index}.
+
+\subsubsection{VIRTIO_DEV_PART_VQ_NOTIFY_CFG}
+\label{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_VQ_NOTIFY_CFG}
+
+For VIRTIO_DEV_PART_VQ_NOTIFY_CFG, \field{part_type} is set to 0x105.
+\field{value} is in the format \field{struct virtio_dev_part_vq_notify_data}.
+\field{length} is the length of \field{struct virtio_dev_part_vq_notify_data}.
+
+\begin{lstlisting}
+struct virtio_dev_part_vq_notify_data {
+        le16 queue_notify_off;
+        le16 queue_notif_config_data;
+        u8 reserved[4];
+};
+\end{lstlisting}
+
+\field{queue_notify_off} and \field{queue_notif_config_data} corresponds to the
+fields in \field{struct virtio_pci_common_cfg} described in
+\hyperref[sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout]{Virtio PCI common configuration space}.
+
+One or multiple instance of the device part VIRTIO_DEV_PART_VQ_NOTIFY_CFG may exist
+in the get and set commands, each such device part corresponds to a unique
+virtqueue identified by the \field{vq_index.index}.
+
+\field{reserved} is reserved and set to 0.
+
+\subsection{Assumptions}
+For the SR-IOV group type, some hypervisors do not allow the driver to access
+the PCI configuration space and the MSI-X Table space directly. Such hypervisors
+query and save these fields without the need for this device parts.
+Therefore, this version of the specification does not have it in the device parts. A future
+extension of the device part may further include them as new device part.
diff --git a/newdevice.tex b/newdevice.tex
@@ -85,3 +85,27 @@ \section{Device Improvements}\label{sec:Creating New Device Types or Extending t
 can use a single bit, but if one feature makes sense without the
 others they should not be gratuitously grouped together to
 conserve feature bits.
+
+\section{How to define a new device part?}\label{sec:Creating New Device Types or Extending the Device / How to define a new device part?}
+Few considerations are necessary when creating new device part or
+when extending the device part structure.
+If the new field is generic for all the device types or most of the device types,
+a new device part should be defined as common device part by claiming a new \field{type} value.
+If the new field is unique to a device type, a new device specific device part should
+be added.
+range.
+
+\section{When to define a new device part?}\label{sec:Creating New Device Types or Extending the Device / When to define a new device part?}
+When the device part for a specific field does not exists, one should
+define a new device part.
+
+\section{How to avoid device part duplication with existing structure?}\label{sec:Creating New Device Types or Extending the Device / How to avoid device part duplication with existing structure?}
+Each device should reuse any existing field definition that may exists as part
+of device control virtqueue or any other existing structure definition.
+
+\section{How to extend the existing device part definition?}\label{sec:Creating New Device Types or Extending the Device / How to extend the existing device part definition?}
+
+When a field is missing in already defined device part, a new field should be added at
+the end of the existing device part. New field MUST not be added at beginning or in
+the middle of the device part structure. Any field which is already present MUST NOT
+be removed.