virtio-net: support the virtqueue coalescing moderation
PATCH v9 1/1 virtio-net: support the virtqueue coalescing moderation
Currently, coalescing parameters are grouped for all transmit and receive virtqueues. This patch supports setting or getting the parameters for a specified virtqueue, and a typical application of this function is netdim[1].
When the traffic between virtqueues is unbalanced, for example, one virtqueue is busy and another virtqueue is idle, then it will be very useful to control coalescing parameters at the virtqueue granularity.
[1] https://docs.kernel.org/networking/net_dim.html
---
This patch is on top of Alvaro's latest v7 patch: https://lists.oasis-open.org/archives/virtio-dev/202302/msg00431.html .
v8->v9:
1. Declare the commands that can be sent for each feature. @Alvaro Karsz
2. Add information about "global values" in the command's explanation. @Alvaro Karsz
v7->v8:
1. Use "best-effort" in Alvaro's patch instead of "the device may set the parameter to a value close to 2". @Michael S . Tsirkin, @David Edmondson
v6->v7:
1. Clarify the relationship of VIRTIO_NET_CTRL_NOTF_COAL_TX/RX_SET and VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET. @Alvaro Karsz, @Michael S. Tsirkin
2. Remove the formula for vqn range. @Parav Pandit
3. Some expressions are clearer. @Parav Pandit, @Michael S. Tsirkin
v5->v6:
1. Explain that the device may set a different value than the one passed in by the driver. @David Edmondson
v4->v5:
1. Add the correspondence between virtio_net_ctrl_coal and virtio_net_ctrl_coal_vq and control commands. @Michael S. Tsirkin
2. Add read and write attributes for each field. @Michael S. Tsirkin
3. A clearer description of how to set coalescing parameters for vq reset. @Michael S. Tsirkin
4. Fix some syntax errors. @Michael S. Tsirkin, @David Edmondson
v3->v4:
1. Include virtio_net_ctrl_coal in the virtio_net_ctrl_coal_vq structure. @Alvaro Karsz
2. Add consideration of vq reset. @Michael S. Tsirkin, @Parav Pandit, @Alvaro Karsz
3. Avoid too many examples by giving a comprehensive example. @Michael S. Tsirkin
4. Fix typos and streamline clarifications. @Michael S. Tsirkin, @Parav Pandit, @Alvaro Karsz
v2->v3:
1. Add the netdim link. @Parav Pandit
2. VIRTIO_NET_F_VQ_NOTF_COAL no longer depends on VIRTIO_NET_F_NOTF_COAL. @Michael S. Tsirkin, @Alvaro Karsz
3. _VQ_GET is explained more. @Michael S. Tsirkin
4. Add more examples to avoid misunderstandings. @Michael S. Tsirkin
5. Clarify some statements. @Michael S. Tsirkin, @Parav Pandit, @Alvaro Karsz
6. Adjust the virtio_net_ctrl_coal_vq structure. @Michael S. Tsirkin
7. Fix some typos. @Michael S. Tsirkin
v1->v2:
1. Rename VIRTIO_NET_F_PERQUEUE_NOTF_COAL to VIRTIO_NET_F_VQ_NOTF_COAL. @Michael S. Tsirkin
2. Use the \field{vqn} instead of the qid. @Michael S. Tsirkin
3. Unify tx and rx control structures into one structure virtio_net_ctrl_coal_vq. @Michael S. Tsirkin
4. Add a new control command VIRTIO_NET_CTRL_NOTF_COAL_VQ. @Michael S. Tsirkin, @Parav Pandit, @Alvaro Karsz
5. The special value 0xFFF is removed because VIRTIO_NET_CTRL_NOTF_COAL can be used. @Alvaro Karsz
6. Clarify some special scenarios. @Michael S. Tsirkin, @Parav Pandit, @Alvaro Karsz
device-types/net/description.tex | 95 +++++++++++++++++++++++++++++--- 1 file changed, 87 insertions(+), 8 deletions(-)
device-types/net/description.tex +87 -8
@@ -83,6 +83,8 @@ \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_VQ_NOTF_COAL(52)] Device supports virtqueue notification coalescing. + \item[VIRTIO_NET_F_NOTF_COAL(53)] Device supports notifications coalescing. \item[VIRTIO_NET_F_GUEST_USO4 (54)] Driver can receive USOv4 packets.
@@ -139,6 +141,7 @@ \subsubsection{Feature bit requirements}\label{sec:Device Types / Network Device \item[VIRTIO_NET_F_NOTF_COAL] Requires VIRTIO_NET_F_CTRL_VQ. \item[VIRTIO_NET_F_RSC_EXT] Requires VIRTIO_NET_F_HOST_TSO4 or VIRTIO_NET_F_HOST_TSO6. \item[VIRTIO_NET_F_RSS] Requires VIRTIO_NET_F_CTRL_VQ. +\item[VIRTIO_NET_F_VQ_NOTF_COAL] Requires VIRTIO_NET_F_CTRL_VQ. \end{description} \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network Device / Feature bits / Legacy Interface: Feature bits}
@@ -1505,8 +1508,17 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi \paragraph{Notifications Coalescing}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing} -If the VIRTIO_NET_F_NOTF_COAL feature is negotiated, the driver can -send control commands for dynamically changing the coalescing parameters. +If the VIRTIO_NET_F_NOTF_COAL feature is negotiated, the driver can send the VIRTIO_NET_CTRL_NOTF_COAL_TX_SET +and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands to dynamically change the coalescing parameters for all transmit +and receive virtqueues, respectively. + +If the VIRTIO_NET_F_VQ_NOTF_COAL feature is negotiated: +\begin{itemize} +\item a driver can send a VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command to set coalescing parameters of a given + enabled transmit/receive virtqueue. +\item a driver can send a VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command to a device, and the device responds with + coalescing parameters of a given enabled transmit/receive virtqueue. +\end{itemize} \begin{note} The behavior of the device in response to these commands is best-effort:
@@ -1519,25 +1531,76 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi le32 max_usecs; }; +struct virtio_net_ctrl_coal_vq { + le16 vqn; + le16 reserved; + struct virtio_net_ctrl_coal coal; +}; + #define VIRTIO_NET_CTRL_NOTF_COAL 6 #define VIRTIO_NET_CTRL_NOTF_COAL_TX_SET 0 #define VIRTIO_NET_CTRL_NOTF_COAL_RX_SET 1 + #define VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET 2 + #define VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET 3 \end{lstlisting} +The VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands use the +virtio_net_ctrl_coal structure to set \field{max_usecs} and \field{max_packets} for all +transmit/receive virtqueues. + +The VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command uses the virtio_net_ctrl_coal_vq structure +to set \field{max_usecs} and \field{max_packets} for the supplied virtqueue number \field{vqn}. + +The VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command gets the values of \field{max_usecs} and +\field{max_packets} of the specified virtqueue from the device by setting \field{vqn} +in the virtio_net_ctrl_coal_vq structure. + +# Read/Write attributes for coalescing parameters +\begin{itemize} +\item For commands VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET, \field{max_usecs} + and \field{max_packets} are write-only for a driver. +\item For the command VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET, \field{vqn}, \field{reserved}, \field{max_usecs} + and \field{max_packets} are write-only for a driver. +\item For the command VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET, \field{vqn} and \field{reserved} are write-only + for a driver, and, \field{max_usecs} and \field{max_packets} are read-only for the driver. +\end{itemize} + Coalescing parameters: \begin{itemize} +\item \field{vqn}: The virtqueue number of an enabled transmit or receive virtqueue. \item \field{max_usecs} for RX: Maximum number of microseconds to delay a RX notification. \item \field{max_usecs} for TX: Maximum number of microseconds to delay a TX notification. \item \field{max_packets} for RX: Maximum number of packets to receive before a RX notification. \item \field{max_packets} for TX: Maximum number of packets to send before a TX notification. \end{itemize} -The class VIRTIO_NET_CTRL_NOTF_COAL has 2 commands: +\field{reserved} is reserved and it is ignored by a device. + +The class VIRTIO_NET_CTRL_NOTF_COAL has 4 commands: \begin{enumerate} -\item VIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues. -\item VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues. +\item VIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues, and values of + coalescing parameters are recorded as TX global values by a device. +\item VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues, and values of + coalescing parameters are recorded as RX global values by a device. +\item VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET: set the \field{max_usecs} and \field{max_packets} parameters for an enabled transmit/receive + virtqueue whose number is \field{vqn}, and do not change the TX/RX global values. +\item VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET: the device returns the \field{max_usecs} and \field{max_packets} parameters for an enabled + transmit/receive virtqueue whose number is \field{vqn}. \end{enumerate} +If coalescing parameters are being set, the device applies the last coalescing parameters received for a +virtqueue, regardless of the command used to set the parameters. For example with 2 pairs of virtqueues: +# Command sequence +Each of the following commands sets \field{max_usecs} and \field{max_packets} parameters for virtqueues. +\begin{itemize} +\item Command1: VIRTIO_NET_CTRL_NOTF_COAL_RX_SET sets coalescing parameters for virtqueue0 and virtqueue2, and, virtqueue1 and virtqueue3 retain their previous parameter values. +\item Command2: VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET with \field{vqn} = 0 sets coalescing parameters for virtqueue0, and virtqueue2 retains the values from command1. +\item Command3: VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET with \field{vqn} = 0, the device responds with coalescing parameters of virtqueue0 set by command2. +\item Command4: VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET with \field{vqn} = 1 sets coalescing parameters for virtqueue1, and virtqueue3 retains its previous values. +\item Command5: VIRTIO_NET_CTRL_NOTF_COAL_TX_SET sets coalescing parameters for virtqueue1 and virtqueue3, and overrides the values set by command4. +\item Command6: VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET with \field{vqn} = 1, the device responds with coalescing parameters of virtqueue1 set by command5. +\end{itemize} + \subparagraph{Operation}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing / Operation} The device sends a used buffer notification once the notification conditions are met and if the notifications are not suppressed as explained in \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Used Buffer Notification Suppression}.
@@ -1549,6 +1612,11 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi When the device has \field{max_usecs} = 0 or \field{max_packets} = 0, the notification conditions are met after every packet received/sent. +When the device receives the VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands, +it saves the values of coalescing parameters as global values, and the VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command +does not change the global values. If the device is reset, the global values will be set to 0. +When a virtqueue is enabled after virtqueue reset, its coalescing parameters are set to global values. + \subparagraph{RX Example}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing / RX Example} If, for example:
@@ -1585,15 +1653,26 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi \drivernormative{\subparagraph}{Notifications Coalescing}{Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing} -If the VIRTIO_NET_F_NOTF_COAL feature has not been negotiated, the driver MUST NOT issue VIRTIO_NET_CTRL_NOTF_COAL commands. +If neither the VIRTIO_NET_F_NOTF_COAL nor the VIRTIO_NET_F_VQ_NOTF_COAL feature +has been negotiated, the driver MUST NOT issue VIRTIO_NET_CTRL_NOTF_COAL commands. + +A driver MUST ignore the values of coalescing parameters received from the VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command if a device responds with VIRTIO_NET_ERR. \devicenormative{\subparagraph}{Notifications Coalescing}{Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing} -A device SHOULD respond to the VIRTIO_NET_CTRL_NOTF_COAL commands with VIRTIO_NET_ERR if it was not able to change the parameters. +A device SHOULD respond to VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands with VIRTIO_NET_ERR if it was not able to change the parameters. + +A device MUST respond to the VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command with VIRTIO_NET_ERR if it was not able to change the parameters. + +A device MUST respond to VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET and VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET commands with VIRTIO_NET_ERR if the given virtqueue is disabled. + +A device MUST ignore \field{reserved}. A device SHOULD NOT send used buffer notifications to the driver if the notifications are suppressed, even if the notification conditions are met. -Upon reset, a device MUST initialize all coalescing parameters to 0. +After disabling and re-enabling a virtqueue, the device MUST revert coalescing parameters of the virtqueue to the global values. + +Upon reset, a device MUST initialize all coalescing parameters to 0 and MUST set the global values to 0. \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device Types / Network Device / Legacy Interface: Framing Requirements}
Signature · 18 lines
2.19.1.6.gb485710b This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC. In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting. Subscribe: [email protected] Unsubscribe: [email protected] List help: [email protected] List archive: https://lists.oasis-open.org/archives/virtio-comment/ Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists Committee: https://www.oasis-open.org/committees/virtio/ Join OASIS: https://www.oasis-open.org/join/
Hi,
Quoted 91 lines
Currently, coalescing parameters are grouped for all transmit and receive virtqueues. This patch supports setting or getting the parameters for a specified virtqueue, and a typical application of this function is netdim[1].
When the traffic between virtqueues is unbalanced, for example, one virtqueue is busy and another virtqueue is idle, then it will be very useful to control coalescing parameters at the virtqueue granularity.
[1] https://docs.kernel.org/networking/net_dim.html
Signed-off-by Heng Qi <[email protected]>Reviewed-by Xuan Zhuo <[email protected]>---
This patch is on top of Alvaro's latest v7 patch: https://lists.oasis-open.org/archives/virtio-dev/202302/msg00431.html .
v8->v9:
1. Declare the commands that can be sent for each feature. @Alvaro Karsz
2. Add information about "global values" in the command's explanation. @Alvaro Karsz
v7->v8:
1. Use "best-effort" in Alvaro's patch instead of "the device may set the parameter to a value close to 2". @Michael S . Tsirkin, @David Edmondson
v6->v7:
1. Clarify the relationship of VIRTIO_NET_CTRL_NOTF_COAL_TX/RX_SET andVIRTIO_NET_CTRL_NOTF_COAL_VQ_SET. @Alvaro Karsz, @Michael S. Tsirkin
2. Remove the formula for vqn range. @Parav Pandit
3. Some expressions are clearer. @Parav Pandit, @Michael S. Tsirkin
v5->v6:
1. Explain that the device may set a different value than the one passed in by the driver. @David Edmondson
v4->v5:
1. Add the correspondence betweenvirtio_net_ctrl_coalandvirtio_net_ctrl_coal_vqand control commands. @Michael S. Tsirkin
2. Add read and write attributes for each field. @Michael S. Tsirkin
3. A clearer description of how to set coalescing parameters for vq reset. @Michael S. Tsirkin
4. Fix some syntax errors. @Michael S. Tsirkin, @David Edmondson
v3->v4:
1. Includevirtio_net_ctrl_coalin thevirtio_net_ctrl_coal_vqstructure. @Alvaro Karsz
2. Add consideration of vq reset. @Michael S. Tsirkin, @Parav Pandit, @Alvaro Karsz
3. Avoid too many examples by giving a comprehensive example. @Michael S. Tsirkin
4. Fix typos and streamline clarifications. @Michael S. Tsirkin, @Parav Pandit, @Alvaro Karsz
v2->v3:
1. Add the netdim link. @Parav Pandit
2.VIRTIO_NET_F_VQ_NOTF_COALno longer depends onVIRTIO_NET_F_NOTF_COAL. @Michael S. Tsirkin, @Alvaro Karsz
3._VQ_GETis explained more. @Michael S. Tsirkin
4. Add more examples to avoid misunderstandings. @Michael S. Tsirkin
5. Clarify some statements. @Michael S. Tsirkin, @Parav Pandit, @Alvaro Karsz
6. Adjust thevirtio_net_ctrl_coal_vqstructure. @Michael S. Tsirkin
7. Fix some typos. @Michael S. Tsirkin
v1->v2:
1. RenameVIRTIO_NET_F_PERQUEUE_NOTF_COALtoVIRTIO_NET_F_VQ_NOTF_COAL. @Michael S. Tsirkin
2. Use the \field{vqn} instead of the qid. @Michael S. Tsirkin
3. Unify tx and rx control structures into one structurevirtio_net_ctrl_coal_vq. @Michael S. Tsirkin
4. Add a new control commandVIRTIO_NET_CTRL_NOTF_COAL_VQ. @Michael S. Tsirkin, @Parav Pandit, @Alvaro Karsz
5. The special value0xFFFis removed becauseVIRTIO_NET_CTRL_NOTF_COALcan be used. @Alvaro Karsz
6. Clarify some special scenarios. @Michael S. Tsirkin, @Parav Pandit, @Alvaro Karszdevice-types/net/description.tex | 95 +++++++++++++++++++++++++++++--- 1 file changed, 87 insertions(+), 8 deletions(-)device-types/net/description.tex +5
-2@@ -83,6 +83,8 @@ \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_VQ_NOTF_COAL(52)] Device supports virtqueue notification coalescing. + \item[VIRTIO_NET_F_NOTF_COAL(53)] Device supports notifications coalescing. \item[VIRTIO_NET_F_GUEST_USO4 (54)] Driver can receive USOv4 packets.@@ -139,6 +141,7 @@ \subsubsection{Feature bit requirements}\label{sec:Device Types / Network Device \item[VIRTIO_NET_F_NOTF_COAL] Requires VIRTIO_NET_F_CTRL_VQ. \item[VIRTIO_NET_F_RSC_EXT] Requires VIRTIO_NET_F_HOST_TSO4 or VIRTIO_NET_F_HOST_TSO6. \item[VIRTIO_NET_F_RSS] Requires VIRTIO_NET_F_CTRL_VQ. +\item[VIRTIO_NET_F_VQ_NOTF_COAL] Requires VIRTIO_NET_F_CTRL_VQ. \end{description} \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network Device / Feature bits / Legacy Interface: Feature bits}@@ -1505,8 +1508,17 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi \paragraph{Notifications Coalescing}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing} -If the VIRTIO_NET_F_NOTF_COAL feature is negotiated, the driver can -send control commands for dynamically changing the coalescing parameters. +If the VIRTIO_NET_F_NOTF_COAL feature is negotiated, the driver can send the VIRTIO_NET_CTRL_NOTF_COAL_TX_SET +and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands to dynamically change the coalescing parameters for all transmit
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1522
Quoted 10 lines
device-types/net/description.tex +9
-0+and receive virtqueues, respectively. + +If the VIRTIO_NET_F_VQ_NOTF_COAL feature is negotiated: +\begin{itemize} +\item a driver can send a VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command to set coalescing parameters of a given + enabled transmit/receive virtqueue. +\item a driver can send a VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command to a device, and the device responds with + coalescing parameters of a given enabled transmit/receive virtqueue. +\end{itemize}
The VQ_NOTF_COAL commands are enclosed in an itemize and the NOTF_COAL commands aren't.
I think that we should be consistent here.
I'm not sure that describing the commands in here is necessary, maybe just mentioning which commands can be used with which feature bit is enough (this is what I meant in v8, sorry if I wasn't clear).
I'm not saying that describing the commands in here is not good, but notice that the commands are described in 3 different places. This is #1.
Quoted 20 lines
device-types/net/description.tex +9
-0\begin{note} The behavior of the device in response to these commands is best-effort:@@ -1519,25 +1531,76 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi le32 max_usecs; }; +struct virtio_net_ctrl_coal_vq { + le16 vqn; + le16 reserved; + struct virtio_net_ctrl_coal coal; +}; + #define VIRTIO_NET_CTRL_NOTF_COAL 6 #define VIRTIO_NET_CTRL_NOTF_COAL_TX_SET 0 #define VIRTIO_NET_CTRL_NOTF_COAL_RX_SET 1 + #define VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET 2 + #define VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET 3 \end{lstlisting} +The VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands use the
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1557
Quoted 10 lines
device-types/net/description.tex +10
-0+virtio_net_ctrl_coal structure to set \field{max_usecs} and \field{max_packets} for all +transmit/receive virtqueues. + +The VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command uses the virtio_net_ctrl_coal_vq structure +to set \field{max_usecs} and \field{max_packets} for the supplied virtqueue number \field{vqn}. + +The VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command gets the values of \field{max_usecs} and +\field{max_packets} of the specified virtqueue from the device by setting \field{vqn} +in the virtio_net_ctrl_coal_vq structure. +
This is #2.
Quoted 25 lines
device-types/net/description.tex +14
-2+# Read/Write attributes for coalescing parameters +\begin{itemize} +\item For commands VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET, \field{max_usecs} + and \field{max_packets} are write-only for a driver. +\item For the command VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET, \field{vqn}, \field{reserved}, \field{max_usecs} + and \field{max_packets} are write-only for a driver. +\item For the command VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET, \field{vqn} and \field{reserved} are write-only + for a driver, and, \field{max_usecs} and \field{max_packets} are read-only for the driver. +\end{itemize} + Coalescing parameters: \begin{itemize} +\item \field{vqn}: The virtqueue number of an enabled transmit or receive virtqueue. \item \field{max_usecs} for RX: Maximum number of microseconds to delay a RX notification. \item \field{max_usecs} for TX: Maximum number of microseconds to delay a TX notification. \item \field{max_packets} for RX: Maximum number of packets to receive before a RX notification. \item \field{max_packets} for TX: Maximum number of packets to send before a TX notification. \end{itemize} -The class VIRTIO_NET_CTRL_NOTF_COAL has 2 commands: +\field{reserved} is reserved and it is ignored by a device. + +The class VIRTIO_NET_CTRL_NOTF_COAL has 4 commands: \begin{enumerate} -\item VIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues.
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1589
Quoted 10 lines
device-types/net/description.tex +8
-1-\item VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues. +\item VIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues, and values of + coalescing parameters are recorded as TX global values by a device. +\item VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues, and values of + coalescing parameters are recorded as RX global values by a device. +\item VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET: set the \field{max_usecs} and \field{max_packets} parameters for an enabled transmit/receive + virtqueue whose number is \field{vqn}, and do not change the TX/RX global values. +\item VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET: the device returns the \field{max_usecs} and \field{max_packets} parameters for an enabled + transmit/receive virtqueue whose number is \field{vqn}. \end{enumerate}
This is #3.
Quoted 18 lines
device-types/net/description.tex +13
-0+If coalescing parameters are being set, the device applies the last coalescing parameters received for a +virtqueue, regardless of the command used to set the parameters. For example with 2 pairs of virtqueues: +# Command sequence +Each of the following commands sets \field{max_usecs} and \field{max_packets} parameters for virtqueues. +\begin{itemize} +\item Command1: VIRTIO_NET_CTRL_NOTF_COAL_RX_SET sets coalescing parameters for virtqueue0 and virtqueue2, and, virtqueue1 and virtqueue3 retain their previous parameter values. +\item Command2: VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET with \field{vqn} = 0 sets coalescing parameters for virtqueue0, and virtqueue2 retains the values from command1. +\item Command3: VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET with \field{vqn} = 0, the device responds with coalescing parameters of virtqueue0 set by command2. +\item Command4: VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET with \field{vqn} = 1 sets coalescing parameters for virtqueue1, and virtqueue3 retains its previous values. +\item Command5: VIRTIO_NET_CTRL_NOTF_COAL_TX_SET sets coalescing parameters for virtqueue1 and virtqueue3, and overrides the values set by command4. +\item Command6: VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET with \field{vqn} = 1, the device responds with coalescing parameters of virtqueue1 set by command5. +\end{itemize} + \subparagraph{Operation}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing / Operation} The device sends a used buffer notification once the notification conditions are met and if the notifications are not suppressed as explained in \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Used Buffer Notification Suppression}.
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1619
Quoted 8 lines
device-types/net/description.tex +5
-0@@ -1549,6 +1612,11 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi When the device has \field{max_usecs} = 0 or \field{max_packets} = 0, the notification conditions are met after every packet received/sent. +When the device receives the VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands, +it saves the values of coalescing parameters as global values, and the VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command +does not change the global values. If the device is reset, the global values will be set to 0. +When a virtqueue is enabled after virtqueue reset, its coalescing parameters are set to global values. +
Maybe this explanation should be put closer to the commands descriptions, where the global coalescing parameters are mentioned for the first time.
Something like:
....
\item VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET: the device returns the \field{max_usecs} and \field{max_packets} parameters for an enabled
transmit/receive virtqueue whose number
is \field{vqn}.
The device maintains global coalescing parameters for TX and RX....
And maybe we should use "global coalescing parameters" instead of "global values" (in devicenormative as well).
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1657
Quoted 10 lines
device-types/net/description.tex +2
-1\subparagraph{RX Example}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing / RX Example} If, for example:@@ -1585,15 +1653,26 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi \drivernormative{\subparagraph}{Notifications Coalescing}{Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing} -If the VIRTIO_NET_F_NOTF_COAL feature has not been negotiated, the driver MUST NOT issue VIRTIO_NET_CTRL_NOTF_COAL commands. +If neither the VIRTIO_NET_F_NOTF_COAL nor the VIRTIO_NET_F_VQ_NOTF_COAL feature +has been negotiated, the driver MUST NOT issue VIRTIO_NET_CTRL_NOTF_COAL commands.
Maybe this part can be splitted to:
if the F1 feature has not been negotiated, the driver must not issue commands C1,C2.
if the F2 feature has not been negotiated, the driver must not issue commands C3,C4.
Quoted 14 lines
device-types/net/description.tex +9
-1+ +A driver MUST ignore the values of coalescing parameters received from the VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command if a device responds with VIRTIO_NET_ERR. \devicenormative{\subparagraph}{Notifications Coalescing}{Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing} -A device SHOULD respond to the VIRTIO_NET_CTRL_NOTF_COAL commands with VIRTIO_NET_ERR if it was not able to change the parameters. +A device SHOULD respond to VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands with VIRTIO_NET_ERR if it was not able to change the parameters. + +A device MUST respond to the VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command with VIRTIO_NET_ERR if it was not able to change the parameters. + +A device MUST respond to VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET and VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET commands with VIRTIO_NET_ERR if the given virtqueue is disabled. + +A device MUST ignore \field{reserved}.
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi
Quoted 10 lines
device-types/net/description.tex +3
-2A device SHOULD NOT send used buffer notifications to the driver if the notifications are suppressed, even if the notification conditions are met. -Upon reset, a device MUST initialize all coalescing parameters to 0. +After disabling and re-enabling a virtqueue, the device MUST revert coalescing parameters of the virtqueue to the global values. + +Upon reset, a device MUST initialize all coalescing parameters to 0 and MUST set the global values to 0. \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device Types / Network Device / Legacy Interface: Framing Requirements} --
Let's wait for more comments before the next version, I guess some may not agree with my comments.
This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.
Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
Hi, Alvaro.
Quoted 98 lines · Alvaro Karsz
Hi,
Quoted 96 lines
Currently, coalescing parameters are grouped for all transmit and receive virtqueues. This patch supports setting or getting the parameters for a specified virtqueue, and a typical application of this function is netdim[1].
When the traffic between virtqueues is unbalanced, for example, one virtqueue is busy and another virtqueue is idle, then it will be very useful to control coalescing parameters at the virtqueue granularity.
[1] https://docs.kernel.org/networking/net_dim.html
Signed-off-by Heng Qi <[email protected]>Reviewed-by Xuan Zhuo <[email protected]>---
This patch is on top of Alvaro's latest v7 patch: https://lists.oasis-open.org/archives/virtio-dev/202302/msg00431.html .
v8->v9:
1. Declare the commands that can be sent for each feature. @Alvaro Karsz
2. Add information about "global values" in the command's explanation. @Alvaro Karsz
v7->v8:
1. Use "best-effort" in Alvaro's patch instead of "the device may set the parameter to a value close to 2". @Michael S . Tsirkin, @David Edmondson
v6->v7:
1. Clarify the relationship of VIRTIO_NET_CTRL_NOTF_COAL_TX/RX_SET andVIRTIO_NET_CTRL_NOTF_COAL_VQ_SET. @Alvaro Karsz, @Michael S. Tsirkin
2. Remove the formula for vqn range. @Parav Pandit
3. Some expressions are clearer. @Parav Pandit, @Michael S. Tsirkin
v5->v6:
1. Explain that the device may set a different value than the one passed in by the driver. @David Edmondson
v4->v5:
1. Add the correspondence betweenvirtio_net_ctrl_coalandvirtio_net_ctrl_coal_vqand control commands. @Michael S. Tsirkin
2. Add read and write attributes for each field. @Michael S. Tsirkin
3. A clearer description of how to set coalescing parameters for vq reset. @Michael S. Tsirkin
4. Fix some syntax errors. @Michael S. Tsirkin, @David Edmondson
v3->v4:
1. Includevirtio_net_ctrl_coalin thevirtio_net_ctrl_coal_vqstructure. @Alvaro Karsz
2. Add consideration of vq reset. @Michael S. Tsirkin, @Parav Pandit, @Alvaro Karsz
3. Avoid too many examples by giving a comprehensive example. @Michael S. Tsirkin
4. Fix typos and streamline clarifications. @Michael S. Tsirkin, @Parav Pandit, @Alvaro Karsz
v2->v3:
1. Add the netdim link. @Parav Pandit
2.VIRTIO_NET_F_VQ_NOTF_COALno longer depends onVIRTIO_NET_F_NOTF_COAL. @Michael S. Tsirkin, @Alvaro Karsz
3._VQ_GETis explained more. @Michael S. Tsirkin
4. Add more examples to avoid misunderstandings. @Michael S. Tsirkin
5. Clarify some statements. @Michael S. Tsirkin, @Parav Pandit, @Alvaro Karsz
6. Adjust thevirtio_net_ctrl_coal_vqstructure. @Michael S. Tsirkin
7. Fix some typos. @Michael S. Tsirkin
v1->v2:
1. RenameVIRTIO_NET_F_PERQUEUE_NOTF_COALtoVIRTIO_NET_F_VQ_NOTF_COAL. @Michael S. Tsirkin
2. Use the \field{vqn} instead of the qid. @Michael S. Tsirkin
3. Unify tx and rx control structures into one structurevirtio_net_ctrl_coal_vq. @Michael S. Tsirkin
4. Add a new control commandVIRTIO_NET_CTRL_NOTF_COAL_VQ. @Michael S. Tsirkin, @Parav Pandit, @Alvaro Karsz
5. The special value0xFFFis removed becauseVIRTIO_NET_CTRL_NOTF_COALcan be used. @Alvaro Karsz
6. Clarify some special scenarios. @Michael S. Tsirkin, @Parav Pandit, @Alvaro Karszdevice-types/net/description.tex | 95 +++++++++++++++++++++++++++++--- 1 file changed, 87 insertions(+), 8 deletions(-)device-types/net/description.tex +10
-2@@ -83,6 +83,8 @@ \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_VQ_NOTF_COAL(52)] Device supports virtqueue notification coalescing. + \item[VIRTIO_NET_F_NOTF_COAL(53)] Device supports notifications coalescing. \item[VIRTIO_NET_F_GUEST_USO4 (54)] Driver can receive USOv4 packets.@@ -139,6 +141,7 @@ \subsubsection{Feature bit requirements}\label{sec:Device Types / Network Device \item[VIRTIO_NET_F_NOTF_COAL] Requires VIRTIO_NET_F_CTRL_VQ. \item[VIRTIO_NET_F_RSC_EXT] Requires VIRTIO_NET_F_HOST_TSO4 or VIRTIO_NET_F_HOST_TSO6. \item[VIRTIO_NET_F_RSS] Requires VIRTIO_NET_F_CTRL_VQ. +\item[VIRTIO_NET_F_VQ_NOTF_COAL] Requires VIRTIO_NET_F_CTRL_VQ. \end{description} \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network Device / Feature bits / Legacy Interface: Feature bits}@@ -1505,8 +1508,17 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi \paragraph{Notifications Coalescing}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing} -If the VIRTIO_NET_F_NOTF_COAL feature is negotiated, the driver can -send control commands for dynamically changing the coalescing parameters. +If the VIRTIO_NET_F_NOTF_COAL feature is negotiated, the driver can send the VIRTIO_NET_CTRL_NOTF_COAL_TX_SET +and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands to dynamically change the coalescing parameters for all transmit +and receive virtqueues, respectively. + +If the VIRTIO_NET_F_VQ_NOTF_COAL feature is negotiated: +\begin{itemize} +\item a driver can send a VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command to set coalescing parameters of a given
Quoted 8 lines
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1522
Quoted 5 lines
device-types/net/description.tex +4
-0+ enabled transmit/receive virtqueue. +\item a driver can send a VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command to a device, and the device responds with + coalescing parameters of a given enabled transmit/receive virtqueue. +\end{itemize}The
VQ_NOTF_COALcommands are enclosed in an itemize and theNOTF_COALcommands aren't.
I think that we should be consistent here.
The VQ commands are enclosed in an itemize because it has both GET and SET operations.
I don't think VIRTIO_NET_CTRL_NOTF_COAL_RX_SET and VIRTIO_NET_CTRL_NOTF_COAL_TX_SET
have to do this, because they are both settings, just in different directions, and we have described them like this elsewhere.
Quoted 3 lines
I'm not sure that describing the commands in here is necessary, maybe just mentioning which commands can be used with which feature bit is
Isn't that what this sentence does?
Quoted 4 lines
enough (this is what I meant in v8, sorry if I wasn't clear).
I'm not saying that describing the commands in here is not good, but notice that the commands are described in 3 different places.
Three places describe different effects.
#1 describes which commands are available for which feature.
#2 describes which command can use which structure.
#3 describes which parameters can be set for each command, and whether they can affect "global values". It is placed in the "Operation" section because it explains how the device should behave.
Maybe #1 and #2 descriptions can be combined and described together.
Quoted 106 lines
This is #1.
Quoted 20 lines
device-types/net/description.tex +9
-0\begin{note} The behavior of the device in response to these commands is best-effort:@@ -1519,25 +1531,76 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi le32 max_usecs; }; +struct virtio_net_ctrl_coal_vq { + le16 vqn; + le16 reserved; + struct virtio_net_ctrl_coal coal; +}; + #define VIRTIO_NET_CTRL_NOTF_COAL 6 #define VIRTIO_NET_CTRL_NOTF_COAL_TX_SET 0 #define VIRTIO_NET_CTRL_NOTF_COAL_RX_SET 1 + #define VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET 2 + #define VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET 3 \end{lstlisting} +The VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands use thedevice-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1557
Quoted 10 lines
device-types/net/description.tex +10
-0+virtio_net_ctrl_coal structure to set \field{max_usecs} and \field{max_packets} for all +transmit/receive virtqueues. + +The VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command uses the virtio_net_ctrl_coal_vq structure +to set \field{max_usecs} and \field{max_packets} for the supplied virtqueue number \field{vqn}. + +The VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command gets the values of \field{max_usecs} and +\field{max_packets} of the specified virtqueue from the device by setting \field{vqn} +in the virtio_net_ctrl_coal_vq structure. +This is #2.
Quoted 25 lines
device-types/net/description.tex +14
-2+# Read/Write attributes for coalescing parameters +\begin{itemize} +\item For commands VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET, \field{max_usecs} + and \field{max_packets} are write-only for a driver. +\item For the command VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET, \field{vqn}, \field{reserved}, \field{max_usecs} + and \field{max_packets} are write-only for a driver. +\item For the command VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET, \field{vqn} and \field{reserved} are write-only + for a driver, and, \field{max_usecs} and \field{max_packets} are read-only for the driver. +\end{itemize} + Coalescing parameters: \begin{itemize} +\item \field{vqn}: The virtqueue number of an enabled transmit or receive virtqueue. \item \field{max_usecs} for RX: Maximum number of microseconds to delay a RX notification. \item \field{max_usecs} for TX: Maximum number of microseconds to delay a TX notification. \item \field{max_packets} for RX: Maximum number of packets to receive before a RX notification. \item \field{max_packets} for TX: Maximum number of packets to send before a TX notification. \end{itemize} -The class VIRTIO_NET_CTRL_NOTF_COAL has 2 commands: +\field{reserved} is reserved and it is ignored by a device. + +The class VIRTIO_NET_CTRL_NOTF_COAL has 4 commands: \begin{enumerate} -\item VIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues.device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1589
Quoted 10 lines
device-types/net/description.tex +8
-1-\item VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues. +\item VIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues, and values of + coalescing parameters are recorded as TX global values by a device. +\item VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues, and values of + coalescing parameters are recorded as RX global values by a device. +\item VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET: set the \field{max_usecs} and \field{max_packets} parameters for an enabled transmit/receive + virtqueue whose number is \field{vqn}, and do not change the TX/RX global values. +\item VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET: the device returns the \field{max_usecs} and \field{max_packets} parameters for an enabled + transmit/receive virtqueue whose number is \field{vqn}. \end{enumerate}This is #3.
Quoted 17 lines
device-types/net/description.tex +13
-0+If coalescing parameters are being set, the device applies the last coalescing parameters received for a +virtqueue, regardless of the command used to set the parameters. For example with 2 pairs of virtqueues: +# Command sequence +Each of the following commands sets \field{max_usecs} and \field{max_packets} parameters for virtqueues. +\begin{itemize} +\item Command1: VIRTIO_NET_CTRL_NOTF_COAL_RX_SET sets coalescing parameters for virtqueue0 and virtqueue2, and, virtqueue1 and virtqueue3 retain their previous parameter values. +\item Command2: VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET with \field{vqn} = 0 sets coalescing parameters for virtqueue0, and virtqueue2 retains the values from command1. +\item Command3: VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET with \field{vqn} = 0, the device responds with coalescing parameters of virtqueue0 set by command2. +\item Command4: VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET with \field{vqn} = 1 sets coalescing parameters for virtqueue1, and virtqueue3 retains its previous values. +\item Command5: VIRTIO_NET_CTRL_NOTF_COAL_TX_SET sets coalescing parameters for virtqueue1 and virtqueue3, and overrides the values set by command4. +\item Command6: VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET with \field{vqn} = 1, the device responds with coalescing parameters of virtqueue1 set by command5. +\end{itemize} + \subparagraph{Operation}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing / Operation} The device sends a used buffer notification once the notification conditions are met and if the notifications are not suppressed as explained in \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Used Buffer Notification Suppression}.device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1619
Quoted 8 lines
device-types/net/description.tex +5
-0@@ -1549,6 +1612,11 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi When the device has \field{max_usecs} = 0 or \field{max_packets} = 0, the notification conditions are met after every packet received/sent. +When the device receives the VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands, +it saves the values of coalescing parameters as global values, and the VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command +does not change the global values. If the device is reset, the global values will be set to 0. +When a virtqueue is enabled after virtqueue reset, its coalescing parameters are set to global values. +Maybe this explanation should be put closer to the commands descriptions, where the global coalescing parameters are mentioned for the first time.
Something like:
....
\itemVIRTIO_NET_CTRL_NOTF_COAL_VQ_GET: the device returns the \field{max_usecs} and \field{max_packets} parameters for an enabled
transmit/receive virtqueue whose number
is \field{vqn}.
Quoted 1 line
The device maintains global coalescing parameters for TX and RX....
This is the "Operation" chapter, and the description of the operation is more likely to be placed here, isn't it?
Quoted 11 lines
And maybe we should use "global coalescing parameters" instead of "global values" (in devicenormative as well).
Quoted 7 lines
device-types/net/description.tex +0
-0\subparagraph{RX Example}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing / RX Example} If, for example:@@ -1585,15 +1653,26 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi \drivernormative{\subparagraph}{Notifications Coalescing}{Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing}
Quoted 8 lines
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1657
Quoted 3 lines
device-types/net/description.tex +2
-1-If the VIRTIO_NET_F_NOTF_COAL feature has not been negotiated, the driver MUST NOT issue VIRTIO_NET_CTRL_NOTF_COAL commands. +If neither the VIRTIO_NET_F_NOTF_COAL nor the VIRTIO_NET_F_VQ_NOTF_COAL feature +has been negotiated, the driver MUST NOT issue VIRTIO_NET_CTRL_NOTF_COAL commands.Maybe this part can be splitted to:
if the F1 feature has not been negotiated, the driver must not issue commands C1,C2.
if the F2 feature has not been negotiated, the driver must not issue commands C3,C4.
Ok.
Thanks.
Quoted 27 lines
Quoted 14 lines
device-types/net/description.tex +9
-1+ +A driver MUST ignore the values of coalescing parameters received from the VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command if a device responds with VIRTIO_NET_ERR. \devicenormative{\subparagraph}{Notifications Coalescing}{Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing} -A device SHOULD respond to the VIRTIO_NET_CTRL_NOTF_COAL commands with VIRTIO_NET_ERR if it was not able to change the parameters. +A device SHOULD respond to VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands with VIRTIO_NET_ERR if it was not able to change the parameters. + +A device MUST respond to the VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command with VIRTIO_NET_ERR if it was not able to change the parameters. + +A device MUST respond to VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET and VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET commands with VIRTIO_NET_ERR if the given virtqueue is disabled. + +A device MUST ignore \field{reserved}.device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi
Quoted 10 lines
device-types/net/description.tex +3
-2A device SHOULD NOT send used buffer notifications to the driver if the notifications are suppressed, even if the notification conditions are met. -Upon reset, a device MUST initialize all coalescing parameters to 0. +After disabling and re-enabling a virtqueue, the device MUST revert coalescing parameters of the virtqueue to the global values. + +Upon reset, a device MUST initialize all coalescing parameters to 0 and MUST set the global values to 0. \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device Types / Network Device / Legacy Interface: Framing Requirements} --Let's wait for more comments before the next version, I guess some may not agree with my comments.
Quoted 3 lines
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
Quoted 322 lines · Heng Qi
Hi, Alvaro.
Quoted 113 lines · Alvaro Karsz
Hi,
Quoted 111 lines
Currently, coalescing parameters are grouped for all transmit and receive virtqueues. This patch supports setting or getting the parameters for a specified virtqueue, and a typical application of this function is netdim[1].
When the traffic between virtqueues is unbalanced, for example, one virtqueue is busy and another virtqueue is idle, then it will be very useful to control coalescing parameters at the virtqueue granularity.
[1] https://docs.kernel.org/networking/net_dim.html
Signed-off-by Heng Qi <[email protected]>Reviewed-by Xuan Zhuo <[email protected]>---
This patch is on top of Alvaro's latest v7 patch: https://lists.oasis-open.org/archives/virtio-dev/202302/msg00431.html .
v8->v9:
1. Declare the commands that can be sent for each feature.
@Alvaro Karsz
2. Add information about "global values" in the command's explanation. @Alvaro Karsz
v7->v8:
1. Use "best-effort" in Alvaro's patch instead of "the device may set the parameter to a value close to 2". @Michael S . Tsirkin, @David Edmondson
v6->v7:
1. Clarify the relationship of VIRTIO_NET_CTRL_NOTF_COAL_TX/RX_SET andVIRTIO_NET_CTRL_NOTF_COAL_VQ_SET. @Alvaro Karsz, @Michael S. Tsirkin
2. Remove the formula for vqn range. @Parav Pandit
3. Some expressions are clearer. @Parav Pandit, @Michael S. Tsirkin
v5->v6:
1. Explain that the device may set a different value than the one passed in by the driver. @David Edmondson
v4->v5:
1. Add the correspondence betweenvirtio_net_ctrl_coalandvirtio_net_ctrl_coal_vqand control commands. @Michael S. Tsirkin
2. Add read and write attributes for each field. @Michael S. Tsirkin
3. A clearer description of how to set coalescing parameters for vq reset. @Michael S. Tsirkin
4. Fix some syntax errors. @Michael S. Tsirkin, @David Edmondson
v3->v4:
1. Includevirtio_net_ctrl_coalin thevirtio_net_ctrl_coal_vqstructure. @Alvaro Karsz
2. Add consideration of vq reset. @Michael S. Tsirkin,
@Parav Pandit, @Alvaro Karsz
3. Avoid too many examples by giving a comprehensive example. @Michael S. Tsirkin
4. Fix typos and streamline clarifications. @Michael S. Tsirkin, @Parav Pandit, @Alvaro Karsz
v2->v3:
1. Add the netdim link. @Parav Pandit
2.VIRTIO_NET_F_VQ_NOTF_COALno longer depends onVIRTIO_NET_F_NOTF_COAL. @Michael S. Tsirkin, @Alvaro Karsz
3._VQ_GETis explained more. @Michael S. Tsirkin
4. Add more examples to avoid misunderstandings. @Michael S. Tsirkin
5. Clarify some statements. @Michael S. Tsirkin, @Parav Pandit, @Alvaro Karsz
6. Adjust thevirtio_net_ctrl_coal_vqstructure. @Michael S. Tsirkin
7. Fix some typos. @Michael S. Tsirkin
v1->v2:
1. RenameVIRTIO_NET_F_PERQUEUE_NOTF_COALtoVIRTIO_NET_F_VQ_NOTF_COAL. @Michael S. Tsirkin
2. Use the \field{vqn} instead of the qid. @Michael S. Tsirkin
3. Unify tx and rx control structures into one structurevirtio_net_ctrl_coal_vq. @Michael S. Tsirkin
4. Add a new control commandVIRTIO_NET_CTRL_NOTF_COAL_VQ.
@Michael S. Tsirkin, @Parav Pandit, @Alvaro Karsz
5. The special value0xFFFis removed becauseVIRTIO_NET_CTRL_NOTF_COALcan be used. @Alvaro Karsz
6. Clarify some special scenarios. @Michael S. Tsirkin,
@Parav Pandit, @Alvaro Karszdevice-types/net/description.tex | 95
+++++++++++++++++++++++++++++---1 file changed, 87 insertions(+), 8 deletions(-)device-types/net/description.tex +0
-0@@ -83,6 +83,8 @@ \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_VQ_NOTF_COAL(52)] Device supports virtqueue notification coalescing.
+
\item[VIRTIO_NET_F_NOTF_COAL(53)] Device supports notifications coalescing.\item[VIRTIO_NET_F_GUEST_USO4 (54)] Driver can receive USOv4 packets.
device-types/net/description.tex +0
-0@@ -139,6 +141,7 @@ \subsubsection{Feature bitrequirements}\label{sec:Device Types / Network Device \item[VIRTIO_NET_F_NOTF_COAL] Requires
VIRTIO_NET_F_CTRL_VQ. \item[VIRTIO_NET_F_RSC_EXT] RequiresVIRTIO_NET_F_HOST_TSO4orVIRTIO_NET_F_HOST_TSO6. \item[VIRTIO_NET_F_RSS] RequiresVIRTIO_NET_F_CTRL_VQ. +\item[VIRTIO_NET_F_VQ_NOTF_COAL] RequiresVIRTIO_NET_F_CTRL_VQ. \end{description}\subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network Device / Feature bits / Legacy Interface: Feature bits}
device-types/net/description.tex +0
-0@@ -1505,8 +1508,17 @@ \subsubsection{ControlVirtqueue}\label{sec:Device Types / Network Device / Devi
\paragraph{Notifications Coalescing}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing}
device-types/net/description.tex +0
-2-If the VIRTIO_NET_F_NOTF_COAL feature is negotiated, the driver can -send control commands for dynamically changing the coalescingparameters.
+If theVIRTIO_NET_F_NOTF_COALfeature is negotiated, the driver can send theVIRTIO_NET_CTRL_NOTF_COAL_TX_SET
+andVIRTIO_NET_CTRL_NOTF_COAL_RX_SETcommands to dynamically change the coalescing parameters for all transmitdevice-types/net/description.tex +5
-0+and receive virtqueues, respectively. + +If the VIRTIO_NET_F_VQ_NOTF_COAL feature is negotiated: +\begin{itemize} +\item a driver can send a VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET commandto set coalescing parameters of a given
+ enabled transmit/receive virtqueue.
+\item a driver can send aVIRTIO_NET_CTRL_NOTF_COAL_VQ_GETcommandQuoted 8 lines
Quoted 5 lines
to a device, and the device responds with
+ coalescing parameters of a given enabled transmit/receive virtqueue.
+\end{itemize}The
VQ_NOTF_COALcommands are enclosed in an itemize and theNOTF_COALcommands aren't.
I think that we should be consistent here.The VQ commands are enclosed in an itemize because it has both GET and SET operations.
I don't think
VIRTIO_NET_CTRL_NOTF_COAL_RX_SETandVIRTIO_NET_CTRL_NOTF_COAL_TX_SET
have to do this, because they are both settings, just in different directions, and we have described them like this elsewhere.Quoted 3 lines
I'm not sure that describing the commands in here is necessary, maybe just mentioning which commands can be used with which feature bit is
Isn't that what this sentence does?
Quoted 4 lines
enough (this is what I meant in v8, sorry if I wasn't clear).
I'm not saying that describing the commands in here is not good, but notice that the commands are described in 3 different places.
Three places describe different effects.
#1 describes which commands are available for which feature.
#2 describes which command can use which structure.
#3 describes which parameters can be set for each command, and whether they can affect "global values". It is placed in the "Operation" section because it explains how the device should behave.Maybe #1 and #2 descriptions can be combined and described together.
Quoted 142 lines
This is #1.
Quoted 35 lines
\begin{note}
The behavior of the device in response to these commands is best-effort:device-types/net/description.tex +0
-0@@ -1519,25 +1531,76 @@ \subsubsection{ControlVirtqueue}\label{sec:Device Types / Network Device / Devi le32
max_usecs;
};device-types/net/description.tex +6
-0+struct virtio_net_ctrl_coal_vq { + le16 vqn; + le16 reserved; + struct virtio_net_ctrl_coal coal; +}; +#define
VIRTIO_NET_CTRL_NOTF_COAL6
#define VIRTIO_NET_CTRL_NOTF_COAL_TX_SET 0
#defineVIRTIO_NET_CTRL_NOTF_COAL_RX_SET1
+ #defineVIRTIO_NET_CTRL_NOTF_COAL_VQ_SET2
+ #defineVIRTIO_NET_CTRL_NOTF_COAL_VQ_GET3
\end{lstlisting}+The
VIRTIO_NET_CTRL_NOTF_COAL_TX_SETandVIRTIO_NET_CTRL_NOTF_COAL_RX_SETcommands use the +virtio_net_ctrl_coal structure to set \field{max_usecs} and \field{max_packets} for alldevice-types/net/description.tex +3
-0+transmit/receive virtqueues. + +The VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command uses the
virtio_net_ctrl_coal_vqstructure
+to set \field{max_usecs} and \field{max_packets} for the supplied virtqueue number \field{vqn}.device-types/net/description.tex +2
-0+ +The VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command gets the values of\field{max_usecs} and
+\field{max_packets} of the specified virtqueue from the device by setting \field{vqn}device-types/net/description.tex
Quoted 2 lines
device-types/net/description.tex +2
-0+in the virtio_net_ctrl_coal_vq structure. +This is #2.
Quoted 42 lines
+# Read/Write attributes for coalescing parameters
+\begin{itemize}
+\item For commandsVIRTIO_NET_CTRL_NOTF_COAL_TX_SETandVIRTIO_NET_CTRL_NOTF_COAL_RX_SET, \field{max_usecs}
+ and \field{max_packets} are write-only for a driver.
+\item For the commandVIRTIO_NET_CTRL_NOTF_COAL_VQ_SET,
\field{vqn}, \field{reserved}, \field{max_usecs}
+ and \field{max_packets} are write-only for a driver.
+\item For the commandVIRTIO_NET_CTRL_NOTF_COAL_VQ_GET, \field{vqn}
and \field{reserved} are write-only
+ for a driver, and, \field{max_usecs} and \field{max_packets}
are read-only for the driver.
+\end{itemize}
+
Coalescing parameters:
\begin{itemize}
+\item \field{vqn}: The virtqueue number of an enabled transmit or
receive virtqueue.
\item \field{max_usecs} for RX: Maximum number of microseconds to delay a RX notification. \item \field{max_usecs} for TX: Maximum number of microseconds to delay a TX notification. \item \field{max_packets} for RX: Maximum number of packets to receive before a RX notification. \item \field{max_packets} for TX: Maximum number of packets to send before a TX notification. \end{itemize}device-types/net/description.tex +3
-1-The class VIRTIO_NET_CTRL_NOTF_COAL has 2 commands: +\field{reserved} is reserved and it is ignored by a device. + +The class VIRTIO_NET_CTRL_NOTF_COAL has 4 commands:\begin{enumerate}
-\itemVIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues. -\itemVIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues. +\itemVIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues, and values of + coalescing parameters are recorded as TX global values by a device.
+\itemVIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues, and values of + coalescing parameters are recorded as RX global values by a device.
+\itemVIRTIO_NET_CTRL_NOTF_COAL_VQ_SET: set the \field{max_usecs}Quoted 8 lines
and \field{max_packets} parameters for an enabled transmit/receive + virtqueue whose number is \field{vqn}, and do not change the TX/RX global values. +\item
VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET: the device returns the \field{max_usecs} and \field{max_packets} parameters for an enabled + transmit/receive virtqueue whose number is \field{vqn}.
\end{enumerate}This is #3.
Quoted 30 lines
+If coalescing parameters are being set, the device applies the last coalescing parameters received for a
+virtqueue, regardless of the command used to set the parameters. For example with 2 pairs of virtqueues:device-types/net/description.tex +2
-0+# Command sequence +Each of the following commands sets \field{max_usecs} and\field{max_packets} parameters for virtqueues.
+\begin{itemize}
+\item Command1:VIRTIO_NET_CTRL_NOTF_COAL_RX_SETsets coalescing
parameters for virtqueue0 and virtqueue2, and, virtqueue1 and virtqueue3 retain their previous parameter values.
+\item Command2:VIRTIO_NET_CTRL_NOTF_COAL_VQ_SETwith \field{vqn} =
0 sets coalescing parameters for virtqueue0, and virtqueue2 retains the values from command1.
+\item Command3:VIRTIO_NET_CTRL_NOTF_COAL_VQ_GETwith \field{vqn} =
0, the device responds with coalescing parameters of virtqueue0 set by command2.
+\item Command4:VIRTIO_NET_CTRL_NOTF_COAL_VQ_SETwith \field{vqn} =
1 sets coalescing parameters for virtqueue1, and virtqueue3 retains its previous values.
+\item Command5:VIRTIO_NET_CTRL_NOTF_COAL_TX_SETsets coalescing
parameters for virtqueue1 and virtqueue3, and overrides the values set by command4.
+\item Command6:VIRTIO_NET_CTRL_NOTF_COAL_VQ_GETwith \field{vqn} =
1, the device responds with coalescing parameters of virtqueue1 set by command5.
+\end{itemize}
+
\subparagraph{Operation}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing / Operation}The device sends a used buffer notification once the notification conditions are met and if the notifications are not suppressed as explained in \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Used Buffer Notification Suppression}.
device-types/net/description.tex +0
-0@@ -1549,6 +1612,11 @@ \subsubsection{ControlVirtqueue}\label{sec:Device Types / Network Device / Devi
When the device has \field{max_usecs} = 0 or \field{max_packets} = 0, the notification conditions are met after every packet received/sent.
Quoted 9 lines
+When the device receives the
VIRTIO_NET_CTRL_NOTF_COAL_TX_SETandVIRTIO_NET_CTRL_NOTF_COAL_RX_SETcommands,
+it saves the values of coalescing parameters as global values, and theVIRTIO_NET_CTRL_NOTF_COAL_VQ_SETcommand
+does not change the global values. If the device is reset, the global values will be set to 0.
+When a virtqueue is enabled after virtqueue reset, its coalescing parameters are set to global values.
+Maybe this explanation should be put closer to the commands descriptions, where the global coalescing parameters are mentioned for the first time.
Something like:
....
\itemVIRTIO_NET_CTRL_NOTF_COAL_VQ_GET: the device returns the \field{max_usecs} and \field{max_packets} parameters for an enabled transmit/receive virtqueue whose number is \field{vqn}.Quoted 1 line
The device maintains global coalescing parameters for TX and RX....
This is the "Operation" chapter, and the description of the operation is more likely to be placed here, isn't it?
Quoted 12 lines
And maybe we should use "global coalescing parameters" instead of "global values" (in devicenormative as well).
Quoted 8 lines
\subparagraph{RX Example}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing / RX Example}
If, for example:
device-types/net/description.tex +0
-0@@ -1585,15 +1653,26 @@ \subsubsection{ControlVirtqueue}\label{sec:Device Types / Network Device / Devi
\drivernormative{\subparagraph}{Notifications Coalescing}{Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing}
Quoted 11 lines
Quoted 6 lines
-If the
VIRTIO_NET_F_NOTF_COALfeature has not been negotiated, the driver MUST NOT issueVIRTIO_NET_CTRL_NOTF_COALcommands. +If neither theVIRTIO_NET_F_NOTF_COALnor theVIRTIO_NET_F_VQ_NOTF_COALfeature
+has been negotiated, the driver MUST NOT issueVIRTIO_NET_CTRL_NOTF_COALcommands.Maybe this part can be splitted to:
if the F1 feature has not been negotiated, the driver must not issue commands C1,C2.
if the F2 feature has not been negotiated, the driver must not issue commands C3,C4.
Quoted 37 lines
Ok.
Thanks.
Quoted 33 lines
Quoted 28 lines
device-types/net/description.tex +2
-0+ +A driver MUST ignore the values of coalescing parameters receivedfrom the
VIRTIO_NET_CTRL_NOTF_COAL_VQ_GETcommand if a device responds withVIRTIO_NET_ERR.\devicenormative{\subparagraph}{Notifications Coalescing}{Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing}
-A device SHOULD respond to the
VIRTIO_NET_CTRL_NOTF_COALcommands
withVIRTIO_NET_ERRif it was not able to change the parameters.
+A device SHOULD respond toVIRTIO_NET_CTRL_NOTF_COAL_TX_SETandVIRTIO_NET_CTRL_NOTF_COAL_RX_SETcommands withVIRTIO_NET_ERRif it was not able to change the parameters.device-types/net/description.tex +2
-0+ +A device MUST respond to the VIRTIO_NET_CTRL_NOTF_COAL_VQ_SETcommand with
VIRTIO_NET_ERRif it was not able to change the parameters.device-types/net/description.tex +2
-0+ +A device MUST respond to VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET and
VIRTIO_NET_CTRL_NOTF_COAL_VQ_GETcommands withVIRTIO_NET_ERRif the given virtqueue is disabled.device-types/net/description.tex +2
-0+ +A device MUST ignore \field{reserved}.A device SHOULD NOT send used buffer notifications to the driver if the notifications are suppressed, even if the notification conditions are met.
device-types/net/description.tex +1
-1-Upon reset, a device MUST initialize all coalescing parameters to 0. +After disabling and re-enabling a virtqueue, the device MUST revertcoalescing parameters of the virtqueue to the global values.
device-types/net/description.tex +2
-0+ +Upon reset, a device MUST initialize all coalescing parameters to 0and MUST set the global values to 0.
Quoted 3 lines
\subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device Types / Network Device / Legacy Interface: Framing Requirements}
Let's wait for more comments before the next version, I guess some may not agree with my comments.
Hi, Michael and Parav, what do you think?
Thanks.
Quoted 9 lines
Quoted 4 lines
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.
Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
Quoted 6 lines
From: [email protected] <[email protected] open.org> On Behalf Of Heng Qi
Quoted 8 lines
Quoted 6 lines
Quoted 6 lines
Quoted 4 lines
\subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
Types / Network Device / Legacy Interface: Framing Requirements} --Let's wait for more comments before the next version, I guess some may not agree with my comments.
Hi, Michael and Parav, what do you think?
I will review today.
Quoted 27 lines
Quoted 9 lines
Quoted 9 lines
device-types/net/description.tex +7
-2-If the VIRTIO_NET_F_NOTF_COAL feature is negotiated, the driver can -send control commands for dynamically changing the coalescing parameters. +If the VIRTIO_NET_F_NOTF_COAL feature is negotiated, the driver can send the VIRTIO_NET_CTRL_NOTF_COAL_TX_SET +and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands to dynamically change the coalescing parameters for all transmit +and receive virtqueues, respectively. + +If the VIRTIO_NET_F_VQ_NOTF_COAL feature is negotiated: +\begin{itemize} +\item a driver can send a VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command to set coalescing parameters of a givenQuoted 8 lines
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1521
Quoted 5 lines
device-types/net/description.tex +4
-0+ enabled transmit/receive virtqueue. +\item a driver can send a VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command to a device, and the device responds with + coalescing parameters of a given enabled transmit/receive virtqueue. +\end{itemize}The
VQ_NOTF_COALcommands are enclosed in an itemize and theNOTF_COALcommands aren't.
I think that we should be consistent here.The VQ commands are enclosed in an itemize because it has both GET and SET operations.
I don't think
VIRTIO_NET_CTRL_NOTF_COAL_RX_SETandVIRTIO_NET_CTRL_NOTF_COAL_TX_SET
have to do this, because they are both settings, just in different directions, and we have described them like this elsewhere.Quoted 1 line
Quoted 5 lines
Quoted 2 lines
I'm not sure that describing the commands in here is necessary, maybe just mentioning which commands can be used with which feature bit is
Isn't that what this sentence does?
Yes, but it also describes what the command does
"to dynamically change the coalescing parameters for all transmit and receive virtqueues"
Seems a bit repetitive to me.
Quoted 5 lines
Quoted 4 lines
enough (this is what I meant in v8, sorry if I wasn't clear).
I'm not saying that describing the commands in here is not good, but notice that the commands are described in 3 different places.
Quoted 9 lines
Three places describe different effects.
#1 describes which commands are available for which feature. #2 describes which command can use which structure.
#3 describes which parameters can be set for each command, and whether they can affect "global values".
It is placed in the "Operation" section because it explains how the device should behave.
You're right, but some parts seems repetitive to me:
#1: "commands to dynamically change the coalescing parameters for all transmit and receive virtqueues"
#2: "commands use the virtio_net_ctrl_coal structure to set \field{max_usecs} and \field{max_packets} for all transmit/receive virtqueues."
#3: " set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues, and values of..."
Feels like every time we re-explain the commands with more detail. So, for example we read #2 and understand what the command does (set usecs and packets), then we read #3 and understand that it does some more stuff.
IMO we need to explain it once, with all the details.
Quoted 108 lines
Maybe #1 and #2 descriptions can be combined and described together.
Quoted 106 lines
This is #1.
Quoted 20 lines
\begin{note}
The behavior of the device in response to these commands is best-effort:device-types/net/description.tex +9
-0@@ -1519,25 +1531,76 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi le32 max_usecs; }; +struct virtio_net_ctrl_coal_vq { + le16 vqn; + le16 reserved; + struct virtio_net_ctrl_coal coal; +}; + #define VIRTIO_NET_CTRL_NOTF_COAL 6 #define VIRTIO_NET_CTRL_NOTF_COAL_TX_SET 0 #define VIRTIO_NET_CTRL_NOTF_COAL_RX_SET 1 + #define VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET 2 + #define VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET 3 \end{lstlisting} +The VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands use thedevice-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1557
Quoted 10 lines
device-types/net/description.tex +10
-0+virtio_net_ctrl_coal structure to set \field{max_usecs} and \field{max_packets} for all +transmit/receive virtqueues. + +The VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command uses the virtio_net_ctrl_coal_vq structure +to set \field{max_usecs} and \field{max_packets} for the supplied virtqueue number \field{vqn}. + +The VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command gets the values of \field{max_usecs} and +\field{max_packets} of the specified virtqueue from the device by setting \field{vqn} +in the virtio_net_ctrl_coal_vq structure. +This is #2.
Quoted 25 lines
device-types/net/description.tex +14
-2+# Read/Write attributes for coalescing parameters +\begin{itemize} +\item For commands VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET, \field{max_usecs} + and \field{max_packets} are write-only for a driver. +\item For the command VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET, \field{vqn}, \field{reserved}, \field{max_usecs} + and \field{max_packets} are write-only for a driver. +\item For the command VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET, \field{vqn} and \field{reserved} are write-only + for a driver, and, \field{max_usecs} and \field{max_packets} are read-only for the driver. +\end{itemize} + Coalescing parameters: \begin{itemize} +\item \field{vqn}: The virtqueue number of an enabled transmit or receive virtqueue. \item \field{max_usecs} for RX: Maximum number of microseconds to delay a RX notification. \item \field{max_usecs} for TX: Maximum number of microseconds to delay a TX notification. \item \field{max_packets} for RX: Maximum number of packets to receive before a RX notification. \item \field{max_packets} for TX: Maximum number of packets to send before a TX notification. \end{itemize} -The class VIRTIO_NET_CTRL_NOTF_COAL has 2 commands: +\field{reserved} is reserved and it is ignored by a device. + +The class VIRTIO_NET_CTRL_NOTF_COAL has 4 commands: \begin{enumerate} -\item VIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues.device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1589
Quoted 10 lines
device-types/net/description.tex +8
-1-\item VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues. +\item VIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues, and values of + coalescing parameters are recorded as TX global values by a device. +\item VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues, and values of + coalescing parameters are recorded as RX global values by a device. +\item VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET: set the \field{max_usecs} and \field{max_packets} parameters for an enabled transmit/receive + virtqueue whose number is \field{vqn}, and do not change the TX/RX global values. +\item VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET: the device returns the \field{max_usecs} and \field{max_packets} parameters for an enabled + transmit/receive virtqueue whose number is \field{vqn}. \end{enumerate}This is #3.
Quoted 17 lines
device-types/net/description.tex +13
-0+If coalescing parameters are being set, the device applies the last coalescing parameters received for a +virtqueue, regardless of the command used to set the parameters. For example with 2 pairs of virtqueues: +# Command sequence +Each of the following commands sets \field{max_usecs} and \field{max_packets} parameters for virtqueues. +\begin{itemize} +\item Command1: VIRTIO_NET_CTRL_NOTF_COAL_RX_SET sets coalescing parameters for virtqueue0 and virtqueue2, and, virtqueue1 and virtqueue3 retain their previous parameter values. +\item Command2: VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET with \field{vqn} = 0 sets coalescing parameters for virtqueue0, and virtqueue2 retains the values from command1. +\item Command3: VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET with \field{vqn} = 0, the device responds with coalescing parameters of virtqueue0 set by command2. +\item Command4: VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET with \field{vqn} = 1 sets coalescing parameters for virtqueue1, and virtqueue3 retains its previous values. +\item Command5: VIRTIO_NET_CTRL_NOTF_COAL_TX_SET sets coalescing parameters for virtqueue1 and virtqueue3, and overrides the values set by command4. +\item Command6: VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET with \field{vqn} = 1, the device responds with coalescing parameters of virtqueue1 set by command5. +\end{itemize} + \subparagraph{Operation}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing / Operation} The device sends a used buffer notification once the notification conditions are met and if the notifications are not suppressed as explained in \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Used Buffer Notification Suppression}.device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1619
Quoted 8 lines
device-types/net/description.tex +5
-0@@ -1549,6 +1612,11 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi When the device has \field{max_usecs} = 0 or \field{max_packets} = 0, the notification conditions are met after every packet received/sent. +When the device receives the VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands, +it saves the values of coalescing parameters as global values, and the VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command +does not change the global values. If the device is reset, the global values will be set to 0. +When a virtqueue is enabled after virtqueue reset, its coalescing parameters are set to global values. +Maybe this explanation should be put closer to the commands descriptions, where the global coalescing parameters are mentioned for the first time.
Something like:
....
\itemVIRTIO_NET_CTRL_NOTF_COAL_VQ_GET: the device returns the \field{max_usecs} and \field{max_packets} parameters for an enabled
transmit/receive virtqueue whose number
is \field{vqn}.
Quoted 5 lines
Quoted 1 line
The device maintains global coalescing parameters for TX and RX....
This is the "Operation" chapter, and the description of the operation is more likely to be placed here, isn't it?
I see your point, but a reader will see the "global notifications coalescing parameter" concept, and won't know what it is until next paragraph.
Maybe we can have a new list with the notification coalescing concepts (like the notification coalescing parameters)? Just throwing an idea here.
Quoted 21 lines
Quoted 12 lines
And maybe we should use "global coalescing parameters" instead of "global values" (in devicenormative as well).
Quoted 7 lines
device-types/net/description.tex +0
-0\subparagraph{RX Example}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing / RX Example} If, for example:@@ -1585,15 +1653,26 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi \drivernormative{\subparagraph}{Notifications Coalescing}{Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing}Quoted 8 lines
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1657
Quoted 3 lines
device-types/net/description.tex +2
-1-If the VIRTIO_NET_F_NOTF_COAL feature has not been negotiated, the driver MUST NOT issue VIRTIO_NET_CTRL_NOTF_COAL commands. +If neither the VIRTIO_NET_F_NOTF_COAL nor the VIRTIO_NET_F_VQ_NOTF_COAL feature +has been negotiated, the driver MUST NOT issue VIRTIO_NET_CTRL_NOTF_COAL commands.Maybe this part can be splitted to:
if the F1 feature has not been negotiated, the driver must not issue commands C1,C2.
if the F2 feature has not been negotiated, the driver must not issue commands C3,C4.
Quoted 30 lines
Ok.
Thanks.
Quoted 26 lines
Quoted 14 lines
device-types/net/description.tex +9
-1+ +A driver MUST ignore the values of coalescing parameters received from the VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command if a device responds with VIRTIO_NET_ERR. \devicenormative{\subparagraph}{Notifications Coalescing}{Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing} -A device SHOULD respond to the VIRTIO_NET_CTRL_NOTF_COAL commands with VIRTIO_NET_ERR if it was not able to change the parameters. +A device SHOULD respond to VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands with VIRTIO_NET_ERR if it was not able to change the parameters. + +A device MUST respond to the VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command with VIRTIO_NET_ERR if it was not able to change the parameters. + +A device MUST respond to VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET and VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET commands with VIRTIO_NET_ERR if the given virtqueue is disabled. + +A device MUST ignore \field{reserved}.device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi
Quoted 10 lines
device-types/net/description.tex +3
-2A device SHOULD NOT send used buffer notifications to the driver if the notifications are suppressed, even if the notification conditions are met. -Upon reset, a device MUST initialize all coalescing parameters to 0. +After disabling and re-enabling a virtqueue, the device MUST revert coalescing parameters of the virtqueue to the global values. + +Upon reset, a device MUST initialize all coalescing parameters to 0 and MUST set the global values to 0. \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device Types / Network Device / Legacy Interface: Framing Requirements} --Let's wait for more comments before the next version, I guess some may not agree with my comments.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
Quoted 65 lines · Alvaro Karsz
Quoted 27 lines
Quoted 9 lines
Quoted 9 lines
device-types/net/description.tex +7
-2-If the VIRTIO_NET_F_NOTF_COAL feature is negotiated, the driver can -send control commands for dynamically changing the coalescing parameters. +If the VIRTIO_NET_F_NOTF_COAL feature is negotiated, the driver can send the VIRTIO_NET_CTRL_NOTF_COAL_TX_SET +and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands to dynamically change the coalescing parameters for all transmit +and receive virtqueues, respectively. + +If the VIRTIO_NET_F_VQ_NOTF_COAL feature is negotiated: +\begin{itemize} +\item a driver can send a VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command to set coalescing parameters of a givenQuoted 8 lines
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1521
Quoted 5 lines
device-types/net/description.tex +4
-0+ enabled transmit/receive virtqueue. +\item a driver can send a VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command to a device, and the device responds with + coalescing parameters of a given enabled transmit/receive virtqueue. +\end{itemize}The
VQ_NOTF_COALcommands are enclosed in an itemize and theNOTF_COALcommands aren't.
I think that we should be consistent here.The VQ commands are enclosed in an itemize because it has both GET and SET operations.
I don't think
VIRTIO_NET_CTRL_NOTF_COAL_RX_SETandVIRTIO_NET_CTRL_NOTF_COAL_TX_SET
have to do this, because they are both settings, just in different directions, and we have described them like this elsewhere.Quoted 1 line
Quoted 5 lines
Quoted 2 lines
I'm not sure that describing the commands in here is necessary, maybe just mentioning which commands can be used with which feature bit is
Isn't that what this sentence does?
Yes, but it also describes what the command does
"to dynamically change the coalescing parameters for all transmit and receive virtqueues"Seems a bit repetitive to me.
Quoted 5 lines
Quoted 4 lines
enough (this is what I meant in v8, sorry if I wasn't clear).
I'm not saying that describing the commands in here is not good, but notice that the commands are described in 3 different places.
Quoted 9 lines
Three places describe different effects.
#1 describes which commands are available for which feature. #2 describes which command can use which structure.
#3 describes which parameters can be set for each command, and whether they can affect "global values".
It is placed in the "Operation" section because it explains how the device should behave.You're right, but some parts seems repetitive to me:
#1: "commands to dynamically change the coalescing parameters for all transmit and receive virtqueues"#2: "commands use the
virtio_net_ctrl_coalstructure to set \field{max_usecs} and \field{max_packets} for all transmit/receive virtqueues."#3: " set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues, and values of..."
Quoted 6 lines
Feels like every time we re-explain the commands with more detail. So, for example we read #2 and understand what the command does (set usecs and packets), then we read #3 and understand that it does some more stuff.
IMO we need to explain it once, with all the details.
This is how we've written it historically. The idea is that reader can get everything on the first pass: 1st high level picture then detailed description then the formalities.
Other specs do it differently so one has to re-read them many times to understand. I don't like this personally and I much prefer the virtio way.
Quoted 114 lines
Quoted 108 lines
Maybe #1 and #2 descriptions can be combined and described together.
Quoted 106 lines
This is #1.
Quoted 20 lines
\begin{note}
The behavior of the device in response to these commands is best-effort:device-types/net/description.tex +9
-0@@ -1519,25 +1531,76 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi le32 max_usecs; }; +struct virtio_net_ctrl_coal_vq { + le16 vqn; + le16 reserved; + struct virtio_net_ctrl_coal coal; +}; + #define VIRTIO_NET_CTRL_NOTF_COAL 6 #define VIRTIO_NET_CTRL_NOTF_COAL_TX_SET 0 #define VIRTIO_NET_CTRL_NOTF_COAL_RX_SET 1 + #define VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET 2 + #define VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET 3 \end{lstlisting} +The VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands use thedevice-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1557
Quoted 10 lines
device-types/net/description.tex +10
-0+virtio_net_ctrl_coal structure to set \field{max_usecs} and \field{max_packets} for all +transmit/receive virtqueues. + +The VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command uses the virtio_net_ctrl_coal_vq structure +to set \field{max_usecs} and \field{max_packets} for the supplied virtqueue number \field{vqn}. + +The VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command gets the values of \field{max_usecs} and +\field{max_packets} of the specified virtqueue from the device by setting \field{vqn} +in the virtio_net_ctrl_coal_vq structure. +This is #2.
Quoted 25 lines
device-types/net/description.tex +14
-2+# Read/Write attributes for coalescing parameters +\begin{itemize} +\item For commands VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET, \field{max_usecs} + and \field{max_packets} are write-only for a driver. +\item For the command VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET, \field{vqn}, \field{reserved}, \field{max_usecs} + and \field{max_packets} are write-only for a driver. +\item For the command VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET, \field{vqn} and \field{reserved} are write-only + for a driver, and, \field{max_usecs} and \field{max_packets} are read-only for the driver. +\end{itemize} + Coalescing parameters: \begin{itemize} +\item \field{vqn}: The virtqueue number of an enabled transmit or receive virtqueue. \item \field{max_usecs} for RX: Maximum number of microseconds to delay a RX notification. \item \field{max_usecs} for TX: Maximum number of microseconds to delay a TX notification. \item \field{max_packets} for RX: Maximum number of packets to receive before a RX notification. \item \field{max_packets} for TX: Maximum number of packets to send before a TX notification. \end{itemize} -The class VIRTIO_NET_CTRL_NOTF_COAL has 2 commands: +\field{reserved} is reserved and it is ignored by a device. + +The class VIRTIO_NET_CTRL_NOTF_COAL has 4 commands: \begin{enumerate} -\item VIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues.device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1589
Quoted 10 lines
device-types/net/description.tex +8
-1-\item VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues. +\item VIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues, and values of + coalescing parameters are recorded as TX global values by a device. +\item VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues, and values of + coalescing parameters are recorded as RX global values by a device. +\item VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET: set the \field{max_usecs} and \field{max_packets} parameters for an enabled transmit/receive + virtqueue whose number is \field{vqn}, and do not change the TX/RX global values. +\item VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET: the device returns the \field{max_usecs} and \field{max_packets} parameters for an enabled + transmit/receive virtqueue whose number is \field{vqn}. \end{enumerate}This is #3.
Quoted 17 lines
device-types/net/description.tex +13
-0+If coalescing parameters are being set, the device applies the last coalescing parameters received for a +virtqueue, regardless of the command used to set the parameters. For example with 2 pairs of virtqueues: +# Command sequence +Each of the following commands sets \field{max_usecs} and \field{max_packets} parameters for virtqueues. +\begin{itemize} +\item Command1: VIRTIO_NET_CTRL_NOTF_COAL_RX_SET sets coalescing parameters for virtqueue0 and virtqueue2, and, virtqueue1 and virtqueue3 retain their previous parameter values. +\item Command2: VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET with \field{vqn} = 0 sets coalescing parameters for virtqueue0, and virtqueue2 retains the values from command1. +\item Command3: VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET with \field{vqn} = 0, the device responds with coalescing parameters of virtqueue0 set by command2. +\item Command4: VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET with \field{vqn} = 1 sets coalescing parameters for virtqueue1, and virtqueue3 retains its previous values. +\item Command5: VIRTIO_NET_CTRL_NOTF_COAL_TX_SET sets coalescing parameters for virtqueue1 and virtqueue3, and overrides the values set by command4. +\item Command6: VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET with \field{vqn} = 1, the device responds with coalescing parameters of virtqueue1 set by command5. +\end{itemize} + \subparagraph{Operation}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing / Operation} The device sends a used buffer notification once the notification conditions are met and if the notifications are not suppressed as explained in \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Used Buffer Notification Suppression}.device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1619
Quoted 8 lines
device-types/net/description.tex +5
-0@@ -1549,6 +1612,11 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi When the device has \field{max_usecs} = 0 or \field{max_packets} = 0, the notification conditions are met after every packet received/sent. +When the device receives the VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands, +it saves the values of coalescing parameters as global values, and the VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command +does not change the global values. If the device is reset, the global values will be set to 0. +When a virtqueue is enabled after virtqueue reset, its coalescing parameters are set to global values. +Maybe this explanation should be put closer to the commands descriptions, where the global coalescing parameters are mentioned for the first time.
Something like:
....
\itemVIRTIO_NET_CTRL_NOTF_COAL_VQ_GET: the device returns the \field{max_usecs} and \field{max_packets} parameters for an enabled
transmit/receive virtqueue whose number
is \field{vqn}.Quoted 5 lines
Quoted 1 line
The device maintains global coalescing parameters for TX and RX....
This is the "Operation" chapter, and the description of the operation is more likely to be placed here, isn't it?
Quoted 6 lines
I see your point, but a reader will see the "global notifications coalescing parameter" concept, and won't know what it is until next paragraph.
Maybe we can have a new list with the notification coalescing concepts (like the notification coalescing parameters)? Just throwing an idea here.
Actually, "global notification coalescing parameters" is confusing:
are these global notifications? global coalescings? global parameters?
The problem is the global qualifier. And it's not even global - there are two sets for rx and for tx and does not apply to cvq at all. How about "RX/TX coalescing parameters"?
Quoted 46 lines
Quoted 46 lines
Quoted 12 lines
And maybe we should use "global coalescing parameters" instead of "global values" (in devicenormative as well).
Quoted 7 lines
device-types/net/description.tex +0
-0\subparagraph{RX Example}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing / RX Example} If, for example:@@ -1585,15 +1653,26 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi \drivernormative{\subparagraph}{Notifications Coalescing}{Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing}Quoted 8 lines
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1657
Quoted 3 lines
device-types/net/description.tex +2
-1-If the VIRTIO_NET_F_NOTF_COAL feature has not been negotiated, the driver MUST NOT issue VIRTIO_NET_CTRL_NOTF_COAL commands. +If neither the VIRTIO_NET_F_NOTF_COAL nor the VIRTIO_NET_F_VQ_NOTF_COAL feature +has been negotiated, the driver MUST NOT issue VIRTIO_NET_CTRL_NOTF_COAL commands.Maybe this part can be splitted to:
if the F1 feature has not been negotiated, the driver must not issue commands C1,C2.
if the F2 feature has not been negotiated, the driver must not issue commands C3,C4.Ok.
Thanks.
Quoted 21 lines
Quoted 21 lines
device-types/net/description.tex +12
-2+ +A driver MUST ignore the values of coalescing parameters received from the VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command if a device responds with VIRTIO_NET_ERR. \devicenormative{\subparagraph}{Notifications Coalescing}{Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing} -A device SHOULD respond to the VIRTIO_NET_CTRL_NOTF_COAL commands with VIRTIO_NET_ERR if it was not able to change the parameters. +A device SHOULD respond to VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands with VIRTIO_NET_ERR if it was not able to change the parameters. + +A device MUST respond to the VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command with VIRTIO_NET_ERR if it was not able to change the parameters. + +A device MUST respond to VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET and VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET commands with VIRTIO_NET_ERR if the given virtqueue is disabled. + +A device MUST ignore \field{reserved}. A device SHOULD NOT send used buffer notifications to the driver if the notifications are suppressed, even if the notification conditions are met. -Upon reset, a device MUST initialize all coalescing parameters to 0. +After disabling and re-enabling a virtqueue, the device MUST revert coalescing parameters of the virtqueue to the global values. + +Upon reset, a device MUST initialize all coalescing parameters to 0 and MUST set the global values to 0.
Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi
Quoted 3 lines
device-types/net/description.tex +0
-1\subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device Types / Network Device / Legacy Interface: Framing Requirements} --Let's wait for more comments before the next version, I guess some may not agree with my comments.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
Quoted 7 lines
Quoted 6 lines
I see your point, but a reader will see the "global notifications coalescing parameter" concept, and won't know what it is until next paragraph.
Maybe we can have a new list with the notification coalescing concepts (like the notification coalescing parameters)? Just throwing an idea here.
Quoted 6 lines
Actually, "global notification coalescing parameters" is confusing:
are these global notifications? global coalescings? global parameters?The problem is the global qualifier. And it's not even global - there are two sets for rx and for tx and does not apply to cvq at all. How about "RX/TX coalescing parameters"?
Seems fine to me.
This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.
Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
Quoted 194 lines · Michael S. Tsirkin
Quoted 59 lines · Alvaro Karsz
Quoted 20 lines
Quoted 9 lines
Quoted 9 lines
device-types/net/description.tex +7
-2-If the VIRTIO_NET_F_NOTF_COAL feature is negotiated, the driver can -send control commands for dynamically changing the coalescing parameters. +If the VIRTIO_NET_F_NOTF_COAL feature is negotiated, the driver can send the VIRTIO_NET_CTRL_NOTF_COAL_TX_SET +and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands to dynamically change the coalescing parameters for all transmit +and receive virtqueues, respectively. + +If the VIRTIO_NET_F_VQ_NOTF_COAL feature is negotiated: +\begin{itemize} +\item a driver can send a VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command to set coalescing parameters of a givenQuoted 8 lines
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1521
Quoted 5 lines
device-types/net/description.tex +4
-0+ enabled transmit/receive virtqueue. +\item a driver can send a VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command to a device, and the device responds with + coalescing parameters of a given enabled transmit/receive virtqueue. +\end{itemize}The
VQ_NOTF_COALcommands are enclosed in an itemize and theNOTF_COALcommands aren't.
I think that we should be consistent here.The VQ commands are enclosed in an itemize because it has both GET and SET operations.
Quoted 9 lines
I don't think
VIRTIO_NET_CTRL_NOTF_COAL_RX_SETandVIRTIO_NET_CTRL_NOTF_COAL_TX_SET
have to do this, because they are both settings, just in different directions, and we have described them like this elsewhere.Quoted 2 lines
I'm not sure that describing the commands in here is necessary, maybe just mentioning which commands can be used with which feature bit is
Isn't that what this sentence does?
Yes, but it also describes what the command does
"to dynamically change the coalescing parameters for all transmit and receive virtqueues"Seems a bit repetitive to me.
Quoted 4 lines
Quoted 4 lines
enough (this is what I meant in v8, sorry if I wasn't clear).
I'm not saying that describing the commands in here is not good, but notice that the commands are described in 3 different places.
Quoted 9 lines
Three places describe different effects.
#1 describes which commands are available for which feature. #2 describes which command can use which structure.
#3 describes which parameters can be set for each command, and whether they can affect "global values".
It is placed in the "Operation" section because it explains how the device should behave.You're right, but some parts seems repetitive to me:
#1: "commands to dynamically change the coalescing parameters for all transmit and receive virtqueues"#2: "commands use the
virtio_net_ctrl_coalstructure to set \field{max_usecs} and \field{max_packets} for all transmit/receive virtqueues."#3: " set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues, and values of..."
Quoted 6 lines
Feels like every time we re-explain the commands with more detail. So, for example we read #2 and understand what the command does (set usecs and packets), then we read #3 and understand that it does some more stuff.
IMO we need to explain it once, with all the details.
This is how we've written it historically. The idea is that reader can get everything on the first pass: 1st high level picture then detailed description then the formalities.
Other specs do it differently so one has to re-read them many times to understand. I don't like this personally and I much prefer the virtio way.
Quoted 112 lines
Quoted 108 lines
Maybe #1 and #2 descriptions can be combined and described together.
Quoted 106 lines
This is #1.
Quoted 20 lines
\begin{note}
The behavior of the device in response to these commands is best-effort:device-types/net/description.tex +9
-0@@ -1519,25 +1531,76 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi le32 max_usecs; }; +struct virtio_net_ctrl_coal_vq { + le16 vqn; + le16 reserved; + struct virtio_net_ctrl_coal coal; +}; + #define VIRTIO_NET_CTRL_NOTF_COAL 6 #define VIRTIO_NET_CTRL_NOTF_COAL_TX_SET 0 #define VIRTIO_NET_CTRL_NOTF_COAL_RX_SET 1 + #define VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET 2 + #define VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET 3 \end{lstlisting} +The VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands use thedevice-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1557
Quoted 10 lines
device-types/net/description.tex +10
-0+virtio_net_ctrl_coal structure to set \field{max_usecs} and \field{max_packets} for all +transmit/receive virtqueues. + +The VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command uses the virtio_net_ctrl_coal_vq structure +to set \field{max_usecs} and \field{max_packets} for the supplied virtqueue number \field{vqn}. + +The VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command gets the values of \field{max_usecs} and +\field{max_packets} of the specified virtqueue from the device by setting \field{vqn} +in the virtio_net_ctrl_coal_vq structure. +This is #2.
Quoted 25 lines
device-types/net/description.tex +14
-2+# Read/Write attributes for coalescing parameters +\begin{itemize} +\item For commands VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET, \field{max_usecs} + and \field{max_packets} are write-only for a driver. +\item For the command VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET, \field{vqn}, \field{reserved}, \field{max_usecs} + and \field{max_packets} are write-only for a driver. +\item For the command VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET, \field{vqn} and \field{reserved} are write-only + for a driver, and, \field{max_usecs} and \field{max_packets} are read-only for the driver. +\end{itemize} + Coalescing parameters: \begin{itemize} +\item \field{vqn}: The virtqueue number of an enabled transmit or receive virtqueue. \item \field{max_usecs} for RX: Maximum number of microseconds to delay a RX notification. \item \field{max_usecs} for TX: Maximum number of microseconds to delay a TX notification. \item \field{max_packets} for RX: Maximum number of packets to receive before a RX notification. \item \field{max_packets} for TX: Maximum number of packets to send before a TX notification. \end{itemize} -The class VIRTIO_NET_CTRL_NOTF_COAL has 2 commands: +\field{reserved} is reserved and it is ignored by a device. + +The class VIRTIO_NET_CTRL_NOTF_COAL has 4 commands: \begin{enumerate} -\item VIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues.device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1589
Quoted 10 lines
device-types/net/description.tex +8
-1-\item VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues. +\item VIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues, and values of + coalescing parameters are recorded as TX global values by a device. +\item VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues, and values of + coalescing parameters are recorded as RX global values by a device. +\item VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET: set the \field{max_usecs} and \field{max_packets} parameters for an enabled transmit/receive + virtqueue whose number is \field{vqn}, and do not change the TX/RX global values. +\item VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET: the device returns the \field{max_usecs} and \field{max_packets} parameters for an enabled + transmit/receive virtqueue whose number is \field{vqn}. \end{enumerate}This is #3.
Quoted 17 lines
device-types/net/description.tex +13
-0+If coalescing parameters are being set, the device applies the last coalescing parameters received for a +virtqueue, regardless of the command used to set the parameters. For example with 2 pairs of virtqueues: +# Command sequence +Each of the following commands sets \field{max_usecs} and \field{max_packets} parameters for virtqueues. +\begin{itemize} +\item Command1: VIRTIO_NET_CTRL_NOTF_COAL_RX_SET sets coalescing parameters for virtqueue0 and virtqueue2, and, virtqueue1 and virtqueue3 retain their previous parameter values. +\item Command2: VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET with \field{vqn} = 0 sets coalescing parameters for virtqueue0, and virtqueue2 retains the values from command1. +\item Command3: VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET with \field{vqn} = 0, the device responds with coalescing parameters of virtqueue0 set by command2. +\item Command4: VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET with \field{vqn} = 1 sets coalescing parameters for virtqueue1, and virtqueue3 retains its previous values. +\item Command5: VIRTIO_NET_CTRL_NOTF_COAL_TX_SET sets coalescing parameters for virtqueue1 and virtqueue3, and overrides the values set by command4. +\item Command6: VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET with \field{vqn} = 1, the device responds with coalescing parameters of virtqueue1 set by command5. +\end{itemize} + \subparagraph{Operation}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing / Operation} The device sends a used buffer notification once the notification conditions are met and if the notifications are not suppressed as explained in \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Used Buffer Notification Suppression}.device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1619
Quoted 8 lines
device-types/net/description.tex +5
-0@@ -1549,6 +1612,11 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi When the device has \field{max_usecs} = 0 or \field{max_packets} = 0, the notification conditions are met after every packet received/sent. +When the device receives the VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands, +it saves the values of coalescing parameters as global values, and the VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command +does not change the global values. If the device is reset, the global values will be set to 0. +When a virtqueue is enabled after virtqueue reset, its coalescing parameters are set to global values. +Maybe this explanation should be put closer to the commands descriptions, where the global coalescing parameters are mentioned for the first time.
Something like:
....
\itemVIRTIO_NET_CTRL_NOTF_COAL_VQ_GET: the device returns the \field{max_usecs} and \field{max_packets} parameters for an enabled
transmit/receive virtqueue whose number
is \field{vqn}.Quoted 4 lines
Quoted 1 line
The device maintains global coalescing parameters for TX and RX....
This is the "Operation" chapter, and the description of the operation is more likely to be placed here, isn't it?
Quoted 6 lines
I see your point, but a reader will see the "global notifications coalescing parameter" concept, and won't know what it is until next paragraph.
Maybe we can have a new list with the notification coalescing concepts (like the notification coalescing parameters)? Just throwing an idea here.
Quoted 6 lines
Actually, "global notification coalescing parameters" is confusing:
are these global notifications? global coalescings? global parameters?The problem is the global qualifier. And it's not even global - there are two sets for rx and for tx and does not apply to cvq at all. How about "RX/TX coalescing parameters"?
As Parav suggested, we probably don't need to mention "global values/coalescing parameters" since this values/parameters are the ones set by CTRL_NOTF_COAL_RX/TX_SET.
Just like this:
"
After disabling and re-enabling a virtuqueue, the device MUST revert to coalescing parameters to the one configured using VIRTIO_NET_CTRL_NOTF_COAL. "
Thanks.
Quoted 45 lines
Quoted 45 lines
Quoted 45 lines
Quoted 12 lines
And maybe we should use "global coalescing parameters" instead of "global values" (in devicenormative as well).
Quoted 7 lines
device-types/net/description.tex +0
-0\subparagraph{RX Example}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing / RX Example} If, for example:@@ -1585,15 +1653,26 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi \drivernormative{\subparagraph}{Notifications Coalescing}{Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing}Quoted 8 lines
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi · line 1657
Quoted 3 lines
device-types/net/description.tex +2
-1-If the VIRTIO_NET_F_NOTF_COAL feature has not been negotiated, the driver MUST NOT issue VIRTIO_NET_CTRL_NOTF_COAL commands. +If neither the VIRTIO_NET_F_NOTF_COAL nor the VIRTIO_NET_F_VQ_NOTF_COAL feature +has been negotiated, the driver MUST NOT issue VIRTIO_NET_CTRL_NOTF_COAL commands.Maybe this part can be splitted to:
if the F1 feature has not been negotiated, the driver must not issue commands C1,C2.
if the F2 feature has not been negotiated, the driver must not issue commands C3,C4.Ok.
Thanks.
Quoted 21 lines
Quoted 21 lines
device-types/net/description.tex +12
-2+ +A driver MUST ignore the values of coalescing parameters received from the VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET command if a device responds with VIRTIO_NET_ERR. \devicenormative{\subparagraph}{Notifications Coalescing}{Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing} -A device SHOULD respond to the VIRTIO_NET_CTRL_NOTF_COAL commands with VIRTIO_NET_ERR if it was not able to change the parameters. +A device SHOULD respond to VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands with VIRTIO_NET_ERR if it was not able to change the parameters. + +A device MUST respond to the VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET command with VIRTIO_NET_ERR if it was not able to change the parameters. + +A device MUST respond to VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET and VIRTIO_NET_CTRL_NOTF_COAL_VQ_GET commands with VIRTIO_NET_ERR if the given virtqueue is disabled. + +A device MUST ignore \field{reserved}. A device SHOULD NOT send used buffer notifications to the driver if the notifications are suppressed, even if the notification conditions are met. -Upon reset, a device MUST initialize all coalescing parameters to 0. +After disabling and re-enabling a virtqueue, the device MUST revert coalescing parameters of the virtqueue to the global values. + +Upon reset, a device MUST initialize all coalescing parameters to 0 and MUST set the global values to 0.
Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
device-types/net/description.tex \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi
Quoted 3 lines
device-types/net/description.tex +0
-1\subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device Types / Network Device / Legacy Interface: Framing Requirements} --Let's wait for more comments before the next version, I guess some may not agree with my comments.
This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.
Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
Quoted 8 lines · Heng Qi
Quoted 3 lines
The problem is the global qualifier. And it's not even global - there are two sets for rx and for tx and does not apply to cvq at all. How about "RX/TX coalescing parameters"?
As Parav suggested, we probably don't need to mention "global values/coalescing parameters" since this values/parameters are the ones set by CTRL_NOTF_COAL_RX/TX_SET.
Quoted 7 lines
Just like this:
"
After disabling and re-enabling a virtuqueue, the device MUST revert to coalescing parameters to the one configured usingVIRTIO_NET_CTRL_NOTF_COAL. "Thanks.
VIRTIO_NET_CTRL_NOTF_COAL is not a thing. Let's wait for Alvaro's new patch to be merged though, see what teminology he comes up with and reuse.
Signature · 18 lines
MST This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC. In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting. Subscribe: [email protected] Unsubscribe: [email protected] List help: [email protected] List archive: https://lists.oasis-open.org/archives/virtio-comment/ Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists Committee: https://www.oasis-open.org/committees/virtio/ Join OASIS: https://www.oasis-open.org/join/
Quoted 14 lines · Michael S. Tsirkin
Quoted 13 lines · Heng Qi
Quoted 3 lines
The problem is the global qualifier. And it's not even global - there are two sets for rx and for tx and does not apply to cvq at all. How about "RX/TX coalescing parameters"?
As Parav suggested, we probably don't need to mention "global values/coalescing parameters" since this values/parameters are the ones set by CTRL_NOTF_COAL_RX/TX_SET.
Just like this:
"
After disabling and re-enabling a virtuqueue, the device MUST revert to coalescing parameters to the one configured usingVIRTIO_NET_CTRL_NOTF_COAL. "
Quoted 4 lines
Quoted 1 line
Thanks.
VIRTIO_NET_CTRL_NOTF_COALis not a thing. Let's wait for Alvaro's new patch to be merged though, see what teminology he comes up with and reuse.
Ok, are you referring to Alvaro's "virtio-net: Fix and update VIRTIO_NET_F_NOTF_COAL feature",
if so I see that his v7 version is stable and has been voted in https://github.com/oasis-tcs/ virtio-spec/issues/159 , this patch was made on top of his v7 version.
Thanks.
This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.
Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
Quoted 5 lines
From: Heng Qi <[email protected]>
Sent: Sunday, February 26, 2023 4:37 AM+# Read/Write attributes for coalescing parameters \begin{itemize} \item
Hash # above is not needed. Please remove.
Quoted 11 lines
+For commands
VIRTIO_NET_CTRL_NOTF_COAL_TX_SETandVIRTIO_NET_CTRL_NOTF_COAL_RX_SET, \field{max_usecs}
+ and \field{max_packets} are write-only for a driver.
+\item For the commandVIRTIO_NET_CTRL_NOTF_COAL_VQ_SET, \field{vqn}, \field{reserved}, \field{max_usecs}
+ and \field{max_packets} are write-only for a driver.
+\item For the commandVIRTIO_NET_CTRL_NOTF_COAL_VQ_GET, \field{vqn} and \field{reserved} are write-only
+ for a driver, and, \field{max_usecs} and \field{max_packets} are read-only
for the driver.
+\end{itemize}
Instead of describing each individual fields of the structure struct virtio_net_ctrl_coal coal as read-only or write-only, better to say the struct itself as read/write only. This way when/if in the future, if struct virtio_net_ctrl_coal coal extends, no need to rewrite this section of the spec.
Quoted 21 lines
+
Coalescing parameters:
\begin{itemize}
+\item \field{vqn}: The virtqueue number of an enabled transmit or receive virtqueue.
\item \field{max_usecs} for RX: Maximum number of microseconds to delay a
RX notification.
\item \field{max_usecs} for TX: Maximum number of microseconds to delay a
TX notification.
\item \field{max_packets} for RX: Maximum number of packets to receive
before a RX notification.
\item \field{max_packets} for TX: Maximum number of packets to send before
a TX notification.
\end{itemize}device-types/net/description.tex +3
-2-The class VIRTIO_NET_CTRL_NOTF_COAL has 2 commands: +\field{reserved} is reserved and it is ignored by a device. + +The class VIRTIO_NET_CTRL_NOTF_COAL has 4 commands: \begin{enumerate} -\item VIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and
Quoted 7 lines
\field{max_packets} parameters for all transmit virtqueues. -\item
VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues. +\itemVIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues, and values of
+ coalescing parameters are recorded as TX global values
by a device.
"recording TX global values" is not conveying anything more as "all transmit virtqueues" is already mentioned. The original text without "recorded as Tx global values" is just fine. Same for the RX below.
Quoted 71 lines
+\item
VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues, and values of
+ coalescing parameters are recorded as RX global values
by a device.
+\itemVIRTIO_NET_CTRL_NOTF_COAL_VQ_SET: set the \field{max_usecs} and \field{max_packets} parameters for an enabled transmit/receive
+ virtqueue whose number is \field{vqn}, and do not
change the TX/RX global values.
+\itemVIRTIO_NET_CTRL_NOTF_COAL_VQ_GET: the device returns the \field{max_usecs} and \field{max_packets} parameters for an enableddevice-types/net/description.tex +3
-0+ transmit/receive virtqueue whose number is \field{vqn}. \end{enumerate} +If coalescing parameters are being set, the device applies the last +coalescing parameters received for a virtqueue, regardless of the commandused to set the parameters. For example with 2 pairs of virtqueues:
(quoted diff) +2
-0+# Command sequence +Each of the following commands sets \field{max_usecs} and\field{max_packets} parameters for virtqueues.
+\begin{itemize}
+\item Command1:VIRTIO_NET_CTRL_NOTF_COAL_RX_SETsets coalescing parameters for virtqueue0 and virtqueue2, and, virtqueue1 and virtqueue3 retain their previous parameter values.
+\item Command2:VIRTIO_NET_CTRL_NOTF_COAL_VQ_SETwith \field{vqn} = 0 sets coalescing parameters for virtqueue0, and virtqueue2 retains the values from command1.
+\item Command3:VIRTIO_NET_CTRL_NOTF_COAL_VQ_GETwith \field{vqn} = 0, the device responds with coalescing parameters of virtqueue0 set by command2.
+\item Command4:VIRTIO_NET_CTRL_NOTF_COAL_VQ_SETwith \field{vqn} = 1 sets coalescing parameters for virtqueue1, and virtqueue3 retains its previous values.
+\item Command5:VIRTIO_NET_CTRL_NOTF_COAL_TX_SETsets coalescing parameters for virtqueue1 and virtqueue3, and overrides the values set by command4.
+\item Command6:VIRTIO_NET_CTRL_NOTF_COAL_VQ_GETwith \field{vqn} = 1, the device responds with coalescing parameters of virtqueue1 set by command5.
+\end{itemize}
+
\subparagraph{Operation}\label{sec:Device Types / Network Device / Device
Operation / Control Virtqueue / Notifications Coalescing / Operation}The device sends a used buffer notification once the notification conditions are
met and if the notifications are not suppressed as explained in \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Used Buffer Notification Suppression}.(quoted diff) +0
-0@@ -1549,6 +1612,11 @@ \subsubsection{ControlVirtqueue}\label{sec:Device Types / Network Device / Devi
When the device has \field{max_usecs} = 0 or \field{max_packets} = 0, the
notification conditions are met after every packet received/sent.(quoted diff) +3
-0+When the device receives the VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and +VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands, it saves the values of +coalescing parameters as global values, and the
VIRTIO_NET_CTRL_NOTF_COAL_VQ_SETcommand does not change the global values. If the device is reset, the global values will be set to 0. +When a virtqueue is enabled after virtqueue reset, its coalescing parameters are set to global values.
+
\subparagraph{RX Example}\label{sec:Device Types / Network Device / Device
Operation / Control Virtqueue / Notifications Coalescing / RX Example}If, for example:
(quoted diff) +0
-0@@ -1585,15 +1653,26 @@ \subsubsection{ControlVirtqueue}\label{sec:Device Types / Network Device / Devi
\drivernormative{\subparagraph}{Notifications Coalescing}{Device Types /
Network Device / Device Operation / Control Virtqueue / Notifications Coalescing}
Quoted 7 lines
-If the
VIRTIO_NET_F_NOTF_COALfeature has not been negotiated, the driver MUST NOT issueVIRTIO_NET_CTRL_NOTF_COALcommands.
+If neither theVIRTIO_NET_F_NOTF_COALnor theVIRTIO_NET_F_VQ_NOTF_COAL
+feature has been negotiated, the driver MUST NOT issueVIRTIO_NET_CTRL_NOTF_COALcommands.
+
I agree to Alvaro's suggestion.
If VIRTIO_NET_F_NOTF_COAL is not negotiated, the driver must not issue commands A and B.
If VIRTIO_NET_F_VQ_NOTF_COAL is not negotiated, the driver must not issue commands C and D.
Quoted 26 lines
+A driver MUST ignore the values of coalescing parameters received from the
VIRTIO_NET_CTRL_NOTF_COAL_VQ_GETcommand if a device responds withVIRTIO_NET_ERR.\devicenormative{\subparagraph}{Notifications Coalescing}{Device Types /
Network Device / Device Operation / Control Virtqueue / Notifications Coalescing}-A device SHOULD respond to the
VIRTIO_NET_CTRL_NOTF_COALcommands withVIRTIO_NET_ERRif it was not able to change the parameters. +A device SHOULD respond toVIRTIO_NET_CTRL_NOTF_COAL_TX_SETandVIRTIO_NET_CTRL_NOTF_COAL_RX_SETcommands withVIRTIO_NET_ERRif it was not able to change the parameters.(quoted diff) +2
-0+ +A device MUST respond to the VIRTIO_NET_CTRL_NOTF_COAL_VQ_SETcommand with
VIRTIO_NET_ERRif it was not able to change the parameters.(quoted diff) +2
-0+ +A device MUST respond to VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET and
VIRTIO_NET_CTRL_NOTF_COAL_VQ_GETcommands withVIRTIO_NET_ERRif the given virtqueue is disabled.device-types/net/description.tex +2
-0+ +A device MUST ignore \field{reserved}. A device SHOULD NOT send used buffer notifications to the driver if thenotifications are suppressed, even if the notification conditions are met.
Review
Quoted 2 lines
(quoted diff) +1
-1-Upon reset, a device MUST initialize all coalescing parameters to 0. +After disabling and re-enabling a virtqueue, the device MUST revert coalescing
revert to
Quoted 2 lines
parameters of the virtqueue to the global values.
+
Like others suggested, above can be reworded as,
After disabling and re-enabling a virtuqueue, the device MUST revert to coalescing parameters to the one configured using VIRTIO_NET_CTRL_NOTF_COAL.
Quoted 3 lines
+Upon reset, a device MUST initialize all coalescing parameters to 0 and MUST set the global values to 0.
No need to mention global values here. "all coalescing parameters to 0" covers per vq and per group of tx and rx vqs.
Quoted 4 lines
\subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
Types / Network Device / Legacy Interface: Framing Requirements} --
2.19.1.6.gb485710b
This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.
Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
Quoted 4 lines · Parav Pandit
Quoted 3 lines
From: Heng Qi <[email protected]>
Sent: Sunday, February 26, 2023 4:37 AM
+# Read/Write attributes for coalescing parameters \begin{itemize} \itemHash # above is not needed. Please remove.
Ok.
Quoted 12 lines
Quoted 12 lines
+For commands
VIRTIO_NET_CTRL_NOTF_COAL_TX_SETandVIRTIO_NET_CTRL_NOTF_COAL_RX_SET, \field{max_usecs}
+ and \field{max_packets} are write-only for a driver.
+\item For the commandVIRTIO_NET_CTRL_NOTF_COAL_VQ_SET, \field{vqn}, \field{reserved}, \field{max_usecs}
+ and \field{max_packets} are write-only for a driver.
+\item For the commandVIRTIO_NET_CTRL_NOTF_COAL_VQ_GET, \field{vqn} and \field{reserved} are write-only
+ for a driver, and, \field{max_usecs} and \field{max_packets} are read-only
for the driver.
+\end{itemize}
Quoted 2 lines
Instead of describing each individual fields of the structure struct
virtio_net_ctrl_coalcoal as read-only or write-only, better to say the struct itself as read/write only. This way when/if in the future, if structvirtio_net_ctrl_coalcoal extends, no need to rewrite this section of the spec.
Good idea, I will modify this.
Quoted 138 lines
Quoted 22 lines
+
Coalescing parameters:
\begin{itemize}
+\item \field{vqn}: The virtqueue number of an enabled transmit or receive virtqueue.
\item \field{max_usecs} for RX: Maximum number of microseconds to delay a
RX notification.
\item \field{max_usecs} for TX: Maximum number of microseconds to delay a
TX notification.
\item \field{max_packets} for RX: Maximum number of packets to receive
before a RX notification.
\item \field{max_packets} for TX: Maximum number of packets to send before
a TX notification.
\end{itemize}device-types/net/description.tex +3
-2-The class VIRTIO_NET_CTRL_NOTF_COAL has 2 commands: +\field{reserved} is reserved and it is ignored by a device. + +The class VIRTIO_NET_CTRL_NOTF_COAL has 4 commands: \begin{enumerate} -\item VIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} andQuoted 7 lines
\field{max_packets} parameters for all transmit virtqueues. -\item
VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues. +\itemVIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues, and values of
+ coalescing parameters are recorded as TX global values
by a device."recording TX global values" is not conveying anything more as "all transmit virtqueues" is already mentioned. The original text without "recorded as Tx global values" is just fine. Same for the RX below.
Quoted 71 lines
+\item
VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues, and values of
+ coalescing parameters are recorded as RX global values
by a device.
+\itemVIRTIO_NET_CTRL_NOTF_COAL_VQ_SET: set the \field{max_usecs} and \field{max_packets} parameters for an enabled transmit/receive
+ virtqueue whose number is \field{vqn}, and do not
change the TX/RX global values.
+\itemVIRTIO_NET_CTRL_NOTF_COAL_VQ_GET: the device returns the \field{max_usecs} and \field{max_packets} parameters for an enableddevice-types/net/description.tex +3
-0+ transmit/receive virtqueue whose number is \field{vqn}. \end{enumerate} +If coalescing parameters are being set, the device applies the last +coalescing parameters received for a virtqueue, regardless of the commandused to set the parameters. For example with 2 pairs of virtqueues:
(quoted diff) +2
-0+# Command sequence +Each of the following commands sets \field{max_usecs} and\field{max_packets} parameters for virtqueues.
+\begin{itemize}
+\item Command1:VIRTIO_NET_CTRL_NOTF_COAL_RX_SETsets coalescing parameters for virtqueue0 and virtqueue2, and, virtqueue1 and virtqueue3 retain their previous parameter values.
+\item Command2:VIRTIO_NET_CTRL_NOTF_COAL_VQ_SETwith \field{vqn} = 0 sets coalescing parameters for virtqueue0, and virtqueue2 retains the values from command1.
+\item Command3:VIRTIO_NET_CTRL_NOTF_COAL_VQ_GETwith \field{vqn} = 0, the device responds with coalescing parameters of virtqueue0 set by command2.
+\item Command4:VIRTIO_NET_CTRL_NOTF_COAL_VQ_SETwith \field{vqn} = 1 sets coalescing parameters for virtqueue1, and virtqueue3 retains its previous values.
+\item Command5:VIRTIO_NET_CTRL_NOTF_COAL_TX_SETsets coalescing parameters for virtqueue1 and virtqueue3, and overrides the values set by command4.
+\item Command6:VIRTIO_NET_CTRL_NOTF_COAL_VQ_GETwith \field{vqn} = 1, the device responds with coalescing parameters of virtqueue1 set by command5.
+\end{itemize}
+
\subparagraph{Operation}\label{sec:Device Types / Network Device / Device
Operation / Control Virtqueue / Notifications Coalescing / Operation}The device sends a used buffer notification once the notification conditions are
met and if the notifications are not suppressed as explained in \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Used Buffer Notification Suppression}.(quoted diff) +0
-0@@ -1549,6 +1612,11 @@ \subsubsection{ControlVirtqueue}\label{sec:Device Types / Network Device / Devi
When the device has \field{max_usecs} = 0 or \field{max_packets} = 0, the
notification conditions are met after every packet received/sent.(quoted diff) +3
-0+When the device receives the VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and +VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands, it saves the values of +coalescing parameters as global values, and the
VIRTIO_NET_CTRL_NOTF_COAL_VQ_SETcommand does not change the global values. If the device is reset, the global values will be set to 0. +When a virtqueue is enabled after virtqueue reset, its coalescing parameters are set to global values.
+
\subparagraph{RX Example}\label{sec:Device Types / Network Device / Device
Operation / Control Virtqueue / Notifications Coalescing / RX Example}If, for example:
(quoted diff) +0
-0@@ -1585,15 +1653,26 @@ \subsubsection{ControlVirtqueue}\label{sec:Device Types / Network Device / Devi
\drivernormative{\subparagraph}{Notifications Coalescing}{Device Types /
Network Device / Device Operation / Control Virtqueue / Notifications Coalescing}Quoted 7 lines
-If the
VIRTIO_NET_F_NOTF_COALfeature has not been negotiated, the driver MUST NOT issueVIRTIO_NET_CTRL_NOTF_COALcommands.
+If neither theVIRTIO_NET_F_NOTF_COALnor theVIRTIO_NET_F_VQ_NOTF_COAL
+feature has been negotiated, the driver MUST NOT issueVIRTIO_NET_CTRL_NOTF_COALcommands.
+I agree to Alvaro's suggestion.
IfVIRTIO_NET_F_NOTF_COALis not negotiated, the driver must not issue commands A and B.If
VIRTIO_NET_F_VQ_NOTF_COALis not negotiated, the driver must not issue commands C and D.Quoted 23 lines
+A driver MUST ignore the values of coalescing parameters received from the
VIRTIO_NET_CTRL_NOTF_COAL_VQ_GETcommand if a device responds withVIRTIO_NET_ERR.\devicenormative{\subparagraph}{Notifications Coalescing}{Device Types /
Network Device / Device Operation / Control Virtqueue / Notifications Coalescing}-A device SHOULD respond to the
VIRTIO_NET_CTRL_NOTF_COALcommands withVIRTIO_NET_ERRif it was not able to change the parameters. +A device SHOULD respond toVIRTIO_NET_CTRL_NOTF_COAL_TX_SETandVIRTIO_NET_CTRL_NOTF_COAL_RX_SETcommands withVIRTIO_NET_ERRif it was not able to change the parameters.(quoted diff) +2
-0+ +A device MUST respond to the VIRTIO_NET_CTRL_NOTF_COAL_VQ_SETcommand with
VIRTIO_NET_ERRif it was not able to change the parameters.(quoted diff) +2
-0+ +A device MUST respond to VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET and
VIRTIO_NET_CTRL_NOTF_COAL_VQ_GETcommands withVIRTIO_NET_ERRif the given virtqueue is disabled.(quoted diff) +2
-0+ +A device MUST ignore \field{reserved}.
Quoted 6 lines
Review
Quoted 5 lines
A device SHOULD NOT send used buffer notifications to the driver if the
notifications are suppressed, even if the notification conditions are met.(quoted diff) +1
-1-Upon reset, a device MUST initialize all coalescing parameters to 0. +After disabling and re-enabling a virtqueue, the device MUST revert coalescingrevert to
Thanks for pointing out.
Quoted 5 lines
Quoted 2 lines
parameters of the virtqueue to the global values.
+Like others suggested, above can be reworded as,
After disabling and re-enabling a virtuqueue, the device MUST revert to coalescing parameters to the one configured using
VIRTIO_NET_CTRL_NOTF_COAL.
I prefer this, I think it's better not to mention "global values".
Quoted 5 lines
Quoted 4 lines
+Upon reset, a device MUST initialize all coalescing parameters to 0 and MUST set the global values to 0.
No need to mention global values here. "all coalescing parameters to 0" covers per vq and per group of tx and rx vqs.
Ok.
Thanks!:)
Quoted 13 lines
Quoted 5 lines
\subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
Types / Network Device / Legacy Interface: Framing Requirements} --
2.19.1.6.gb485710bThis publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.
Quoted 8 lines
Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.
Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
Quoted 18 lines · Parav Pandit
Quoted 5 lines
From: Heng Qi <[email protected]>
Sent: Sunday, February 26, 2023 4:37 AM+# Read/Write attributes for coalescing parameters \begin{itemize} \item
Hash # above is not needed. Please remove.
Quoted 11 lines
+For commands
VIRTIO_NET_CTRL_NOTF_COAL_TX_SETandVIRTIO_NET_CTRL_NOTF_COAL_RX_SET, \field{max_usecs}
+ and \field{max_packets} are write-only for a driver.
+\item For the commandVIRTIO_NET_CTRL_NOTF_COAL_VQ_SET, \field{vqn}, \field{reserved}, \field{max_usecs}
+ and \field{max_packets} are write-only for a driver.
+\item For the commandVIRTIO_NET_CTRL_NOTF_COAL_VQ_GET, \field{vqn} and \field{reserved} are write-only
+ for a driver, and, \field{max_usecs} and \field{max_packets} are read-only
for the driver.
+\end{itemize}
Quoted 1 line
Instead of describing each individual fields of the structure struct
virtio_net_ctrl_coalcoal as read-only or write-only, better to say the struct itself as read/write only.
I don't see how you can reasonably do this. Which fields are RO and which WO depends on the command.
Quoted 1 line
This way when/if in the future, if struct
virtio_net_ctrl_coalcoal extends, no need to rewrite this section of the spec.
Exactly the reverse.
If you specify RO/WO for each field then you don't need to touch existing description when adding fields.
If you write in one place that all of struct is RO, when you add WO fields you need to change it.
Quoted 15 lines
Quoted 15 lines
+
Coalescing parameters:
\begin{itemize}
+\item \field{vqn}: The virtqueue number of an enabled transmit or receive virtqueue.
\item \field{max_usecs} for RX: Maximum number of microseconds to delay a
RX notification.
\item \field{max_usecs} for TX: Maximum number of microseconds to delay a
TX notification.
\item \field{max_packets} for RX: Maximum number of packets to receive
before a RX notification.
\item \field{max_packets} for TX: Maximum number of packets to send before
a TX notification.
\end{itemize}
Quoted 15 lines
Quoted 6 lines
device-types/net/description.tex +3
-2-The class VIRTIO_NET_CTRL_NOTF_COAL has 2 commands: +\field{reserved} is reserved and it is ignored by a device. + +The class VIRTIO_NET_CTRL_NOTF_COAL has 4 commands: \begin{enumerate} -\item VIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} andQuoted 7 lines
\field{max_packets} parameters for all transmit virtqueues. -\item
VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues. +\itemVIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all transmit virtqueues, and values of
+ coalescing parameters are recorded as TX global values
by a device."recording TX global values" is not conveying anything more as "all transmit virtqueues" is already mentioned. The original text without "recorded as Tx global values" is just fine. Same for the RX below.
I agree.
Quoted 81 lines
Quoted 71 lines
+\item
VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{max_usecs} and \field{max_packets} parameters for all receive virtqueues, and values of
+ coalescing parameters are recorded as RX global values
by a device.
+\itemVIRTIO_NET_CTRL_NOTF_COAL_VQ_SET: set the \field{max_usecs} and \field{max_packets} parameters for an enabled transmit/receive
+ virtqueue whose number is \field{vqn}, and do not
change the TX/RX global values.
+\itemVIRTIO_NET_CTRL_NOTF_COAL_VQ_GET: the device returns the \field{max_usecs} and \field{max_packets} parameters for an enableddevice-types/net/description.tex +3
-0+ transmit/receive virtqueue whose number is \field{vqn}. \end{enumerate} +If coalescing parameters are being set, the device applies the last +coalescing parameters received for a virtqueue, regardless of the commandused to set the parameters. For example with 2 pairs of virtqueues:
(quoted diff) +2
-0+# Command sequence +Each of the following commands sets \field{max_usecs} and\field{max_packets} parameters for virtqueues.
+\begin{itemize}
+\item Command1:VIRTIO_NET_CTRL_NOTF_COAL_RX_SETsets coalescing parameters for virtqueue0 and virtqueue2, and, virtqueue1 and virtqueue3 retain their previous parameter values.
+\item Command2:VIRTIO_NET_CTRL_NOTF_COAL_VQ_SETwith \field{vqn} = 0 sets coalescing parameters for virtqueue0, and virtqueue2 retains the values from command1.
+\item Command3:VIRTIO_NET_CTRL_NOTF_COAL_VQ_GETwith \field{vqn} = 0, the device responds with coalescing parameters of virtqueue0 set by command2.
+\item Command4:VIRTIO_NET_CTRL_NOTF_COAL_VQ_SETwith \field{vqn} = 1 sets coalescing parameters for virtqueue1, and virtqueue3 retains its previous values.
+\item Command5:VIRTIO_NET_CTRL_NOTF_COAL_TX_SETsets coalescing parameters for virtqueue1 and virtqueue3, and overrides the values set by command4.
+\item Command6:VIRTIO_NET_CTRL_NOTF_COAL_VQ_GETwith \field{vqn} = 1, the device responds with coalescing parameters of virtqueue1 set by command5.
+\end{itemize}
+
\subparagraph{Operation}\label{sec:Device Types / Network Device / Device
Operation / Control Virtqueue / Notifications Coalescing / Operation}The device sends a used buffer notification once the notification conditions are
met and if the notifications are not suppressed as explained in \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Used Buffer Notification Suppression}.(quoted diff) +0
-0@@ -1549,6 +1612,11 @@ \subsubsection{ControlVirtqueue}\label{sec:Device Types / Network Device / Devi
When the device has \field{max_usecs} = 0 or \field{max_packets} = 0, the
notification conditions are met after every packet received/sent.(quoted diff) +3
-0+When the device receives the VIRTIO_NET_CTRL_NOTF_COAL_TX_SET and +VIRTIO_NET_CTRL_NOTF_COAL_RX_SET commands, it saves the values of +coalescing parameters as global values, and the
VIRTIO_NET_CTRL_NOTF_COAL_VQ_SETcommand does not change the global values. If the device is reset, the global values will be set to 0. +When a virtqueue is enabled after virtqueue reset, its coalescing parameters are set to global values.
+
\subparagraph{RX Example}\label{sec:Device Types / Network Device / Device
Operation / Control Virtqueue / Notifications Coalescing / RX Example}If, for example:
(quoted diff) +0
-0@@ -1585,15 +1653,26 @@ \subsubsection{ControlVirtqueue}\label{sec:Device Types / Network Device / Devi
\drivernormative{\subparagraph}{Notifications Coalescing}{Device Types /
Network Device / Device Operation / Control Virtqueue / Notifications Coalescing}Quoted 7 lines
-If the
VIRTIO_NET_F_NOTF_COALfeature has not been negotiated, the driver MUST NOT issueVIRTIO_NET_CTRL_NOTF_COALcommands.
+If neither theVIRTIO_NET_F_NOTF_COALnor theVIRTIO_NET_F_VQ_NOTF_COAL
+feature has been negotiated, the driver MUST NOT issueVIRTIO_NET_CTRL_NOTF_COALcommands.
+I agree to Alvaro's suggestion.
IfVIRTIO_NET_F_NOTF_COALis not negotiated, the driver must not issue commands A and B.
Quoted 1 line
If
VIRTIO_NET_F_VQ_NOTF_COALis not negotiated, the driver must not issue commands C and D.
Yea. Though double negatives are annoying. One way to avoid them is
The driver MUST negotiate VIRTIO_NET_F_NOTF_COAL before issuing commands A and B.
or
The driver is REQUIRED to negotiate VIRTIO_NET_F_NOTF_COAL before issuing commands A and B.
Quoted 26 lines
Quoted 26 lines
+A driver MUST ignore the values of coalescing parameters received from the
VIRTIO_NET_CTRL_NOTF_COAL_VQ_GETcommand if a device responds withVIRTIO_NET_ERR.\devicenormative{\subparagraph}{Notifications Coalescing}{Device Types /
Network Device / Device Operation / Control Virtqueue / Notifications Coalescing}-A device SHOULD respond to the
VIRTIO_NET_CTRL_NOTF_COALcommands withVIRTIO_NET_ERRif it was not able to change the parameters. +A device SHOULD respond toVIRTIO_NET_CTRL_NOTF_COAL_TX_SETandVIRTIO_NET_CTRL_NOTF_COAL_RX_SETcommands withVIRTIO_NET_ERRif it was not able to change the parameters.(quoted diff) +2
-0+ +A device MUST respond to the VIRTIO_NET_CTRL_NOTF_COAL_VQ_SETcommand with
VIRTIO_NET_ERRif it was not able to change the parameters.(quoted diff) +2
-0+ +A device MUST respond to VIRTIO_NET_CTRL_NOTF_COAL_VQ_SET and
VIRTIO_NET_CTRL_NOTF_COAL_VQ_GETcommands withVIRTIO_NET_ERRif the given virtqueue is disabled.device-types/net/description.tex +2
-0+ +A device MUST ignore \field{reserved}. A device SHOULD NOT send used buffer notifications to the driver if thenotifications are suppressed, even if the notification conditions are met.
Quoted 8 lines
Review
Quoted 2 lines
(quoted diff) +1
-1-Upon reset, a device MUST initialize all coalescing parameters to 0. +After disabling and re-enabling a virtqueue, the device MUST revert coalescingrevert to
Quoted 2 lines
parameters of the virtqueue to the global values.
+Like others suggested, above can be reworded as,
After disabling and re-enabling a virtuqueue, the device MUST revert to coalescing parameters to the one configured using
VIRTIO_NET_CTRL_NOTF_COAL.
meaning RX/TX I guess. be explicit.
... or 0 if RX/TX was not set?
Quoted 4 lines
Quoted 3 lines
+Upon reset, a device MUST initialize all coalescing parameters to 0 and MUST set the global values to 0.
No need to mention global values here. "all coalescing parameters to 0" covers per vq and per group of tx and rx vqs.
Let's wait for new version of Alvaro's patch, rebase on top of that.
Quoted 4 lines
Quoted 4 lines
\subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
Types / Network Device / Legacy Interface: Framing Requirements} --
2.19.1.6.gb485710b
This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC.
In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting.
Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/