From 2f8cdb5ebaa9a196c3026ada07f20f6868e8ea9d Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Sat, 1 Jun 2024 17:50:41 +0300 Subject: [PATCH] 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: https://github.com/oasis-tcs/virtio-spec/issues/176 Signed-off-by: Parav Pandit --- admin-cmds-device-parts.tex | 37 ++++++ content.tex | 1 + device-parts.tex | 231 ++++++++++++++++++++++++++++++++++++ newdevice.tex | 24 ++++ 4 files changed, 293 insertions(+) create mode 100644 device-parts.tex diff --git a/admin-cmds-device-parts.tex b/admin-cmds-device-parts.tex index 36a45d3..05d2477 100644 --- 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 index d7d544e..8849522 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{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 new file mode 100644 index 0000000..7384408 --- /dev/null +++ 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 index c18689f..870ea68 100644 --- 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.