From 3fdaa170307f63ce0abdfb28c7fd855b76069d77 Mon Sep 17 00:00:00 2001 From: jeshwank Date: Thu, 28 Sep 2023 11:42:30 +0530 Subject: [PATCH 01/62] virtio-tee: Reserve device ID 46 for TEE device MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In a virtual environment, an application running in guest VM may want to delegate security sensitive tasks to a Trusted Application (TA) running within a Trusted Execution Environment (TEE). A TEE is a trusted OS running in some secure environment, for example, TrustZone on ARM CPUs, or a separate secure co-processor etc. A virtual TEE device emulates a TEE within a guest VM. Such a virtual TEE device supports multiple operations such as: VIRTIO_TEE_CMD_OPEN_DEVICE – Open a communication channel with virtio TEE device. VIRTIO_TEE_CMD_CLOSE_DEVICE – Close communication channel with virtio TEE device. VIRTIO_TEE_CMD_GET_VERSION – Get version of virtio TEE. VIRTIO_TEE_CMD_OPEN_SESSION – Open a session to communicate with trusted application running in TEE. VIRTIO_TEE_CMD_CLOSE_SESSION – Close a session to end communication with trusted application running in TEE. VIRTIO_TEE_CMD_INVOKE_FUNC – Invoke a command or function in trusted application running in TEE. VIRTIO_TEE_CMD_CANCEL_REQ – Cancel an ongoing command within TEE. VIRTIO_TEE_CMD_REGISTER_MEM - Register shared memory with TEE. VIRTIO_TEE_CMD_UNREGISTER_MEM - Unregister shared memory from TEE. We would like to reserve device ID 46 for Virtio-TEE device. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/175 Signed-off-by: Jeshwanth Kumar Reviewed-by: Rijo Thomas Reviewed-by: Parav Pandit Acked-by: Sumit Garg Signed-off-by: Cornelia Huck --- content.tex | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content.tex b/content.tex index 0a62dce..644aa4a 100644 --- a/content.tex +++ b/content.tex @@ -739,6 +739,8 @@ \chapter{Device Types}\label{sec:Device Types} \hline 45 & SPI master \\ \hline +46 & TEE device \\ +\hline \end{tabular} Some of the devices above are unspecified by this document, From 42f389989823039724f95bbbd243291ab0064f82 Mon Sep 17 00:00:00 2001 From: Xuan Zhuo Date: Mon, 9 Oct 2023 09:31:35 +0800 Subject: [PATCH 02/62] virtio-net: support device stats This patch allows the driver to obtain some statistics from the device. In the device implementation, we can count a lot of such information, which can be used for debugging and judging the running status of the device. We hope to directly display it to the user through ethtool. To get stats atomically, try to get stats for all/multiple queue pairs in one command. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/180 Signed-off-by: Xuan Zhuo Suggested-by: Michael S. Tsirkin Reviewed-by: Parav Pandit Signed-off-by: Cornelia Huck --- device-types/net/description.tex | 512 +++++++++++++++++++++++- device-types/net/device-conformance.tex | 1 + device-types/net/driver-conformance.tex | 1 + 3 files changed, 511 insertions(+), 3 deletions(-) diff --git a/device-types/net/description.tex b/device-types/net/description.tex index 76585b0..aff5e08 100644 --- a/device-types/net/description.tex +++ b/device-types/net/description.tex @@ -88,6 +88,9 @@ \subsection{Feature bits}\label{sec:Device Types / Network Device / Feature bits \item[VIRTIO_NET_F_CTRL_MAC_ADDR(23)] Set MAC address through control channel. +\item[VIRTIO_NET_F_DEVICE_STATS(50)] Device can provide device-level statistics + to the driver through the control virtqueue. + \item[VIRTIO_NET_F_HASH_TUNNEL(51)] Device supports inner header hash for encapsulated packets. \item[VIRTIO_NET_F_VQ_NOTF_COAL(52)] Device supports virtqueue notification coalescing. @@ -1156,6 +1159,7 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi u8 command; u8 command-specific-data[]; u8 ack; + u8 command-specific-result[]; }; /* ack values */ @@ -1164,9 +1168,12 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi \end{lstlisting} The \field{class}, \field{command} and command-specific-data are set by the -driver, and the device sets the \field{ack} byte. There is little it can -do except issue a diagnostic if \field{ack} is not -VIRTIO_NET_OK. +driver, and the device sets the \field{ack} byte and optionally +\field{command-specific-result}. There is little the driver can +do except issue a diagnostic if \field{ack} is not VIRTIO_NET_OK. + +The command VIRTIO_NET_CTRL_STATS_QUERY and VIRTIO_NET_CTRL_STATS_GET contain +\field{command-specific-result}. \paragraph{Packet Receive Filtering}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Packet Receive Filtering} \label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Setting Promiscuous Mode}%old label for latexdiff @@ -1805,6 +1812,505 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi Upon reset, a device MUST initialize all coalescing parameters to 0. +\paragraph{Device Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics} + +If the VIRTIO_NET_F_DEVICE_STATS feature is negotiated, the driver can obtain +device statistics from the device by using the following command. + +Different types of virtqueues have different statistics. The statistics of the +receiveq are different from those of the transmitq. + +The statistics of a certain type of virtqueue are also divided into multiple types +because different types require different features. This enables the expansion +of new statistics. + +In one command, the driver can obtain the statistics of one or multiple virtqueues. +Additionally, the driver can obtain multiple type statistics of each virtqueue. + +\subparagraph{Query Statistic Capabilities}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Query Statistic Capabilities} + +\begin{lstlisting} +#define VIRTIO_NET_CTRL_STATS 8 +#define VIRTIO_NET_CTRL_STATS_QUERY 0 +#define VIRTIO_NET_CTRL_STATS_GET 1 + +struct virtio_net_stats_capabilities { + +#define VIRTIO_NET_STATS_TYPE_CVQ (1 << 32) + +#define VIRTIO_NET_STATS_TYPE_RX_BASIC (1 << 0) +#define VIRTIO_NET_STATS_TYPE_RX_CSUM (1 << 1) +#define VIRTIO_NET_STATS_TYPE_RX_GSO (1 << 2) +#define VIRTIO_NET_STATS_TYPE_RX_SPEED (1 << 3) + +#define VIRTIO_NET_STATS_TYPE_TX_BASIC (1 << 16) +#define VIRTIO_NET_STATS_TYPE_TX_CSUM (1 << 17) +#define VIRTIO_NET_STATS_TYPE_TX_GSO (1 << 18) +#define VIRTIO_NET_STATS_TYPE_TX_SPEED (1 << 19) + + le64 supported_stats_types[1]; +} +\end{lstlisting} + +To obtain device statistic capability, use the VIRTIO_NET_CTRL_STATS_QUERY +command. When the command completes successfully, \field{command-specific-result} +is in the format of \field{struct virtio_net_stats_capabilities}. + +\subparagraph{Get Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Get Statistics} + +\begin{lstlisting} +struct virtio_net_ctrl_queue_stats { + struct { + le16 vq_index; + le16 reserved[3]; + le64 types_bitmap[1]; + } stats[]; +}; + +struct virtio_net_stats_reply_hdr { +#define VIRTIO_NET_STATS_TYPE_REPLY_CVQ 32 + +#define VIRTIO_NET_STATS_TYPE_REPLY_RX_BASIC 0 +#define VIRTIO_NET_STATS_TYPE_REPLY_RX_CSUM 1 +#define VIRTIO_NET_STATS_TYPE_REPLY_RX_GSO 2 +#define VIRTIO_NET_STATS_TYPE_REPLY_RX_SPEED 3 + +#define VIRTIO_NET_STATS_TYPE_REPLY_TX_BASIC 16 +#define VIRTIO_NET_STATS_TYPE_REPLY_TX_CSUM 17 +#define VIRTIO_NET_STATS_TYPE_REPLY_TX_GSO 18 +#define VIRTIO_NET_STATS_TYPE_REPLY_TX_SPEED 19 + u8 type; + u8 reserved; + le16 vq_index; + le16 reserved1; + le16 size; +} +\end{lstlisting} + +To obtain device statistics, use the VIRTIO_NET_CTRL_STATS_GET command with the +\field{command-specific-data} which is in the format of +\field{struct virtio_net_ctrl_queue_stats}. When the command completes +successfully, \field{command-specific-result} contains multiple statistic +results, each statistic result has the \field{struct virtio_net_stats_reply_hdr} +as the header. + +The fields of the \field{struct virtio_net_ctrl_queue_stats}: +\begin{description} + \item [vq_index] + The index of the virtqueue to obtain the statistics. + + \item [types_bitmap] + This is a bitmask of the types of statistics to be obtained. Therefore, a + \field{stats} inside \field{struct virtio_net_ctrl_queue_stats} may + indicate multiple statistic replies for the virtqueue. +\end{description} + +The fields of the \field{struct virtio_net_stats_reply_hdr}: +\begin{description} + \item [type] + The type of the reply statistic. + + \item [vq_index] + The virtqueue index of the reply statistic. + + \item [size] + The number of bytes for the statistics entry including size of \field{struct virtio_net_stats_reply_hdr}. + +\end{description} + +\subparagraph{Controlq Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Controlq Statistics} + +The structure corresponding to the controlq statistics is +\field{struct virtio_net_stats_cvq}. The corresponding type is +VIRTIO_NET_STATS_TYPE_CVQ. This is for the controlq. + +\begin{lstlisting} +struct virtio_net_stats_cvq { + struct virtio_net_stats_reply_hdr hdr; + + le64 command_num; + le64 ok_num; +}; +\end{lstlisting} + +\begin{description} + \item [command_num] + The number of commands received by the device including the current command. + + \item [ok_num] + The number of commands completed successfully by the device including the current command. +\end{description} + + +\subparagraph{Receiveq Basic Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Receiveq Basic Statistics} + +The structure corresponding to the receiveq basic statistics is +\field{struct virtio_net_stats_rx_basic}. The corresponding type is +VIRTIO_NET_STATS_TYPE_RX_BASIC. This is for the receiveq. + +Receiveq basic statistics do not require any feature. As long as the device supports +VIRTIO_NET_F_DEVICE_STATS, the following are the receiveq basic statistics. + +\begin{lstlisting} +struct virtio_net_stats_rx_basic { + struct virtio_net_stats_reply_hdr hdr; + + le64 rx_notifications; + + le64 rx_packets; + le64 rx_bytes; + + le64 rx_interrupts; + + le64 rx_drops; + le64 rx_drop_overruns; +}; +\end{lstlisting} + +The packets described below were all presented on the specified virtqueue. +\begin{description} + \item [rx_notifications] + The number of driver notifications received by the device for this + receiveq. + + \item [rx_packets] + This is the number of packets passed to the driver by the device. + + \item [rx_bytes] + This is the bytes of packets passed to the driver by the device. + + \item [rx_interrupts] + The number of interrupts generated by the device for this receiveq. + + \item [rx_drops] + This is the number of packets dropped by the device. The count includes + all types of packets dropped by the device. + + \item [rx_drop_overruns] + This is the number of packets dropped by the device when no more + descriptors were available. + +\end{description} + +\subparagraph{Transmitq Basic Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Transmitq Basic Statistics} + +The structure corresponding to the transmitq basic statistics is +\field{struct virtio_net_stats_tx_basic}. The corresponding type is +VIRTIO_NET_STATS_TYPE_TX_BASIC. This is for the transmitq. + +Transmitq basic statistics do not require any feature. As long as the device supports +VIRTIO_NET_F_DEVICE_STATS, the following are the transmitq basic statistics. + +\begin{lstlisting} +struct virtio_net_stats_tx_basic { + struct virtio_net_stats_reply_hdr hdr; + + le64 tx_notifications; + + le64 tx_packets; + le64 tx_bytes; + + le64 tx_interrupts; + + le64 tx_drops; + le64 tx_drop_malformed; +}; +\end{lstlisting} + +The packets described below are all for a specific virtqueue. +\begin{description} + \item [tx_notifications] + The number of driver notifications received by the device for this + transmitq. + + \item [tx_packets] + This is the number of packets sent by the device (not the packets + got from the driver). + + \item [tx_bytes] + This is the number of bytes sent by the device for all the sent packets + (not the bytes sent got from the driver). + + \item [tx_interrupts] + The number of interrupts generated by the device for this transmitq. + + \item [tx_drops] + The number of packets dropped by the device. The count includes all + types of packets dropped by the device. + + \item [tx_drop_malformed] + The number of packets dropped by the device, when the descriptors are + malformed. For example, the buffer is too short. +\end{description} + +\subparagraph{Receiveq CSUM Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Receiveq CSUM Statistics} + +The structure corresponding to the receiveq checksum statistics is +\field{struct virtio_net_stats_rx_csum}. The corresponding type is +VIRTIO_NET_STATS_TYPE_RX_CSUM. This is for the receiveq. + +Only after the VIRTIO_NET_F_GUEST_CSUM is negotiated, the receiveq checksum +statistics can be obtained. + +\begin{lstlisting} +struct virtio_net_stats_rx_csum { + struct virtio_net_stats_reply_hdr hdr; + + le64 rx_csum_valid; + le64 rx_needs_csum; + le64 rx_csum_none; + le64 rx_csum_bad; +}; +\end{lstlisting} + +The packets described below were all presented on the specified virtqueue. +\begin{description} + \item [rx_csum_valid] + The number of packets with VIRTIO_NET_HDR_F_DATA_VALID. + + \item [rx_needs_csum] + The number of packets with VIRTIO_NET_HDR_F_NEEDS_CSUM. + + \item [rx_csum_none] + The number of packets without hardware checksum. The packet here refers + to the non-TCP/UDP packet that the device cannot recognize. + + \item [rx_csum_bad] + The number of packets with checksum mismatch. + +\end{description} + +\subparagraph{Transmitq CSUM Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Transmitq CSUM Statistics} + +The structure corresponding to the transmitq checksum statistics is +\field{struct virtio_net_stats_tx_csum}. The corresponding type is +VIRTIO_NET_STATS_TYPE_TX_CSUM. This is for the transmitq. + +Only after the VIRTIO_NET_F_CSUM is negotiated, the transmitq checksum +statistics can be obtained. + +The following are the transmitq checksum statistics: + +\begin{lstlisting} +struct virtio_net_stats_tx_csum { + struct virtio_net_stats_reply_hdr hdr; + + le64 tx_csum_none; + le64 tx_needs_csum; +}; +\end{lstlisting} + +The packets described below are all for a specific virtqueue. +\begin{description} + \item [tx_csum_none] + The number of packets which do not require hardware checksum. + + \item [tx_needs_csum] + The number of packets which require checksum calculation by the device. + +\end{description} + +\subparagraph{Receiveq GSO Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Receiveq GSO Statistics} + +The structure corresponding to the receivq GSO statistics is +\field{struct virtio_net_stats_rx_gso}. The corresponding type is +VIRTIO_NET_STATS_TYPE_RX_GSO. This is for the receiveq. + +If one or more of the VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6 +have been negotiated, the receiveq GSO statistics can be obtained. + +GSO packets refer to packets passed by the device to the driver where +\field{gso_type} is not VIRTIO_NET_HDR_GSO_NONE. + +\begin{lstlisting} +struct virtio_net_stats_rx_gso { + struct virtio_net_stats_reply_hdr hdr; + + le64 rx_gso_packets; + le64 rx_gso_bytes; + le64 rx_gso_packets_coalesced; + le64 rx_gso_bytes_coalesced; +}; +\end{lstlisting} + +The packets described below were all presented on the specified virtqueue. +\begin{description} + \item [rx_gso_packets] + The number of the GSO packets received by the device. + + \item [rx_gso_bytes] + The bytes of the GSO packets received by the device. + This includes the header size of the GSO packet. + + \item [rx_gso_packets_coalesced] + The number of the GSO packets coalesced by the device. + + \item [rx_gso_bytes_coalesced] + The bytes of the GSO packets coalesced by the device. + This includes the header size of the GSO packet. +\end{description} + +\subparagraph{Transmitq GSO Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Transmitq GSO Statistics} + +The structure corresponding to the transmitq GSO statistics is +\field{struct virtio_net_stats_tx_gso}. The corresponding type is +VIRTIO_NET_STATS_TYPE_TX_GSO. This is for the transmitq. + +If one or more of the VIRTIO_NET_F_HOST_TSO4, VIRTIO_NET_F_HOST_TSO6, +VIRTIO_NET_F_HOST_USO options have been negotiated, the transmitq GSO statistics +can be obtained. + +GSO packets refer to packets passed by the driver to the device where +\field{gso_type} is not VIRTIO_NET_HDR_GSO_NONE. +See more \ref{sec:Device Types / Network Device / Device Operation / Packet +Transmission}. + +\begin{lstlisting} +struct virtio_net_stats_tx_gso { + struct virtio_net_stats_reply_hdr hdr; + + le64 tx_gso_packets; + le64 tx_gso_bytes; + le64 tx_gso_segments; + le64 tx_gso_segments_bytes; + le64 tx_gso_packets_noseg; + le64 tx_gso_bytes_noseg; +}; +\end{lstlisting} + +The packets described below are all for a specific virtqueue. +\begin{description} + \item [tx_gso_packets] + The number of the GSO packets sent by the device. + + \item [tx_gso_bytes] + The bytes of the GSO packets sent by the device. + + \item [tx_gso_segments] + The number of segments prepared from GSO packets. + + \item [tx_gso_segments_bytes] + The bytes of segments prepared from GSO packets. + + \item [tx_gso_packets_noseg] + The number of the GSO packets without segmentation. + + \item [tx_gso_bytes_noseg] + The bytes of the GSO packets without segmentation. + +\end{description} + +\subparagraph{Receiveq Speed Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Receiveq Speed Statistics} + +The structure corresponding to the receiveq speed statistics is +\field{struct virtio_net_stats_rx_speed}. The corresponding type is +VIRTIO_NET_STATS_TYPE_RX_SPEED. This is for the receiveq. + +The device has the allowance for the speed. If VIRTIO_NET_F_SPEED_DUPLEX has +been negotiated, the driver can get this by \field{speed}. When the received +packets bitrate exceeds the \field{speed}, some packets may be dropped by the +device. + +\begin{lstlisting} +struct virtio_net_stats_rx_speed { + struct virtio_net_stats_reply_hdr hdr; + + le64 rx_packets_allowance_exceeded; + le64 rx_bytes_allowance_exceeded; +}; +\end{lstlisting} + +The packets described below were all presented on the specified virtqueue. +\begin{description} + \item [rx_packets_allowance_exceeded] + The number of the packets dropped by the device due to the received + packets bitrate exceeding the \field{speed}. + + \item [rx_bytes_allowance_exceeded] + The bytes of the packets dropped by the device due to the received + packets bitrate exceeding the \field{speed}. + +\end{description} + +\subparagraph{Transmitq Speed Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Transmitq Speed Statistics} + +The structure corresponding to the transmitq speed statistics is +\field{struct virtio_net_stats_tx_speed}. The corresponding type is +VIRTIO_NET_STATS_TYPE_TX_SPEED. This is for the transmitq. + +The device has the allowance for the speed. If VIRTIO_NET_F_SPEED_DUPLEX has +been negotiated, the driver can get this by \field{speed}. When the transmit +packets bitrate exceeds the \field{speed}, some packets may be dropped by the +device. + +\begin{lstlisting} +struct virtio_net_stats_tx_speed { + struct virtio_net_stats_reply_hdr hdr; + + le64 tx_packets_allowance_exceeded; + le64 tx_bytes_allowance_exceeded; +}; +\end{lstlisting} + +The packets described below were all presented on the specified virtqueue. +\begin{description} + \item [tx_packets_allowance_exceeded] + The number of the packets dropped by the device due to the transmit packets + bitrate exceeding the \field{speed}. + + \item [tx_bytes_allowance_exceeded] + The bytes of the packets dropped by the device due to the transmit packets + bitrate exceeding the \field{speed}. + +\end{description} + +\devicenormative{\subparagraph}{Device Statistics}{Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics} + +When the VIRTIO_NET_F_DEVICE_STATS feature is negotiated, the device MUST reply +to the command VIRTIO_NET_CTRL_STATS_QUERY with the +\field{struct virtio_net_stats_capabilities}. \field{supported_stats_types} +includes all the statistic types supported by the device. + +If \field{struct virtio_net_ctrl_queue_stats} is incorrect (such as the +following), the device MUST set \field{ack} to VIRTIO_NET_ERR. Even if there is +only one error, the device MUST fail the entire command. +\begin{itemize} + \item \field{vq_index} exceeds the queue range. + \item \field{types_bitmap} contains unknown types. + \item One or more of the bits present in \field{types_bitmap} is not valid + for the specified virtqueue. + \item The feature corresponding to the specified \field{types_bitmap} was + not negotiated. +\end{itemize} + +The device MUST set the actual size of the bytes occupied by the reply to the +\field{size} of the \field{hdr}. And the device MUST set the \field{type} and +the \field{vq_index} of the statistic header. + +The \field{command-specific-result} buffer allocated by the driver may be +smaller or bigger than all the statistics specified by +\field{struct virtio_net_ctrl_queue_stats}. The device MUST fill up only upto +the valid bytes. + +The statistics counter replied by the device MUST wrap around to zero by the +device on the overflow. + +\drivernormative{\subparagraph}{Device Statistics}{Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics} + +The types contained in the \field{types_bitmap} MUST be queried from the device +via command VIRTIO_NET_CTRL_STATS_QUERY. + +\field{types_bitmap} in \field{struct virtio_net_ctrl_queue_stats} MUST be valid to the +vq specified by \field{vq_index}. + +The \field{command-specific-result} buffer allocated by the driver MUST have +enough capacity to store all the statistics reply headers defined in +\field{struct virtio_net_ctrl_queue_stats}. If the +\field{command-specific-result} buffer is fully utilized by the device but some +replies are missed, it is possible that some statistics may exceed the capacity +of the driver's records. In such cases, the driver should allocate additional +space for the \field{command-specific-result} buffer. + \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device Types / Network Device / Legacy Interface: Framing Requirements} diff --git a/device-types/net/device-conformance.tex b/device-types/net/device-conformance.tex index f88f48b..52526e4 100644 --- a/device-types/net/device-conformance.tex +++ b/device-types/net/device-conformance.tex @@ -15,4 +15,5 @@ \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) / RSS processing} \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing} \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Inner Header Hash} +\item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics} \end{itemize} diff --git a/device-types/net/driver-conformance.tex b/device-types/net/driver-conformance.tex index 9d853d9..c693c4f 100644 --- a/device-types/net/driver-conformance.tex +++ b/device-types/net/driver-conformance.tex @@ -15,4 +15,5 @@ \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) } \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing} \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Inner Header Hash} +\item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics} \end{itemize} From 925b42e3f72fdd113a5e4cc219b739c2c74dba23 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Fri, 27 Oct 2023 16:32:36 +0300 Subject: [PATCH 03/62] conformance: Add missing virtqueue reset conformance references Add the missing references to the virtqueue reset related conformance requirements. Signed-off-by: Parav Pandit Reviewed-by: Xuan Zhuo [CH: pushed as an editorial change] Signed-off-by: Cornelia Huck --- conformance.tex | 2 ++ 1 file changed, 2 insertions(+) diff --git a/conformance.tex b/conformance.tex index dc00e84..863f9c5 100644 --- a/conformance.tex +++ b/conformance.tex @@ -76,6 +76,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item \ref{drivernormative:Basic Facilities of a Virtio Device / Device Reset} \item \ref{drivernormative:Basic Facilities of a Virtio Device / Device Configuration Space} \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues} +\item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset / Virtqueue Reset} \item \ref{drivernormative:Basic Facilities of a Virtio Device / Message Framing} \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table} \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors} @@ -162,6 +163,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Feature Bits} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Device Reset} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Device Configuration Space} +\item \ref{devicenormative:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset / Virtqueue Reset} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Message Framing} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors} From 68d5cc4fe4081a49235885005647b095b7965c0b Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Sun, 29 Oct 2023 16:04:37 +0200 Subject: [PATCH 04/62] packed-ring: Change host,guest to device,driver Rest of the packed ring description already uses the device and driver terminology. Change the introductory line as well from host and guest to device and driver respectively. Signed-off-by: Parav Pandit Acked-by: Michael S. Tsirkin [CH: pushed as an editorial update] Signed-off-by: Cornelia Huck --- packed-ring.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packed-ring.tex b/packed-ring.tex index 9eeb382..2bb66de 100644 --- a/packed-ring.tex +++ b/packed-ring.tex @@ -2,7 +2,7 @@ \section{Packed Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Pack Packed virtqueues is an alternative compact virtqueue layout using read-write memory, that is memory that is both read and written -by both host and guest. +by both the device and the driver. Use of packed virtqueues is negotiated by the VIRTIO_F_RING_PACKED feature bit. From c8249d73d2fdbbfd38e8bf45c8492057bc2485e9 Mon Sep 17 00:00:00 2001 From: Cornelia Huck Date: Mon, 30 Oct 2023 14:42:05 +0100 Subject: [PATCH 05/62] editorial: allow for longer device id table Move to "longtable" to allow the table to span multiple pages (it became too long to fit on one page with the latest addition.) Signed-off-by: Cornelia Huck --- content.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content.tex b/content.tex index 644aa4a..98b9c31 100644 --- a/content.tex +++ b/content.tex @@ -649,7 +649,7 @@ \chapter{Device Types}\label{sec:Device Types} Discovering what devices are available and their type is bus-dependent. -\begin{tabular} { |l|c| } +\begin{longtable} { |l|c| } \hline Device ID & Virtio Device \\ \hline \hline @@ -741,7 +741,7 @@ \chapter{Device Types}\label{sec:Device Types} \hline 46 & TEE device \\ \hline -\end{tabular} +\end{longtable} Some of the devices above are unspecified by this document, because they are seen as immature or especially niche. Be warned From 4cb03b12dc951f0152cd2cd9c79b24492e174e43 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Sun, 29 Oct 2023 16:16:15 +0200 Subject: [PATCH 06/62] description: Avoid splitting the word virtqueue Don't split the word virtqueue. Signed-off-by: Parav Pandit [CH: applied as editorial] Signed-off-by: Cornelia Huck --- device-types/gpu/description.tex | 2 +- packed-ring.tex | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/device-types/gpu/description.tex b/device-types/gpu/description.tex index 4435248..66e4873 100644 --- a/device-types/gpu/description.tex +++ b/device-types/gpu/description.tex @@ -190,7 +190,7 @@ \subsubsection{Device Operation: Configure mouse cursor} \subsubsection{Device Operation: Request header}\label{sec:Device Types / GPU Device / Device Operation / Device Operation: Request header} -All requests and responses on the virt queues have a fixed header +All requests and responses on the virtqueues have a fixed header using the following layout structure and definitions: \begin{lstlisting} diff --git a/packed-ring.tex b/packed-ring.tex index 2bb66de..3ee55a1 100644 --- a/packed-ring.tex +++ b/packed-ring.tex @@ -194,7 +194,7 @@ \subsection{Scatter-Gather Support} The device limits the number of descriptors in a list through a transport-specific and/or device-specific value. If not limited, -the maximum number of descriptors in a list is the virt queue +the maximum number of descriptors in a list is the virtqueue size. \subsection{Next Flag: Descriptor Chaining} From 878a5e7287d77470e7345183cd31efdaa044aa2c Mon Sep 17 00:00:00 2001 From: Shujun Xue Date: Tue, 23 Jan 2024 09:32:01 -0800 Subject: [PATCH 07/62] Define the DEVICE ID of Virtio Cpu balloon device as 47. The Virtio CPU balloon device is a primitive device for managing guest CPU capacity: the device asks for certain CPU cores to be online, offline or throttled, and the driver performs the requested operation. This allows the guest to adapt to changes in allowance of underlying CPU capacity. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/187 Signed-off-by: Shujun Xue Signed-off-by: Cornelia Huck --- content.tex | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content.tex b/content.tex index 98b9c31..e964c41 100644 --- a/content.tex +++ b/content.tex @@ -741,6 +741,8 @@ \chapter{Device Types}\label{sec:Device Types} \hline 46 & TEE device \\ \hline +47 & CPU balloon device \\ +\hline \end{longtable} Some of the devices above are unspecified by this document, From 07bb9f7f642df2ea9ef93ac3e834077038020a1d Mon Sep 17 00:00:00 2001 From: Harald Mommer Date: Fri, 9 Jun 2023 16:22:43 +0200 Subject: [PATCH 08/62] virtio-can: Device specification. virtio-can is a virtual CAN device. It provides a way to give access to a CAN controller from a driver guest. The device is aimed to be used by driver guests running a HLOS as well as by driver guests running a typical RTOS as used in controller environments. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/186 Signed-off-by: Harald Mommer Signed-off-by: Mikhail Golubev-Ciuchea Signed-off-by: Cornelia Huck --- conformance.tex | 12 +- content.tex | 1 + device-types/can/description.tex | 249 ++++++++++++++++++++++++ device-types/can/device-conformance.tex | 8 + device-types/can/driver-conformance.tex | 7 + introduction.tex | 2 + 6 files changed, 275 insertions(+), 4 deletions(-) create mode 100644 device-types/can/description.tex create mode 100644 device-types/can/device-conformance.tex create mode 100644 device-types/can/driver-conformance.tex diff --git a/conformance.tex b/conformance.tex index 863f9c5..ce54456 100644 --- a/conformance.tex +++ b/conformance.tex @@ -32,8 +32,9 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \ref{sec:Conformance / Driver Conformance / Memory Driver Conformance}, \ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance}, \ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance}, -\ref{sec:Conformance / Driver Conformance / GPIO Driver Conformance} or -\ref{sec:Conformance / Driver Conformance / PMEM Driver Conformance}. +\ref{sec:Conformance / Driver Conformance / GPIO Driver Conformance}, +\ref{sec:Conformance / Driver Conformance / PMEM Driver Conformance} or +\ref{sec:Conformance / Driver Conformance / CAN Driver Conformance}. \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}. \end{itemize} @@ -59,8 +60,9 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \ref{sec:Conformance / Device Conformance / Memory Device Conformance}, \ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance}, \ref{sec:Conformance / Device Conformance / SCMI Device Conformance}, -\ref{sec:Conformance / Device Conformance / GPIO Device Conformance} or -\ref{sec:Conformance / Device Conformance / PMEM Device Conformance}. +\ref{sec:Conformance / Device Conformance / GPIO Device Conformance}, +\ref{sec:Conformance / Device Conformance / PMEM Device Conformance} or +\ref{sec:Conformance / Device Conformance / CAN Device Conformance}. \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}. \end{itemize} @@ -153,6 +155,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \input{device-types/scmi/driver-conformance.tex} \input{device-types/gpio/driver-conformance.tex} \input{device-types/pmem/driver-conformance.tex} +\input{device-types/can/driver-conformance.tex} \conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance} @@ -240,6 +243,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \input{device-types/scmi/device-conformance.tex} \input{device-types/gpio/device-conformance.tex} \input{device-types/pmem/device-conformance.tex} +\input{device-types/can/device-conformance.tex} \conformance{\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance} A conformant implementation MUST be either transitional or diff --git a/content.tex b/content.tex index e964c41..42e907d 100644 --- a/content.tex +++ b/content.tex @@ -771,6 +771,7 @@ \chapter{Device Types}\label{sec:Device Types} \input{device-types/scmi/description.tex} \input{device-types/gpio/description.tex} \input{device-types/pmem/description.tex} +\input{device-types/can/description.tex} \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits} diff --git a/device-types/can/description.tex b/device-types/can/description.tex new file mode 100644 index 0000000..2511d9c --- /dev/null +++ b/device-types/can/description.tex @@ -0,0 +1,249 @@ +\section{CAN Device}\label{sec:Device Types / CAN Device} + +virtio-can is a virtio based CAN (Controller Area Network) controller. +It is used to give a virtual machine access to a CAN bus. The CAN bus +might either be a physical CAN bus or a virtual CAN bus between virtual +machines or a combination of both. + +\subsection{Device ID}\label{sec:Device Types / CAN Device / Device ID} + +36 + +\subsection{Virtqueues}\label{sec:Device Types / CAN Device / Virtqueues} + +\begin{description} +\item[0] Txq +\item[1] Rxq +\item[2] Controlq +\end{description} + +The \field{Txq} is used to send CAN packets to the CAN bus. + +The \field{Rxq} is used to receive CAN packets from the CAN bus. + +The \field{Controlq} is used to control the state of the CAN controller. + +\subsection{Feature bits}{Device Types / CAN Device / Feature bits} + +Actual CAN controllers support Extended CAN IDs with 29 bits (CAN~2.0B) +as well as Standard CAN IDs with 11 bits (CAN~2.0A). The support of +CAN~2.0B Extended CAN IDs is considered as mandatory for this +specification. + +\begin{description} + +\item[VIRTIO_CAN_F_CAN_CLASSIC (0)] + +The device supports classic CAN frames with a maximum payload size of 8 +bytes. + +\item[VIRTIO_CAN_F_CAN_FD (1)] + +The device supports CAN FD frames with a maximum payload size of 64 +bytes. + +\item[VIRTIO_CAN_F_RTR_FRAMES (2)] + +The device supports RTR (remote transmission request) frames. RTR frames +are only supported with classic CAN. + +\item[VIRTIO_CAN_F_LATE_TX_ACK (3)] + +The virtio CAN device marks transmission requests from the \field{Txq} +as used after the CAN message has been transmitted on the CAN bus. If +this feature bit has not been negotiated, the device is allowed to mark +transmission requests already as used when the CAN message has been +scheduled for transmission but might not yet have been transmitted on +the CAN bus. + +\end{description} + +\subsubsection{Feature bit requirements}\label{sec:Device Types / CAN Device / Feature bits / Feature bit requirements} + +Some CAN feature bits require other CAN feature bits: +\begin{description} +\item[VIRTIO_CAN_F_RTR_FRAMES] Requires VIRTIO_CAN_F_CAN_CLASSIC. +\end{description} + +It is required that at least one of VIRTIO_CAN_F_CAN_CLASSIC and +VIRTIO_CAN_F_CAN_FD is negotiated. + +\subsection{Device configuration layout}\label{sec:Device Types / CAN Device / Device configuration layout} + +Device configuration fields are listed below, they are read-only for a +driver. The \field{status} always exists. A single read-only bit (for +the driver) is currently defined for \field{status}: + +\begin{lstlisting} +struct virtio_can_config { +#define VIRTIO_CAN_S_CTRL_BUSOFF (1 << 0) + le16 status; +}; +\end{lstlisting} + +The bit VIRTIO_CAN_S_CTRL_BUSOFF in \field{status} is used to indicate +the unsolicited CAN controller state change from started to stopped due +to a detected bus off condition. + +\drivernormative{\subsubsection}{Device Initialization}{Device Types / CAN Device / Device Operation / Initialization} + +The driver MUST populate the \field{Rxq} with empty device-writeable +buffers of at least the size of struct virtio_can_rx, see section +\ref{struct virtio_can_rx}. + +\subsection{Device Operation}\label{sec:Device Types / CAN Device / Device Operation} + +A device operation has an outcome which is described by one of the +following values: + +\begin{lstlisting} +#define VIRTIO_CAN_RESULT_OK 0 +#define VIRTIO_CAN_RESULT_NOT_OK 1 +\end{lstlisting} + +Other values are to be treated like VIRTIO_CAN_RESULT_NOT_OK. + +\subsubsection{Controller Mode}\label{sec:Device Types / CAN Device / Device Operation / Controller Mode} + +The general format of a request in the \field{Controlq} is + +\begin{lstlisting} +struct virtio_can_control_out { +#define VIRTIO_CAN_SET_CTRL_MODE_START 0x0201 +#define VIRTIO_CAN_SET_CTRL_MODE_STOP 0x0202 + le16 msg_type; +}; +\end{lstlisting} + +To participate in bus communication the CAN controller is started by +sending a VIRTIO_CAN_SET_CTRL_MODE_START control message, to stop +participating in bus communication it is stopped by sending a +VIRTIO_CAN_SET_CTRL_MODE_STOP control message. Both requests are +confirmed by the result of the operation. + +\begin{lstlisting} +struct virtio_can_control_in { + u8 result; +}; +\end{lstlisting} + +If the transition succeeded the \field{result} is VIRTIO_CAN_RESULT_OK +otherwise it is VIRTIO_CAN_RESULT_NOT_OK. If a status update is +necessary, the device updates the configuration \field{status} before +marking the request used. As the configuration \field{status} change is +caused by a request from the driver the device is allowed to omit the +configuration change notification here. The device marks the request +used when the CAN controller has finalized the transition to the +requested controller mode. + +On transition to the STOPPED state the device cancels all CAN messages +already pending for transmission and marks them as used with +\field{result} VIRTIO_CAN_RESULT_NOT_OK. In the STOPPED state the +device marks messages received from the +\field{Txq} as used with \field{result} VIRTIO_CAN_RESULT_NOT_OK without +transmitting them to the CAN bus. + +Initially the CAN controller is in the STOPPED state. + +Control queue messages are processed in order. + +\devicenormative{\subsubsection}{CAN Message Transmission}{Device Types / CAN Device / Device Operation / CAN Message Transmission} + +The driver transmits messages by placing outgoing CAN messages in the +\field{Txq} virtqueue. + +\label{struct virtio_can_tx_out} +\begin{lstlisting} +struct virtio_can_tx_out { +#define VIRTIO_CAN_TX 0x0001 + le16 msg_type; + le16 length; /* 0..8 CC, 0..64 CAN-FD, 0..2048 CAN-XL, 12 bits */ + u8 reserved_classic_dlc; /* If CAN classic length = 8 then DLC can be 8..15 */ + u8 padding; + le16 reserved_xl_priority; /* May be needed for CAN XL priority */ +#define VIRTIO_CAN_FLAGS_FD 0x4000 +#define VIRTIO_CAN_FLAGS_EXTENDED 0x8000 +#define VIRTIO_CAN_FLAGS_RTR 0x2000 + le32 flags; + le32 can_id; + u8 sdu[]; +}; + +struct virtio_can_tx_in { + u8 result; +}; +\end{lstlisting} + +The length of the \field{sdu} is determined by the \field{length}. + +The type of a CAN message identifier is determined by \field{flags}. The +3 most significant bits of \field{can_id} do not bear the information +about the type of the CAN message identifier and are 0. + +The device MUST reject any CAN frame type for which support has not been +negotiated with VIRTIO_CAN_RESULT_NOT_OK in \field{result} and MUST NOT +schedule the message for transmission. A CAN frame with an undefined bit +set in \field{flags} is treated like a CAN frame for which support has +not been negotiated. + +The device MUST reject any CAN frame for which \field{can_id} or +\field{sdu} length are out of range or the CAN controller is in an +invalid state with VIRTIO_CAN_RESULT_NOT_OK in \field{result} and MUST +NOT schedule the message for transmission. + +If the parameters are valid the message is scheduled for transmission. + +If feature VIRTIO_CAN_F_CAN_LATE_TX_ACK has been negotiated the +transmission request MUST be marked as used with \field{result} set to +VIRTIO_CAN_OK after the CAN controller acknowledged the successful +transmission on the CAN bus. If this feature bit has not been negotiated +the transmission request MAY already be marked as used with +\field{result} set to VIRTIO_CAN_OK when the transmission request has +been processed by the virtio CAN device and send down the protocol stack +being scheduled for transmission. + +\subsubsection{CAN Message Reception}\label{sec:Device Types / CAN Device / Device Operation / CAN Message Reception} + +Messages can be received by providing empty incoming buffers to the +virtqueue \field{Rxq}. + +\label{struct virtio_can_rx} +\begin{lstlisting} +struct virtio_can_rx { +#define VIRTIO_CAN_RX 0x0101 + le16 msg_type; + le16 length; /* 0..8 CC, 0..64 CAN-FD, 0..2048 CAN-XL, 12 bits */ + u8 reserved_classic_dlc; /* If CAN classic length = 8 then DLC can be 8..15 */ + u8 padding; + le16 reserved_xl_priority; /* May be needed for CAN XL priority */ + le32 flags; + le32 can_id; + u8 sdu[]; +}; +\end{lstlisting} + +If the feature VIRTIO_CAN_F_CAN_FD has been negotiated the maximal +possible \field{sdu} length is 64, if the feature has not been +negotiated the maximal possible \field{sdu} length is 8. + +The actual length of the \field{sdu} is determined by the \field{length}. + +The type of a CAN message identifier is determined by \field{flags} in +the same way as for transmitted CAN messages, see section \ref{struct +virtio_can_tx_out}. The 3 most significant bits of \field{can_id} do not +bear the information about the type of the CAN message identifier and +are 0. The flag bits are exactly the same as for the \field{flags} of +struct virtio_can_tx_out. + +\subsubsection{BusOff Indication}\label{sec:Device Types / CAN Device / Device Operation / BusOff Indication} + +There are certain error conditions so that the physical CAN controller +has to stop participating in CAN communication on the bus. If such an +error condition occurs the device informs the driver about the +unsolicited CAN controller state change by setting the +VIRTIO_CAN_S_CTRL_BUSOFF bit in the configuration \field{status} field. + +After bus-off detection the CAN controller is in STOPPED state. The CAN +controller does not participate in bus communication any more so all CAN +messages pending for transmission are put into the used queue with +\field{result} VIRTIO_CAN_RESULT_NOT_OK. diff --git a/device-types/can/device-conformance.tex b/device-types/can/device-conformance.tex new file mode 100644 index 0000000..f944ffd --- /dev/null +++ b/device-types/can/device-conformance.tex @@ -0,0 +1,8 @@ +\conformance{\subsection}{CAN Device Conformance}\label{sec:Conformance / Device Conformance / CAN Device Conformance} + +A CAN device MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{devicenormative:Device Types / CAN Device / Feature bits} +\item \ref{devicenormative:Device Types / CAN Device / Device Operation / CAN Message Transmission} +\end{itemize} diff --git a/device-types/can/driver-conformance.tex b/device-types/can/driver-conformance.tex new file mode 100644 index 0000000..32e3e87 --- /dev/null +++ b/device-types/can/driver-conformance.tex @@ -0,0 +1,7 @@ +\conformance{\subsection}{CAN Driver Conformance}\label{sec:Conformance / Driver Conformance / CAN Driver Conformance} + +A CAN driver MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{drivernormative:Device Types / CAN Device / Device Operation / Initialization} +\end{itemize} diff --git a/introduction.tex b/introduction.tex index 1e39a4b..8bcef03 100644 --- a/introduction.tex +++ b/introduction.tex @@ -141,6 +141,8 @@ \section{Normative References}\label{sec:Normative References} \phantomsection\label{intro:TCP}\textbf{[TCP]} & TRANSMISSION CONTROL PROTOCOL \newline\url{https://www.rfc-editor.org/rfc/rfc793}\\ + \phantomsection\label{intro:CAN}\textbf{[CAN]} & + ISO 11898-1:2015 Road vehicles -- Controller area network (CAN) -- Part 1: Data link layer and physical signalling\\ \end{longtable} \section{Non-Normative References} From 193daee1d7a3b3f985664894f489b4d52149941a Mon Sep 17 00:00:00 2001 From: Heng Qi Date: Tue, 7 Nov 2023 14:29:37 +0800 Subject: [PATCH 09/62] virtio-net: support the RSS context Commit 84a1d9c48200 ("net: ethtool: extend RXNFC API to support RSS spreading of filter matches") adds support for RSS context as a destination for receive flow filters (see WIP work: https://lists.oasis-open.org/archives/virtio-comment/202308/msg00194.html). An RSS context consists of configurable parameters specified by receive-side scaling. Some use cases: 1. When users want some data flows to be steered to specific multiple rxqs, they can set receive flow filter rules for these data flows to an RSS context with desired rxqs. 2. Traffic isolation. Used when users want the traffic of certain applications to occupy several queues without being distubed. How to set/configure an RSS context: Assuming no RSS context has been created before. 1. ethtool -X eth0 context new start 5 equal 8 This command creates an RSS context with an id=1 for eth0, and fills in the indirection table with rxq indexes 5-8 circularly. The hash key and hash types reuse the default RSS configuration. Then, we can use 'ethtool -x eth0 context 1' to query the above configuration. 2. ethtool -X eth0 context new start 6 equal 7 \ hkey 8f:bf:dd:11:23:58:d2:8a:00:31:d0:32:a3:b5:1f:\ 1f:e4:d1:fe:47:7f:64:42:fd:d0:61:16:b8:b0:f9:71:e8:2d:36:7f:18:dd:4d:c8:f3 This command creates an RSS context with an id=2 for eth0, and fills in the indirection table with rxq indexes 6-7 circularly. The hash key is 8f:bf:dd:11:23:58:d2:8a:00:31:d0\ :32:a3:b5:1f:1f:e4:d1:fe:47:7f:64:42:fd:d0:61:16:b8:b0:f9:71:e8:2d:36:7f:18:dd:4d:c8:f3. Hash types reuse the default RSS configuration. 3. ethtool -N eth0 rx-flow-hash tcp4 sdfn context 1 This command specifies the hash types for the RSS context whose id=1 on eth0. Now this RSS context only has the hash key to reuse the default RSS configuration. 4. ethtool -N eth0 flow-type udp4 src-ip 1.1.1.1 context 1 This command configures a receive flow filter rule for eth0, and the data flow matching this rule will continue to select the final rxq according to the RSS context configuration with id=1. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/178 Signed-off-by: Heng Qi Signed-off-by: Parav Pandit Acked-by: Satananda Burla Acked-by: Xuan Zhuo Signed-off-by: Cornelia Huck --- device-types/net/description.tex | 85 +++++++++++++++++++++++++ device-types/net/device-conformance.tex | 1 + device-types/net/driver-conformance.tex | 1 + 3 files changed, 87 insertions(+) diff --git a/device-types/net/description.tex b/device-types/net/description.tex index aff5e08..61cce1f 100644 --- a/device-types/net/description.tex +++ b/device-types/net/description.tex @@ -122,6 +122,8 @@ \subsection{Feature bits}\label{sec:Device Types / Network Device / Feature bits device with the same MAC address. \item[VIRTIO_NET_F_SPEED_DUPLEX(63)] Device reports speed and duplex. + +\item[VIRTIO_NET_F_RSS_CONTEXT(64)] Device supports multiple RSS contexts. \end{description} \subsubsection{Feature bit requirements}\label{sec:Device Types / Network Device / Feature bits / Feature bit requirements} @@ -153,6 +155,7 @@ \subsubsection{Feature bit requirements}\label{sec:Device Types / Network Device \item[VIRTIO_NET_F_RSS] Requires VIRTIO_NET_F_CTRL_VQ. \item[VIRTIO_NET_F_VQ_NOTF_COAL] Requires VIRTIO_NET_F_CTRL_VQ. \item[VIRTIO_NET_F_HASH_TUNNEL] Requires VIRTIO_NET_F_CTRL_VQ along with VIRTIO_NET_F_RSS or VIRTIO_NET_F_HASH_REPORT. +\item[VIRTIO_NET_F_RSS_CONTEXT] Requires VIRTIO_NET_F_CTRL_VQ and VIRTIO_NET_F_RSS. \end{description} \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network Device / Feature bits / Legacy Interface: Feature bits} @@ -1613,6 +1616,88 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi \item If the destination receive queue is being reset (See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}), the device MUST drop the packet. \end{itemize} +\paragraph{RSS Context}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / RSS Context} + +An RSS context consists of configurable parameters specified by \ref{sec:Device Types / Network Device +/ Device Operation / Control Virtqueue / Receive-side scaling (RSS)}. + +The RSS configuration supported by VIRTIO_NET_F_RSS is considered the default RSS configuration. + +The device offers the feature VIRTIO_NET_F_RSS_CONTEXT if it supports one or multiple RSS contexts +(excluding the default RSS configuration) and configurable parameters. + +\subparagraph{Querying RSS Context Capability}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / RSS Context / Querying RSS Context Capability} + +\begin{lstlisting} +#define VIRTNET_RSS_CTX_CTRL 9 + #define VIRTNET_RSS_CTX_CTRL_CAP_GET 0 + #define VIRTNET_RSS_CTX_CTRL_ADD 1 + #define VIRTNET_RSS_CTX_CTRL_MOD 2 + #define VIRTNET_RSS_CTX_CTRL_DEL 3 + +struct virtnet_rss_ctx_cap { + le16 max_rss_contexts; +} +\end{lstlisting} + +Field \field{max_rss_contexts} specifies the maximum number of RSS contexts \ref{sec:Device Types / Network Device / +Device Operation / Control Virtqueue / RSS Context} supported by the device. + +The driver queries the RSS context capability of the device by sending the command VIRTNET_RSS_CTX_CTRL_CAP_GET +with the structure virtnet_rss_ctx_cap. + +For the command VIRTNET_RSS_CTX_CTRL_CAP_GET, the structure virtnet_rss_ctx_cap is write-only for the device. + +\subparagraph{Setting RSS Context Parameters}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / RSS Context / Setting RSS Context Parameters} + +\begin{lstlisting} +struct virtnet_rss_ctx_add_modify { + le16 rss_ctx_id; + u8 reserved[6]; + struct virtio_net_rss_config rss; +}; + +struct virtnet_rss_ctx_del { + le16 rss_ctx_id; +}; +\end{lstlisting} + +RSS context parameters: +\begin{itemize} +\item \field{rss_ctx_id}: ID of the specific RSS context. +\item \field{rss}: RSS context parameters of the specific RSS context whose id is \field{rss_ctx_id}. +\end{itemize} + +\field{reserved} is reserved and it is ignored by the device. + +If the feature VIRTIO_NET_F_RSS_CONTEXT has been negotiated, the driver can send the following +VIRTNET_RSS_CTX_CTRL class commands: +\begin{enumerate} +\item VIRTNET_RSS_CTX_CTRL_ADD: use the structure virtnet_rss_ctx_add_modify to + add an RSS context configured as \field{rss} and id as \field{rss_ctx_id} for the device. +\item VIRTNET_RSS_CTX_CTRL_MOD: use the structure virtnet_rss_ctx_add_modify to + configure parameters of the RSS context whose id is \field{rss_ctx_id} as \field{rss} for the device. +\item VIRTNET_RSS_CTX_CTRL_DEL: use the structure virtnet_rss_ctx_del to delete + the RSS context whose id is \field{rss_ctx_id} for the device. +\end{enumerate} + +For commands VIRTNET_RSS_CTX_CTRL_ADD and VIRTNET_RSS_CTX_CTRL_MOD, the structure virtnet_rss_ctx_add_modify is read-only for the device. +For the command VIRTNET_RSS_CTX_CTRL_DEL, the structure virtnet_rss_ctx_del is read-only for the device. + +\devicenormative{\subparagraph}{RSS Context}{Device Types / Network Device / Device Operation / Control Virtqueue / RSS Context} + +The device MUST set \field{max_rss_contexts} to at least 1 if it offers VIRTIO_NET_F_RSS_CONTEXT. + +Upon reset, the device MUST clear all previously configured RSS contexts. + +\drivernormative{\subparagraph}{RSS Context}{Device Types / Network Device / Device Operation / Control Virtqueue / RSS Context} + +The driver MUST have negotiated the VIRTIO_NET_F_RSS_CONTEXT feature when issuing the VIRTNET_RSS_CTX_CTRL class commands. + +The driver MUST set \field{rss_ctx_id} to between 1 and \field{max_rss_contexts} inclusive. + +The driver MUST NOT send the command VIRTIO_NET_CTRL_MQ_VQ_PAIRS_SET when the device has successfully configured at least one RSS context. + \paragraph{Offloads State Configuration}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Offloads State Configuration} If the VIRTIO_NET_F_CTRL_GUEST_OFFLOADS feature is negotiated, the driver can diff --git a/device-types/net/device-conformance.tex b/device-types/net/device-conformance.tex index 52526e4..c71341e 100644 --- a/device-types/net/device-conformance.tex +++ b/device-types/net/device-conformance.tex @@ -16,4 +16,5 @@ \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing} \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Inner Header Hash} \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics} +\item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / RSS Context} \end{itemize} diff --git a/device-types/net/driver-conformance.tex b/device-types/net/driver-conformance.tex index c693c4f..7081ec3 100644 --- a/device-types/net/driver-conformance.tex +++ b/device-types/net/driver-conformance.tex @@ -16,4 +16,5 @@ \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing} \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Inner Header Hash} \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics} +\item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / RSS Context} \end{itemize} From bb11bf9b25cc86c6ff02bf9f243da55b0d383a32 Mon Sep 17 00:00:00 2001 From: Haixu Cui Date: Tue, 2 Jan 2024 15:36:40 +0800 Subject: [PATCH 10/62] content: Rename SPI master to SPI controller SPI master is an outdated term and should use SPI controller. Signed-off-by: Haixu Cui Reviewed-by: Viresh Kumar Signed-off-by: Cornelia Huck --- content.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content.tex b/content.tex index 42e907d..45ac17a 100644 --- a/content.tex +++ b/content.tex @@ -737,7 +737,7 @@ \chapter{Device Types}\label{sec:Device Types} \hline 44 & ISM device \\ \hline -45 & SPI master \\ +45 & SPI controller \\ \hline 46 & TEE device \\ \hline From a402acce814fac0513f14c0e9fc73f97c8ed52df Mon Sep 17 00:00:00 2001 From: Haixu Cui Date: Tue, 2 Jan 2024 15:36:41 +0800 Subject: [PATCH 11/62] virtio-spi: add the device specification The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI controller that allows the driver to operate and use the SPI controller under the control of the host. This patch adds the specification for virtio-spi. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/189 Signed-off-by: Haixu Cui Reviewed-by: Viresh Kumar Signed-off-by: Cornelia Huck --- conformance.tex | 12 +- content.tex | 1 + device-types/spi/description.tex | 286 ++++++++++++++++++++++++ device-types/spi/device-conformance.tex | 7 + device-types/spi/driver-conformance.tex | 7 + 5 files changed, 309 insertions(+), 4 deletions(-) create mode 100644 device-types/spi/description.tex create mode 100644 device-types/spi/device-conformance.tex create mode 100644 device-types/spi/driver-conformance.tex diff --git a/conformance.tex b/conformance.tex index ce54456..183c059 100644 --- a/conformance.tex +++ b/conformance.tex @@ -33,8 +33,9 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance}, \ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance}, \ref{sec:Conformance / Driver Conformance / GPIO Driver Conformance}, -\ref{sec:Conformance / Driver Conformance / PMEM Driver Conformance} or -\ref{sec:Conformance / Driver Conformance / CAN Driver Conformance}. +\ref{sec:Conformance / Driver Conformance / PMEM Driver Conformance}, +\ref{sec:Conformance / Driver Conformance / CAN Driver Conformance} or +\ref{sec:Conformance / Driver Conformance / SPI Controller Driver Conformance}. \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}. \end{itemize} @@ -61,8 +62,9 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance}, \ref{sec:Conformance / Device Conformance / SCMI Device Conformance}, \ref{sec:Conformance / Device Conformance / GPIO Device Conformance}, -\ref{sec:Conformance / Device Conformance / PMEM Device Conformance} or -\ref{sec:Conformance / Device Conformance / CAN Device Conformance}. +\ref{sec:Conformance / Device Conformance / PMEM Device Conformance}, +\ref{sec:Conformance / Device Conformance / CAN Device Conformance} or +\ref{sec:Conformance / Device Conformance / SPI Controller Device Conformance}. \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}. \end{itemize} @@ -156,6 +158,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \input{device-types/gpio/driver-conformance.tex} \input{device-types/pmem/driver-conformance.tex} \input{device-types/can/driver-conformance.tex} +\input{device-types/spi/driver-conformance.tex} \conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance} @@ -244,6 +247,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \input{device-types/gpio/device-conformance.tex} \input{device-types/pmem/device-conformance.tex} \input{device-types/can/device-conformance.tex} +\input{device-types/spi/device-conformance.tex} \conformance{\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance} A conformant implementation MUST be either transitional or diff --git a/content.tex b/content.tex index 45ac17a..d7d544e 100644 --- a/content.tex +++ b/content.tex @@ -772,6 +772,7 @@ \chapter{Device Types}\label{sec:Device Types} \input{device-types/gpio/description.tex} \input{device-types/pmem/description.tex} \input{device-types/can/description.tex} +\input{device-types/spi/description.tex} \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits} diff --git a/device-types/spi/description.tex b/device-types/spi/description.tex new file mode 100644 index 0000000..84fd2c9 --- /dev/null +++ b/device-types/spi/description.tex @@ -0,0 +1,286 @@ +\section{SPI Controller Device}\label{sec:Device Types / SPI Controller Device} + +The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI controller that +allows the driver to operate and use the SPI controller under the control of the host, +either a physical SPI controller, or an emulated one. + +The Virtio SPI device has a single virtqueue. SPI transfer requests are placed into +the virtqueue by the driver, and are serviced by the device. + +In a typical host and guest architecture with the Virtio SPI device, the Virtio SPI driver +is the front-end running in the guest, and the Virtio SPI device is the back-end +in the host. + +\subsection{Device ID}\label{sec:Device Types / SPI Controller Device / Device ID} +45 + +\subsection{Virtqueues}\label{sec:Device Types / SPI Controller Device / Virtqueues} + +\begin{description} +\item[0] requestq +\end{description} + +\subsection{Feature bits}\label{sec:Device Types / SPI Controller Device / Feature bits} + +None + +\subsection{Device configuration layout}\label{sec:Device Types / SPI Controller Device / Device configuration layout} + +All fields of this configuration are mandatory and read-only for the driver. +The config space shows the features and settings supported by the device. + +\begin{lstlisting} +struct virtio_spi_config { + u8 cs_max_number; + u8 cs_change_supported; + u8 tx_nbits_supported; + u8 rx_nbits_supported; + le32 bits_per_word_mask; + le32 mode_func_supported; + le32 max_freq_hz; + le32 max_word_delay_ns; + le32 max_cs_setup_ns; + le32 max_cs_hold_ns; + le32 max_cs_inactive_ns; +}; +\end{lstlisting} + +\field{cs_max_number} is the maximum number of chipselect the device supports. + +Note: chipselect is an electrical signal, which is used to select the SPI peripherals connected +to the controller. + +\field{cs_change_supported} indicates if the device supports to toggle chipselect +after each transfer in one message: + 0: unsupported, chipselect will be kept in active state throughout the message transaction; + 1: supported. + +Note: Message here contains a sequence of SPI transfers. + +\field{tx_nbits_supported} and \field{rx_nbits_supported} indicate the different n-bit transfer +modes supported by the device, for writing and reading respectively. SINGLE is always supported. +A set bit here indicates that the corresponding n-bit transfer is supported, otherwise not: + bit 0: DUAL; + bit 1: QUAD; + bit 2: OCTAL; + other bits are reserved and must be set as 0 by the device. + +Note: The commonly used SPI n-bit transfer options are: +\begin{itemize} +\item SINGLE: 1-bit transfer +\item DUAL: 2-bit transfer +\item QUAD: 4-bit transfer +\item OCTAL: 8-bit transfer +\end{itemize} + +\field{bits_per_word_mask} is a mask indicating which values of bits_per_word are supported. +If bit n of \field{bits_per_word_mask} is set, the bits_per_word with value (n+1) is supported. +If \field{bits_per_word_mask} is 0, there is no limitation for bits_per_word. + +Note: bits_per_word corresponds to \field{bits_per_word} in \field{struct virtio_spi_transfer_head}. + +\field{mode_func_supported} indicates whether the following features are supported or not: + bit 0-1: CPHA feature, + 0b00: invalid, must support as least one CPHA setting. + 0b01: supports CPHA=0 only; + 0b10: supports CPHA=1 only; + 0b11: supports CPHA=0 and CPHA=1; + + bit 2-3: CPOL feature, + 0b00: invalid, must support as least one CPOL setting. + 0b01: supports CPOL=0 only; + 0b10: supports CPOL=1 only; + 0b11: supports CPOL=0 and CPOL=1; + + bit 4: chipselect active high feature, 0 for unsupported and 1 for supported, + chipselect active low must always be supported. + + bit 5: LSB first feature, 0 for unsupported and 1 for supported, MSB first must always be + supported. + + bit 6: loopback mode feature, 0 for unsupported and 1 for supported, normal mode + must always be supported. + +Note: CPOL is clock polarity and CPHA is clock phase. If CPOL is 0, the clock idles at the logical +low voltage, otherwise it idles at the logical high voltage. CPHA determines how data is outputted +and sampled. If CPHA is 0, the first bit is outputted immediately when chipselect is active and +subsequent bits are outputted on the clock edges when the clock transitions from active level to idle +level. Data is sampled on the clock edges when the clock transitions from idle level to active level. +If CPHA is 1, the first bit is outputted on the fist clock edge after chipselect is active, subsequent +bits are outputted on the clock edges when the clock transitions from idle level to active level. +Data is sampled on the clock edges when the clock transitions from active level to idle level. + +Note: LSB first indicates that data is transferred least significant bit first, and MSB first +indicates that data is transferred most significant bit first. + +\field{max_freq_hz} is the maximum clock rate supported in Hz unit, 0 means no limitation +for transfer speed. + +\field{max_word_delay_ns} is the maximum word delay supported in ns unit, 0 means word delay +feature is unsupported. + +Note: Just as one message contains a sequence of transfers, one transfer may contain +a sequence of words. + +\field{max_cs_setup_ns} is the maximum delay supported after chipselect is asserted, in ns unit, +0 means delay is not supported to introduce after chipselect is asserted. + +\field{max_cs_hold_ns} is the maximum delay supported before chipselect is deasserted, in ns unit, +0 means delay is not supported to introduce before chipselect is deasserted. + +\field{max_cs_incative_ns} is the maximum delay supported after chipselect is deasserted, in ns unit, +0 means delay is not supported to introduce after chipselect is deasserted. + +\subsection{Device Initialization}\label{sec:Device Types / SPI Controller Device / Device Initialization} + +\begin{enumerate} +\item The Virtio SPI driver configures and initializes the virtqueue. +\end{enumerate} + +\subsection{Device Operation}\label{sec:Device Types / SPI Controller Device / Device Operation} + +\subsubsection{Device Operation: Request Queue}\label{sec:Device Types / SPI Controller Device / Device Operation: Request Queue} + +The Virtio SPI driver enqueues requests to the virtqueue, and they are used by the Virtio SPI device. +Each request represents one SPI transfer and is of the form: + +\begin{lstlisting} +struct virtio_spi_transfer_head { + u8 chip_select_id; + u8 bits_per_word; + u8 cs_change; + u8 tx_nbits; + u8 rx_nbits; + u8 reserved[3]; + le32 mode; + le32 freq; + le32 word_delay_ns; + le32 cs_setup_ns; + le32 cs_delay_hold_ns; + le32 cs_change_delay_inactive_ns; +}; +\end{lstlisting} + +\begin{lstlisting} +struct virtio_spi_transfer_result { + u8 result; +}; +\end{lstlisting} + +\begin{lstlisting} +struct virtio_spi_transfer_req { + struct virtio_spi_transfer_head head; + u8 tx_buf[]; + u8 rx_buf[]; + struct virtio_spi_transfer_result result; +}; +\end{lstlisting} + +\field{chip_select_id} indicates the chipselect index to use for the SPI transfer. + +\field{bits_per_word} indicates the number of bits in each SPI transfer word. + +\field{cs_change} indicates whether to deselect device before starting the next SPI transfer, +0 means chipselect keep asserted and 1 means chipselect deasserted then asserted again. + +\field{tx_nbits} and \field{rx_nbits} indicate n-bit transfer mode for writing and reading: + 0,1: SINGLE; + 2 : DUAL; + 4 : QUAD; + 8 : OCTAL; + other values are invalid. + +\field{reserved} is currently unused and might be used for further extensions in the future. + +\field{mode} indicates some transfer settings. Bit definitions as follows: + bit 0: CPHA, determines the timing (i.e. phase) of the data bits relative to the + clock pulses. + bit 1: CPOL, determines the polarity of the clock. + bit 2: CS_HIGH, if 1, chipselect active high, else active low. + bit 3: LSB_FIRST, determines per-word bits-on-wire, if 0, MSB first, else LSB first. + bit 4: LOOP, if 1, device is in loopback mode, else normal mode. + +\field{freq} indicates the SPI transfer speed in Hz. + +\field{word_delay_ns} indicates delay to be inserted between consecutive words of a transfer, +in ns unit. + +\field{cs_setup_ns} indicates delay to be introduced after chipselect is asserted, in ns unit. + +\field{cs_delay_hold_ns} indicates delay to be introduced before chipselect is deasserted, +in ns unit. + +\field{cs_change_delay_inactive_ns} indicates delay to be introduced after chipselect is +deasserted and before next asserted, in ns unit. + +\field{tx_buf} is the buffer for data sent to the device. + +\field{rx_buf} is the buffer for data received from the device. + +\field{result} is the transfer result, it may be one of the following values: + +\begin{lstlisting} +#define VIRTIO_SPI_TRANS_OK 0 +#define VIRTIO_SPI_PARAM_ERR 1 +#define VIRTIO_SPI_TRANS_ERR 2 +\end{lstlisting} + +VIRTIO_SPI_TRANS_OK indicates successful completion of the transfer. + +VIRTIO_SPI_PARAM_ERR indicates a parameter error, which means the parameters in +\field{struct virtio_spi_transfer_head} are not all valid, or some fields are set as +non-zero values but the corresponding features are not supported by device. +In particular, for full-duplex transfer, VIRTIO_SPI_PARAM_ERR can also indicate that +\field{tx_buf} and \field{rx_buf} are not of the same length. + +VIRTIO_SPI_TRANS_ERR indicates a transfer error, which means that the parameters are all +valid but the transfer process failed. + +\subsubsection{Device Operation: Operation Status}\label{sec:Device Types / SPI Controller Device / Device Operation: Operation Status} + +Fields in \field{struct virtio_spi_transfer_head} are written by the Virtio SPI driver, while +\field{result} in \field{struct virtio_spi_transfer_result} is written by the Virtio SPI device. + +virtio-spi supports three transfer types: +\begin{itemize} +\item half-duplex read; +\item half-duplex write; +\item full-duplex transfer. +\end{itemize} + +For half-duplex read and full-duplex transfer, \field{rx_buf} is filled by the Virtio SPI device +and consumed by the Virtio SPI driver. For half-duplex write and full-duplex transfer, \field{tx_buf} +is filled by the Virtio SPI driver and consumed by the Virtio SPI device. + +\drivernormative{\subsubsection}{Device Operation}{Device Types / SPI Controller Device / Device Operation} + +For half-duplex read, the Virtio SPI driver MUST send \field{struct virtio_spi_transfer_head}, +\field{rx_buf} and \field{struct virtio_spi_transfer_result} to the SPI Virtio Device in that order. + +For half-duplex write, the Virtio SPI driver MUST send \field{struct virtio_spi_transfer_head}, +\field{tx_buf} and \field{struct virtio_spi_transfer_result} to the SPI Virtio Device in that order. + +For full-duplex transfer, the Virtio SPI driver MUST send \field{struct virtio_spi_transfer_head}, +\field{tx_buf}, \field{rx_buf} and \field{struct virtio_spi_transfer_result} to the SPI Virtio Device +in that order. + +For full-duplex transfer, the Virtio SPI driver MUST guarantee that the buffer size of \field{tx_buf} +and \field{rx_buf} is the same. + +The Virtio SPI driver MUST not use \field{rx_buf} if the \field{result} returned from the Virtio SPI device is +not VIRTIO_SPI_TRANS_OK. + +\devicenormative{\subsubsection}{Device Operation}{Device Types / SPI Controller Device / Device Operation} + +The Virtio SPI device MUST set all the fields of \field{struct virtio_spi_config} before they are +read by the Virtio SPI driver. + +The Virtio SPI device MUST NOT change the data in \field{tx_buf}. + +The Virtio SPI device MUST verify the parameters in \field{struct virtio_spi_transfer_head} after receiving +the request, and MUST set \field{struct virtio_spi_transfer_result} as VIRTIO_SPI_PARAM_ERR if not all +parameters are valid or some device unsupported features are set. + +For full-duplex transfer, the Virtio SPI device MUST verify that the buffer size of \field{tx_buf} is equal to +that of \field{rx_buf}. If not, the Virtio SPI device MUST set \field{struct virtio_spi_transfer_result} +as VIRTIO_SPI_PARAM_ERR. diff --git a/device-types/spi/device-conformance.tex b/device-types/spi/device-conformance.tex new file mode 100644 index 0000000..4509156 --- /dev/null +++ b/device-types/spi/device-conformance.tex @@ -0,0 +1,7 @@ +\conformance{\subsection}{SPI Controller Device Conformance}\label{sec:Conformance / Device Conformance / SPI Controller Device Conformance} + +An SPI Controller device MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{devicenormative:Device Types / SPI Controller Device / Device Operation} +\end{itemize} diff --git a/device-types/spi/driver-conformance.tex b/device-types/spi/driver-conformance.tex new file mode 100644 index 0000000..bbd1967 --- /dev/null +++ b/device-types/spi/driver-conformance.tex @@ -0,0 +1,7 @@ +\conformance{\subsection}{SPI Controller Driver Conformance}\label{sec:Conformance / Driver Conformance / SPI Controller Driver Conformance} + +An SPI Controller driver MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{drivernormative:Device Types / SPI Controller Device / Device Operation} +\end{itemize} From 37c6a406678a5ee891fdf5671298cb4fcfa517f2 Mon Sep 17 00:00:00 2001 From: "Pape, Andreas (ADITG/ESS3)" Date: Mon, 5 Feb 2024 14:41:00 +0000 Subject: [PATCH 12/62] sound: add sampling rates 12000Hz and 24000Hz 24kHz is used for 'super wideband' voice transmission 12kHz is added 'for completeness' Fixes: https://github.com/oasis-tcs/virtio-spec/issues/184 Signed-off-by: Andreas Pape Reviewed-by: Anton Yakovlev Signed-off-by: Cornelia Huck --- device-types/sound/description.tex | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/device-types/sound/description.tex b/device-types/sound/description.tex index 54c9c8e..bad4415 100644 --- a/device-types/sound/description.tex +++ b/device-types/sound/description.tex @@ -504,7 +504,9 @@ \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / Dev VIRTIO_SND_PCM_RATE_96000, VIRTIO_SND_PCM_RATE_176400, VIRTIO_SND_PCM_RATE_192000, - VIRTIO_SND_PCM_RATE_384000 + VIRTIO_SND_PCM_RATE_384000, + VIRTIO_SND_PCM_RATE_12000, + VIRTIO_SND_PCM_RATE_24000 }; struct virtio_snd_pcm_info { From 550b760622702d324f1b5e00ef4d24910b2415bb Mon Sep 17 00:00:00 2001 From: "Michael S. Tsirkin" Date: Thu, 11 Jul 2024 15:01:19 -0400 Subject: [PATCH 13/62] can: drop a broken conformance link CAN device has a single device conformance section, drop a link to a non-existent section, fixing a Latex error. Fixes: 07bb9f7 ("virtio-can: Device specification.") Message-ID: <87a6c3c4463e9f304cdd5dd5fac2194a95a8bcd2.1720724591.git.mst@redhat.com> Signed-off-by: Michael S. Tsirkin --- device-types/can/device-conformance.tex | 1 - 1 file changed, 1 deletion(-) diff --git a/device-types/can/device-conformance.tex b/device-types/can/device-conformance.tex index f944ffd..3725164 100644 --- a/device-types/can/device-conformance.tex +++ b/device-types/can/device-conformance.tex @@ -3,6 +3,5 @@ A CAN device MUST conform to the following normative statements: \begin{itemize} -\item \ref{devicenormative:Device Types / CAN Device / Feature bits} \item \ref{devicenormative:Device Types / CAN Device / Device Operation / CAN Message Transmission} \end{itemize} From 61b65cbade3ed8dc3ccaee5c53badad61de4664d Mon Sep 17 00:00:00 2001 From: Cornelia Huck Date: Mon, 30 Oct 2023 14:42:05 +0100 Subject: [PATCH 14/62] editorial: allow for longer device id table: makediff 1.3 Move to "longtable" to allow the table to span multiple pages (it became too long to fit on one page with the latest addition.) Signed-off-by: Cornelia Huck (cherry picked from commit c8249d73d2fdbbfd38e8bf45c8492057bc2485e9) --- content.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content.tex b/content.tex index c17ffa6..f18f056 100644 --- a/content.tex +++ b/content.tex @@ -649,7 +649,7 @@ \chapter{Device Types}\label{sec:Device Types} Discovering what devices are available and their type is bus-dependent. -\begin{tabular} { |l|c| } +\begin{longtable} { |l|c| } \hline Device ID & Virtio Device \\ \hline \hline @@ -739,7 +739,7 @@ \chapter{Device Types}\label{sec:Device Types} \hline 45 & SPI master \\ \hline -\end{tabular} +\end{longtable} Some of the devices above are unspecified by this document, because they are seen as immature or especially niche. Be warned From 79b04be2e0221400e267add84b5da518011b699a Mon Sep 17 00:00:00 2001 From: "Michael S. Tsirkin" Date: Thu, 11 Jul 2024 18:12:56 -0400 Subject: [PATCH 15/62] makediff: update base version to 1.3 might cause minor conflicts if we merge 1.3 branch again, but seems cleaner than seeing full diff here. Signed-off-by: Michael S. Tsirkin --- DIFFVERSION | 2 +- makediff.sh | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/DIFFVERSION b/DIFFVERSION index 67ec309..9bcc9ec 100644 --- a/DIFFVERSION +++ b/DIFFVERSION @@ -1 +1 @@ -v1.2-cs01 +v1.3-wd02 diff --git a/makediff.sh b/makediff.sh index 830a226..d6c9bcc 100755 --- a/makediff.sh +++ b/makediff.sh @@ -20,8 +20,7 @@ while read -r rev; do echo "Applying $rev" git cherry-pick --keep-redundant-commits --allow-empty `git rev-list -1 -F --grep "$rev" $newrev` || exit 1 done << 'EOF' -content.tex Fix Driver notifications label -editorial: update "Computer Language Definitions" URL +editorial: allow for longer device id table: makediff 1.3 EOF #mv specvars.tex specvars-orig.tex From 18e47c01207b2983a7dfd1e2c7de1bdc408d391a Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Tue, 21 May 2024 15:21:19 +0300 Subject: [PATCH 16/62] virtio-blk: Fix data type of num_queues field Correct the endianness of num_queues field to be little endian. Suggested-by: Max Gurtovoy Reviewed-by: Max Gurtovoy Signed-off-by: Parav Pandit Reviewed-by: Stefano Garzarella Reviewed-by: Stefan Hajnoczi Message-Id: <20240521122119.2004071-1-parav@nvidia.com> Signed-off-by: Michael S. Tsirkin --- device-types/blk/description.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/device-types/blk/description.tex b/device-types/blk/description.tex index f04c932..2712ada 100644 --- a/device-types/blk/description.tex +++ b/device-types/blk/description.tex @@ -108,7 +108,7 @@ \subsection{Device configuration layout}\label{sec:Device Types / Block Device / } topology; u8 writeback; u8 unused0; - u16 num_queues; + le16 num_queues; le32 max_discard_sectors; le32 max_discard_seg; le32 discard_sector_alignment; From 00806815385340dd411cc67df3f6837935bb5e26 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Thu, 6 Jun 2024 13:20:12 +0300 Subject: [PATCH 17/62] virtio-net: Fix receive buffer size calculation text Receive buffer size calculation is based on the following negotiated features. The text has wrong calculation for IPv6 and also it has missed VIRTIO_NET_F_HASH_REPORT. The problem of igorance of VIRTIO_NET_F_HASH_REPORT is reported in [1], however fix for ipv6 payload length must also be considered. Since for the both the fixes touching same requirements, a new issue is created as [2]. This patch brings following fixes. 1. Fix annotating struct virtio_net_hdr as field 2. Fix receive buffer calculation for guest GSO cases to consider ipv6 payload length 3. small grammar corrections for article 4. reword the requirement to consider the virtio_ndr_hdr which is depends on the negotiated feature, hence first clarify the struct virtio_net_hdr size [1] https://github.com/oasis-tcs/virtio-spec/issues/170 [2] https://github.com/oasis-tcs/virtio-spec/issues/183 Fixes: https://github.com/oasis-tcs/virtio-spec/issues/170 Fixes: https://github.com/oasis-tcs/virtio-spec/issues/183 Reviewed-by: Xuan Zhuo Signed-off-by: Parav Pandit Message-Id: <20240606102014.2103986-2-parav@nvidia.com> Signed-off-by: Michael S. Tsirkin --- device-types/net/description.tex | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/device-types/net/description.tex b/device-types/net/description.tex index 61cce1f..d8271fc 100644 --- a/device-types/net/description.tex +++ b/device-types/net/description.tex @@ -660,10 +660,15 @@ \subsubsection{Setting Up Receive Buffers}\label{sec:Device Types / Network Devi If the VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6, VIRTIO_NET_F_GUEST_UFO, VIRTIO_NET_F_GUEST_USO4 or VIRTIO_NET_F_GUEST_USO6 features are used, the maximum incoming packet -will be to 65550 bytes long (the maximum size of a -TCP or UDP packet, plus the 14 byte ethernet header), otherwise -1514 bytes. The 12-byte struct virtio_net_hdr is prepended to this, -making for 65562 or 1526 bytes. +will be 65589 bytes long (14 bytes of Ethernet header, plus 40 bytes of +the IPv6 header, plus 65535 bytes of maximum IPv6 payload including any +extension header), otherwise 1514 bytes. +When VIRTIO_NET_F_HASH_REPORT is not negotiated, the required receive buffer +size is either 65601 or 1526 bytes accounting for 20 bytes of +\field{struct virtio_net_hdr} followed by receive packet. +When VIRTIO_NET_F_HASH_REPORT is negotiated, the required receive buffer +size is either 65609 or 1534 bytes accounting for 12 bytes of +\field{struct virtio_net_hdr} followed by receive packet. \drivernormative{\paragraph}{Setting Up Receive Buffers}{Device Types / Network Device / Device Operation / Setting Up Receive Buffers} @@ -672,18 +677,25 @@ \subsubsection{Setting Up Receive Buffers}\label{sec:Device Types / Network Devi \begin{itemize} \item If VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6, VIRTIO_NET_F_GUEST_UFO, VIRTIO_NET_F_GUEST_USO4 or VIRTIO_NET_F_GUEST_USO6 are negotiated, the driver SHOULD populate - the receive queue(s) with buffers of at least 65562 bytes. + the receive queue(s) with buffers of at least 65609 bytes if + VIRTIO_NET_F_HASH_REPORT is negotiated, and of at least 65601 bytes if not. \item Otherwise, the driver SHOULD populate the receive queue(s) - with buffers of at least 1526 bytes. + with buffers of at least 1534 bytes if VIRTIO_NET_F_HASH_REPORT + is negotiated, and of at least 1526 bytes if not. \end{itemize} \item If VIRTIO_NET_F_MRG_RXBUF is negotiated, each buffer MUST be at -least the size of the struct virtio_net_hdr. +least size of \field{struct virtio_net_hdr}, +i.e. 20 bytes if VIRTIO_NET_F_HASH_REPORT is negotiated, and 12 bytes if not. \end{itemize} \begin{note} Obviously each buffer can be split across multiple descriptor elements. \end{note} +When calculating the size of \field{struct virtio_net_hdr}, the driver +MUST consider all the fields inclusive up to \field{padding_reserved}, +i.e. 20 bytes if VIRTIO_NET_F_HASH_REPORT is negotiated, and 12 bytes if not. + If VIRTIO_NET_F_MQ is negotiated, each of receiveq1\ldots receiveqN that will be used SHOULD be populated with receive buffers. From bf0fdf8ba828b694a22c44d45cb3fd34cf813e99 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Thu, 6 Jun 2024 13:20:13 +0300 Subject: [PATCH 18/62] virtio-net: Clarify the size of the struct virtio_net_hdr for tx The feature VIRTIO_NET_F_HASH_REPORT only applies to the receive side. However, when VIRTIO_NET_F_HASH_REPORT feature was introduced, it was not clarified that the size of the struct virtio_net_hdr on the packet transmission also uses higher size when VIRTIO_NET_F_HASH_REPORT is negotiated. Explicitly clarify this. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/183 Reviewed-by: Xuan Zhuo Signed-off-by: Parav Pandit Message-Id: <20240606102014.2103986-3-parav@nvidia.com> Signed-off-by: Michael S. Tsirkin --- device-types/net/description.tex | 3 +++ 1 file changed, 3 insertions(+) diff --git a/device-types/net/description.tex b/device-types/net/description.tex index d8271fc..d24ffb7 100644 --- a/device-types/net/description.tex +++ b/device-types/net/description.tex @@ -531,6 +531,9 @@ \subsubsection{Packet Transmission}\label{sec:Device Types / Network Device / De \drivernormative{\paragraph}{Packet Transmission}{Device Types / Network Device / Device Operation / Packet Transmission} +For the transmit packet buffer, the driver MUST use the size of the +structure \field{struct virtio_net_hdr} same as the receive packet buffer. + The driver MUST set \field{num_buffers} to zero. If VIRTIO_NET_F_CSUM is not negotiated, the driver MUST set From 6abd42fd2398718ff689dc51fa93d38ede97be8f Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Thu, 6 Jun 2024 13:20:14 +0300 Subject: [PATCH 19/62] virtio-net: Annotate virtio_net_hdr as field At several places struct virtio_net_hdr missed out the field annotation. Add it. Reviewed-by: Xuan Zhuo Signed-off-by: Parav Pandit Message-Id: <20240606102014.2103986-4-parav@nvidia.com> Signed-off-by: Michael S. Tsirkin --- device-types/net/description.tex | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/device-types/net/description.tex b/device-types/net/description.tex index d24ffb7..a66d6b0 100644 --- a/device-types/net/description.tex +++ b/device-types/net/description.tex @@ -437,11 +437,11 @@ \subsection{Device Operation}\label{sec:Device Types / Network Device / Device O \subsubsection{Legacy Interface: Device Operation}\label{sec:Device Types / Network Device / Device Operation / Legacy Interface: Device Operation} When using the legacy interface, transitional devices and drivers -MUST format the fields in struct virtio_net_hdr +MUST format the fields in \field{struct virtio_net_hdr} according to the native endian of the guest rather than (necessarily when not using the legacy interface) little-endian. -The legacy driver only presented \field{num_buffers} in the struct virtio_net_hdr +The legacy driver only presented \field{num_buffers} in the \field{struct virtio_net_hdr} when VIRTIO_NET_F_MRG_RXBUF was negotiated; without that feature the structure was 2 bytes shorter. @@ -735,7 +735,7 @@ \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network chains them together to form a single packet in a way similar to how it would store it in a single buffer spread over multiple descriptors. - The other buffers will not begin with a struct virtio_net_hdr. + The other buffers will not begin with a \field{struct virtio_net_hdr}. \item If \field{num_buffers} is one, then the entire packet will be @@ -2416,7 +2416,7 @@ \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device When using legacy interfaces, transitional drivers which have not negotiated VIRTIO_F_ANY_LAYOUT MUST use a single descriptor for the -struct virtio_net_hdr on both transmit and receive, with the +\field{struct virtio_net_hdr} on both transmit and receive, with the network data in the following descriptors. Additionally, when using the control virtqueue (see \ref{sec:Device From fdd39cfa7d76da022be7747e230553fd3119d2a9 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Tue, 4 Jun 2024 16:28:51 +0300 Subject: [PATCH 20/62] admin: Introduce self group Define self group to control the self device itself. Subsequent patches introduces the concept of device capabilities and device resources which utilizes the self group to access capabilities and uses device resources to refer to the device itself. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179 Signed-off-by: Parav Pandit Signed-off-by: Michael S. Tsirkin Acked-by: Satananda Burla Message-Id: <20240604132903.2093195-2-parav@nvidia.com> Signed-off-by: Michael S. Tsirkin --- admin.tex | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/admin.tex b/admin.tex index 0803c26..44e0f83 100644 --- a/admin.tex +++ b/admin.tex @@ -1,7 +1,10 @@ \section{Device groups}\label{sec:Basic Facilities of a Virtio Device / Device groups} It is occasionally useful to have a device control a group of -other devices. Terminology used in such cases: +other devices (the group may occasionally include the device +itself) within a group. The owner device itself is not a +member of the group (except in the special case of the self group). +Terminology used in such cases: \begin{description} \item[Device group] @@ -10,7 +13,7 @@ \section{Device groups}\label{sec:Basic Facilities of a Virtio Device / Device g or owner, the device controlling the group. \item[Member device] a device within a group. The owner device itself is not - a member of the group. + a member of the group except for the \field{Self group type}. \item[Member identifier] each member has this identifier, unique within the group and used to address it through the owner device. @@ -37,6 +40,11 @@ \section{Device groups}\label{sec:Basic Facilities of a Virtio Device / Device g The following group types, and their identifiers, are currently specified: \begin{description} +\item[Self group type (0x0)] +This device group includes the owner device itself and no other devices. +The group type identifier for this group is 0x0. +The member identifier for this group has a value of 0x0. + \item[SR-IOV group type (0x1)] This device group has a PCI Single Root I/O Virtualization (SR-IOV) physical function (PF) device as the owner and includes @@ -78,6 +86,7 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti /* Device-readable part */ le16 opcode; /* + * 0 - Self * 1 - SR-IOV * 2-65535 - reserved */ From bfe175d9e0186d4eb00a40f2532802aabd61cdba Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Tue, 4 Jun 2024 16:28:52 +0300 Subject: [PATCH 21/62] admin: Use already defined names for the legacy commands Instead of description, use the existing name for defining the legacy commands. While at it, prefer the shorter label names which are already unique and refer them as hyperreference in the table for quick naviation. This is editorial change to align to subsequent patches. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179 Signed-off-by: Parav Pandit Acked-by: Satananda Burla Message-Id: <20240604132903.2093195-3-parav@nvidia.com> Signed-off-by: Michael S. Tsirkin --- admin-cmds-legacy-interface.tex | 24 ++++++++++++++---------- admin.tex | 10 +++++----- 2 files changed, 19 insertions(+), 15 deletions(-) diff --git a/admin-cmds-legacy-interface.tex b/admin-cmds-legacy-interface.tex index b9c96d4..7b1ce4e 100644 --- a/admin-cmds-legacy-interface.tex +++ b/admin-cmds-legacy-interface.tex @@ -17,10 +17,10 @@ \subsubsection{Legacy Interfaces}\label{sec:Basic Facilities of a Virtio Device The following commands support such a legacy interface functionality: \begin{enumerate} -\item Legacy Common Configuration Write Command -\item Legacy Common Configuration Read Command -\item Legacy Device Configuration Write Command -\item Legacy Device Configuration Read Command +\item VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE +\item VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ +\item VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE +\item VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ \end{enumerate} These commands are currently only defined for the SR-IOV group type and @@ -29,8 +29,8 @@ \subsubsection{Legacy Interfaces}\label{sec:Basic Facilities of a Virtio Device Bus / PCI Device Layout / Legacy Interfaces: A Note on PCI Device Layout} except that little-endian format is assumed unconditionally. -\paragraph{Legacy Common Configuration Write Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group -administration commands / Legacy Interface / Legacy Common Configuration Write Command} +\paragraph{VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE} This command has the same effect as writing into the virtio common configuration structure through the legacy interface. The \field{command_specific_data} is in @@ -59,7 +59,8 @@ \subsubsection{Legacy Interfaces}\label{sec:Basic Facilities of a Virtio Device This command has no command specific result. -\paragraph{Legacy Common Configuration Read Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / Legacy Common Configuration Read Command} +\paragraph{VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ} This command has the same effect as reading from the virtio common configuration structure through the legacy interface. The \field{command_specific_data} is in @@ -94,7 +95,8 @@ \subsubsection{Legacy Interfaces}\label{sec:Basic Facilities of a Virtio Device returned by the device. The length of the data read is simply the length of \field{data}. -\paragraph{Legacy Device Configuration Write Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / Legacy Device Configuration Write Command} +\paragraph{VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE} This command has the same effect as writing into the virtio device-specific configuration through the legacy interface. The \field{command_specific_data} is in @@ -123,7 +125,8 @@ \subsubsection{Legacy Interfaces}\label{sec:Basic Facilities of a Virtio Device This command has no command specific result. -\paragraph{Legacy Device Configuration Read Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / Legacy Device Configuration Read Command} +\paragraph{VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ} This command has the same effect as reading from the virtio device-specific configuration through the legacy interface. The \field{command_specific_data} is in @@ -159,7 +162,8 @@ \subsubsection{Legacy Interfaces}\label{sec:Basic Facilities of a Virtio Device The length of the data read is simply the length of \field{data}. -\paragraph{Legacy Driver Notification}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / Legacy Driver Notifications} +\paragraph{VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO} The driver of the owner device can send a driver notification to the member device operated using the legacy interface by executing diff --git a/admin.tex b/admin.tex index 44e0f83..7838301 100644 --- a/admin.tex +++ b/admin.tex @@ -126,15 +126,15 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti \hline 0x0001 & VIRTIO_ADMIN_CMD_LIST_USE & Provides to device list of commands used for this group type \\ \hline -0x0002 & VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE & Writes into the legacy common configuration structure \\ +0x0002 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE]{VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE} & Writes into the legacy common configuration structure \\ \hline -0x0003 & VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ & Reads from the legacy common configuration structure \\ +0x0003 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ]{VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ} & Reads from the legacy common configuration structure \\ \hline -0x0004 & VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE & Writes into the legacy device configuration structure \\ +0x0004 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE]{VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE} & Writes into the legacy device configuration structure \\ \hline -0x0005 & VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ & Reads into the legacy device configuration structure \\ +0x0005 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ]{VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ} & Reads into the legacy device configuration structure \\ \hline -0x0006 & VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO & Query the notification region information \\ +0x0006 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO]{VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO} & Query the notification region information \\ \hline 0x0007 - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd} \\ \hline From 88a24d28db5b9ddbadec908571fbcdee1b15276f Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Tue, 4 Jun 2024 16:28:53 +0300 Subject: [PATCH 22/62] admin: Add theory of operation for capability admin commands Device capability indicates the supported functionality and resources of the device to the driver. Driver capability indicates the supported functionality and resources which driver will be using. Driver capability is subset of the device capability. Add theory of operation describing it. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179 Signed-off-by: Parav Pandit Signed-off-by: Michael S. Tsirkin Acked-by: Satananda Burla Message-Id: <20240604132903.2093195-4-parav@nvidia.com> Signed-off-by: Michael S. Tsirkin --- admin-cmds-capabilities.tex | 34 ++++++++++++++++++++++++++++++++++ admin.tex | 1 + 2 files changed, 35 insertions(+) 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..ef9481c --- /dev/null +++ b/admin-cmds-capabilities.tex @@ -0,0 +1,34 @@ +\subsubsection{Device and driver capabilities}\label{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities} + +Device and driver capabilities are implemented as structured groupings for +specific device functionality and their related resource objects. The device exposes +its supported functionality and resource object limits through an administration +command, utilizing the 'self group type.' Each capability possesses a +unique ID. Through an administration command, also employing the +'self group type,' the driver reports the functionality and +resource object limits it intends to use. Before executing any operations +related to the capabilities, the driver communicates these +capabilities to the device. The driver is allowed to set the +capability at any time, provided there are no pending operations +at the device level associated with that capability. + +The device presents the supported capability IDs to the driver as a bitmap. +The driver uses the administration command to learn about the +supported capabilities bitmap. + +A capability consists of one or more fields, where each field can be a +limit number, a bitmap, or an array of entries. In an array field, +the structure depends on the specific array and the capability type. +For each bitmap field, the driver sets the desired bits - but only out of +those bits in a bitmap that the device has presented. +The driver sets each limit number field to a desired value that +is smaller than or equal to the value the device presented. +Similarly, for an array field, the driver sets the desired capability +entries but only out of the capability entries that the device has presented. + +It is anticipated that any necessary new fields for a capability will be +appended to the structure's end, ensuring both forward and backward +compatibility between the device and driver. Furthermore, to avoid +indefinite growth of a single capability, it is expected that new +functionality will lead to the creation of new capability rather +than expanding existing ones. diff --git a/admin.tex b/admin.tex index 7838301..56c92a6 100644 --- a/admin.tex +++ b/admin.tex @@ -306,6 +306,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} From 72a91e6d63653b54d2a47425f1ceffb3d4ad3495 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Tue, 4 Jun 2024 16:28:54 +0300 Subject: [PATCH 23/62] admin: Prepare table for multipage listing If the table spans across two pages, it is not readable. Make use of xltabular package that supports table spanning across multiple pages. Signed-off-by: Parav Pandit Acked-by: Satananda Burla Message-Id: <20240604132903.2093195-5-parav@nvidia.com> Signed-off-by: Michael S. Tsirkin --- admin.tex | 4 ++-- virtio.tex | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/admin.tex b/admin.tex index 56c92a6..c93c74c 100644 --- a/admin.tex +++ b/admin.tex @@ -118,7 +118,7 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti \field{opcode} specifies the command. The valid values for \field{opcode} can be found in the following table: -\begin{tabularx}{\textwidth}{ |l||l|X| } +\begin{xltabular}{\textwidth}{ |l||l|X| } \hline opcode & Name & Command Description \\ \hline \hline @@ -140,7 +140,7 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti \hline 0x8000 - 0xFFFF & - & Reserved for future commands (possibly using a different structure) \\ \hline -\end{tabularx} +\end{xltabular} The \field{group_type} specifies the group type identifier. The \field{group_member_id} specifies the member identifier within the group. diff --git a/virtio.tex b/virtio.tex index 37e49b1..7c52a40 100644 --- a/virtio.tex +++ b/virtio.tex @@ -35,6 +35,7 @@ \usepackage{xltxtra} \usepackage{etoolbox} \usepackage{tabularx} +\usepackage{xltabular} \usepackage{underscore} \usepackage{xstring} \usepackage{enumitem} From d60a39072890dce31bb6a39c68fb1f577362ad8f Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Tue, 4 Jun 2024 16:28:55 +0300 Subject: [PATCH 24/62] admin: Add capability admin commands Add three capabilities related administration commands. First to get the device capability. Second to set the driver capability. Third for the driver to discover which capabilities can be accessed. Even though the current series restricts device capability reading to the self group type, same structure and command format etc will be reusable in future to read the capability from the owner device and also to set the device capability via owner device using new DEV_CAP_SET command. Resource objects are introduced in subsequent patch which utilizes the capability, however some description around resource object limit is covered in this patch to keep things simple. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179 Signed-off-by: Parav Pandit Signed-off-by: Michael S. Tsirkin Acked-by: Satananda Burla Message-Id: <20240604132903.2093195-6-parav@nvidia.com> Signed-off-by: Michael S. Tsirkin --- admin-cmds-capabilities.tex | 196 ++++++++++++++++++++++++++++++++++++ admin.tex | 12 ++- conformance.tex | 2 + virtio.tex | 1 + 4 files changed, 210 insertions(+), 1 deletion(-) diff --git a/admin-cmds-capabilities.tex b/admin-cmds-capabilities.tex index ef9481c..07b8ddb 100644 --- a/admin-cmds-capabilities.tex +++ b/admin-cmds-capabilities.tex @@ -32,3 +32,199 @@ \subsubsection{Device and driver capabilities}\label{sec:Basic Facilities of a V indefinite growth of a single capability, it is expected that new functionality will lead to the creation of new capability rather than expanding existing ones. + +Capabilities are categorized into two ranges by their IDs, as listed: + +\begin{table}[H] +\caption{Capability ids} +\label{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / capability ids} +\begin{tabularx}{\textwidth}{ |l|X| } +\hline +Id & Description \\ +\hline \hline +0x0000-0x07ff & Generic capability for all device types \\ +\hline +0x0800-0x0fff & Device type specific capability \\ +\hline +0x1000 - 0xFFFF & Reserved for future \\ +\hline +\end{tabularx} +\end{table} + +Device type specific capabilities are described separately for each device +type under \field{Device and driver capabilities}. + +The device and driver capabilities commands are currently defined for self group +type. + +\begin{enumerate} +\item VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY +\item VIRTIO_ADMIN_CMD_DEVICE_CAP_GET +\item VIRTIO_ADMIN_CMD_DRIVER_CAP_SET +\end{enumerate} + +\paragraph{VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY} + +This command queries the bitmap of capability ids +listed in \ref{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / capability ids}. + +For the command VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY, \field{opcode} is set to 0x7. +\field{group_member_id} is set to zero. + +This command has no command specific data. + +\begin{lstlisting} +struct virtio_admin_cmd_query_cap_id_result { + le64 supported_caps[]; +}; +\end{lstlisting} + +When the command completes successfully, \field{command_specific_result} +is in the format \field{struct virtio_admin_cmd_query_cap_id_result}. + +\field{supported_caps} is an array of 64 bit values in little-endian byte +order, in which a bit is set if the specific capability is supported. +Thus, \field{supported_caps[0]} refers to the first 64-bit value in this +array corresponding to capability ids 0 to +63, \field{supported_caps[1]} is the second 64-bit value corresponding to +capability ids 64 to 127, etc. For example, the array of size 2 including +the values 0x3 in \field{supported_caps[0]} and 0x1 in +\field{supported_caps[1]} indicates that only capability id 0, 1 +and 64 are supported. +The length of the array depends on the supported capabilities - it is +large enough to include bits set for all supported capability ids, +that is the length can be calculated by starting with the largest +supported capability id adding one, dividing by 64 and rounding up. +In other words, for VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY the length of +\field{command_specific_result} will be +$DIV_ROUND_UP(max_cap_id, 64) * 8$ where DIV_ROUND_UP is integer division +with round up and \field{max_cap_id} is the largest available capability id. + +The array is also allowed to be larger and to additionally include an arbitrary +number of all-zero entries. + +\paragraph{VIRTIO_ADMIN_CMD_DEVICE_CAP_GET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO_ADMIN_CMD_DEVICE_CAP_GET} + +This command gets the device capability for the specified capability +id \field{id}. + +For the command VIRTIO_ADMIN_CMD_DEVICE_CAP_GET, \field{opcode} is set to 0x8. +\field{group_member_id} is set to zero. + +\field{command_specific_data} is in format +\field{struct virtio_admin_cmd_cap_get_data}. + +\begin{lstlisting} +struct virtio_admin_cmd_cap_get_data { + le16 id; + u8 reserved[6]; +}; +\end{lstlisting} + +\field{id} refers to the capability id listed in \ref{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / capability ids}. +\field{reserved} is reserved for future use and set to zero. + +\begin{lstlisting} +struct virtio_admin_cmd_cap_get_result { + 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_get_result} responded +by the device. Each capability uses different capability specific +\field{cap_specific_data} and is described separately. + +\paragraph{VIRTIO_ADMIN_CMD_DRIVER_CAP_SET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO_ADMIN_CMD_DRIVER_CAP_SET} + +This command sets the driver capability, indicating to the device which capability +the driver uses. The driver can set a resource object limit capability that is smaller +than or equal to the value published by the device capability. +If the capability is a set of flags, the driver sets the flag bits that are set +in the device capability; the driver does not set any flag bits that are not +set by the device. + +For the command VIRTIO_ADMIN_CMD_DRIVER_CAP_SET, \field{opcode} is set to 0x9. +\field{group_member_id} is set to zero. +The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_cap_set_data}. + +\begin{lstlisting} +struct virtio_admin_cmd_cap_set_data { + le16 id; + u8 reserved[6]; + u8 cap_specific_data[]; +}; +\end{lstlisting} + +\field{id} refers to the capability id listed in \ref{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / capability ids}. +\field{reserved} is reserved for future use and set to zero. + +There is no command specific result. +When the command completes successfully, the driver capability is updated to +the 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 the commands +VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY, +VIRTIO_ADMIN_CMD_DRIVER_CAP_SET, and +VIRTIO_ADMIN_CMD_DEVICE_CAP_GET. + +For the VIRTIO_ADMIN_CMD_DRIVER_CAP_SET command, +\begin{itemize} +\item the device MUST support the setting of resource object limit driver capability to a +value that is same as or smaller than the one reported in the device +capability, +\item the device MUST support the setting of capability flags bits to +all or fewer bits than the one reported in the device capability; +\end{itemize} +this is applicable unless specific capability fields are explicitly +stated as non-writable in the VIRTIO_ADMIN_CMD_DEVICE_CAP_GET command. + +The device MAY complete the command VIRTIO_ADMIN_CMD_DRIVER_CAP_SET with +\field{status} set to VIRTIO_ADMIN_STATUS_EINVAL, +if the capability resource object limit is larger than the value reported by the +device's capability, or the capability flag bit is set, which is not set in +the device's capability. + +The device MUST complete the commands VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY, +VIRTIO_ADMIN_CMD_DRIVER_CAP_GET, and VIRTIO_ADMIN_CMD_DRIVER_CAP_SET +with \field{status} set to VIRTIO_ADMIN_STATUS_EINVAL if the commands are not +for the self group type. + +The device SHOULD complete the commands VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY, +VIRTIO_ADMIN_CMD_DRIVER_CAP_GET, VIRTIO_ADMIN_CMD_DRIVER_CAP_SET with +\field{status} set to VIRTIO_ADMIN_STATUS_EINVAL if the commands are not for the +self group type. + +The device SHOULD complete the command VIRTIO_ADMIN_CMD_DRIVER_CAP_SET with +\field{status} set to VIRTIO_ADMIN_STATUS_EBUSY if the command requests to disable +a capability while the device still has valid resource objects related to the +capability being disabled. + +The device SHOULD complete the comands VIRTIO_ADMIN_CMD_DEVICE_CAP_GET and +VIRTIO_ADMIN_CMD_DRIVER_CAP_SET with \field{status} set to +VIRTIO_ADMIN_STATUS_ENXIO if the capability id is not reported +in command VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY. + +Upon a device reset, the device MUST reset all 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 the command VIRTIO_ADMIN_CMD_DRIVER_CAP_SET before +using any resource objects that depend on such a capability. + +In VIRTIO_ADMIN_CMD_DRIVER_CAP_SET command, the driver MUST NOT set +\begin{itemize} +\item the resource object limit value larger than the value reported +by the device in the command VIRTIO_ADMIN_CMD_DEVICE_CAP_GET, +\item flags bits which was not reported by the device in the command +VIRTIO_ADMIN_CMD_DEVICE_CAP_GET, +\item array entries not reported by the device in the command +VIRTIO_ADMIN_CMD_DEVICE_CAP_GET. +\end{itemize} + +The driver MUST NOT disable any of the driver capability using the command +VIRTIO_ADMIN_CMD_DRIVER_CAP_SET when related resource objects +are created but not destroyed. diff --git a/admin.tex b/admin.tex index c93c74c..c8b3de4 100644 --- a/admin.tex +++ b/admin.tex @@ -136,7 +136,13 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti \hline 0x0006 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO]{VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO} & Query the notification region information \\ \hline -0x0007 - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd} \\ +0x0007 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY]{VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY} & Query the supported device capabilities bitmap \\ +\hline +0x0008 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO_ADMIN_CMD_DEVICE_CAP_GET]{VIRTIO_ADMIN_CMD_DEVICE_CAP_GET} & Get the device capabilities \\ +\hline +0x0009 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO_ADMIN_CMD_DRIVER_CAP_SET]{VIRTIO_ADMIN_CMD_DRIVER_CAP_SET} & Set the 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 @@ -162,10 +168,14 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti \hline \hline 00 & VIRTIO_ADMIN_STATUS_OK & successful completion \\ \hline +06 & VIRTIO_ADMIN_STATUS_ENXIO & no such capability \\ +\hline 11 & VIRTIO_ADMIN_STATUS_EAGAIN & try again \\ \hline 12 & VIRTIO_ADMIN_STATUS_ENOMEM & insufficient resources \\ \hline +16 & VIRTIO_ADMIN_STATUS_EBUSY & device busy \\ +\hline 22 & VIRTIO_ADMIN_STATUS_EINVAL & invalid command \\ \hline other & - & group administration command error \\ diff --git a/conformance.tex b/conformance.tex index 183c059..8b77eba 100644 --- a/conformance.tex +++ b/conformance.tex @@ -99,6 +99,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} @@ -181,6 +182,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} diff --git a/virtio.tex b/virtio.tex index 7c52a40..3bb5c14 100644 --- a/virtio.tex +++ b/virtio.tex @@ -39,6 +39,7 @@ \usepackage{underscore} \usepackage{xstring} \usepackage{enumitem} +\usepackage{float} \IfFileExists{ellipsis.sty}{\usepackage{ellipsis}}{ \message{!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!} \message{LaTeX Warning: Missing ellipsis.sty: dots (...) will look ugly} From 738f0a21330709d61abb009297daf54fbea84305 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Tue, 4 Jun 2024 16:28:56 +0300 Subject: [PATCH 25/62] admin: Add theory of operation for device resource objects The driver controls the device by means of device resource objects. These operations include create, query, modify, and destroy the device resource objects. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179 Signed-off-by: Parav Pandit Signed-off-by: Michael S. Tsirkin Acked-by: Satananda Burla Message-Id: <20240604132903.2093195-7-parav@nvidia.com> Signed-off-by: Michael S. Tsirkin --- admin-cmds-resource-objects.tex | 69 +++++++++++++++++++++++++++++++++ admin.tex | 1 + 2 files changed, 70 insertions(+) create mode 100644 admin-cmds-resource-objects.tex diff --git a/admin-cmds-resource-objects.tex b/admin-cmds-resource-objects.tex new file mode 100644 index 0000000..a74cb3b --- /dev/null +++ b/admin-cmds-resource-objects.tex @@ -0,0 +1,69 @@ +\subsubsection{Device resource objects}\label{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects} + +Providing certain functionality consumes limited device resources such as +memory, processing units, buffer memory, or end-to-end credits. A device may +support multiple types of resource objects, each controlling different device +functionality. To manage this, virtio provides +\field{Device resource objects} that the driver can create, modify, and +destroy using administration commands with the self group type. Creating and +destroying a resource object consume and release device resources, respectively. +The device resource object query command returns the resource object as +maintained by the device. + +For each resource type, the number of resource objects that can be created +is reported by the device as part of a device capability +\ref{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities}. +The driver reports the desired (same or lower) number of resource objects +as part of a driver capability \ref{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities}. +For each device object type, resource object limit is defined by field +\field{limit} using \field{Device and driver capabilities}. + +\begin{lstlisting} +le32 limit; /* maximum resource id = limit - 1 */ +\end{lstlisting} + +Each resource object has a unique resource object ID - a driver-assigned number +in the range of 0 to \field{limit - 1}, where the \field{limit} is the maximum +number set by the driver for this resource object type. These resource IDs are unique within +each resource object type. The driver assigns the resource ID when creating a +device resource object. Once the resource object is successfully created, +subsequent resource modification, query, and destroy commands use this +resource object ID. No two resource objects share the same ID. Destroying a +resource object allows for the reuse of its ID for another resource object +of the same type. + +A valid resource object id is \field{limit - 1}. For example, when a device +reports a \field{limit = 10} capability for a resource object, and drivers sets +\field{limit = 8}, the valid resource object id range for the device and the +driver is 0 to 7 for all the resource object commands. In this example, +the driver can only create 8 resource objects of a specified type. + +A resource object of one type may depend on the resource object of another type. +Such dependency between resource objects is established by referring to the unique +resource ID in the administration commands. For example, a driver creates a +resource object identified by ID A of one type, then creates another resource +object identified by ID B of a different type, which depends on resource object +A. This dependency establishes the lifecycle of these resource objects. The driver +that creates the dependent resource object must destroy the resource objects in the +exact reverse order of their creation. In this example, the driver would +destroy resource object B before destroying resource object A. + +Some resource object types are generic, common across multiple devices. +Others are specific for one device type. + +\begin{tabular}{|l|l|} +\hline +Resource object type & Description \\ +\hline \hline +0x000-0x1ff & Generic resource object type common across all devices \\ +\hline +0x200-0x4ff & Device type specific resource object \\ +\hline +0x500-0xffff & Reserved for future use \\ +\hline +\end{tabular} + +When the device resets, it starts with zero resources of each type; the driver +can create resources up to the published \field{limit}. The driver can +destroy and recreate the resource one or multiple times. Upon device reset, +all resource objects created by the driver are destroyed within the device. diff --git a/admin.tex b/admin.tex index c8b3de4..d8a19c4 100644 --- a/admin.tex +++ b/admin.tex @@ -317,6 +317,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-resource-objects.tex} \devicenormative{\subsubsection}{Group administration commands}{Basic Facilities of a Virtio Device / Device groups / Group administration commands} From 5040f36bd8c9ac29ca6dc7ef75fd7679f2d6d92b Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Tue, 4 Jun 2024 16:28:57 +0300 Subject: [PATCH 26/62] admin: Add device resource objects admin commands Add generic administration commands create, modify, query and destroy device resource object. Each resource object defines resource specific attributes for the commands. Once the resource object is created by the driver, it can be query/modify or destroyed by the driver. Each resource object is identified using a unique resource id per resource type. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179 Signed-off-by: Parav Pandit Signed-off-by: Michael S. Tsirkin Acked-by: Satananda Burla Message-Id: <20240604132903.2093195-8-parav@nvidia.com> Signed-off-by: Michael S. Tsirkin --- admin-cmds-capabilities.tex | 3 + admin-cmds-resource-objects.tex | 199 ++++++++++++++++++++++++++++++++ admin.tex | 14 ++- conformance.tex | 2 + 4 files changed, 216 insertions(+), 2 deletions(-) diff --git a/admin-cmds-capabilities.tex b/admin-cmds-capabilities.tex index 07b8ddb..8119a56 100644 --- a/admin-cmds-capabilities.tex +++ b/admin-cmds-capabilities.tex @@ -210,6 +210,9 @@ \subsubsection{Device and driver capabilities}\label{sec:Basic Facilities of a V Upon a device reset, the device MUST reset all driver capabilities. +The device SHOULD treat the driver resource limits as zero if the +driver has not set such capability, unless otherwise explicitly stated. + \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 the command VIRTIO_ADMIN_CMD_DRIVER_CAP_SET before diff --git a/admin-cmds-resource-objects.tex b/admin-cmds-resource-objects.tex index a74cb3b..291f7e6 100644 --- a/admin-cmds-resource-objects.tex +++ b/admin-cmds-resource-objects.tex @@ -67,3 +67,202 @@ \subsubsection{Device resource objects}\label{sec:Basic Facilities of a Virtio D can create resources up to the published \field{limit}. The driver can destroy and recreate the resource one or multiple times. Upon device reset, all resource objects created by the driver are destroyed within the device. + +Following administration commands control device resource objects, +they are only supported for the self group type: + +\begin{enumerate} +\item VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE +\item VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY +\item VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY +\item VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY +\end{enumerate} + +Each resource object administration command uses a common header +\field{struct virtio_admin_cmd_resource_obj_cmd_hdr}. + +\begin{lstlisting} +struct virtio_admin_cmd_resource_obj_cmd_hdr { + le16 type; + u8 reserved[2]; + le32 id; /* Indicates unique resource object id per resource object type */ +}; + +\end{lstlisting} + +\field{type} refers to the device resource object type. +\field{id} uniquely identifies the resource object of a specified \field{type}. + +\paragraph{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE} + +This command creates the specified resource object of \field{type} identified by the +resource id \field{id}. The valid range of \field{id} is defined by the +device in the related device capability. The driver assigns the unique \field{id} +for the resource for the specified \field{type}. + +For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, \field{opcode} is set to 0xa. +\field{group_member_id} is set to zero. +The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_resource_obj_create_data}. +\field{resource_obj_specific_data} refers to the resource object specific data. +Each resource uses a different \field{resource_obj_specific_data} and is described +separately. + +\field{flags} is reserved for future extension for optional resource object attributes and +is set to 0. Each resource object uses a different value for +\field{flags} and it is described separately. + +\begin{lstlisting} +struct virtio_admin_cmd_resource_obj_create_data { + struct virtio_admin_cmd_resource_obj_cmd_hdr hdr; + le64 flags; + u8 resource_obj_specific_data[]; +}; +\end{lstlisting} + +When the command completes successfully, the resource object is created by the +device and the device can immediately begin using it. +This command has no command specific result. + +\paragraph{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY} + +This command modifies the attributes of an existing device resource object. +For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY, \field{opcode} is set to 0xb. +The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_resource_modify_data}. +\field{group_member_id} is set to zero. +\field{id} identifies the resource object of type \field{type} whose attributes +to modify. +This command modifies the attributes supplied in \field{resource_obj_specific_data}. + +\begin{lstlisting} +struct virtio_admin_cmd_resource_modify_data { + struct virtio_admin_cmd_resource_obj_cmd_hdr hdr; + le64 flags; + u8 resource_obj_specific_data[]; +}; +\end{lstlisting} + +This command has no command specific result. +When the command completes successfully, attributes of the resource object is +set to the values supplied in \field{resource_obj_specific_data}. + +\paragraph{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY} + +This command queries attributes of the existing resource object. +For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY, \field{opcode} is set to 0xc. +\field{group_member_id} is set to zero. +The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_resource_obj_query_data}. +\field{id} identifies the existing resource object of type \field{type} whose +attributes to query. + +\begin{lstlisting} +struct virtio_admin_cmd_resource_obj_query_data { + struct virtio_admin_cmd_resource_obj_cmd_hdr hdr; + le64 flags; +}; +\end{lstlisting} + +\begin{lstlisting} +struct virtio_admin_cmd_resource_obj_query_result { + u8 resource_obj_specific_result[]; +}; +\end{lstlisting} + +\field{command_specific_result} is in the format +\field{virtio_admin_cmd_resource_obj_query_result}. + +When the command completes successfully, the attributes of the specified +resource object are are set in \field{resource_obj_specific_data}. + +\paragraph{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY} + +This command destroys the previously created device resource object. +For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY, \field{opcode} is set to 0xd. +The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_resource_obj_cmd_hdr}. +\field{group_member_id} is set to zero. +\field{id} identifies the existing resource object of type \field{type}. + +This command destroys the specified resource object of \field{type} identified +by \field{id}, which is previously created using +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE command. + +This command has no command specific result. +When the command completes successfully, the resource object is destroyed from the device. + +\devicenormative{\paragraph}{Device resource objects}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects} + +The device SHOULD complete the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE +with \field{status} set to VIRTIO_ADMIN_STATUS_EEXIST if a resource object already exists +with supplied resource \field{id} for the specified \field{type}. + +The device SHOULD complete the commands VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY, +VIRTIO_ADMIN_CMD_RESOURCE_QUERY and +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY with \field{status} set to +VIRTIO_ADMIN_STATUS_ENXIO if the specified resource object does not exist. + +The device SHOULD set \field{status} to VIRTIO_ADMIN_STATUS_ENOSPC for the +command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE if the device fail to create the +resource object. + +The device SHOULD complete the commands VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY or +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY commands with \field{status} set to +VIRTIO_ADMIN_STATUS_EBUSY if other resource objects depend on the resource object +being modified or destroyed. + +The device MUST allow recreating the resource object using the command +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE which was previously +destroyed using the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY respectively +without undergoing a device reset. + +The device SHOULD allow creating the resource object using +the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE with any resource +id as long as the resource object is not created. + +The device MAY fail the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE 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. + +When a capability represents a number of resource objects, the device SHOULD +allow creating as many resource objects as represented by the driver capability. + +The device MUST NOT have any side effects on the resource object when the command +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY fails. + +The device MUST complete the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY +with \field{resource_obj_specific_data} which is matching the +\field{resource_obj_specific_data} of last VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE +or VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY command. + +On device reset, the device MUST destroy all the resource objects which +have been created. + +\drivernormative{\paragraph}{Device resource objects}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects} + +The driver MUST not create a second resource object of the same type with same +ID using command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE before destroying the +previously created resource object. + +The driver MUST NOT create more resource objects of a specified \field{type} using +command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE than the maximum limit set by the +driver capability. + +The driver SHOULD NOT modify, query and destroy the resource object which is +already destroyed previously by the driver. + +The driver SHOULD NOT destroy the resource object on which other resource objects +are depending; the driver SHOULD destroy all the resource objects which do not depend +on other resource objects. + +The driver MUST NOT set the capability related to the resource objects if the +resource objects have been created using the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE +and not yet destroyed. + +The driver MUST send the command VIRTIO_ADMIN_CMD_DRIVER_CAP_SET before using +any resources related to such capability. diff --git a/admin.tex b/admin.tex index d8a19c4..5b908ae 100644 --- a/admin.tex +++ b/admin.tex @@ -142,7 +142,15 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti \hline 0x0009 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO_ADMIN_CMD_DRIVER_CAP_SET]{VIRTIO_ADMIN_CMD_DRIVER_CAP_SET} & Set the driver capabilities \\ \hline -0x000a - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd} \\ +0x000a & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE} & Create a device resource object \\ +\hline +0x000c & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY} & Modify a device resource object \\ +\hline +0x000b & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY} & Query a device resource object \\ +\hline +0x000d & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY} & Destroy a device resource object \\ +\hline +0x000e - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd} \\ \hline 0x8000 - 0xFFFF & - & Reserved for future commands (possibly using a different structure) \\ \hline @@ -168,7 +176,7 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti \hline \hline 00 & VIRTIO_ADMIN_STATUS_OK & successful completion \\ \hline -06 & VIRTIO_ADMIN_STATUS_ENXIO & no such capability \\ +06 & VIRTIO_ADMIN_STATUS_ENXIO & no such capability or resource\\ \hline 11 & VIRTIO_ADMIN_STATUS_EAGAIN & try again \\ \hline @@ -178,6 +186,8 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti \hline 22 & VIRTIO_ADMIN_STATUS_EINVAL & invalid command \\ \hline +28 & VIRTIO_ADMIN_STATUS_ENOSPC & resources exhausted on device \\ +\hline other & - & group administration command error \\ \hline \end{tabular} diff --git a/conformance.tex b/conformance.tex index 8b77eba..297b78a 100644 --- a/conformance.tex +++ b/conformance.tex @@ -100,6 +100,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 resource objects} \end{itemize} \conformance{\subsection}{PCI Driver Conformance}\label{sec:Conformance / Driver Conformance / PCI Driver Conformance} @@ -183,6 +184,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 resource objects} \end{itemize} \conformance{\subsection}{PCI Device Conformance}\label{sec:Conformance / Device Conformance / PCI Device Conformance} From 7b3bdd63d82184bdf9fd49362892de1a1342e397 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Tue, 4 Jun 2024 16:28:58 +0300 Subject: [PATCH 27/62] virtio-net: Add theory of operation for flow filter Currently packet allow/drop interface has following limitations. 1. Driver can either select which MAC and VLANs to consider for allowing/dropping packets, here, the driver has a limitation that driver needs to supply full mac table or full vlan table for each type. Driver cannot add or delete an individual entry. 2. Driver cannot select mac+vlan combination for which to allow/drop packet. 3. Driver cannot not set other commonly used packet match fields such as IP header fields, TCP, UDP, SCP header fields. 4. Driver cannot steer specific packets based on the match fields to specific receiveq. 5. Driver do not have multiple or dedicated virtqueues to perform flow filter requests in accelerated manner in the device. Flow filter as a generic framework overcome above limitations. As starting point it is useful to support at least two use cases. a. ARFS b. ethtool ntuple steering In future it can be further extended for usecases such as switching device, connection tracking or may be more. The flow filter has following properties. 1. It is an extendible object that driver can create, destroy. 2. It belongs to a flow filter group. 3. Each flow filter rule is identified using a unique id, has priority, match key, destination(rq) and action(allow/drop). 4. Flow filter key also refers to the mask to learn which fields of the packets to match. This patch adds theory of operation for flow filter functionality. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179 Signed-off-by: Parav Pandit Signed-off-by: Heng Qi Signed-off-by: Michael S. Tsirkin Acked-by: Satananda Burla Message-Id: <20240604132903.2093195-9-parav@nvidia.com> Signed-off-by: Michael S. Tsirkin --- device-types/net/description.tex | 68 ++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/device-types/net/description.tex b/device-types/net/description.tex index a66d6b0..5be45b2 100644 --- a/device-types/net/description.tex +++ b/device-types/net/description.tex @@ -2411,6 +2411,74 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi of the driver's records. In such cases, the driver should allocate additional space for the \field{command-specific-result} buffer. +\subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Operation / Flow filter} + +A network device can support one or more flow filter rules. Each flow filter rule +is applied by matching a packet and then taking an action, such as directing the packet +to a specific receiveq or dropping the packet. An example of a match is +matching on specific source and destination IP addresses. + +A flow filter rule is a device resource object that consists of a key, +a processing priority, and an action to either direct a packet to a +receive queue or drop the packet. + +Each rule uses a classifier. The key is matched against the packet using +a classifier, defining which fields in the packet are matched. +A classifier resource object consists of one or more field selectors, each with +a type that specifies the header fields to be matched against, and a mask. +The mask can match whole fields or parts of a field in a header. Each +rule resource object depends on the classifier resource object. + +When a packet is received, relevant fields are extracted +(in the same way) from both the packet and the key according to the +classifier. The resulting field contents are then compared - +if they are identical the rule action is taken, if they are not, the rule is ignored. + +Multiple flow filter rules are part of a group. The rule resource object +depends on the group. Each rule within a +group has a rule priority, and each group also has a group priority. For a +packet, a group with the highest priority is selected first. Within a group, +rules are applied from highest to lowest priority, until one of the rules +matches the packet and an action is taken. If all the rules within a group +are ignored, the group with the next highest priority is selected, and so on. + +The driver controls the flow filter rule, classifier and group resource objects using +administration commands described in +\ref{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects}. + +\paragraph{Packet processing order}\label{sec:sec:Device Types / Network Device / Device Operation / Flow filter / Packet processing order} + +Note that flow filter rules are applied after MAC/VLAN filtering. Flow filter +rules take precedence over steering: if a flow filter rule results in an action, +the steering configuration does not apply. The steering configuration only applies +to packets for which no flow filter rule action was performed. For example, +incoming packets can be processed in the following order: + +\begin{itemize} +\item apply steering configuration received using control virtqueue commands + VIRTIO_NET_CTRL_RX, VIRTIO_NET_CTRL_MAC and VIRTIO_NET_CTRL_VLAN. +\item apply flow filter rules if any. +\item if no filter rule applied, apply steering configuration received using command + VIRTIO_NET_CTRL_MQ_RSS_CONFIG or as per automatic receive steering. +\end{itemize} + +Some incoming packet processing examples: +\begin{itemize} +\item If the packet is dropped by the flow filter rule, RSS + steering is ignored for the packet. +\item If the packet is directed to a specific receiveq using flow filter rule, + the RSS steering is ignored for the packet. +\item If a packet is dropped due to the VIRTIO_NET_CTRL_MAC configuration, + both flow filter rules and the RSS steering are ignored for the packet. +\item If a packet does not match any flow filter rules, + the RSS steering is used to select the receiveq for the packet (if enabled). +\item If there are two flow filter groups configured as group_A and group_B + with respective group priorities as 4, and 5; flow filter rules of + group_B are applied first having highest group priority, if there is a match, + the flow filter rules of group_A are ignored; if there is no match for + the flow filter rules in group_B, the flow filter rules of next level group_A are applied. +\end{itemize} + \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device Types / Network Device / Legacy Interface: Framing Requirements} From 899bb0ca24d8ee9d7223826e516fb8f48658c9db Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Tue, 4 Jun 2024 16:28:59 +0300 Subject: [PATCH 28/62] virtio-net: Add flow filter capability Add first flow filter capability that indicates device resource limits such as number of flow filter rules, groups and selectors. add second capability that indicates supported selectors defining which packet headers and their fields supported. [Parav Pandit: resolve conflict: editorial: in spec links] Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179 Signed-off-by: Parav Pandit Signed-off-by: Heng Qi Signed-off-by: Michael S. Tsirkin Acked-by: Satananda Burla Message-Id: <20240604132903.2093195-10-parav@nvidia.com> Signed-off-by: Michael S. Tsirkin --- device-types/net/description.tex | 194 +++++++++++++++++++++++++++++++ introduction.tex | 13 +++ 2 files changed, 207 insertions(+) diff --git a/device-types/net/description.tex b/device-types/net/description.tex index 5be45b2..faa0e5b 100644 --- a/device-types/net/description.tex +++ b/device-types/net/description.tex @@ -401,6 +401,22 @@ \subsection{Device Initialization}\label{sec:Device Types / Network Device / Dev A truly minimal driver would only accept VIRTIO_NET_F_MAC and ignore everything else. +\subsection{Device and driver capabilities}\label{sec:Device Types / Network Device / Device and driver capabilities} + +The network device has the following capabilities. + +\begin{tabularx}{\textwidth}{ |l||l|X| } +\hline +Identifier & Name & Description \\ +\hline \hline +0x0800 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_RESOURCE_CAP]{VIRTIO_NET_FF_RESOURCE_CAP} & Flow filter resource capability \\ +\hline +0x0801 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_SELECTOR_CAP]{VIRTIO_NET_FF_SELECTOR_CAP} & Flow filter classifier capability \\ +\hline +0x0802 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_ACTION_CAP]{VIRTIO_NET_FF_ACTION_CAP} & Flow filter action capability \\ +\hline +\end{tabularx} + \subsection{Device Operation}\label{sec:Device Types / Network Device / Device Operation} Packets are transmitted by placing them in the @@ -2442,6 +2458,14 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope matches the packet and an action is taken. If all the rules within a group are ignored, the group with the next highest priority is selected, and so on. +The device and the driver indicates flow filter resource limits using the capability +\ref{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_RESOURCE_CAP} specifying the limits on the number of flow filter rule, +group and classifier resource objects. The capability \ref{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_SELECTOR_CAP} specifies which selectors the device supports. +The driver indicates the selectors it is using by setting the flow +filter selector capability, prior to adding any resource objects. + +The capability \ref{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_ACTION_CAP} specifies which actions the device supports. + The driver controls the flow filter rule, classifier and group resource objects using administration commands described in \ref{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects}. @@ -2479,6 +2503,176 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope the flow filter rules in group_B, the flow filter rules of next level group_A are applied. \end{itemize} +\paragraph{Device and driver capabilities} +\label{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities} + +\subparagraph{VIRTIO_NET_FF_RESOURCE_CAP} +\label{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_RESOURCE_CAP} + +The capability VIRTIO_NET_FF_RESOURCE_CAP indicates the flow filter resource limits. +\field{cap_specific_data} is in the format +\field{struct virtio_net_ff_cap_data}. + +\begin{lstlisting} +struct virtio_net_ff_cap_data { + le32 groups_limit; + le32 selectors_limit; + le32 rules_limit; + le32 rules_per_group_limit; + u8 last_rule_priority; + u8 selectors_per_classifier_limit; +}; +\end{lstlisting} + +\field{groups_limit}, and \field{selectors_limit} represent the maximum +number of flow filter groups and selectors, respectively, that the driver can create. + \field{rules_limit} is the maximum number of +flow fiilter rules that the driver can create across all the groups. +\field{rules_per_group_limit} is the maximum number of flow filter rules that the driver +can create for each flow filter group. + +\field{last_rule_priority} is the highest priority that can be assigned to a +flow filter rule. + +\field{selectors_per_classifier_limit} is the maximum number of selectors +that a classifier can have. + +\subparagraph{VIRTIO_NET_FF_SELECTOR_CAP} +\label{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_SELECTOR_CAP} + +The capability VIRTIO_NET_FF_SELECTOR_CAP lists the supported selectors and the +supported packet header fields for each selector. +\field{cap_specific_data} is in the format \field{struct virtio_net_ff_cap_mask_data}. + +\begin{lstlisting}[label={lst:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_SELECTOR_CAP / virtio_net_ff_selector}] +struct virtio_net_ff_selector { + u8 type; + u8 flags; + u8 reserved[2]; + u8 length; + u8 reserved1[3]; + u8 mask[]; +}; + +struct virtio_net_ff_cap_mask_data { + u8 count; + u8 reserved[7]; + struct virtio_net_ff_selector selectors[]; +}; + +#define VIRTIO_NET_FF_MASK_F_PARTIAL_MASK (1 << 0) +\end{lstlisting} + +\field{count} indicates number of valid entries in the \field{selectors} array. +\field{selectors[]} is an array of supported selectors. Within each array entry: +\field{type} specifies the type of the packet header, as defined in table +\ref{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_SELECTOR_CAP / flow filter selector types}. \field{mask} specifies which fields of the +packet header can be matched in a flow filter rule. + +Each \field{type} is also listed in table +\ref{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_SELECTOR_CAP / flow filter selector types}. \field{mask} is a byte array +in network byte order. For example, when \field{type} is VIRTIO_NET_FF_MASK_TYPE_IPV6, +the \field{mask} is in the format \hyperref[intro:IPv6-Header-Format]{IPv6 Header Format}. + +If partial masking is not set, then all bits in each field have to be either all 0s +to ignore this field or all 1s to match on this field. If partial masking is set, +then any combination of bits can bit set to match on these bits. +For example, when a selector \field{type} is VIRTIO_NET_FF_MASK_TYPE_ETH, if +\field{mask[0-12]} are zero and \field{mask[13-14]} are 0xff (all 1s), it +indicates that matching is only supported for \field{EtherType} of +\field{Ethernet MAC frame}, matching is not supported for +\field{Destination Address} and \field{Source Address}. + +The entries in the array \field{selectors} are ordered by +\field{type}, with each \field{type} value only appearing once. + +\field{length} is the length of a dynamic array \field{mask} in bytes. +\field{reserved} and \field{reserved1} are reserved and set to zero. + +\begin{table}[H] +\caption{Flow filter selector types} +\label{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_SELECTOR_CAP / flow filter selector types} +\begin{tabularx}{\textwidth}{ |l|X|X| } +\hline +Type & Name & Description \\ +\hline \hline +0x0 & - & Reserved \\ +\hline +0x1 & VIRTIO_NET_FF_MASK_TYPE_ETH & 14 bytes of frame header starting from destination address described in \hyperref[intro:IEEE 802.3-2022]{IEEE 802.3-2022} \\ +\hline +0x2 & VIRTIO_NET_FF_MASK_TYPE_IPV4 & 20 bytes of \hyperref[intro:Internet-Header-Format]{IPv4: Internet Header Format} \\ +\hline +0x3 & VIRTIO_NET_FF_MASK_TYPE_IPV6 & 40 bytes of \hyperref[intro:IPv6-Header-Format]{IPv6 Header Format} \\ +\hline +0x4 & VIRTIO_NET_FF_MASK_TYPE_TCP & 20 bytes of \hyperref[intro:TCP-Header-Format]{TCP Header Format} \\ +\hline +0x5 & VIRTIO_NET_FF_MASK_TYPE_UDP & 8 bytes of UDP header described in \hyperref[intro:UDP]{UDP} \\ +\hline +0x6 - 0xFF & & Reserved for future \\ +\hline +\end{tabularx} +\end{table} + +When VIRTIO_NET_FF_MASK_F_PARTIAL_MASK (bit 0) is set, it indicates that +partial masking is supported for all the fields of the selector identified by \field{type}. + +For the selector \field{type} VIRTIO_NET_FF_MASK_TYPE_IPV4, if a partial mask is unsupported, +then matching on an individual bit of \field{Flags} in the +\field{IPv4: Internet Header Format} is unsupported. \field{Flags} has to match as a whole +if it is supported. + +For the selector \field{type} VIRTIO_NET_FF_MASK_TYPE_IPV4, \field{mask} includes fields +up to the \field{Destination Address}; that is, \field{Options} and +\field{Padding} are excluded. + +For the selector \field{type} VIRTIO_NET_FF_MASK_TYPE_IPV6, the \field{Next Header} field +of the \field{mask} corresponds to the \field{Next Header} in the packet +when \field{IPv6 Extension Headers} are not present. When the packet includes +one or more \field{IPv6 Extension Headers}, the \field{Next Header} field of +the \field{mask} corresponds to the \field{Next Header} of the last +\field{IPv6 Extension Header} in the packet. + +For the selector \field{type} VIRTIO_NET_FF_MASK_TYPE_TCP, \field{Control bits} +are treated as individual fields for matching; that is, matching individual +\field{Control bits} does not depend on the partial mask support. + +\subparagraph{VIRTIO_NET_FF_ACTION_CAP} +\label{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_ACTION_CAP} + +The capability VIRTIO_NET_FF_ACTION_CAP lists the supported actions in a rule. +\field{cap_specific_data} is in the format \field{struct virtio_net_ff_cap_actions}. + +\begin{lstlisting} +struct virtio_net_ff_actions { + u8 count; + u8 reserved[7]; + u8 actions[]; +}; +\end{lstlisting} + +\field{actions} is an array listing all possible actions. +The entries in the array are ordered from the smallest to the largest, +with each supported value appearing exactly once. Each entry can have the +following values: + +\begin{table}[H] +\caption{Flow filter rule actions} +\label{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_ACTION_CAP / flow filter rule actions} +\begin{tabularx}{\textwidth}{ |l|X|X| } +\hline +Action & Name & Description \\ +\hline \hline +0x0 & - & reserved \\ +\hline +0x1 & VIRTIO_NET_FF_ACTION_DROP & Matching packet will be dropped by the device \\ +\hline +0x2 & VIRTIO_NET_FF_ACTION_DIRECT_RX_VQ & Matching packet will be directed to a receive queue \\ +\hline +0x3 - 0xFF & & Reserved for future \\ +\hline +\end{tabularx} +\end{table} + \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device Types / Network Device / Legacy Interface: Framing Requirements} diff --git a/introduction.tex b/introduction.tex index bd58493..1a91152 100644 --- a/introduction.tex +++ b/introduction.tex @@ -59,6 +59,10 @@ \section{Normative References}\label{sec:Normative References} IEEE Standard for Local and Metropolitan Area Networks: Overview and Architecture, \newline\url{http://www.ieee802.org/}, IEEE\\ + \phantomsection\label{intro:IEEE 802.3-2022}\textbf{[IEEE 802.3-2022]} & + IEEE Standard for Ethernet, + \newline\url{https://doi.org/10.1109/IEEESTD.2022.9844436}, + IEEE 802.3-2022\\ \phantomsection\label{intro:SAM}\textbf{[SAM]} & SCSI Architectural Model, \newline\url{http://www.t10.org/cgi-bin/ac.pl?t=f&f=sam4r05.pdf}\\ @@ -135,12 +139,21 @@ \section{Normative References}\label{sec:Normative References} \phantomsection\label{intro:IP}\textbf{[IP]} & INTERNET PROTOCOL \newline\url{https://www.rfc-editor.org/rfc/rfc791}\\ + \phantomsection\label{intro:Internet-Header-Format}\textbf{[Internet Header Format]} & + Internet Header Format + \newline\url{https://datatracker.ietf.org/doc/html/rfc791#section-3.1}\\ + \phantomsection\label{intro:IPv6-Header-Format}\textbf{[IPv6 Header Format]} & + IPv6 Header Format + \newline\url{https://www.rfc-editor.org/rfc/rfc8200#section-3}\\ \phantomsection\label{intro:UDP}\textbf{[UDP]} & User Datagram Protocol \newline\url{https://www.rfc-editor.org/rfc/rfc768}\\ \phantomsection\label{intro:TCP}\textbf{[TCP]} & TRANSMISSION CONTROL PROTOCOL \newline\url{https://www.rfc-editor.org/rfc/rfc793}\\ + \phantomsection\label{intro:TCP-Header-Format}\textbf{[TCP Header Format]} & + TCP Header Format + \newline\url{https://www.rfc-editor.org/rfc/rfc9293#name-header-format}\\ \phantomsection\label{intro:CAN}\textbf{[CAN]} & ISO 11898-1:2015 Road vehicles -- Controller area network (CAN) -- Part 1: Data link layer and physical signalling\\ \phantomsection\label{intro:rfc8174}\textbf{[RFC8174]} & From 224e98b0f53c136b798b4d5ea073b5a0f5fb3ed1 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Tue, 4 Jun 2024 16:29:00 +0300 Subject: [PATCH 29/62] virtio-net: Add flow filter group, classifier and rule resource objects Flow filter rules depend on the flow filter group resource object. The device can have one or more flow filter groups. Each flow filter group has its own order. The group order defines the packet processing order in the flow filter domain. Define flow filter classifier object which consists of one or multiple types of packet header fields to consider for matching. A mask can match on partial field or whole field if the device supports partial masking for a given mask type. Define flow filter rule resource which consists of match key, reference to group and mask objects and an action. Currently it covers the most common filter types and value of Ethernet header, IPV4 and IPV6 headers and TCP and UDP headers. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179 Signed-off-by: Parav Pandit Signed-off-by: Heng Qi Signed-off-by: Michael S. Tsirkin Acked-by: Satananda Burla Message-Id: <20240604132903.2093195-11-parav@nvidia.com> Signed-off-by: Michael S. Tsirkin --- device-types/net/description.tex | 173 +++++++++++++++++++++++++++++++ introduction.tex | 8 ++ 2 files changed, 181 insertions(+) diff --git a/device-types/net/description.tex b/device-types/net/description.tex index faa0e5b..8560df9 100644 --- a/device-types/net/description.tex +++ b/device-types/net/description.tex @@ -417,6 +417,22 @@ \subsection{Device and driver capabilities}\label{sec:Device Types / Network Dev \hline \end{tabularx} +\subsection{Device resource objects}\label{sec:Device Types / Network Device / Device resource objects} + +The network device has the following resource objects. + +\begin{tabularx}{\textwidth}{ |l||l|X| } +\hline +type & Name & Description \\ +\hline \hline +0x0200 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO_NET_RESOURCE_OBJ_FF_GROUP]{VIRTIO_NET_RESOURCE_OBJ_FF_GROUP} & Flow filter group resource object \\ +\hline +0x0201 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER]{VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER} & Flow filter mask object \\ +\hline +0x0202 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO_NET_RESOURCE_OBJ_FF_RULE]{VIRTIO_NET_RESOURCE_OBJ_FF_RULE} & Flow filter rule object \\ +\hline +\end{tabularx} + \subsection{Device Operation}\label{sec:Device Types / Network Device / Device Operation} Packets are transmitted by placing them in the @@ -2673,6 +2689,163 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope \end{tabularx} \end{table} +\paragraph{Resource objects} +\label{par:Device Types / Network Device / Device Operation / Flow filter / Resource objects} + +\subparagraph{VIRTIO_NET_RESOURCE_OBJ_FF_GROUP}\label{par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO_NET_RESOURCE_OBJ_FF_GROUP} + +A flow filter group contains between 0 and \field{rules_limit} rules, as specified by the +capability VIRTIO_NET_FF_RESOURCE_CAP. For the flow filter group object both +\field{resource_obj_specific_data} and +\field{resource_obj_specific_result} are in the format +\field{struct virtio_net_resource_obj_ff_group}. + +\begin{lstlisting} +struct virtio_net_resource_obj_ff_group { + le16 group_priority; +}; +\end{lstlisting} + +\field{group_priority} specifies the priority for the group. Each group has a +distinct priority. For each incoming packet, the device tries to apply rules +from groups from higher \field{group_priority} value to lower, until either a +rule matches the packet or all groups have been tried. + +\subparagraph{VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER}\label{par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER} + +A classifier is used to match a flow filter key against a packet. The +classifier defines the desired packet fields to match, and is represented by +the VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER device resource object. + +For the flow filter classifier object both \field{resource_obj_specific_data} and +\field{resource_obj_specific_result} are in the format +\field{struct virtio_net_resource_obj_ff_classifier}. + +\begin{lstlisting} +struct virtio_net_resource_obj_ff_classifier { + u8 count; + u8 reserved[7]; + struct virtio_net_ff_selector selectors[]; +}; +\end{lstlisting} + +A classifier is an array of \field{selectors}. The number of selectors in the +array is indicated by \field{count}. The selector has a type that specifies +the header fields to be matched against, and a mask. +See \ref{lst:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_SELECTOR_CAP / virtio_net_ff_selector} +for details about selectors. + +The first selector is always VIRTIO_NET_FF_MASK_TYPE_ETH. When there are multiple +selectors, a second selector can be either VIRTIO_NET_FF_MASK_TYPE_IPV4 +or VIRTIO_NET_FF_MASK_TYPE_IPV6. If the third selector exists, the third +selector can be either VIRTIO_NET_FF_MASK_TYPE_UDP or VIRTIO_NET_FF_MASK_TYPE_TCP. +For example, to match a Ethernet IPv6 UDP packet, +\field{selectors[0].type} is set to VIRTIO_NET_FF_MASK_TYPE_ETH, \field{selectors[1].type} +is set to VIRTIO_NET_FF_MASK_TYPE_IPV6 and \field{selectors[2].type} is +set to VIRTIO_NET_FF_MASK_TYPE_UDP; accordingly, \field{selectors[0].mask[0-13]} is +for Ethernet header fields, \field{selectors[1].mask[0-39]} is set for IPV6 header +and \field{selectors[2].mask[0-7]} is set for UDP header. + +When there are multiple selectors, the type of the (N+1)\textsuperscript{th} selector +affects the mask of the (N)\textsuperscript{th} selector. If +\field{count} is 2 or more, all the mask bits within \field{selectors[0]} +corresponding to \field{EtherType} of an Ethernet header are set. + +If \field{count} is more than 2: +\begin{itemize} +\item if \field{selector[1].type} is, VIRTIO_NET_FF_MASK_TYPE_IPV4, then, all the mask bits within +\field{selector[1]} for \field{Protocol} is set. +\item if \field{selector[1].type} is, VIRTIO_NET_FF_MASK_TYPE_IPV6, then, all the mask bits within +\field{selector[1]} for \field{Next Header} is set. +\end{itemize} + +If for a given packet header field, a subset of bits of a field is to be matched, +and if the partial mask is supported, the flow filter +mask object can specify a mask which has fewer bits set than the packet header +field size. For example, a partial mask for the Ethernet header source mac +address can be of 1-bit for multicast detection instead of 48-bits. + +\subparagraph{VIRTIO_NET_RESOURCE_OBJ_FF_RULE}\label{par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO_NET_RESOURCE_OBJ_FF_RULE} + +Each flow filter rule resource object comprises a key, a priority, and an action. +For the flow filter rule object, +\field{resource_obj_specific_data} and +\field{resource_obj_specific_result} are in the format +\field{struct virtio_net_resource_obj_ff_rule}. + +\begin{lstlisting} +struct virtio_net_resource_obj_ff_rule { + le32 group_id; + le32 classifier_id; + u8 rule_priority; + u8 key_length; /* length of key in bytes */ + u8 action; + u8 reserved; + le16 vq_index; + u8 reserved1[2]; + u8 keys[][]; +}; +\end{lstlisting} + +\field{group_id} is the resource object ID of the flow filter group to which +this rule belongs. \field{classifier_id} is the resource object ID of the +classifier used to match a packet against the \field{key}. + +\field{rule_priority} denotes the priority of the rule within the group +specified by the \field{group_id}. +Rules within the group are applied from the highest to the lowest priority +until a rule matches the packet and an +action is taken. Rules with the same priority can be applied in any order. + +\field{reserved} and \field{reserved1} are reserved and set to 0. + +\field{keys[][]} is an array of keys to match against packets, using +the classifier specified by \field{classifier_id}. Each entry (key) comprises +a byte array, and they are located one immediately after another. +The size (number of entries) of the array is exactly the same as that of +\field{selectors} in the classifier, or in other words, \field{count} +in the classifier. + +\field{key_length} specifies the total length of \field{keys} in bytes. +In other words, it equals the sum total of \field{length} of all +selectors in \field{selectors} in the classifier specified by +\field{classifier_id}. + +For example, if a classifier object's \field{selectors[0].type} is +VIRTIO_NET_FF_MASK_TYPE_ETH and \field{selectors[1].type} is +VIRTIO_NET_FF_MASK_TYPE_IPV6, +then selectors[0].length is 14 and selectors[1].length is 40. +Accordingly, the \field{key_length} is set to 54. +This setting indicates that the \field{key} array's length is 54 bytes +comprising a first byte array of 14 bytes for the +Ethernet MAC header in bytes 0-13, immediately followed by 40 bytes for the +IPv6 header in bytes 14-53. + +When there are multiple selectors in the classifier object, the key bytes +for (N)\textsuperscript{th} selector are set so that +(N+1)\textsuperscript{th} selector can be matched. + +If \field{count} is 2 or more, key bytes of \field{EtherType} +are set according to \hyperref[intro:IEEE 802 Ethertypes]{IEEE 802 Ethertypes} +for VIRTIO_NET_FF_MASK_TYPE_IPV4 or VIRTIO_NET_FF_MASK_TYPE_IPV6 respectively. + +If \field{count} is more than 2, when \field{selector[1].type} is +VIRTIO_NET_FF_MASK_TYPE_IPV4 or VIRTIO_NET_FF_MASK_TYPE_IPV6, key +bytes of \field{Protocol} or \field{Next Header} is set as per +\field{Protocol Numbers} defined \hyperref[intro:IANA Protocol Numbers]{IANA Protocol Numbers} +respectively. + +\field{action} is the action to take when a packet matches the +\field{key} using the \field{classifier_id}. Supported actions are described in +\ref{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_ACTION_CAP / flow filter rule actions}. + +\field{vq_index} specifies a receive virtqueue. When the \field{action} is set +to VIRTIO_NET_FF_ACTION_DIRECT_RX_VQ, and the packet matches the \field{key}, +the matching packet is directed to this virtqueue. + +Note that at most one action is ever taken for a given packet. If a rule is +applied and an action is taken, the action of other rules is not taken. + \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device Types / Network Device / Legacy Interface: Framing Requirements} diff --git a/introduction.tex b/introduction.tex index 1a91152..e60298a 100644 --- a/introduction.tex +++ b/introduction.tex @@ -63,6 +63,14 @@ \section{Normative References}\label{sec:Normative References} IEEE Standard for Ethernet, \newline\url{https://doi.org/10.1109/IEEESTD.2022.9844436}, IEEE 802.3-2022\\ + \phantomsection\label{intro:IEEE 802 Ethertypes}\textbf{[IEEE 802 Ethertypes]} & + IEEE 802 Ethertypes, + \newline\url{https://www.iana.org/assignments/ieee-802-numbers/ieee-802-numbers.xhtml}, + IANA\\ + \phantomsection\label{intro:IANA Protocol Numbers}\textbf{[IANA Protocol Numbers]} & + IANA Protocol Numbers, + \newline\url{https://www.iana.org/assignments/protocol-numbers}, + IANA\\ \phantomsection\label{intro:SAM}\textbf{[SAM]} & SCSI Architectural Model, \newline\url{http://www.t10.org/cgi-bin/ac.pl?t=f&f=sam4r05.pdf}\\ From 3b7b7371dbed3684b6e20ed78bcdae432079bcd3 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Tue, 4 Jun 2024 16:29:01 +0300 Subject: [PATCH 30/62] virtio-net: Add flow filter device and driver requirements Add device and driver flow filter requirements. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/179 Signed-off-by: Parav Pandit Signed-off-by: Heng Qi Acked-by: Satananda Burla Message-Id: <20240604132903.2093195-12-parav@nvidia.com> Signed-off-by: Michael S. Tsirkin --- device-types/net/description.tex | 174 ++++++++++++++++++++++++ device-types/net/device-conformance.tex | 1 + device-types/net/driver-conformance.tex | 1 + 3 files changed, 176 insertions(+) diff --git a/device-types/net/description.tex b/device-types/net/description.tex index 8560df9..29f1ee8 100644 --- a/device-types/net/description.tex +++ b/device-types/net/description.tex @@ -2846,6 +2846,180 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope Note that at most one action is ever taken for a given packet. If a rule is applied and an action is taken, the action of other rules is not taken. +\devicenormative{\paragraph}{Flow filter}{Device Types / Network Device / Device Operation / Flow filter} + +When the device supports flow filter operations, +\begin{itemize} +\item the device MUST set VIRTIO_NET_FF_RESOURCE_CAP, VIRTIO_NET_FF_SELECTOR_CAP +and VIRTIO_NET_FF_ACTION_CAP capability in the \field{supported_caps} in the +command VIRTIO_ADMIN_CMD_CAP_SUPPORT_QUERY. +\item the device MUST support the administration commands +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY, VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY, +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY for the resource types +VIRTIO_NET_RESOURCE_OBJ_FF_GROUP, VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER and +VIRTIO_NET_RESOURCE_OBJ_FF_RULE. +\end{itemize} + +When any of the VIRTIO_NET_FF_RESOURCE_CAP, VIRTIO_NET_FF_SELECTOR_CAP, or +VIRTIO_NET_FF_ACTION_CAP capability is disabled, the device SHOULD set +\field{status} to VIRTIO_ADMIN_STATUS_Q_INVALID_OPCODE for the commands +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY, VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY, +and VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY. These commands apply to the resource +\field{type} of VIRTIO_NET_RESOURCE_OBJ_FF_GROUP, VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER, and +VIRTIO_NET_RESOURCE_OBJ_FF_RULE. + +The device SHOULD set \field{status} to VIRTIO_ADMIN_STATUS_EINVAL for the +command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE when the resource \field{type} +is VIRTIO_NET_RESOURCE_OBJ_FF_GROUP, if a flow filter group already exists +with the supplied \field{group_priority}. + +The device SHOULD set \field{status} to VIRTIO_ADMIN_STATUS_ENOSPC for the +command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE when the resource \field{type} +is VIRTIO_NET_RESOURCE_OBJ_FF_GROUP, if the number of flow filter group +objects in the device exceeds the lower of the configured driver +capabilities \field{groups_limit} and \field{rules_per_group_limit}. + +The device SHOULD set \field{status} to VIRTIO_ADMIN_STATUS_ENOSPC for the +command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE when the resource \field{type} is +VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER, if the number of flow filter selector +objects in the device exceeds the configured driver capability +\field{selectors_limit}. + +The device SHOULD set \field{status} to VIRTIO_ADMIN_STATUS_EBUSY for the +command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY for a flow filter group when +the flow filter group has one or more flow filter rules depending on it. + +The device SHOULD set \field{status} to VIRTIO_ADMIN_STATUS_EBUSY for the +command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY for a flow filter classifier when +the flow filter classifier has one or more flow filter rules depending on it. + +The device SHOULD fail the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE for the +flow filter rule resource object if, +\begin{itemize} +\item \field{vq_index} is not a valid receive virtqueue index for +the VIRTIO_NET_FF_ACTION_DIRECT_RX_VQ action, +\item \field{priority} is greater than or equal to + \field{last_rule_priority}, +\item \field{id} is greater than or equal to \field{rules_limit} or + greater than or equal to \field{rules_per_group_limit}, whichever is lower, +\item the length of \field{keys} and the length of all the mask bytes of + \field{selectors[].mask} as referred by \field{classifier_id} differs, +\item the supplied \field{action} is not supported in the capability VIRTIO_NET_FF_ACTION_CAP. +\end{itemize} + +When the flow filter directs a packet to the virtqueue identified by +\field{vq_index} and if the receive virtqueue is reset, the device +MUST drop such packets. + +Upon applying a flow filter rule to a packet, the device MUST STOP any further +application of rules and cease applying any other steering configurations. + +For multiple flow filter groups, the device MUST apply the rules from +the group with the highest priority. If any rule from this group is applied, +the device MUST ignore the remaining groups. If none of the rules from the +highest priority group match, the device MUST apply the rules from +the group with the next highest priority, until either a rule matches or +all groups have been attempted. + +The device MUST apply the rules within the group from the highest to the +lowest priority until a rule matches the packet, and the device MUST take +the action. If an action is taken, the device MUST not take any other +action for this packet. + +The device MAY apply the rules with the same \field{rule_priority} in any +order within the group. + +The device MUST process incoming packets in the following order: +\begin{itemize} +\item apply the steering configuration received using control virtqueue + commands VIRTIO_NET_CTRL_RX, VIRTIO_NET_CTRL_MAC, and + VIRTIO_NET_CTRL_VLAN. +\item apply flow filter rules if any. +\item if no filter rule is applied, apply the steering configuration + received using the command VIRTIO_NET_CTRL_MQ_RSS_CONFIG + or according to automatic receive steering. +\end{itemize} + +When processing an incoming packet, if the packet is dropped at any stage, the device +MUST skip further processing. + +When the device drops the packet due to the configuration done using the control +virtqueue commands VIRTIO_NET_CTRL_RX or VIRTIO_NET_CTRL_MAC or VIRTIO_NET_CTRL_VLAN, +the device MUST skip flow filter rules for this packet. + +When the device performs flow filter match operations and if the operation +result did not have any match in all the groups, the receive packet processing +continues to next level, i.e. to apply configuration done using +VIRTIO_NET_CTRL_MQ_RSS_CONFIG command. + +The device MUST support the creation of flow filter classifier objects +using the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE with \field{flags} +set to VIRTIO_NET_FF_MASK_F_PARTIAL_MASK; +this support is required even if all the bits of the masks are set for +a field in \field{selectors}, provided that partial masking is supported +for the selectors. + +\drivernormative{\paragraph}{Flow filter}{Device Types / Network Device / Device Operation / Flow filter} + +The driver MUST enable VIRTIO_NET_FF_RESOURCE_CAP, VIRTIO_NET_FF_SELECTOR_CAP, +and VIRTIO_NET_FF_ACTION_CAP capabilities to use flow filter. + +The driver SHOULD NOT remove a flow filter group using the command +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY when one or more flow filter rules +depend on that group. The driver SHOULD only destroy the group after +all the associated rules have been destroyed. + +The driver SHOULD NOT remove a flow filter classifier using the command +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY when one or more flow filter rules +depend on the classifier. The driver SHOULD only destroy the classifier +after all the associated rules have been destroyed. + +The driver SHOULD NOT add multiple flow filter rules with the same +\field{rule_priority} within a flow filter group, as these rules MAY match +the same packet. The driver SHOULD assign different \field{rule_priority} +values to different flow filter rules if multiple rules may match a single +packet. + +For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, when creating a resource +of \field{type} VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER, the driver MUST set: +\begin{itemize} +\item \field{selectors[0].type} to VIRTIO_NET_FF_MASK_TYPE_ETH. +\item \field{selectors[1].type} to VIRTIO_NET_FF_MASK_TYPE_IPV4 or + VIRTIO_NET_FF_MASK_TYPE_IPV6 when \field{count} is more than 1, +\item \field{selectors[2].type} VIRTIO_NET_FF_MASK_TYPE_UDP or + VIRTIO_NET_FF_MASK_TYPE_TCP when \field{count} is more than 2. +\end{itemize} + +For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, when creating a resource +of \field{type} VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER, the driver MUST set: +\begin{itemize} +\item \field{selectors[0].mask} bytes to all 1s for the \field{EtherType} + when \field{count} is 2 or more. +\item \field{selectors[1].mask} bytes to all 1s for \field{Protocol} or \field{Next Header} + when \field{selector[1].type} is VIRTIO_NET_FF_MASK_TYPE_IPV4 or VIRTIO_NET_FF_MASK_TYPE_IPV6, + and when \field{count} is more than 2. +\end{itemize} + +For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, the resource \field{type} +VIRTIO_NET_RESOURCE_OBJ_FF_RULE, if the corresponding classifier object's +\field{count} is 2 or more, the driver MUST SET the \field{keys} bytes of +\field{EtherType} in accordance with +\hyperref[intro:IEEE 802 Ethertypes]{IEEE 802 Ethertypes} +for either VIRTIO_NET_FF_MASK_TYPE_IPV4 or VIRTIO_NET_FF_MASK_TYPE_IPV6. + +For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, when creating a resource of +\field{type} VIRTIO_NET_RESOURCE_OBJ_FF_RULE, if the corresponding classifier +object's \field{count} is more than 2, and the \field{selector[1].type} is either +VIRTIO_NET_FF_MASK_TYPE_IPV4 or VIRTIO_NET_FF_MASK_TYPE_IPV6, the driver MUST +set the \field{keys} bytes for the \field{Protocol} or \field{Next Header} +according to \hyperref[intro:IANA Protocol Numbers]{IANA Protocol Numbers} respectively. + +The driver SHOULD set all the bits for a field in the mask of a selector in both the +capability and the classifier object, unless the VIRTIO_NET_FF_MASK_F_PARTIAL_MASK +is enabled. + \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device Types / Network Device / Legacy Interface: Framing Requirements} diff --git a/device-types/net/device-conformance.tex b/device-types/net/device-conformance.tex index c71341e..d88484c 100644 --- a/device-types/net/device-conformance.tex +++ b/device-types/net/device-conformance.tex @@ -17,4 +17,5 @@ \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Inner Header Hash} \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics} \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / RSS Context} +\item \ref{devicenormative:Device Types / Network Device / Device Operation / Flow filter} \end{itemize} diff --git a/device-types/net/driver-conformance.tex b/device-types/net/driver-conformance.tex index 7081ec3..d346b88 100644 --- a/device-types/net/driver-conformance.tex +++ b/device-types/net/driver-conformance.tex @@ -17,4 +17,5 @@ \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Inner Header Hash} \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics} \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / RSS Context} +\item \ref{drivernormative:Device Types / Network Device / Device Operation / Flow filter} \end{itemize} From 9b3129fe72360a78e76b6dd890d3abc5a45fa915 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20Kr=C3=B6ning?= Date: Thu, 6 Jun 2024 13:07:30 +0000 Subject: [PATCH 31/62] virtio_pci_cap64: specify offset_hi, length_hi endianness MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit While the capability introduction says "This virtio structure capability uses little-endian format," it might be preferrable to be explicit about the endianness of offset_hi and length_hi. Signed-off-by: Martin Kröning Reviewed-by: Parav Pandit Fixes: https://github.com/oasis-tcs/virtio-spec/issues/196 Message-Id: Signed-off-by: Michael S. Tsirkin --- transport-pci.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/transport-pci.tex b/transport-pci.tex index a5c6719..95b08b8 100644 --- a/transport-pci.tex +++ b/transport-pci.tex @@ -252,8 +252,8 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option \begin{lstlisting} struct virtio_pci_cap64 { struct virtio_pci_cap cap; - u32 offset_hi; - u32 length_hi; + le32 offset_hi; + le32 length_hi; }; \end{lstlisting} From 67141d1cb0fe0ff4bc5b82a60688db080617d181 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Sat, 1 Jun 2024 17:50:38 +0300 Subject: [PATCH 32/62] admin: Add theory of operation for device parts A device can get and set the state of the device which is organized as multiple device parts. This can be useful in cases of VM snapshot, VM migration, debug or some other use cases. Add the theory of operations on how to get/set device parts and how it affects when the device is stopped or resumed. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/176 Signed-off-by: Michael S. Tsirkin Signed-off-by: Parav Pandit Message-Id: <20240601145042.2074739-2-parav@nvidia.com> --- admin-cmds-capabilities.tex | 16 +++++++++++ admin-cmds-device-parts.tex | 55 +++++++++++++++++++++++++++++++++++++ admin.tex | 1 + 3 files changed, 72 insertions(+) create mode 100644 admin-cmds-device-parts.tex diff --git a/admin-cmds-capabilities.tex b/admin-cmds-capabilities.tex index 8119a56..9865254 100644 --- a/admin-cmds-capabilities.tex +++ b/admin-cmds-capabilities.tex @@ -51,6 +51,22 @@ \subsubsection{Device and driver capabilities}\label{sec:Basic Facilities of a V \end{tabularx} \end{table} +Common capabilities are listed: + +\begin{table}[H] +\caption{Common capability ids} +\label{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / Common capability ids} +\begin{tabularx}{\textwidth}{ |l|l|X| } +\hline +Id & Name & Description \\ +\hline \hline +0x0000 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO_DEV_PARTS_CAP]{VIRTIO_DEV_PARTS_CAP} & Device parts capability \\ +\hline +0x0001-0x07ff & - & Generic capability for all device types \\ +\hline +\end{tabularx} +\end{table} + Device type specific capabilities are described separately for each device type under \field{Device and driver capabilities}. diff --git a/admin-cmds-device-parts.tex b/admin-cmds-device-parts.tex new file mode 100644 index 0000000..9cec0ad --- /dev/null +++ b/admin-cmds-device-parts.tex @@ -0,0 +1,55 @@ +\subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts} + +In some systems, there is a need to capture the state of all or part of +a device and subsequently restore either the same device or a +different one to this captured state. A group owner device can support +administration commands to facilitate these get and set operations for +the group member devices. + +For example, a hypervisor can use the administration commands to +capture parts of the device state and save the result as part of +a VM snapshot. Later, the hypervisor can retrieve the snapshot and use the +administration commands to restore parts of a device to resume +VM operation. + +As another example, these commands can be used to facilitate VM migration by the +hypervisor: one (source) hypervisor can get parts of a device and send +the results to another (destination) hypervisor, which will in turn +set (restore) parts of (another) device to resume the VM operation on +the destination. + +The device comprises many device parts which the driver can get and set. +Administration commands are provided to either get and set all the device +parts at once, or to get the device parts metadata that indicates which +device parts are present, and later to get and set specific device parts. +To get and set the device parts or their metadata, the driver first creates a +device parts resource object, indicating whether the object should +handle get or set operations but not both simultaneously. The device and the +driver indicate the device parts resource objects' limit using the capability +VIRTIO_DEV_PARTS_CAP. + +The device can be stopped to prevent device parts from changing. +When the device is stopped, it does not initiate any transport requests. +For instance, the device refrains from sending any configuration or +virtqueue notifications and does not access any virtqueues or the driver's +buffer memory. While the driver may remain active and continue to send +notifications to the device, potentially updating some device parts, +the device itself will not initiate any transport requests. + +\paragraph{VIRTIO_DEV_PARTS_CAP} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO_DEV_PARTS_CAP} + +The capability VIRTIO_DEV_PARTS_CAP indicates the device parts resource objects limit. +\field{cap_specific_data} is in the format \field{struct virtio_dev_parts_cap}. + +\begin{lstlisting} +struct virtio_dev_parts_cap { + u8 get_parts_resource_objects_limit; + u8 set_parts_resource_objects_limit; +}; +\end{lstlisting} + +\field{get_parts_resource_objects_limit} indicates the supported device parts +resource objects for retrieving the device parts. +\field{set_parts_resource_objects_limit} indicates the supported device parts +resource objects for restoring the device parts. diff --git a/admin.tex b/admin.tex index 5b908ae..8ac74aa 100644 --- a/admin.tex +++ b/admin.tex @@ -328,6 +328,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-resource-objects.tex} +\input{admin-cmds-device-parts.tex} \devicenormative{\subsubsection}{Group administration commands}{Basic Facilities of a Virtio Device / Device groups / Group administration commands} From a1281addd9b247300f64a2c818ff50eeb76a0dbd Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Sat, 1 Jun 2024 17:50:39 +0300 Subject: [PATCH 33/62] admin: Extend resource objects for sr-iov group type occasionally the group owner device accesses the device parts of the member device. Extend the usage of resource objects for member device parts access. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/176 Signed-off-by: Parav Pandit Message-Id: <20240601145042.2074739-3-parav@nvidia.com> --- admin-cmds-resource-objects.tex | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/admin-cmds-resource-objects.tex b/admin-cmds-resource-objects.tex index 291f7e6..3eae87d 100644 --- a/admin-cmds-resource-objects.tex +++ b/admin-cmds-resource-objects.tex @@ -69,7 +69,9 @@ \subsubsection{Device resource objects}\label{sec:Basic Facilities of a Virtio D all resource objects created by the driver are destroyed within the device. Following administration commands control device resource objects, -they are only supported for the self group type: +they are supported for the self group type, occasionally some resource +objects can be created for the SR-IOV group type as well. Such sr-iov group +type specific resource objects are listed where such objects is defined. \begin{enumerate} \item VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE @@ -102,7 +104,8 @@ \subsubsection{Device resource objects}\label{sec:Basic Facilities of a Virtio D for the resource for the specified \field{type}. For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, \field{opcode} is set to 0xa. -\field{group_member_id} is set to zero. +\field{group_member_id} is set to zero for self-group type and set to +the member device to be accessed for the SR-IOV group type. The \field{command_specific_data} is in the format \field{struct virtio_admin_cmd_resource_obj_create_data}. \field{resource_obj_specific_data} refers to the resource object specific data. @@ -132,7 +135,8 @@ \subsubsection{Device resource objects}\label{sec:Basic Facilities of a Virtio D For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY, \field{opcode} is set to 0xb. The \field{command_specific_data} is in the format \field{struct virtio_admin_cmd_resource_modify_data}. -\field{group_member_id} is set to zero. +\field{group_member_id} is set to zero for self-group type and set to +the member device to be accessed for the SR-IOV group type. \field{id} identifies the resource object of type \field{type} whose attributes to modify. This command modifies the attributes supplied in \field{resource_obj_specific_data}. @@ -154,7 +158,8 @@ \subsubsection{Device resource objects}\label{sec:Basic Facilities of a Virtio D This command queries attributes of the existing resource object. For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY, \field{opcode} is set to 0xc. -\field{group_member_id} is set to zero. +\field{group_member_id} is set to zero for self-group type and set to +the member device to be accessed for the SR-IOV group type. The \field{command_specific_data} is in the format \field{struct virtio_admin_cmd_resource_obj_query_data}. \field{id} identifies the existing resource object of type \field{type} whose @@ -186,7 +191,8 @@ \subsubsection{Device resource objects}\label{sec:Basic Facilities of a Virtio D For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY, \field{opcode} is set to 0xd. The \field{command_specific_data} is in the format \field{struct virtio_admin_cmd_resource_obj_cmd_hdr}. -\field{group_member_id} is set to zero. +\field{group_member_id} is set to zero for self-group type and set to +the member device to be accessed for the SR-IOV group type. \field{id} identifies the existing resource object of type \field{type}. This command destroys the specified resource object of \field{type} identified From aa4f6f069ab3e9f4e3b014cec21c9ae52ecbda59 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Sat, 1 Jun 2024 17:50:40 +0300 Subject: [PATCH 34/62] admin: Add admin commands for device parts Add administration commands to handle device parts such as get/set device parts, get metadata of the device parts, Fixes: https://github.com/oasis-tcs/virtio-spec/issues/176 Signed-off-by: Parav Pandit Message-Id: <20240601145042.2074739-4-parav@nvidia.com> --- admin-cmds-device-parts.tex | 229 ++++++++++++++++++++++++++++++++ admin-cmds-resource-objects.tex | 13 ++ admin.tex | 11 +- 3 files changed, 252 insertions(+), 1 deletion(-) diff --git a/admin-cmds-device-parts.tex b/admin-cmds-device-parts.tex index 9cec0ad..36a45d3 100644 --- a/admin-cmds-device-parts.tex +++ b/admin-cmds-device-parts.tex @@ -53,3 +53,232 @@ \subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Dev resource objects for retrieving the device parts. \field{set_parts_resource_objects_limit} indicates the supported device parts resource objects for restoring the device parts. + +\paragraph{VIRTIO_RESOURCE_OBJ_DEV_PARTS}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO_RESOURCE_OBJ_DEV_PARTS} + +A device parts resource object is used to either get or set the device parts. +Before performing any get or set operation for the device parts, the driver +creates the device parts resource object +VIRTIO_RESOURCE_OBJ_DEV_PARTS using the administration command +\hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE}. +The driver indicates the intended purpose (get or set) at the time of creating the +device parts resource object. +For the device parts resource object, both \field{resource_obj_specific_data} and +\field{resource_obj_specific_result} are in the format +\field{struct virtio_resource_obj_dev_parts}. + +\begin{lstlisting} +struct virtio_resource_obj_dev_parts { + u8 type; +#define VIRTIO_RESOURCE_OBJ_DEV_PARTS_TYPE_GET 0 +#define VIRTIO_RESOURCE_OBJ_DEV_PARTS_TYPE_SET 1 + u8 reserved[7]; +}; +\end{lstlisting} + +When \field{type} is set to VIRTIO_RESOURCE_OBJ_DEV_PARTS_TYPE_GET, +the driver can use the object to capture the device parts and the metadata of +these device parts. When \field{type} is set to +VIRTIO_RESOURCE_OBJ_DEV_PARTS_TYPE_SET, the driver can use the +object to restore the device parts. + +\paragraph{Device parts handling commands}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands} + +The owner driver uses the following resource object handling administration +commands. These commands are only used for the device parts resource +object after the driver creates the VIRTIO_RESOURCE_OBJ_DEV_PARTS object. +These commands are currently only defined for the SR-IOV group type: + +\begin{enumerate} +\item VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET +\item VIRTIO_ADMIN_CMD_DEV_PARTS_GET +\item VIRTIO_ADMIN_CMD_DEV_PARTS_SET +\end{enumerate} + +\subparagraph{VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET} + +This command obtains the metadata of the device parts. This metadata includes +the maximum size of the device parts, the count of device parts, and a list of +the device part headers. + +For the command VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET, \field{opcode} is set +to 0xe. The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_dev_parts_metadata_data}. +\field{group_member_id} refers to the member device to be accessed. +The resource object \field{type} in the \field{hdr} is set to +VIRTIO_RESOURCE_OBJ_DEV_PARTS and \field{id} is set to the ID of the +device parts resource object. + +\begin{lstlisting} +struct virtio_admin_cmd_dev_parts_metadata_data { + struct virtio_admin_cmd_resource_obj_cmd_hdr hdr; + u8 type; + u8 reserved[7]; +}; + +#define VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_SIZE 0 +#define VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_COUNT 1 +#define VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_LIST 2 + +struct virtio_admin_cmd_dev_parts_metadata_result { + union { + struct { + le32 size; + le32 reserved; + } parts_size; + struct { + le32 count; + le32 reserved; + } hdr_list_count; + { + le32 count; + le32 reserved; + struct virtio_dev_part_hdr hdrs[]; + } hdr_list; + }; +}; +\end{lstlisting} + +When the command completes successfully, the +\field{command_specific_result} is in the format +\field{struct virtio_admin_cmd_dev_parts_metadata_result}. + +When \field{type} is set to VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_SIZE, +the device responds with \field{parts_size}. \field{parts_size.size} indicates +the maximum size in bytes for all the device parts. + +When \field{type} is set to VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_COUNT, the +device responds with \field{hdr_list_count.count}. The +\field{hdr_list_count.count} indicates an count of +\field{struct virtio_dev_part_hdr} metadata entries that the device can +provide when the \field{type} is set to VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_HDR +in a subsequent VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET command. + +When \field{type} is set to VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_HDR, +the device responds with \field{hdr_list}. \field{hdr_list} +indicates the device parts metadata. + +\field{reserved} is reserved and set to 0. + +The command responds with the \field{status} VIRTIO_ADMIN_STATUS_ENOMEM +when the size of \field{command_specific_result} is not sufficient enough +for the response. + +\subparagraph{VIRTIO_ADMIN_CMD_DEV_PARTS_GET} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO_ADMIN_CMD_DEV_PARTS_GET} + +This command captures the device parts. For the command +VIRTIO_ADMIN_CMD_DEV_PARTS_GET, \field{opcode} is set to 0xf. +The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_dev_parts_get_data}. +\field{group_member_id} refers to the member device to be accessed. +The resource object \field{type} in the \field{hdr} is set to +VIRTIO_RESOURCE_OBJ_DEV_PARTS and \field{id} is set to the ID of the +device parts resource object. + +\begin{lstlisting} +struct virtio_admin_cmd_dev_parts_get_data { + struct virtio_admin_cmd_resource_obj_cmd_hdr hdr; + u8 type; + u8 reserved[7]; + struct virtio_dev_part_hdr hdr_list[]; +}; + +#define VIRTIO_ADMIN_CMD_DEV_PARTS_GET_TYPE_SELECTED 0 +#define VIRTIO_ADMIN_CMD_DEV_PARTS_GET_TYPE_ALL 1 + +struct virtio_admin_cmd_dev_parts_get_result { + struct virtio_dev_part parts[]; +}; + +\end{lstlisting} + +When the driver wants to capture specific device parts, \field{type} is set to +VIRTIO_ADMIN_CMD_DEV_PARTS_GET_TYPE_SELECTED and \field{hdr_list} is set to the +device parts of interest. + +When the driver wants to retrieve all the device parts, \field{type} is set to +VIRTIO_ADMIN_CMD_DEV_PARTS_GET_TYPE_ALL, and \field{hdr_list} is empty. + +\field{reserved} is reserved and set to 0. + +When the command completes successfully, the \field{command_specific_result} is +in the format \field{struct virtio_admin_cmd_dev_parts_get_result}, containing +either the selected device parts or all the device parts. + +If the requested device part does not exist, the device skips the device part +without any error. + +\subparagraph{VIRTIO_ADMIN_CMD_DEV_PARTS_SET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO_ADMIN_CMD_DEV_PARTS_SET} + +This command sets one or multiple device parts. For the command +VIRTIO_ADMIN_CMD_DEV_PARTS_SET, \field{opcode} is set to 0x10. +The \field{group_member_id} refers to the member device to be accessed. +The resource object \field{type} in the \field{hdr} is set to +VIRTIO_RESOURCE_OBJ_DEV_PARTS and \field{id} is set to the ID of the +device parts resource object. + +\begin{lstlisting} +struct virtio_admin_cmd_dev_parts_set_data { + struct virtio_admin_cmd_resource_obj_cmd_hdr hdr; + struct virtio_dev_part parts[]; +}; +\end{lstlisting} + +The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_dev_parts_set_data}. + +This command has no command specific result. + +The driver stops the device before setting any device parts. + +When the command completes successfully, the device has updated device +parts to the value supplied in \field{virtio_admin_cmd_dev_parts_set_data}. + +The device parts set by this command take effect when the device is resumed +using the VIRTIO_ADMIN_CMD_DEV_MODE_SET command. + +When the command fails with a status other than VIRTIO_ADMIN_STATUS_OK, the +device does not have any side effects. + +\subparagraph{VIRTIO_ADMIN_CMD_DEV_MODE_SET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO_ADMIN_CMD_DEV_MODE_SET} + +This command either stops the device from initiating any transport requests or +resumes the device operation. For the command VIRTIO_ADMIN_CMD_DEV_MODE_SET, +\field{opcode} is set to 0x11. \field{group_member_id} indicates the member +device to be accessed. + +The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_dev_mode_set_data}. + +\begin{lstlisting} +struct virtio_admin_cmd_dev_mode_set_data { + u8 flags; +}; + +#define VIRTIO_ADMIN_CMD_DEV_MODE_F_STOPPED 0 +\end{lstlisting} + +This command has no command specific result. + +When the command completes successfully and if the \field{flags} field is set +to VIRTIO_ADMIN_CMD_DEV_MODE_F_STOPPED (bit 0), the device is stopped. +When the device is stopped, the device stops initiating all transport +communications, which includes: + +\begin{enumerate} +\item stopping configuration change notifications +\item stopping all virtqueue notifications +\item stops accessing all virtqueues and the driver buffer memory +\end{enumerate} + +After the device is stopped, the device parts remain unchanged unless +the driver initiates any transport requests. + +When the device is stopped, it writes back any associated descriptors for all +observed buffers to prevent out-of-order processing if the device is resumed. + +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. diff --git a/admin-cmds-resource-objects.tex b/admin-cmds-resource-objects.tex index 3eae87d..388aa69 100644 --- a/admin-cmds-resource-objects.tex +++ b/admin-cmds-resource-objects.tex @@ -63,6 +63,19 @@ \subsubsection{Device resource objects}\label{sec:Basic Facilities of a Virtio D \hline \end{tabular} +Following generic resource objects are defined which are described separately. + +\begin{xltabular}{\textwidth}{ |X||X|X| } +\hline +Resource object type & Name & Description \\ +\hline \hline +0x000 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO_RESOURCE_OBJ_DEV_PARTS]{VIRTIO_RESOURCE_OBJ_DEV_PARTS} & Device parts object \\ +\hline +0x001-0x1ff & - & Generic resource object range reserved \\ +\hline +\hline +\end{xltabular} + When the device resets, it starts with zero resources of each type; the driver can create resources up to the published \field{limit}. The driver can destroy and recreate the resource one or multiple times. Upon device reset, diff --git a/admin.tex b/admin.tex index 8ac74aa..d60d6f1 100644 --- a/admin.tex +++ b/admin.tex @@ -150,7 +150,16 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti \hline 0x000d & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY} & Destroy a device resource object \\ \hline -0x000e - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd} \\ +0x000e & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET]{VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET} & Get the metadata of the device parts \\ +\hline +0x000f & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO_ADMIN_CMD_DEV_PARTS_GET]{VIRTIO_ADMIN_CMD_DEV_PARTS_GET} & Get the device parts \\ +\hline +0x0010 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO_ADMIN_CMD_DEV_PARTS_SET]{VIRTIO_ADMIN_CMD_DEV_PARTS_SET} & Set the device parts \\ +\hline +0x0011 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO_ADMIN_CMD_DEV_MODE_SET]{VIRTIO_ADMIN_CMD_DEV_MODE_SET} & Stop or resume the device \\ +\hline +\hline +0x0013 - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd} \\ \hline 0x8000 - 0xFFFF & - & Reserved for future commands (possibly using a different structure) \\ \hline From 617aa2d62a885450f6f634bddad80bf8afaa6915 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Sat, 1 Jun 2024 17:50:41 +0300 Subject: [PATCH 35/62] 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. [Parav Pandit: resolve conflict: editorial: empty blank line at end of file newdevice.tex] Fixes: https://github.com/oasis-tcs/virtio-spec/issues/176 Signed-off-by: Parav Pandit Message-Id: <20240601145042.2074739-5-parav@nvidia.com> --- admin-cmds-device-parts.tex | 37 ++++++ content.tex | 1 + device-parts.tex | 231 ++++++++++++++++++++++++++++++++++++ newdevice.tex | 24 +++- 4 files changed, 292 insertions(+), 1 deletion(-) 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 7ebd5fc..c32c218 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 ed0124b..4a71beb 100644 --- a/newdevice.tex +++ b/newdevice.tex @@ -65,4 +65,26 @@ \section{Device Improvements}\label{sec:Creating New Device Types / Device Impro 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. From 52d320c8b3c54ae035c0ddc1d23ae997cbfa13b2 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Sat, 1 Jun 2024 17:50:42 +0300 Subject: [PATCH 36/62] admin: Add requirements of device parts commands Add device and driver side requirements for the device parts related commands. Fixes: https://github.com/oasis-tcs/virtio-spec/issues/176 Signed-off-by: Parav Pandit Message-Id: <20240601145042.2074739-6-parav@nvidia.com> --- admin-cmds-device-parts.tex | 148 ++++++++++++++++++++++++++++++++++++ conformance.tex | 2 + 2 files changed, 150 insertions(+) diff --git a/admin-cmds-device-parts.tex b/admin-cmds-device-parts.tex index 05d2477..ab6e83b 100644 --- a/admin-cmds-device-parts.tex +++ b/admin-cmds-device-parts.tex @@ -319,3 +319,151 @@ \subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Dev \hline \end{xltabular} \end{table} + +\devicenormative{\subparagraph}{Device parts}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts} + +A device MUST either support all of, or none of +VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET, +VIRTIO_ADMIN_CMD_DEV_PARTS_GET, VIRTIO_ADMIN_CMD_DEV_PARTS_SET, +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY, VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY, and +VIRTIO_ADMIN_CMD_DEV_MODE_SET commands, where resource commands apply to +the resource object VIRTIO_RESOURCE_OBJ_DEV_PARTS. + +The device MUST support getting the device parts multiple times +with the command VIRTIO_ADMIN_CMD_DEV_PARTS_GET. + +When there are multiple device parts in the command +VIRTIO_ADMIN_CMD_DEV_PARTS_GET, the device MUST respond the device parts in the +same order as listed in the table +\hyperref[table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts order/ Device parts order]{device parts order}. + +The device SHOULD respond with an error status for the command +VIRTIO_ADMIN_CMD_DEV_PARTS_SET if the device is not stopped. + +The device MUST support the command VIRTIO_ADMIN_CMD_DEV_PARTS_SET, +allowing the same or different device parts to be set multiple times. + +The device MUST respond with an error for the command +VIRTIO_ADMIN_CMD_DEV_PARTS_SET, if there is a mismatch between the +device part length supplied in the VIRTIO_ADMIN_CMD_DEV_PARTS_SET +and the device part length in the device. + +The device MUST NOT set the device part VIRTIO_DEV_PART_DEV_FEATURES in +the command VIRTIO_ADMIN_CMD_DEV_PARTS_SET; instead, +it must verify that the device features supplied in +VIRTIO_DEV_PART_DEV_FEATURES match those the device has. + +The device may ignore the setting of a device part that has the +VIRTIO_DEV_PART_F_OPTIONAL bit set. + +For the SR-IOV group type, when the device is stopped using the command +VIRTIO_ADMIN_CMD_DEV_MODE_SET, +\begin{itemize} +\item the device MUST not initiate any PCI transaction, +\item the device MUST finish all the outstanding PCI transactions before completing + the command VIRTIO_ADMIN_CMD_DEV_MODE_SET, +\item the device MUST write any associated descriptors to the driver memory for + all the observed buffers, +\item the device MUST accept driver notifications and the device MAY update any + device parts, +\item the device MUST respond with valid values for PCI read requests, +\item the device MUST operate in the same way for the PCI architected interfaces + regardless of the device mode. +\item the device MUST not generate any PCI PME. +\end{itemize} + +When the device is stopped, +\begin{itemize} +\item the device MUST not access any virtqueue memory or any memory referred + by the virtqueue. +\item the device MUST not generate any configuration change notification + or any virtqueue notification. +\end{itemize} + +For the SR-IOV group type, +\begin{itemize} +\item the device MUST respond to the commands +VIRTIO_ADMIN_CMD_DEV_MODE_SET, VIRTIO_ADMIN_CMD_DEV_PARTS_SET +after the member device completes FLR, if the FLR is in progress on the device +when the device receives any of these commands. + +\item the member device MUST respond to the commands +VIRTIO_ADMIN_CMD_DEV_MODE_SET and VIRTIO_ADMIN_CMD_DEV_PARTS_SET +after the device reset completes in the device, if the +device reset is in progress when the device receives any of these commands. + +\item the member device MUST respond to commands +VIRTIO_ADMIN_CMD_DEV_MODE_SET and VIRTIO_ADMIN_CMD_DEV_PARTS_SET +after the device power management state +transition completes on the device, if the power management state transition +is in progress when the device receives any of these commands. +\end{itemize} + +When the \field{flags} is set to VIRTIO_ADMIN_CMD_DEV_MODE_FLAGS_STOPPED +in the command VIRTIO_ADMIN_CMD_DEV_MODE_SET, and if the device is already +stopped before, the device MUST complete the command successfully. + +When the VIRTIO_ADMIN_CMD_DEV_MODE_FLAGS_STOPPED \field{flags} clear, +in the command VIRTIO_ADMIN_CMD_DEV_MODE_SET, and if the device is +not stopped before, the device MUST complete the command successfully. + +For the SR-IOV group type, the device MUST clear all the device parts to +the default value when the member device is reset or undergo an PCI FLR. + +The device MAY NOT respond to the selected device part in \field{hdr_list} +in the command VIRTIO_ADMIN_CMD_DEV_PARTS_GET if the device part is invalid +in the device. + +For the commands VIRTIO_ADMIN_CMD_DEV_PARTS_GET and +VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET, when the device responds with: +\begin{itemize} +\item +VIRTIO_DEV_PART_DRV_FEATURES or VIRTIO_DEV_PART_PCI_COMMON_CFG, it MUST be +preceded by VIRTIO_DEV_PART_DEV_FEATURES. + +\item VIRTIO_DEV_PART_PCI_COMMON_CFG, it MUST be preceded by +VIRTIO_DEV_PART_DEV_FEATURES. + +\item VIRTIO_DEV_PART_PCI_COMMON_CFG, it MUST be preceded by +VIRTIO_DEV_PART_DEV_FEATURES and VIRTIO_DEV_PART_DRV_FEATURES. + +\item VIRTIO_DEV_PART_DEV_CFG, it MUST be preceded by VIRTIO_DEV_PART_DEV_FEATURES. + +\item VIRTIO_DEV_PART_DRV_CFG, it be preceded by VIRTIO_DEV_PART_DEV_FEATURES, +VIRTIO_DEV_PART_DRV_FEATURES and VIRTIO_DEV_PART_DEV_CFG. + +\item VIRTIO_DEV_PART_DEVICE_STAtUS, it is preceded by VIRTIO_DEV_PART_DEV_FEATURES, +VIRTIO_DEV_PART_DRV_FEATURES, and VIRTIO_DEV_PART_DEV_CFG. +\end{itemize} + +When the device receives a VIRTIO_ADMIN_CMD_DEV_PARTS_SET command containing the +parts VIRTIO_DEV_PART_DEV_FEATURES, VIRTIO_DEV_PART_PCI_COMMON_CFG and +VIRTIO_DEV_PART_DEV_CFG, the device SHOULD only verify that the provided configuration is +correct but SHOULD NOT apply it, especially for the fields that are designated +as read-only and invariant. This ensures that the device respects the +immutability of certain configuration aspects while still performing necessary +validation checks. + +\drivernormative{\subparagraph}{Device parts}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts} + +The driver MUST set the mode to VIRTIO_ADMIN_CMD_DEV_MODE_F_STOPPED in +the command VIRTIO_ADMIN_CMD_DEV_MODE_SET before setting parts using the command +VIRTIO_ADMIN_CMD_DEV_PARTS_SET. + +When there are multiple device parts in the command +VIRTIO_ADMIN_CMD_DEV_PARTS_SET, the driver MUST set the device parts in the same +order as listed in the table +\hyperref[table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts order/ Device parts order]{device parts order}. + +For the SR-IOV group type, the driver SHOULD NOT access the device configuration +space described in section +\ref{sec:Basic Facilities of a Virtio Device / Device Configuration Space} +when the device is stopped. + +The driver SHOULD allocate sufficient response buffer to receive all the device +parts metadata in the command VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET. + +The driver SHOULD allocate sufficient response buffer to receive all the device +parts in the command VIRTIO_ADMIN_CMD_DEV_PARTS_GET. diff --git a/conformance.tex b/conformance.tex index 297b78a..d92a236 100644 --- a/conformance.tex +++ b/conformance.tex @@ -101,6 +101,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \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 resource objects} +\item \ref{drivernormative:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts} \end{itemize} \conformance{\subsection}{PCI Driver Conformance}\label{sec:Conformance / Driver Conformance / PCI Driver Conformance} @@ -185,6 +186,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \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 resource objects} +\item \ref{devicenormative:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts} \end{itemize} \conformance{\subsection}{PCI Device Conformance}\label{sec:Conformance / Device Conformance / PCI Device Conformance} From 24e93e10fdd4f60350aa42e9b83cd72b47ae5a31 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Sun, 14 Jul 2024 17:20:36 +0300 Subject: [PATCH 37/62] editorial: replace hyperref with ref Replace hyperreference with the name reference. Fix the broken reference link for the DEVICE_STATUS part. Fixes: aa4f6f069ab3 ("admin: Add admin commands for device parts") Fixes: 617aa2d62a88 ("admin: Define common device parts") Suggested-by: Michael S. Tsirkin Signed-off-by: Parav Pandit Message-Id: <20240714144023.3291803-1-parav@vr-arch-host06.mtvr.labs.mlnx> Signed-off-by: Michael S. Tsirkin --- admin-cmds-device-parts.tex | 6 +++--- admin-cmds-resource-objects.tex | 2 +- device-parts.tex | 21 +++++++++++---------- 3 files changed, 15 insertions(+), 14 deletions(-) diff --git a/admin-cmds-device-parts.tex b/admin-cmds-device-parts.tex index ab6e83b..ad3f8e3 100644 --- a/admin-cmds-device-parts.tex +++ b/admin-cmds-device-parts.tex @@ -60,7 +60,7 @@ \subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Dev Before performing any get or set operation for the device parts, the driver creates the device parts resource object VIRTIO_RESOURCE_OBJ_DEV_PARTS using the administration command -\hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE}. +\nameref{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE}. The driver indicates the intended purpose (get or set) at the time of creating the device parts resource object. For the device parts resource object, both \field{resource_obj_specific_data} and @@ -337,7 +337,7 @@ \subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Dev When there are multiple device parts in the command VIRTIO_ADMIN_CMD_DEV_PARTS_GET, the device MUST respond the device parts in the same order as listed in the table -\hyperref[table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts order/ Device parts order]{device parts order}. +\nameref{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts order/ Device parts order}. The device SHOULD respond with an error status for the command VIRTIO_ADMIN_CMD_DEV_PARTS_SET if the device is not stopped. @@ -455,7 +455,7 @@ \subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Dev When there are multiple device parts in the command VIRTIO_ADMIN_CMD_DEV_PARTS_SET, the driver MUST set the device parts in the same order as listed in the table -\hyperref[table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts order/ Device parts order]{device parts order}. +\nameref{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts order/ Device parts order}. For the SR-IOV group type, the driver SHOULD NOT access the device configuration space described in section diff --git a/admin-cmds-resource-objects.tex b/admin-cmds-resource-objects.tex index 388aa69..d0a6647 100644 --- a/admin-cmds-resource-objects.tex +++ b/admin-cmds-resource-objects.tex @@ -69,7 +69,7 @@ \subsubsection{Device resource objects}\label{sec:Basic Facilities of a Virtio D \hline Resource object type & Name & Description \\ \hline \hline -0x000 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO_RESOURCE_OBJ_DEV_PARTS]{VIRTIO_RESOURCE_OBJ_DEV_PARTS} & Device parts object \\ +0x000 & VIRTIO_RESOURCE_OBJ_DEV_PARTS & Device parts object, see \ref{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO_RESOURCE_OBJ_DEV_PARTS} \\ \hline 0x001-0x1ff & - & Generic resource object range reserved \\ \hline diff --git a/device-parts.tex b/device-parts.tex index 7384408..e6047db 100644 --- a/device-parts.tex +++ b/device-parts.tex @@ -70,7 +70,7 @@ \section{Device parts}\label{sec:Basic Facilities of a Virtio Device / Device pa \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, +field in the \nameref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout}. 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 @@ -89,17 +89,17 @@ \subsection{Common device parts}\label{sec:Basic Facilities of a Virtio Device / \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 \\ +0x100 & VIRTIO_DEV_PART_DEV_FEATURES & Device features, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_DEV_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 \\ +0x101 & VIRTIO_DEV_PART_DRV_FEATURES & Driver features, \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_DRV_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 \\ +0x102 & VIRTIO_DEV_PART_PCI_COMMON_CFG & PCI common configuration, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_PCI_COMMON_CFG} \\ \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 \\ +0x103 & VIRTIO_DEV_PART_DEVICE_STATUS & Device status, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_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 \\ +0x104 & VIRTIO_DEV_PART_VQ_CFG & Virtqueue configuration, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_VQ_CFG} \\ \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 \\ +0x105 & VIRTIO_DEV_PART_VQ_NOTIFY_CFG & Virtqueue notification configuration, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_VQ_NOTIFY_CFG} \\ \hline 0x106 - 0x2FF & - & Common device parts range reserved for future \\ \hline @@ -157,7 +157,8 @@ \subsubsection{VIRTIO_DEV_PART_PCI_COMMON_CFG} 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} +\subsubsection{VIRTIO_DEV_PART_DEVICE_STATUS} +\label{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / 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 @@ -214,8 +215,8 @@ \subsubsection{VIRTIO_DEV_PART_VQ_NOTIFY_CFG} \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}. +fields in \field{struct virtio_pci_common_cfg} described in the +\nameref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout}. 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 From 737935487b9ed1b2423ceb8ef809e1cd7dee0b9d Mon Sep 17 00:00:00 2001 From: "Michael S. Tsirkin" Date: Mon, 15 Jul 2024 12:49:36 -0400 Subject: [PATCH 38/62] makediff: look in subjects only We currently use rev-list with -F to find commits. This helps if commit subject has any special characters but means that pattern can apply anywhere in the line. In particular, a common Fixes: (hash) "subject" pattern we started using implies that fixups are picked up instead of the commit. For now, just switch to using regexp (dropping -F) and add "^" in front to only look for the string at beginning of the line. We'll worry about more elaborate logic later, if it's ever needed. Message-Id: <1130700f4ae71a93d9887af35cf105731219f057.1721062136.git.mst@redhat.com> Signed-off-by: Michael S. Tsirkin --- makediff.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/makediff.sh b/makediff.sh index d6c9bcc..f98fa33 100755 --- a/makediff.sh +++ b/makediff.sh @@ -18,7 +18,7 @@ cd "${cur}/old" git checkout $oldrev while read -r rev; do echo "Applying $rev" - git cherry-pick --keep-redundant-commits --allow-empty `git rev-list -1 -F --grep "$rev" $newrev` || exit 1 + git cherry-pick --keep-redundant-commits --allow-empty `git rev-list -1 --grep "^$rev" $newrev` || exit 1 done << 'EOF' editorial: allow for longer device id table: makediff 1.3 EOF From 98ad5fcc88abce80e787fd7bfd57186f1c157c69 Mon Sep 17 00:00:00 2001 From: "Michael S. Tsirkin" Date: Mon, 15 Jul 2024 12:49:39 -0400 Subject: [PATCH 39/62] makediff: cherry pick table env change latexdiff can not cope with environment name changes. cherry pick to avoid confusing it. Fixes: 72a91e6 ("admin: Prepare table for multipage listing") Message-Id: Signed-off-by: Michael S. Tsirkin --- makediff.sh | 1 + 1 file changed, 1 insertion(+) diff --git a/makediff.sh b/makediff.sh index f98fa33..11e518a 100755 --- a/makediff.sh +++ b/makediff.sh @@ -21,6 +21,7 @@ while read -r rev; do git cherry-pick --keep-redundant-commits --allow-empty `git rev-list -1 --grep "^$rev" $newrev` || exit 1 done << 'EOF' editorial: allow for longer device id table: makediff 1.3 +admin: Prepare table for multipage listing EOF #mv specvars.tex specvars-orig.tex From 849b421941a44596c2a9e7f0af088ad808c5ce3a Mon Sep 17 00:00:00 2001 From: "Michael S. Tsirkin" Date: Mon, 15 Jul 2024 12:49:41 -0400 Subject: [PATCH 40/62] admin: switch to tabularx xltabular seems to confuse htlatex. Switch to an older tabularx which seems to be sufficient for our purposes. Message-Id: <29ebb999f6d3808edbf32cd6e95b69fefc1a6e34.1721062136.git.mst@redhat.com> Signed-off-by: Michael S. Tsirkin --- admin.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/admin.tex b/admin.tex index d60d6f1..35d614c 100644 --- a/admin.tex +++ b/admin.tex @@ -118,7 +118,7 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti \field{opcode} specifies the command. The valid values for \field{opcode} can be found in the following table: -\begin{xltabular}{\textwidth}{ |l||l|X| } +\begin{tabularx}{\textwidth}{ |l||l|X| } \hline opcode & Name & Command Description \\ \hline \hline @@ -163,7 +163,7 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti \hline 0x8000 - 0xFFFF & - & Reserved for future commands (possibly using a different structure) \\ \hline -\end{xltabular} +\end{tabularx} The \field{group_type} specifies the group type identifier. The \field{group_member_id} specifies the member identifier within the group. From 8e81624195ba131d8f47cfd04edc2559bca6153a Mon Sep 17 00:00:00 2001 From: "Michael S. Tsirkin" Date: Mon, 15 Jul 2024 12:49:44 -0400 Subject: [PATCH 41/62] admin-cmds-device-parts: switch to tabularx xltabular seems to confuse htlatex. Switch to an older tabularx which seems to be sufficient for our purposes. Message-Id: Signed-off-by: Michael S. Tsirkin --- admin-cmds-device-parts.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/admin-cmds-device-parts.tex b/admin-cmds-device-parts.tex index ad3f8e3..e64b756 100644 --- a/admin-cmds-device-parts.tex +++ b/admin-cmds-device-parts.tex @@ -297,7 +297,7 @@ \subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Dev \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| } +\begin{tabularx}{\textwidth}{ |l|l|X| } \hline Part name & Optional & Mandatory preceding parts \\ \hline \hline @@ -317,7 +317,7 @@ \subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Dev VIRTIO_DEV_PART_DEVICE_STATUS, VIRTIO_DEV_PART_VQ_CFG \\ \hline \hline -\end{xltabular} +\end{tabularx} \end{table} \devicenormative{\subparagraph}{Device parts}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts} From 886fc333de8b780219159d0784a3f4989c6d22fe Mon Sep 17 00:00:00 2001 From: "Michael S. Tsirkin" Date: Mon, 15 Jul 2024 12:49:47 -0400 Subject: [PATCH 42/62] device-parts: switch to tabularx xltabular seems to confuse htlatex. Switch to an older tabularx which seems to be sufficient for our purposes. Message-Id: <00f72154c624fbbe8c3da9dbdb4e4369c36b7f10.1721062136.git.mst@redhat.com> Signed-off-by: Michael S. Tsirkin --- device-parts.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/device-parts.tex b/device-parts.tex index e6047db..92b65f4 100644 --- a/device-parts.tex +++ b/device-parts.tex @@ -85,7 +85,7 @@ \subsection{Common device parts}\label{sec:Basic Facilities of a Virtio Device / \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| } +\begin{tabularx}{\textwidth}{ |l||l|X| } \hline Type & Name & Description \\ \hline \hline @@ -104,7 +104,7 @@ \subsection{Common device parts}\label{sec:Basic Facilities of a Virtio Device / 0x106 - 0x2FF & - & Common device parts range reserved for future \\ \hline \hline -\end{xltabular} +\end{tabularx} \end{table} \subsubsection{VIRTIO_DEV_PART_DEV_FEATURES} From a5fb7b5edd8aa896b61893ab6720b51820e79d3f Mon Sep 17 00:00:00 2001 From: "Michael S. Tsirkin" Date: Mon, 15 Jul 2024 12:49:50 -0400 Subject: [PATCH 43/62] admin-cmds-resource-objects: switch to tabularx xltabular seems to confuse htlatex. Switch to an older tabularx which seems to be sufficient for our purposes. Message-Id: <3f7be88a42af0a384621ef07b65c7a31755ef42e.1721062136.git.mst@redhat.com> Signed-off-by: Michael S. Tsirkin --- admin-cmds-resource-objects.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/admin-cmds-resource-objects.tex b/admin-cmds-resource-objects.tex index d0a6647..e0bbb4a 100644 --- a/admin-cmds-resource-objects.tex +++ b/admin-cmds-resource-objects.tex @@ -65,7 +65,7 @@ \subsubsection{Device resource objects}\label{sec:Basic Facilities of a Virtio D Following generic resource objects are defined which are described separately. -\begin{xltabular}{\textwidth}{ |X||X|X| } +\begin{tabularx}{\textwidth}{ |X||X|X| } \hline Resource object type & Name & Description \\ \hline \hline @@ -74,7 +74,7 @@ \subsubsection{Device resource objects}\label{sec:Basic Facilities of a Virtio D 0x001-0x1ff & - & Generic resource object range reserved \\ \hline \hline -\end{xltabular} +\end{tabularx} When the device resets, it starts with zero resources of each type; the driver can create resources up to the published \field{limit}. The driver can From 459f1aa9ef74db32fe33c9da4c4ed4821b3c0a1b Mon Sep 17 00:00:00 2001 From: "Michael S. Tsirkin" Date: Mon, 15 Jul 2024 12:49:53 -0400 Subject: [PATCH 44/62] virtio: replace xltabular with ltablex now that we only use tabularx, switch to ltablex to make tabularx tables paginate properly. Message-Id: <15b11ce5ac9bbe1aaa7818403b999ff39c74a479.1721062136.git.mst@redhat.com> Signed-off-by: Michael S. Tsirkin --- virtio.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/virtio.tex b/virtio.tex index 3bb5c14..748df96 100644 --- a/virtio.tex +++ b/virtio.tex @@ -35,7 +35,7 @@ \usepackage{xltxtra} \usepackage{etoolbox} \usepackage{tabularx} -\usepackage{xltabular} +\usepackage{ltablex} \usepackage{underscore} \usepackage{xstring} \usepackage{enumitem} From e48de848f9765fb976d33cb4d049f31a632ae5c2 Mon Sep 17 00:00:00 2001 From: "Michael S. Tsirkin" Date: Mon, 15 Jul 2024 12:49:55 -0400 Subject: [PATCH 45/62] makediff: cherry pick switch to tabularx Message-Id: <88cdb7020f5b2771a6d201b1f65005da97e54f16.1721062136.git.mst@redhat.com> Signed-off-by: Michael S. Tsirkin --- makediff.sh | 1 + 1 file changed, 1 insertion(+) diff --git a/makediff.sh b/makediff.sh index 11e518a..e068506 100755 --- a/makediff.sh +++ b/makediff.sh @@ -22,6 +22,7 @@ while read -r rev; do done << 'EOF' editorial: allow for longer device id table: makediff 1.3 admin: Prepare table for multipage listing +admin: switch to tabularx EOF #mv specvars.tex specvars-orig.tex From 6c2340547951ada46447c973b1d8133165785840 Mon Sep 17 00:00:00 2001 From: "Michael S. Tsirkin" Date: Mon, 15 Jul 2024 12:50:05 -0400 Subject: [PATCH 46/62] admin: get rid of _ in labels it's not the 1st time we find out underscores in labels confuse latexdiff machinery when generating html. Errors look like this: ! Missing \endcsname inserted. \unhbox .... ? ! Emergency stop. \unhbox To fix, convert underscores in labels to dashes. Message-Id: <3e773fcfd4246e66e6f39d3be95d2c0335e34532.1721062136.git.mst@redhat.com> Signed-off-by: Michael S. Tsirkin --- admin-cmds-capabilities.tex | 8 +++--- admin-cmds-device-parts.tex | 14 +++++----- admin-cmds-legacy-interface.tex | 10 ++++---- admin-cmds-resource-objects.tex | 10 ++++---- admin.tex | 32 +++++++++++------------ device-parts.tex | 24 ++++++++--------- device-types/can/description.tex | 10 ++++---- device-types/net/description.tex | 44 ++++++++++++++++---------------- 8 files changed, 76 insertions(+), 76 deletions(-) diff --git a/admin-cmds-capabilities.tex b/admin-cmds-capabilities.tex index 9865254..f917a0d 100644 --- a/admin-cmds-capabilities.tex +++ b/admin-cmds-capabilities.tex @@ -60,7 +60,7 @@ \subsubsection{Device and driver capabilities}\label{sec:Basic Facilities of a V \hline Id & Name & Description \\ \hline \hline -0x0000 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO_DEV_PARTS_CAP]{VIRTIO_DEV_PARTS_CAP} & Device parts capability \\ +0x0000 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO-DEV-PARTS-CAP]{VIRTIO_DEV_PARTS_CAP} & Device parts capability \\ \hline 0x0001-0x07ff & - & Generic capability for all device types \\ \hline @@ -79,7 +79,7 @@ \subsubsection{Device and driver capabilities}\label{sec:Basic Facilities of a V \item VIRTIO_ADMIN_CMD_DRIVER_CAP_SET \end{enumerate} -\paragraph{VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY} +\paragraph{VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO-ADMIN-CMD-CAP-ID-LIST-QUERY} This command queries the bitmap of capability ids listed in \ref{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / capability ids}. @@ -119,7 +119,7 @@ \subsubsection{Device and driver capabilities}\label{sec:Basic Facilities of a V The array is also allowed to be larger and to additionally include an arbitrary number of all-zero entries. -\paragraph{VIRTIO_ADMIN_CMD_DEVICE_CAP_GET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO_ADMIN_CMD_DEVICE_CAP_GET} +\paragraph{VIRTIO_ADMIN_CMD_DEVICE_CAP_GET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO-ADMIN-CMD-DEVICE-CAP-GET} This command gets the device capability for the specified capability id \field{id}. @@ -151,7 +151,7 @@ \subsubsection{Device and driver capabilities}\label{sec:Basic Facilities of a V by the device. Each capability uses different capability specific \field{cap_specific_data} and is described separately. -\paragraph{VIRTIO_ADMIN_CMD_DRIVER_CAP_SET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO_ADMIN_CMD_DRIVER_CAP_SET} +\paragraph{VIRTIO_ADMIN_CMD_DRIVER_CAP_SET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO-ADMIN-CMD-DRIVER-CAP-SET} This command sets the driver capability, indicating to the device which capability the driver uses. The driver can set a resource object limit capability that is smaller diff --git a/admin-cmds-device-parts.tex b/admin-cmds-device-parts.tex index e64b756..4c88045 100644 --- a/admin-cmds-device-parts.tex +++ b/admin-cmds-device-parts.tex @@ -37,7 +37,7 @@ \subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Dev the device itself will not initiate any transport requests. \paragraph{VIRTIO_DEV_PARTS_CAP} -\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO_DEV_PARTS_CAP} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO-DEV-PARTS-CAP} The capability VIRTIO_DEV_PARTS_CAP indicates the device parts resource objects limit. \field{cap_specific_data} is in the format \field{struct virtio_dev_parts_cap}. @@ -54,13 +54,13 @@ \subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Dev \field{set_parts_resource_objects_limit} indicates the supported device parts resource objects for restoring the device parts. -\paragraph{VIRTIO_RESOURCE_OBJ_DEV_PARTS}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO_RESOURCE_OBJ_DEV_PARTS} +\paragraph{VIRTIO_RESOURCE_OBJ_DEV_PARTS}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO-RESOURCE-OBJ-DEV-PARTS} A device parts resource object is used to either get or set the device parts. Before performing any get or set operation for the device parts, the driver creates the device parts resource object VIRTIO_RESOURCE_OBJ_DEV_PARTS using the administration command -\nameref{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE}. +\nameref{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-CREATE}. The driver indicates the intended purpose (get or set) at the time of creating the device parts resource object. For the device parts resource object, both \field{resource_obj_specific_data} and @@ -96,7 +96,7 @@ \subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Dev \end{enumerate} \subparagraph{VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET} -\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO-ADMIN-CMD-DEV-PARTS-METADATA-GET} This command obtains the metadata of the device parts. This metadata includes the maximum size of the device parts, the count of device parts, and a list of @@ -166,7 +166,7 @@ \subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Dev for the response. \subparagraph{VIRTIO_ADMIN_CMD_DEV_PARTS_GET} -\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO_ADMIN_CMD_DEV_PARTS_GET} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO-ADMIN-CMD-DEV-PARTS-GET} This command captures the device parts. For the command VIRTIO_ADMIN_CMD_DEV_PARTS_GET, \field{opcode} is set to 0xf. @@ -210,7 +210,7 @@ \subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Dev If the requested device part does not exist, the device skips the device part without any error. -\subparagraph{VIRTIO_ADMIN_CMD_DEV_PARTS_SET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO_ADMIN_CMD_DEV_PARTS_SET} +\subparagraph{VIRTIO_ADMIN_CMD_DEV_PARTS_SET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO-ADMIN-CMD-DEV-PARTS-SET} This command sets one or multiple device parts. For the command VIRTIO_ADMIN_CMD_DEV_PARTS_SET, \field{opcode} is set to 0x10. @@ -242,7 +242,7 @@ \subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Dev When the command fails with a status other than VIRTIO_ADMIN_STATUS_OK, the device does not have any side effects. -\subparagraph{VIRTIO_ADMIN_CMD_DEV_MODE_SET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO_ADMIN_CMD_DEV_MODE_SET} +\subparagraph{VIRTIO_ADMIN_CMD_DEV_MODE_SET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO-ADMIN-CMD-DEV-MODE-SET} This command either stops the device from initiating any transport requests or resumes the device operation. For the command VIRTIO_ADMIN_CMD_DEV_MODE_SET, diff --git a/admin-cmds-legacy-interface.tex b/admin-cmds-legacy-interface.tex index 7b1ce4e..56142aa 100644 --- a/admin-cmds-legacy-interface.tex +++ b/admin-cmds-legacy-interface.tex @@ -30,7 +30,7 @@ \subsubsection{Legacy Interfaces}\label{sec:Basic Facilities of a Virtio Device that little-endian format is assumed unconditionally. \paragraph{VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE} -\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-COMMON-CFG-WRITE} This command has the same effect as writing into the virtio common configuration structure through the legacy interface. The \field{command_specific_data} is in @@ -60,7 +60,7 @@ \subsubsection{Legacy Interfaces}\label{sec:Basic Facilities of a Virtio Device This command has no command specific result. \paragraph{VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ} -\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-COMMON-CFG-READ} This command has the same effect as reading from the virtio common configuration structure through the legacy interface. The \field{command_specific_data} is in @@ -96,7 +96,7 @@ \subsubsection{Legacy Interfaces}\label{sec:Basic Facilities of a Virtio Device \field{data}. \paragraph{VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE} -\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-DEV-CFG-WRITE} This command has the same effect as writing into the virtio device-specific configuration through the legacy interface. The \field{command_specific_data} is in @@ -126,7 +126,7 @@ \subsubsection{Legacy Interfaces}\label{sec:Basic Facilities of a Virtio Device This command has no command specific result. \paragraph{VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ} -\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-DEV-CFG-READ} This command has the same effect as reading from the virtio device-specific configuration through the legacy interface. The \field{command_specific_data} is in @@ -163,7 +163,7 @@ \subsubsection{Legacy Interfaces}\label{sec:Basic Facilities of a Virtio Device The length of the data read is simply the length of \field{data}. \paragraph{VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO} -\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-NOTIFY-INFO} The driver of the owner device can send a driver notification to the member device operated using the legacy interface by executing diff --git a/admin-cmds-resource-objects.tex b/admin-cmds-resource-objects.tex index e0bbb4a..68f5862 100644 --- a/admin-cmds-resource-objects.tex +++ b/admin-cmds-resource-objects.tex @@ -69,7 +69,7 @@ \subsubsection{Device resource objects}\label{sec:Basic Facilities of a Virtio D \hline Resource object type & Name & Description \\ \hline \hline -0x000 & VIRTIO_RESOURCE_OBJ_DEV_PARTS & Device parts object, see \ref{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO_RESOURCE_OBJ_DEV_PARTS} \\ +0x000 & VIRTIO_RESOURCE_OBJ_DEV_PARTS & Device parts object, see \ref{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO-RESOURCE-OBJ-DEV-PARTS} \\ \hline 0x001-0x1ff & - & Generic resource object range reserved \\ \hline @@ -109,7 +109,7 @@ \subsubsection{Device resource objects}\label{sec:Basic Facilities of a Virtio D \field{id} uniquely identifies the resource object of a specified \field{type}. \paragraph{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE} -\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-CREATE} This command creates the specified resource object of \field{type} identified by the resource id \field{id}. The valid range of \field{id} is defined by the @@ -142,7 +142,7 @@ \subsubsection{Device resource objects}\label{sec:Basic Facilities of a Virtio D This command has no command specific result. \paragraph{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY} -\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-MODIFY} This command modifies the attributes of an existing device resource object. For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY, \field{opcode} is set to 0xb. @@ -167,7 +167,7 @@ \subsubsection{Device resource objects}\label{sec:Basic Facilities of a Virtio D set to the values supplied in \field{resource_obj_specific_data}. \paragraph{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY} -\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-QUERY} This command queries attributes of the existing resource object. For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY, \field{opcode} is set to 0xc. @@ -198,7 +198,7 @@ \subsubsection{Device resource objects}\label{sec:Basic Facilities of a Virtio D resource object are are set in \field{resource_obj_specific_data}. \paragraph{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY} -\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-DESTROY} This command destroys the previously created device resource object. For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY, \field{opcode} is set to 0xd. diff --git a/admin.tex b/admin.tex index 35d614c..39fc072 100644 --- a/admin.tex +++ b/admin.tex @@ -126,37 +126,37 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti \hline 0x0001 & VIRTIO_ADMIN_CMD_LIST_USE & Provides to device list of commands used for this group type \\ \hline -0x0002 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE]{VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE} & Writes into the legacy common configuration structure \\ +0x0002 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-COMMON-CFG-WRITE]{VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE} & Writes into the legacy common configuration structure \\ \hline -0x0003 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ]{VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ} & Reads from the legacy common configuration structure \\ +0x0003 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-COMMON-CFG-READ]{VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ} & Reads from the legacy common configuration structure \\ \hline -0x0004 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE]{VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE} & Writes into the legacy device configuration structure \\ +0x0004 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-DEV-CFG-WRITE]{VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE} & Writes into the legacy device configuration structure \\ \hline -0x0005 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ]{VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ} & Reads into the legacy device configuration structure \\ +0x0005 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-DEV-CFG-READ]{VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ} & Reads into the legacy device configuration structure \\ \hline -0x0006 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO]{VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO} & Query the notification region information \\ +0x0006 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-NOTIFY-INFO]{VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO} & Query the notification region information \\ \hline -0x0007 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY]{VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY} & Query the supported device capabilities bitmap \\ +0x0007 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO-ADMIN-CMD-CAP-ID-LIST-QUERY]{VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY} & Query the supported device capabilities bitmap \\ \hline -0x0008 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO_ADMIN_CMD_DEVICE_CAP_GET]{VIRTIO_ADMIN_CMD_DEVICE_CAP_GET} & Get the device capabilities \\ +0x0008 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO-ADMIN-CMD-DEVICE-CAP-GET]{VIRTIO_ADMIN_CMD_DEVICE_CAP_GET} & Get the device capabilities \\ \hline -0x0009 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO_ADMIN_CMD_DRIVER_CAP_SET]{VIRTIO_ADMIN_CMD_DRIVER_CAP_SET} & Set the driver capabilities \\ +0x0009 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO-ADMIN-CMD-DRIVER-CAP-SET]{VIRTIO_ADMIN_CMD_DRIVER_CAP_SET} & Set the driver capabilities \\ \hline -0x000a & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE} & Create a device resource object \\ +0x000a & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-CREATE]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE} & Create a device resource object \\ \hline -0x000c & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY} & Modify a device resource object \\ +0x000c & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-MODIFY]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY} & Modify a device resource object \\ \hline -0x000b & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY} & Query a device resource object \\ +0x000b & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-QUERY]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY} & Query a device resource object \\ \hline -0x000d & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY} & Destroy a device resource object \\ +0x000d & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-DESTROY]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY} & Destroy a device resource object \\ \hline -0x000e & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET]{VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET} & Get the metadata of the device parts \\ +0x000e & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO-ADMIN-CMD-DEV-PARTS-METADATA-GET]{VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET} & Get the metadata of the device parts \\ \hline -0x000f & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO_ADMIN_CMD_DEV_PARTS_GET]{VIRTIO_ADMIN_CMD_DEV_PARTS_GET} & Get the device parts \\ +0x000f & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO-ADMIN-CMD-DEV-PARTS-GET]{VIRTIO_ADMIN_CMD_DEV_PARTS_GET} & Get the device parts \\ \hline -0x0010 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO_ADMIN_CMD_DEV_PARTS_SET]{VIRTIO_ADMIN_CMD_DEV_PARTS_SET} & Set the device parts \\ +0x0010 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO-ADMIN-CMD-DEV-PARTS-SET]{VIRTIO_ADMIN_CMD_DEV_PARTS_SET} & Set the device parts \\ \hline -0x0011 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO_ADMIN_CMD_DEV_MODE_SET]{VIRTIO_ADMIN_CMD_DEV_MODE_SET} & Stop or resume the device \\ +0x0011 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO-ADMIN-CMD-DEV-MODE-SET]{VIRTIO_ADMIN_CMD_DEV_MODE_SET} & Stop or resume the device \\ \hline \hline 0x0013 - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd} \\ diff --git a/device-parts.tex b/device-parts.tex index 92b65f4..7197929 100644 --- a/device-parts.tex +++ b/device-parts.tex @@ -89,17 +89,17 @@ \subsection{Common device parts}\label{sec:Basic Facilities of a Virtio Device / \hline Type & Name & Description \\ \hline \hline -0x100 & VIRTIO_DEV_PART_DEV_FEATURES & Device features, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_DEV_FEATURES} \\ +0x100 & VIRTIO_DEV_PART_DEV_FEATURES & Device features, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-DEV-FEATURES} \\ \hline -0x101 & VIRTIO_DEV_PART_DRV_FEATURES & Driver features, \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_DRV_FEATURES} \\ +0x101 & VIRTIO_DEV_PART_DRV_FEATURES & Driver features, \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-DRV-FEATURES} \\ \hline -0x102 & VIRTIO_DEV_PART_PCI_COMMON_CFG & PCI common configuration, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_PCI_COMMON_CFG} \\ +0x102 & VIRTIO_DEV_PART_PCI_COMMON_CFG & PCI common configuration, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-PCI-COMMON-CFG} \\ \hline -0x103 & VIRTIO_DEV_PART_DEVICE_STATUS & Device status, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_DEVICE_STATUS} \\ +0x103 & VIRTIO_DEV_PART_DEVICE_STATUS & Device status, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-DEVICE-STATUS} \\ \hline -0x104 & VIRTIO_DEV_PART_VQ_CFG & Virtqueue configuration, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_VQ_CFG} \\ +0x104 & VIRTIO_DEV_PART_VQ_CFG & Virtqueue configuration, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-VQ-CFG} \\ \hline -0x105 & VIRTIO_DEV_PART_VQ_NOTIFY_CFG & Virtqueue notification configuration, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_VQ_NOTIFY_CFG} \\ +0x105 & VIRTIO_DEV_PART_VQ_NOTIFY_CFG & Virtqueue notification configuration, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-VQ-NOTIFY-CFG} \\ \hline 0x106 - 0x2FF & - & Common device parts range reserved for future \\ \hline @@ -108,7 +108,7 @@ \subsection{Common device parts}\label{sec:Basic Facilities of a Virtio Device / \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} +\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. @@ -130,7 +130,7 @@ \subsubsection{VIRTIO_DEV_PART_DEV_FEATURES} \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} +\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. @@ -143,7 +143,7 @@ \subsubsection{VIRTIO_DEV_PART_DRV_FEATURES} 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} +\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 @@ -158,7 +158,7 @@ \subsubsection{VIRTIO_DEV_PART_PCI_COMMON_CFG} get or set commands; each such part corresponds to a unique \field{offset}. \subsubsection{VIRTIO_DEV_PART_DEVICE_STATUS} -\label{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO_DEV_PART_DEVICE_STATUS} +\label{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / 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 @@ -173,7 +173,7 @@ \subsubsection{VIRTIO_DEV_PART_DEVICE_STATUS} 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} +\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}. @@ -200,7 +200,7 @@ \subsubsection{VIRTIO_DEV_PART_VQ_CFG} 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} +\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}. diff --git a/device-types/can/description.tex b/device-types/can/description.tex index 2511d9c..24b29ed 100644 --- a/device-types/can/description.tex +++ b/device-types/can/description.tex @@ -89,7 +89,7 @@ \subsection{Device configuration layout}\label{sec:Device Types / CAN Device / D The driver MUST populate the \field{Rxq} with empty device-writeable buffers of at least the size of struct virtio_can_rx, see section -\ref{struct virtio_can_rx}. +\ref{struct virtio-can-rx}. \subsection{Device Operation}\label{sec:Device Types / CAN Device / Device Operation} @@ -152,7 +152,7 @@ \subsubsection{Controller Mode}\label{sec:Device Types / CAN Device / Device Ope The driver transmits messages by placing outgoing CAN messages in the \field{Txq} virtqueue. -\label{struct virtio_can_tx_out} +\label{struct virtio-can-tx-out} \begin{lstlisting} struct virtio_can_tx_out { #define VIRTIO_CAN_TX 0x0001 @@ -207,7 +207,7 @@ \subsubsection{CAN Message Reception}\label{sec:Device Types / CAN Device / Devi Messages can be received by providing empty incoming buffers to the virtqueue \field{Rxq}. -\label{struct virtio_can_rx} +\label{struct virtio-can-rx} \begin{lstlisting} struct virtio_can_rx { #define VIRTIO_CAN_RX 0x0101 @@ -229,8 +229,8 @@ \subsubsection{CAN Message Reception}\label{sec:Device Types / CAN Device / Devi The actual length of the \field{sdu} is determined by the \field{length}. The type of a CAN message identifier is determined by \field{flags} in -the same way as for transmitted CAN messages, see section \ref{struct -virtio_can_tx_out}. The 3 most significant bits of \field{can_id} do not +the same way as for transmitted CAN messages, see section +\ref{struct virtio-can-tx-out}. The 3 most significant bits of \field{can_id} do not bear the information about the type of the CAN message identifier and are 0. The flag bits are exactly the same as for the \field{flags} of struct virtio_can_tx_out. diff --git a/device-types/net/description.tex b/device-types/net/description.tex index 29f1ee8..b2a0d39 100644 --- a/device-types/net/description.tex +++ b/device-types/net/description.tex @@ -409,11 +409,11 @@ \subsection{Device and driver capabilities}\label{sec:Device Types / Network Dev \hline Identifier & Name & Description \\ \hline \hline -0x0800 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_RESOURCE_CAP]{VIRTIO_NET_FF_RESOURCE_CAP} & Flow filter resource capability \\ +0x0800 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-RESOURCE-CAP]{VIRTIO_NET_FF_RESOURCE_CAP} & Flow filter resource capability \\ \hline -0x0801 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_SELECTOR_CAP]{VIRTIO_NET_FF_SELECTOR_CAP} & Flow filter classifier capability \\ +0x0801 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-SELECTOR-CAP]{VIRTIO_NET_FF_SELECTOR_CAP} & Flow filter classifier capability \\ \hline -0x0802 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_ACTION_CAP]{VIRTIO_NET_FF_ACTION_CAP} & Flow filter action capability \\ +0x0802 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-ACTION-CAP]{VIRTIO_NET_FF_ACTION_CAP} & Flow filter action capability \\ \hline \end{tabularx} @@ -425,11 +425,11 @@ \subsection{Device resource objects}\label{sec:Device Types / Network Device / D \hline type & Name & Description \\ \hline \hline -0x0200 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO_NET_RESOURCE_OBJ_FF_GROUP]{VIRTIO_NET_RESOURCE_OBJ_FF_GROUP} & Flow filter group resource object \\ +0x0200 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO-NET-RESOURCE-OBJ-FF-GROUP]{VIRTIO_NET_RESOURCE_OBJ_FF_GROUP} & Flow filter group resource object \\ \hline -0x0201 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER]{VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER} & Flow filter mask object \\ +0x0201 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO-NET-RESOURCE-OBJ-FF-CLASSIFIER]{VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER} & Flow filter mask object \\ \hline -0x0202 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO_NET_RESOURCE_OBJ_FF_RULE]{VIRTIO_NET_RESOURCE_OBJ_FF_RULE} & Flow filter rule object \\ +0x0202 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO-NET-RESOURCE-OBJ-FF-RULE]{VIRTIO_NET_RESOURCE_OBJ_FF_RULE} & Flow filter rule object \\ \hline \end{tabularx} @@ -2475,12 +2475,12 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope are ignored, the group with the next highest priority is selected, and so on. The device and the driver indicates flow filter resource limits using the capability -\ref{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_RESOURCE_CAP} specifying the limits on the number of flow filter rule, -group and classifier resource objects. The capability \ref{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_SELECTOR_CAP} specifies which selectors the device supports. +\ref{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-RESOURCE-CAP} specifying the limits on the number of flow filter rule, +group and classifier resource objects. The capability \ref{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-SELECTOR-CAP} specifies which selectors the device supports. The driver indicates the selectors it is using by setting the flow filter selector capability, prior to adding any resource objects. -The capability \ref{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_ACTION_CAP} specifies which actions the device supports. +The capability \ref{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-ACTION-CAP} specifies which actions the device supports. The driver controls the flow filter rule, classifier and group resource objects using administration commands described in @@ -2523,7 +2523,7 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope \label{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities} \subparagraph{VIRTIO_NET_FF_RESOURCE_CAP} -\label{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_RESOURCE_CAP} +\label{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-RESOURCE-CAP} The capability VIRTIO_NET_FF_RESOURCE_CAP indicates the flow filter resource limits. \field{cap_specific_data} is in the format @@ -2554,13 +2554,13 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope that a classifier can have. \subparagraph{VIRTIO_NET_FF_SELECTOR_CAP} -\label{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_SELECTOR_CAP} +\label{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-SELECTOR-CAP} The capability VIRTIO_NET_FF_SELECTOR_CAP lists the supported selectors and the supported packet header fields for each selector. \field{cap_specific_data} is in the format \field{struct virtio_net_ff_cap_mask_data}. -\begin{lstlisting}[label={lst:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_SELECTOR_CAP / virtio_net_ff_selector}] +\begin{lstlisting}[label={lst:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-SELECTOR-CAP / virtio-net-ff-selector}] struct virtio_net_ff_selector { u8 type; u8 flags; @@ -2582,11 +2582,11 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope \field{count} indicates number of valid entries in the \field{selectors} array. \field{selectors[]} is an array of supported selectors. Within each array entry: \field{type} specifies the type of the packet header, as defined in table -\ref{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_SELECTOR_CAP / flow filter selector types}. \field{mask} specifies which fields of the +\ref{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-SELECTOR-CAP / flow filter selector types}. \field{mask} specifies which fields of the packet header can be matched in a flow filter rule. Each \field{type} is also listed in table -\ref{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_SELECTOR_CAP / flow filter selector types}. \field{mask} is a byte array +\ref{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-SELECTOR-CAP / flow filter selector types}. \field{mask} is a byte array in network byte order. For example, when \field{type} is VIRTIO_NET_FF_MASK_TYPE_IPV6, the \field{mask} is in the format \hyperref[intro:IPv6-Header-Format]{IPv6 Header Format}. @@ -2607,7 +2607,7 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope \begin{table}[H] \caption{Flow filter selector types} -\label{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_SELECTOR_CAP / flow filter selector types} +\label{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-SELECTOR-CAP / flow filter selector types} \begin{tabularx}{\textwidth}{ |l|X|X| } \hline Type & Name & Description \\ @@ -2653,7 +2653,7 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope \field{Control bits} does not depend on the partial mask support. \subparagraph{VIRTIO_NET_FF_ACTION_CAP} -\label{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_ACTION_CAP} +\label{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-ACTION-CAP} The capability VIRTIO_NET_FF_ACTION_CAP lists the supported actions in a rule. \field{cap_specific_data} is in the format \field{struct virtio_net_ff_cap_actions}. @@ -2673,7 +2673,7 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope \begin{table}[H] \caption{Flow filter rule actions} -\label{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_ACTION_CAP / flow filter rule actions} +\label{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-ACTION-CAP / flow filter rule actions} \begin{tabularx}{\textwidth}{ |l|X|X| } \hline Action & Name & Description \\ @@ -2692,7 +2692,7 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope \paragraph{Resource objects} \label{par:Device Types / Network Device / Device Operation / Flow filter / Resource objects} -\subparagraph{VIRTIO_NET_RESOURCE_OBJ_FF_GROUP}\label{par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO_NET_RESOURCE_OBJ_FF_GROUP} +\subparagraph{VIRTIO_NET_RESOURCE_OBJ_FF_GROUP}\label{par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO-NET-RESOURCE-OBJ-FF-GROUP} A flow filter group contains between 0 and \field{rules_limit} rules, as specified by the capability VIRTIO_NET_FF_RESOURCE_CAP. For the flow filter group object both @@ -2711,7 +2711,7 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope from groups from higher \field{group_priority} value to lower, until either a rule matches the packet or all groups have been tried. -\subparagraph{VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER}\label{par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER} +\subparagraph{VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER}\label{par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO-NET-RESOURCE-OBJ-FF-CLASSIFIER} A classifier is used to match a flow filter key against a packet. The classifier defines the desired packet fields to match, and is represented by @@ -2732,7 +2732,7 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope A classifier is an array of \field{selectors}. The number of selectors in the array is indicated by \field{count}. The selector has a type that specifies the header fields to be matched against, and a mask. -See \ref{lst:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_SELECTOR_CAP / virtio_net_ff_selector} +See \ref{lst:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-SELECTOR-CAP / virtio-net-ff-selector} for details about selectors. The first selector is always VIRTIO_NET_FF_MASK_TYPE_ETH. When there are multiple @@ -2765,7 +2765,7 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope field size. For example, a partial mask for the Ethernet header source mac address can be of 1-bit for multicast detection instead of 48-bits. -\subparagraph{VIRTIO_NET_RESOURCE_OBJ_FF_RULE}\label{par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO_NET_RESOURCE_OBJ_FF_RULE} +\subparagraph{VIRTIO_NET_RESOURCE_OBJ_FF_RULE}\label{par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO-NET-RESOURCE-OBJ-FF-RULE} Each flow filter rule resource object comprises a key, a priority, and an action. For the flow filter rule object, @@ -2837,7 +2837,7 @@ \subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Ope \field{action} is the action to take when a packet matches the \field{key} using the \field{classifier_id}. Supported actions are described in -\ref{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO_NET_FF_ACTION_CAP / flow filter rule actions}. +\ref{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-ACTION-CAP / flow filter rule actions}. \field{vq_index} specifies a receive virtqueue. When the \field{action} is set to VIRTIO_NET_FF_ACTION_DIRECT_RX_VQ, and the packet matches the \field{key}, From 2a5a957a25718e0b9e28b49ed6ef1a28f1b7097e Mon Sep 17 00:00:00 2001 From: Viresh Kumar Date: Wed, 14 Aug 2024 20:27:00 +0530 Subject: [PATCH 47/62] virtio-transport: Add a section to define mandatory transport requirements The current Virtio documentation lacks a set of generic requirements applicable to all transports. Defining these generic requirements could be beneficial when integrating support for a new transport. This section outlines the essential requirements that any transport method must adhere to. Signed-off-by: Viresh Kumar Fixes: https://github.com/oasis-tcs/virtio-spec/issues/201 Reviewed-by: Stefano Garzarella Link: https://lore.kernel.org/r/4c24ede14e2545b2e9c69e7d9b79dc15744fd965.1723647318.git.viresh.kumar@linaro.org --- main.tex | 2 ++ newtransport.tex | 43 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+) create mode 100644 newtransport.tex diff --git a/main.tex b/main.tex index b1913d6..6d33721 100644 --- a/main.tex +++ b/main.tex @@ -42,6 +42,8 @@ \input{newdevice.tex} +\input{newtransport.tex} + % acknowledgements \input{acknowledgements.tex} diff --git a/newtransport.tex b/newtransport.tex new file mode 100644 index 0000000..b3e0df4 --- /dev/null +++ b/newtransport.tex @@ -0,0 +1,43 @@ +\chapter{Creating New Transports}\label{sec:Creating New Transports} + +Devices and drivers utilize various transport methods to facilitate +communication, such as PCI, MMIO, or Channel I/O. These transport +methods determine aspects of the interaction between the device and the +driver, including device discovery, capability exchange, interrupt +handling, and data transfer. For instance, in a host/guest architecture, +the host might expose a device to the guest via a virtual PCI bus, and +the guest would use a PCI device driver to interface with the device. + +This section outlines the mandatory requirements that a transport method +implements. + +A transport provides a mechanism to implement configuration space for +the device. + +A transport provides a mechanism for the driver to identify the device +type. + +A transport provides a mechanism for the driver to read the device's +FEATURES_OK and DEVICE_NEEDS_RESET status bits. + +A transport provides a mechanism for the driver to modify the device's +status. + +A transport provides a mechanism for the driver to read and modify the +device's feature bits. + +A transport allows one or more virtqueues to be implemented by the +device. The number of virtqueues is device specific and not specified by +the transport. + +A transport provides a mechanism for the driver to communicate virtqueue +configuration and memory location to the device. + +A transport provides a mechanism for the device to send device +notifications to the driver, such as used buffer notifications. + +A transport provides a mechanism for the driver to send driver +notifications to the device, such as available buffer notifications. + +A transport provides a mechanism for the driver to initiate a device +reset. From 1d388440700dca2cb2fca220990036a21723c992 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Mon, 16 Sep 2024 06:08:31 +0300 Subject: [PATCH 48/62] device-parts: editorial: Add missing struct keyword 'struct' keyword was missing in the definition. Add it. Branch: virtio-1.4 Fixes: aa4f6f06 ("admin: Add admin commands for device parts") Signed-off-by: Parav Pandit Link: https://lore.kernel.org/r/20240916030835.68178-2-parav@nvidia.com --- admin-cmds-device-parts.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/admin-cmds-device-parts.tex b/admin-cmds-device-parts.tex index 4c88045..27d8251 100644 --- a/admin-cmds-device-parts.tex +++ b/admin-cmds-device-parts.tex @@ -131,7 +131,7 @@ \subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Dev le32 count; le32 reserved; } hdr_list_count; - { + struct { le32 count; le32 reserved; struct virtio_dev_part_hdr hdrs[]; From 9081da1f1e5880d88c8b871efe6a64bb3109fcff Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Mon, 16 Sep 2024 06:08:32 +0300 Subject: [PATCH 49/62] device-parts: editorial: Fix metadata type name The description is for the type VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_LIST; however, it referred to a non-existent definition. Correct it. Branch: virtio-1.4 Fixes: aa4f6f069ab3 ("admin: Add admin commands for device parts") Fixes: https://github.com/oasis-tcs/virtio-spec/issues/205 Reviewed-by: Matias Ezequiel Vara Larsen Signed-off-by: Parav Pandit Link: https://lore.kernel.org/r/20240916030835.68178-3-parav@nvidia.com --- admin-cmds-device-parts.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/admin-cmds-device-parts.tex b/admin-cmds-device-parts.tex index 27d8251..3a16692 100644 --- a/admin-cmds-device-parts.tex +++ b/admin-cmds-device-parts.tex @@ -152,10 +152,10 @@ \subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Dev device responds with \field{hdr_list_count.count}. The \field{hdr_list_count.count} indicates an count of \field{struct virtio_dev_part_hdr} metadata entries that the device can -provide when the \field{type} is set to VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_HDR +provide when the \field{type} is set to VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_LIST in a subsequent VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET command. -When \field{type} is set to VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_HDR, +When \field{type} is set to VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_LIST, the device responds with \field{hdr_list}. \field{hdr_list} indicates the device parts metadata. From b820c61e4840bfb618fd3704ec55e2933999f1f3 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Mon, 16 Sep 2024 06:08:33 +0300 Subject: [PATCH 50/62] crypto: editorial: Fix spelling errors Fix spelling errors. Branch: virtio-1.4 Fixes: a385dd3366a2 ("virtio-crypto: Add virtio crypto device specification") Fixes: https://github.com/oasis-tcs/virtio-spec/issues/205 Reviewed-by: Matias Ezequiel Vara Larsen Signed-off-by: Parav Pandit Link: https://lore.kernel.org/r/20240916030835.68178-4-parav@nvidia.com --- device-types/crypto/description.tex | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/device-types/crypto/description.tex b/device-types/crypto/description.tex index 5705e26..e053cc7 100644 --- a/device-types/crypto/description.tex +++ b/device-types/crypto/description.tex @@ -424,11 +424,11 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Crypto Device / Devic \field{header} is a general header (see above). -\field{op_flf} is the opcode (in \field{header}) specific fixed-length paramenters. +\field{op_flf} is the opcode (in \field{header}) specific fixed-length parameters. \field{flf_len} depends on the VIRTIO_CRYPTO_F_REVISION_1 feature bit (see below). -\field{op_vlf} is the opcode (in \field{header}) specific variable-length paramenters. +\field{op_vlf} is the opcode (in \field{header}) specific variable-length parameters. \field{vlf_len} is the size of the specific structure used. \begin{note} @@ -509,7 +509,7 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Crypto Device / Devic \subparagraph{Session operation: HASH session}\label{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation / Session operation: HASH session} -The fixed-length paramenters of HASH session requests is as follows: +The fixed-length parameters of HASH session requests is as follows: \begin{lstlisting} struct virtio_crypto_hash_create_session_flf { @@ -1386,7 +1386,7 @@ \subsubsection{Symmetric algorithms Operation}\label{sec:Device Types / Crypto D \end{itemize*} The length of \field{op_type_flf} is fixed to 40 bytes, the data of unused -part (if has) will be ingored. +part (if has) will be ignored. \field{op_type_vlf} is the \field{op_type} specific parameters, it MUST starts with or be one of the following structures: @@ -1536,7 +1536,7 @@ \subsubsection{Symmetric algorithms Operation}\label{sec:Device Types / Crypto D \end{itemize*} The length of \field{op_type_flf} is fixed to 72 bytes, the data of unused -part (if has) will be ingored. +part (if has) will be ignored. \field{op_type_vlf} is the \field{op_type} specific parameters, it MUST starts with or be one of the following structures: From ec1845bd5a0261a65e29137f949ba03bf2fb44e2 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Mon, 16 Sep 2024 06:08:34 +0300 Subject: [PATCH 51/62] gpu: editorial: Fix spelling errors Fix spelling errors. Branch: virtio-1.4 Fixes: fed64230bf31 ("Add virtio gpu device specification.") Fixes: https://github.com/oasis-tcs/virtio-spec/issues/205 Reviewed-by: Matias Ezequiel Vara Larsen Signed-off-by: Parav Pandit Link: https://lore.kernel.org/r/20240916030835.68178-5-parav@nvidia.com --- device-types/gpu/description.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/device-types/gpu/description.tex b/device-types/gpu/description.tex index 66e4873..ba4ea76 100644 --- a/device-types/gpu/description.tex +++ b/device-types/gpu/description.tex @@ -166,7 +166,7 @@ \subsubsection{Device Operation: Multihead setup} \devicenormative{\subsubsection}{Device Operation: Command lifecycle and fencing}{Device Types / GPU Device / Device Operation / Device Operation: Command lifecycle and fencing} -The device MAY process controlq commands asyncronously and return them +The device MAY process controlq commands asynchronously and return them to the driver before the processing is complete. If the driver needs to know when the processing is finished it can set the VIRTIO_GPU_FLAG_FENCE flag in the request. The device MUST finish the @@ -345,7 +345,7 @@ \subsubsection{Device Operation: controlq}\label{sec:Device Types / GPU Device / display). The \field{enabled} field is set when the user enabled the display. -It is roughly the same as the connected state of a phyiscal display +It is roughly the same as the connected state of a physical display connector. \item[VIRTIO_GPU_CMD_GET_EDID] Retrieve the EDID data for a given From 9d60d8457df04f21ca6edcc94474ff53a3be2adf Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Mon, 16 Sep 2024 06:08:35 +0300 Subject: [PATCH 52/62] common: editorial: Fix spelling errors Fix spelling errors. Branch: virtio-1.4 Fixes: 5f1a8ac61c15 ("admin: introduce virtio admin virtqueues") Fixes: 68f66ff7a3d9 ("content: define what an exported object is") Fixes: ef16b644cc25 ("content.tex: spec text converted to latex") Fixes: https://github.com/oasis-tcs/virtio-spec/issues/205 Reviewed-by: Matias Ezequiel Vara Larsen Signed-off-by: Parav Pandit Link: https://lore.kernel.org/r/20240916030835.68178-6-parav@nvidia.com --- admin.tex | 2 +- content.tex | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/admin.tex b/admin.tex index 39fc072..cfca5e3 100644 --- a/admin.tex +++ b/admin.tex @@ -491,7 +491,7 @@ \section{Administration Virtqueues}\label{sec:Basic Facilities of a Virtio Devic than one administration virtqueue. If VIRTIO_F_ADMIN_VQ has been negotiated, an owner device exposes one -or more adminstration virtqueues. The number and locations of the +or more administration virtqueues. The number and locations of the administration virtqueues are exposed by the owner device in a transport specific manner. diff --git a/content.tex b/content.tex index c32c218..0851c53 100644 --- a/content.tex +++ b/content.tex @@ -493,7 +493,7 @@ \section{Driver Notifications} \label{sec:Basic Facilities of a Virtio Device / \section{Exporting Objects}\label{sec:Basic Facilities of a Virtio Device / Exporting Objects} When an object created by one virtio device needs to be -shared with a seperate virtio device, the first device can +shared with a separate virtio device, the first device can export the object by generating a UUID which can then be passed to the second device to identify the object. @@ -508,7 +508,7 @@ \section{Exporting Objects}\label{sec:Basic Facilities of a Virtio Device / Expo \chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation} We start with an overview of device initialization, then expand on the -details of the device and how each step is preformed. This section +details of the device and how each step is performed. This section is best read along with the bus-specific section which describes how to communicate with the specific device. From e98070a9573fcb89fba6111df236ffe7559c9def Mon Sep 17 00:00:00 2001 From: Albert Esteve Date: Fri, 6 Sep 2024 09:08:33 +0200 Subject: [PATCH 53/62] content: Reserve ID for media device Reserve device ID 49 for media device. Compatible with video encoder, video decoder, and capture devices. Signed-off-by: Albert Esteve Fixes: https://github.com/oasis-tcs/virtio-spec/issues/202 Link: https://lore.kernel.org/r/20240906070833.1949727-1-aesteve@redhat.com --- content.tex | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content.tex b/content.tex index 0851c53..67b1bf3 100644 --- a/content.tex +++ b/content.tex @@ -744,6 +744,8 @@ \chapter{Device Types}\label{sec:Device Types} \hline 47 & CPU balloon device \\ \hline +48 & Media device \\ +\hline \end{longtable} Some of the devices above are unspecified by this document, From 417fb28849c6ecac3b18a35e8a154c03f8dba66f Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Sun, 27 Oct 2024 06:44:57 +0200 Subject: [PATCH 54/62] virtio-gpu: Fix spelling error Fix spelling error. Fixes: fed64230bf31 ("Add virtio gpu device specification.") Fixes: https://github.com/oasis-tcs/virtio-spec/issues/192 Signed-off-by: Parav Pandit Reviewed-by: Matias Ezequiel Vara Larsen --- device-types/gpu/description.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/device-types/gpu/description.tex b/device-types/gpu/description.tex index ba4ea76..c5706bc 100644 --- a/device-types/gpu/description.tex +++ b/device-types/gpu/description.tex @@ -128,7 +128,7 @@ \subsubsection{Device Operation: Create a framebuffer and configure scanout} \item Allocate a framebuffer from guest ram, and attach it as backing storage to the resource just created, using VIRTIO_GPU_CMD_RESOURCE_ATTACH_BACKING. Scatter lists are - supported, so the framebuffer doesn't need to be contignous in guest + supported, so the framebuffer doesn't need to be contiguous in guest physical memory. \item Use VIRTIO_GPU_CMD_SET_SCANOUT to link the framebuffer to a display scanout. From d17c70ab971c62b0be518e055626a460c4453092 Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Sun, 3 Nov 2024 07:09:58 +0200 Subject: [PATCH 55/62] Revert "virtio-gpu: Fix spelling error" This reverts commit 417fb28849c6ecac3b18a35e8a154c03f8dba66f. Reverted due to missing Link in commit log. Signed-off-by: Parav Pandit --- device-types/gpu/description.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/device-types/gpu/description.tex b/device-types/gpu/description.tex index c5706bc..ba4ea76 100644 --- a/device-types/gpu/description.tex +++ b/device-types/gpu/description.tex @@ -128,7 +128,7 @@ \subsubsection{Device Operation: Create a framebuffer and configure scanout} \item Allocate a framebuffer from guest ram, and attach it as backing storage to the resource just created, using VIRTIO_GPU_CMD_RESOURCE_ATTACH_BACKING. Scatter lists are - supported, so the framebuffer doesn't need to be contiguous in guest + supported, so the framebuffer doesn't need to be contignous in guest physical memory. \item Use VIRTIO_GPU_CMD_SET_SCANOUT to link the framebuffer to a display scanout. From 4a5df407eca342ca3737d2fd598dbd393d958b4f Mon Sep 17 00:00:00 2001 From: Parav Pandit Date: Sun, 27 Oct 2024 06:44:57 +0200 Subject: [PATCH 56/62] virtio-gpu: Fix spelling error Fix spelling error. Fixes: fed64230bf31 ("Add virtio gpu device specification.") Fixes: https://github.com/oasis-tcs/virtio-spec/issues/192 Signed-off-by: Parav Pandit Reviewed-by: Matias Ezequiel Vara Larsen Link: https://lore.kernel.org/r/20241027044457.495730-1-parav@nvidia.com --- device-types/gpu/description.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/device-types/gpu/description.tex b/device-types/gpu/description.tex index ba4ea76..c5706bc 100644 --- a/device-types/gpu/description.tex +++ b/device-types/gpu/description.tex @@ -128,7 +128,7 @@ \subsubsection{Device Operation: Create a framebuffer and configure scanout} \item Allocate a framebuffer from guest ram, and attach it as backing storage to the resource just created, using VIRTIO_GPU_CMD_RESOURCE_ATTACH_BACKING. Scatter lists are - supported, so the framebuffer doesn't need to be contignous in guest + supported, so the framebuffer doesn't need to be contiguous in guest physical memory. \item Use VIRTIO_GPU_CMD_SET_SCANOUT to link the framebuffer to a display scanout. From 8a1a2fdda11e2e1ed46fd73133176ed814bfa448 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Tue, 5 Nov 2024 12:22:18 +0000 Subject: [PATCH 57/62] github: tweak PR template for virtio-msg (!UPSTREAM) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit While we are working on the virtio-msg specification in the repository lets not confuse people by using the canned response for the upstream repository. Signed-off-by: Alex Bennée --- .github/PULL_REQUEST_TEMPLATE.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 69d41fc..ea4ed16 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,10 +1,8 @@ -# Thanks for proposing a change to the Virtual I/O Device (VIRTIO) specification! -The VIRTIO TC is not yet accepting pull requests at this time as they are not -integrated with our voting system. +# Thanks for proposing a change to the virtio-msg specification -Instead, please -- [] Propose the spec change (preferably as a patch) on the [mailing list](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback). -- [] Open an [issue](https://github.com/oasis-tcs/virtio-spec/issues), - including the link to the proposal in the [mailing list archives](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback). +This is not the same as proposing a change to the VirtIO spec. This +repository is intended for preparing the virtio-msg transport +specification before it's submission to the VIRTIO TC. -The TC will vote and apply the change. +If your intention was to suggestion to change to the upstream please +propose the change as a patch to the [mailing list](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback). From cc3232f71c023997efa36f7665f5f1001f66d36b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Tue, 12 Nov 2024 15:41:13 +0000 Subject: [PATCH 58/62] REVISION: set to 1.4 working draft as a base (!UPSTREAM) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Alex Bennée --- REVISION | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/REVISION b/REVISION index ba56baf..e3c043e 100644 --- a/REVISION +++ b/REVISION @@ -1 +1 @@ -virtio-v1.3-csd01 +virtio-v1.4-wd01 From 986b7e07a99f83376e037db374b0d93524afcd72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Mon, 23 Mar 2020 18:39:57 +0000 Subject: [PATCH 59/62] Makefile: add some simple make automations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is just a helpful shortcut, especially when editing the documents within an IDE which will offer up make targets to build the documents. Signed-off-by: Alex Bennée --- Makefile | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 Makefile diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..4c7dc66 --- /dev/null +++ b/Makefile @@ -0,0 +1,26 @@ +# -*- Mode: makefile -*- +# +# Basic Makefile to aid automation of document building +# + +.PHONY: all +all: + ./makeall.sh + +.PHONY: html +html: + ./makehtml.sh + +.PHONY: clean +clean: + git clean -fd + +.PHONY: help +help: + @echo "Build the VIRTIO specification documents." + @echo "" + @echo "Possible operations are:" + @echo + @echo " $(MAKE) Build everything" + @echo " $(MAKE) html Build local html" + @echo " $(MAKE) clean Remove all intermediate files" From 224761f8308f1a04cb67cb52ea2aa04f1f352dcf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Fri, 19 Jun 2020 21:23:09 +0100 Subject: [PATCH 60/62] make-setup-generated: optionally add GIT metadata MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This isn't a full conversion to git based metadata but it allows for local builds to add git commit and tree status to the final built product. The normal formal build process is unaffected and uses manually updated VERSION, REVISION and REVISION-DATE metadata. Signed-off-by: Alex Bennée --- Makefile | 11 +++++++++-- make-setup-generated.sh | 31 +++++++++++++++++++++++++++---- makeall.sh | 4 ++-- makehtml.sh | 2 +- makepdf.sh | 2 +- 5 files changed, 40 insertions(+), 10 deletions(-) diff --git a/Makefile b/Makefile index 4c7dc66..989b429 100644 --- a/Makefile +++ b/Makefile @@ -3,14 +3,21 @@ # Basic Makefile to aid automation of document building # -.PHONY: all +.PHONY: all local all: ./makeall.sh -.PHONY: html +local-all: + ./makeall.sh local + +.PHONY: html local-html + html: ./makehtml.sh +local-html: + ./makehtml.sh local + .PHONY: clean clean: git clean -fd diff --git a/make-setup-generated.sh b/make-setup-generated.sh index 2c5c7f8..3380437 100755 --- a/make-setup-generated.sh +++ b/make-setup-generated.sh @@ -1,16 +1,31 @@ #! /bin/sh +# +# Generate version and metadata preamble for the document +# DATESTR=${DATESTR:-`cat REVISION-DATE 2>/dev/null`} -if [ x"$DATESTR" = x ]; then - ISODATE=`git show --format=format:'%cd' --date=iso | head -n 1` - DATESTR=`date -d "$DATE" +'%d %B %Y'` + +# If a second argument is passed we extract what we can from git +# metadata (closest lightweight tag) and local tree status. This +# allows locally generated copies to be tagged appropriately. +# +# The formal build process skips this. +if ! test -z "$2"; then + TAG=$(git describe --dirty --tags) + # base date on now + DATESTR=$(date +'%d %B %Y') + COMMIT=$(git rev-parse --short HEAD) + + # Finally check if we have un-committed changes in the tree + if ! git diff-index --quiet HEAD -- ; then + COMMIT="$COMMIT with local changes" + fi fi case "$1" in *-wd*) STAGE=wd STAGENAME="Working Draft" - WORKINGDRAFT=`basename "$1" | sed 's/.*-wd//'` ;; *-os*) STAGE=os @@ -41,6 +56,14 @@ esac VERSION=`echo "$1"| sed -e 's/virtio-v//' -e 's/-.*//'` +# +# Finally if we are building a local draft copy append the commit +# details to the end of the working draft +# +if ! test -z "$COMMIT" ; then + STAGEEXTRATITLE="$STAGEEXTRATITLE (@ git $COMMIT)" +fi + #Prepend OASIS unless already there case "$STAGENAME" in OASIS*) diff --git a/makeall.sh b/makeall.sh index 37e6c34..5f5d5dc 100755 --- a/makeall.sh +++ b/makeall.sh @@ -3,8 +3,8 @@ export SPECDOC=${SPECDOC:-`cat REVISION`} export DATESTR=${DATESTR:-`cat REVISION-DATE`} ./makezip.sh -./makehtml.sh -./makepdf.sh +./makehtml.sh $1 +./makepdf.sh $1 zip $SPECDOC.zip $SPECDOC.pdf echo Generated file $SPECDOC.zip echo To change output file name, set SPECDOC environment variable diff --git a/makehtml.sh b/makehtml.sh index 45b7080..cf1a8d7 100755 --- a/makehtml.sh +++ b/makehtml.sh @@ -1,7 +1,7 @@ #!/bin/sh SPECDOC=${SPECDOC:-`cat REVISION`} -./make-setup-generated.sh "$SPECDOC" +./make-setup-generated.sh "$SPECDOC" $1 cp virtio-html.tex $SPECDOC.tex diff --git a/makepdf.sh b/makepdf.sh index 9cae903..bdfb8e5 100755 --- a/makepdf.sh +++ b/makepdf.sh @@ -1,7 +1,7 @@ #!/bin/sh SPECDOC=${SPECDOC:-`cat REVISION`} -./make-setup-generated.sh "$SPECDOC" +./make-setup-generated.sh "$SPECDOC" $1 rm $SPECDOC.aux $SPECDOC.pdf $SPECDOC.out xelatex --jobname $SPECDOC virtio.tex From b31fdee9e411500f229584c0379b36c49e973a30 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Tue, 5 Nov 2024 12:14:20 +0000 Subject: [PATCH 61/62] github: add basic test build MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Alex Bennée --- .github/workflows/test.yml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 .github/workflows/test.yml diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..180fd17 --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,18 @@ +name: CI + +on: + push: + pull_request: + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Install Tools + run: | + sudo apt install texlive-full + + - name: Build HTML + run: | + make local-html From 61c244f7687c64d8dbfeed827e646bf736647f6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Wed, 13 Nov 2024 09:49:32 +0000 Subject: [PATCH 62/62] github: add deploy step MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This pushes the PDF as a release artefact. Signed-off-by: Alex Bennée --- .github/workflows/deploy.yaml | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 .github/workflows/deploy.yaml diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml new file mode 100644 index 0000000..2cc39e3 --- /dev/null +++ b/.github/workflows/deploy.yaml @@ -0,0 +1,27 @@ +name: Deploy current state + +on: + push: + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Install Tools + run: | + sudo apt install texlive-full + + - name: Build Docs + run: | + make local-all + echo ${{ github.sha }} > Release.txt + + - name: Create a Draft Release + uses: softprops/action-gh-release@v2 + with: + draft: true + name: working-draft + files: | + Release.txt + virtio-v1.4-wd01.pdf