After another inspection, I found some typos in the patch, will be fixed in the next version.
> > This patch adds a new feature, VIRTIO_NET_F_NOTF_COAL_LOW_HIGH, while > clarifying/fixing existing coalescing concepts. > > The new feature adds 4 new commands to VIRTIO_NET_CTRL_NOTF_COAL class: > - VIRTIO_NET_CTRL_NOTF_COAL_LOW_TX_SET - coalescing parameters > to use when the packet rate is equal or lower then the low > threshold for TX. s/then/than/ > - VIRTIO_NET_CTRL_NOTF_COAL_LOW_RX_SET - coalescing parameters > to use when the packet rate is equal or lower then the low > threshold for RX. s/then/than/ > - VIRTIO_NET_CTRL_NOTF_COAL_HIGH_TX_SET - coalescing parameters > to use when the packet rate is equal or higher then the high > threshold for TX. s/then/than/ > - VIRTIO_NET_CTRL_NOTF_COAL_HIGH_RX_SET - coalescing parameters > to use when the packet rate is equal or higher then the high > threshold for RX. s/then/than/ > On top of the new feature, this patch: > - Unifies the virtio_net_ctrl_coal structs, since the one for tx > and the one for rx are identical. > - Clarifies that the coalescing commands are best-effort. > - Specifies coalescing in respect to delivering interrupts when config > changes. > > Signed-off-by: Alvaro Karsz <alvaro.ka...@solid-run.com> > --- > v2: > - Remove the "set of coalescing parameters" concept, use > "coalescing parameters" instead. > - Unify struct virtio_net_ctrl_coal_rx and strcut > virtio_net_ctrl_coal_tx s/strcut/struct > to struct virtio_net_ctrl_coal. > - Separate the commands to tx and rx, so devices could have > different low/high rate coalescing parameters for tx and rx. > - Unify struct virtio_net_ctrl_coal_high and struct > virtio_net_ctrl_coal_low to struct virtio_net_ctrl_coal_threshold. > - Clarify that the packet rate is in packet per second units. > - Clarify that any notification coalescing command is best-effort. > - Specify coalescing in respect to delivering interrupts when config > changes. > --- > content.tex | 105 +++++++++++++++++++++++++++++++++++++++++++--------- > 1 file changed, 87 insertions(+), 18 deletions(-) > > diff --git a/content.tex b/content.tex > index 96f4723..82b2597 100644 > --- a/content.tex > +++ b/content.tex > @@ -3088,6 +3088,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_NOTF_COAL_LOW_HIGH(50)] Device supports notifications > coalescing low rate and high rate sets. > + Replace with: Device supports low/high packet rate coalescing parameters. > \item[VIRTIO_NET_F_NOTF_COAL(53)] Device supports notifications coalescing. > > \item[VIRTIO_NET_F_GUEST_USO4 (54)] Driver can receive USOv4 packets. > @@ -3142,6 +3144,7 @@ \subsubsection{Feature bit > requirements}\label{sec:Device Types / Network Device > \item[VIRTIO_NET_F_MQ] Requires VIRTIO_NET_F_CTRL_VQ. > \item[VIRTIO_NET_F_CTRL_MAC_ADDR] Requires VIRTIO_NET_F_CTRL_VQ. > \item[VIRTIO_NET_F_NOTF_COAL] Requires VIRTIO_NET_F_CTRL_VQ. > +\item[VIRTIO_NET_F_NOTF_COAL_LOW_HIGH] Requires VIRTIO_NET_F_NOTF_COAL. > \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. > \end{description} > @@ -4493,43 +4496,62 @@ \subsubsection{Control Virtqueue}\label{sec:Device > Types / Network Device / Devi > If the VIRTIO_NET_F_NOTF_COAL feature is negotiated, the driver can > send control commands for dynamically changing the coalescing parameters. > > +Note: In general, these commands are best-effort: A device could send a > notification even if it is not supposed to. > + > \begin{lstlisting} > -struct virtio_net_ctrl_coal_rx { > - le32 rx_max_packets; > - le32 rx_usecs; > +struct virtio_net_ctrl_coal { > + le32 max_packets; > + le32 usecs; > }; > > -struct virtio_net_ctrl_coal_tx { > - le32 tx_max_packets; > - le32 tx_usecs; > +struct virtio_net_ctrl_coal_threshold { > + le32 pkt_rate; > + struct virtio_net_ctrl_coal params; > }; > > #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_LOW_TX_SET 2 //Only if > VIRTIO_NET_F_NOTF_COAL_LOW_HIGH negotiated > + #define VIRTIO_NET_CTRL_NOTF_COAL_LOW_RX_SET 3 //Only if > VIRTIO_NET_F_NOTF_COAL_LOW_HIGH negotiated > + #define VIRTIO_NET_CTRL_NOTF_COAL_HIGH_TX_SET 4 //Only if > VIRTIO_NET_F_NOTF_COAL_LOW_HIGH negotiated > + #define VIRTIO_NET_CTRL_NOTF_COAL_HIGH_RX_SET 5 //Only if > VIRTIO_NET_F_NOTF_COAL_LOW_HIGH negotiated > \end{lstlisting} > > -Coalescing parameters: > +TX Coalescing parameters: > +\begin{itemize} > +\item \field{usecs}: Maximum number of usecs to delay a TX notification. > +\item \field{max_packets}: Maximum number of packets to send before a TX > notification. > +\end{itemize} > + > +RX Coalescing parameters: > +\begin{itemize} > +\item \field{usecs}: Maximum number of usecs to delay a RX notification. > +\item \field{max_packets}: Maximum number of packets to receive before a RX > notification. > +\end{itemize} > + > +General Coalescing parameters: > \begin{itemize} > -\item \field{rx_usecs}: Maximum number of usecs to delay a RX notification. > -\item \field{tx_usecs}: Maximum number of usecs to delay a TX notification. > -\item \field{rx_max_packets}: Maximum number of packets to receive before a > RX notification. > -\item \field{tx_max_packets}: Maximum number of packets to send before a TX > notification. > +\item \field{pkt_rate}: Threshold for low/high packet rate coalescing > parameters, in units of packets per second. > \end{itemize} > > > -The class VIRTIO_NET_CTRL_NOTF_COAL has 2 commands: > +The class VIRTIO_NET_CTRL_NOTF_COAL has 6 commands: > \begin{enumerate} > -\item VIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{tx_usecs} and > \field{tx_max_packets} parameters. > -\item VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{rx_usecs} and > \field{rx_max_packets} parameters. > +\item VIRTIO_NET_CTRL_NOTF_COAL_TX_SET: set the \field{usecs} and > \field{max_packets} coalescing parameters for TX. > +\item VIRTIO_NET_CTRL_NOTF_COAL_RX_SET: set the \field{usecs} and > \field{max_packets} coalescing parameters for RX. > +\item VIRTIO_NET_CTRL_NOTF_COAL_LOW_TX_SET: set the \field{usecs} and > \field{max_packets} coalescing parameters for packet rate of \field{pkt_rate} > or lower, for TX. > +\item VIRTIO_NET_CTRL_NOTF_COAL_LOW_RX_SET: set the \field{usecs} and > \field{max_packets} coalescing parameters for packet rate of \field{pkt_rate} > or lower, for RX. > +\item VIRTIO_NET_CTRL_NOTF_COAL_HIGH_TX_SET: set the \field{usecs} and > \field{max_packets} coalescing parameters for packet rate of \field{pkt_rate} > or higher, for TX. > +\item VIRTIO_NET_CTRL_NOTF_COAL_HIGH_RX_SET: set the \field{usecs} and > \field{max_packets} coalescing parameters for packet rate of \field{pkt_rate} > or higher, for RX. > \end{enumerate} > > \subparagraph{RX Notifications}\label{sec:Device Types / Network Device / > Device Operation / Control Virtqueue / Notifications Coalescing / RX > Notifications} > > If, for example: > \begin{itemize} > -\item \field{rx_usecs} = 10. > -\item \field{rx_max_packets} = 15. > +\item \field{usecs} = 10. > +\item \field{max_packets} = 15. > \end{itemize} > > The device will operate as follows: > @@ -4543,8 +4565,8 @@ \subsubsection{Control Virtqueue}\label{sec:Device > Types / Network Device / Devi > > If, for example: > \begin{itemize} > -\item \field{tx_usecs} = 10. > -\item \field{tx_max_packets} = 15. > +\item \field{usecs} = 10. > +\item \field{max_packets} = 15. > \end{itemize} > > The device will operate as follows: > @@ -4554,18 +4576,65 @@ \subsubsection{Control Virtqueue}\label{sec:Device > Types / Network Device / Devi > \item If the notifications are not suppressed by the driver, the device will > send an used buffer notification, otherwise, the device will not send an used > buffer notification as long as the notifications are suppressed. > \end{itemize} > > +\subparagraph{Notifications When Coalescing Parameters > Change}\label{sec:Device Types / Network Device / Device Operation / Control > Virtqueue / Notifications Coalescing / Notifications When Coalescing > Parameters Change} > + > +When a device changes the coalescing parameters, the device needs to check > if the new parameters are met and issue a notification if so. > + > +For example, \field{max_packets} = 15 for TX. > + > +If the device sends 10 packets, then it receives a > VIRTIO_NET_CTRL_NOTF_COAL_TX_SET command with \field{max_packets} = 8, the > device needs to immediately send a TX notification, if the notifications are > not suppressed by the driver. > + > +\subparagraph{Low/High Rate Notifications}\label{sec:Device Types / Network > Device / Device Operation / Control Virtqueue / Notifications Coalescing / > Low/High Rate Notifications} > + > +If the VIRTIO_NET_F_NOTF_COAL_LOW_HIGH feature is negotiated, the driver can > send the following low/high rate coalescing commands to the device: > + > +\begin{itemize} > +\item VIRTIO_NET_CTRL_NOTF_COAL_LOW_TX_SET. > +\item VIRTIO_NET_CTRL_NOTF_COAL_LOW_RX_SET. > +\item VIRTIO_NET_CTRL_NOTF_COAL_HIGH_TX_SET. > +\item VIRTIO_NET_CTRL_NOTF_COAL_HIGH_RX_SET. > +\end{itemize} > + > +For VIRTIO_NET_CTRL_NOTF_COAL_LOW_TX_SET and > VIRTIO_NET_CTRL_NOTF_COAL_LOW_RX_SET, struct virtio_net_ctrl_coal_threshold > specifies the coalescing parameters to use when the packet rate is > \field{pkt_rate} or lower. > + > +For VIRTIO_NET_CTRL_NOTF_COAL_HIGH_TX_SET and > VIRTIO_NET_CTRL_NOTF_COAL_HIGH_RX_SET, struct virtio_net_ctrl_coal_threshold > specifies the coalescing parameters to use when the packet rate is > \field{pkt_rate} or higher. > + > \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 the VIRTIO_NET_F_NOTF_COAL_LOW_HIGH feature has not been negotiated, the > driver MUST NOT issue low/high rate coalescing commands. > + > +The driver SHOULD issue a low/high rate coalescing command with > \field{pkt_rate} 0 in order to remove the low/high rate coalescing parameters. > + > +The driver MUST NOT issue a VIRTIO_NET_CTRL_NOTF_COAL_LOW_TX_SET command > with \field{pkt_rate} equal or higher than a \field{pkt_rate} previously sent > with a VIRTIO_NET_CTRL_NOTF_COAL_HIGH_TX_SET command. > + > +The driver MUST NOT issue a VIRTIO_NET_CTRL_NOTF_COAL_LOW_RX_SET command > with \field{pkt_rate} equal or higher than a \field{pkt_rate} previously sent > with a VIRTIO_NET_CTRL_NOTF_COAL_HIGH_RX_SET command. > + > +The driver MUST NOT issue a VIRTIO_NET_CTRL_NOTF_COAL_HIGH_TX_SET command > with \field{pkt_rate} equal or lower than a \field{pkt_rate} previously sent > with a VIRTIO_NET_CTRL_NOTF_COAL_LOW_TX_SET command. > + > +The driver MUST NOT issue a VIRTIO_NET_CTRL_NOTF_COAL_HIGH_RX_SET command > with \field{pkt_rate} equal or lower than a \field{pkt_rate} previously sent > with a VIRTIO_NET_CTRL_NOTF_COAL_LOW_RX_SET command. > + > \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 NOT send used buffer notifications to the driver, if the > notifications are suppressed as explained in \ref{sec:Basic Facilities of a > Virtio Device / Virtqueues / Used Buffer Notification Suppression}, even if > the coalescing counters expired. > > +A device MUST remove the low/high rate coalescing parameters, if a low/high > rate coalescing command is received with \field{pkt_rate} 0. > + > +A device MUST respond with VIRTIO_NET_ERR to a > VIRTIO_NET_CTRL_NOTF_COAL_LOW_TX_SET command with \field{pkt_rate} equal or > higher than a \field{pkt_rate} previously received with a > VIRTIO_NET_CTRL_NOTF_COAL_HIGH_TX_SET command. > + > +A device MUST respond with VIRTIO_NET_ERR to a > VIRTIO_NET_CTRL_NOTF_COAL_LOW_RX_SET command with \field{pkt_rate} equal or > higher than a \field{pkt_rate} previously received with a > VIRTIO_NET_CTRL_NOTF_COAL_HIGH_RX_SET command. > + > +A device MUST respond with VIRTIO_NET_ERR to a > VIRTIO_NET_CTRL_NOTF_COAL_HIGH_TX_SET command with \field{pkt_rate} equal or > lower than a \field{pkt_rate} previously received with a > VIRTIO_NET_CTRL_NOTF_COAL_LOW_TX_SET command. > + > +A device MUST respond with VIRTIO_NET_ERR to a > VIRTIO_NET_CTRL_NOTF_COAL_HIGH_RX_SET command with \field{pkt_rate} equal or > lower than a \field{pkt_rate} previously received with a > VIRTIO_NET_CTRL_NOTF_COAL_LOW_RX_SET command. > + > Upon reset, a device MUST initialize all coalescing parameters to 0. > > +Upon reset, a device MUST not have a low/high rate coalescing parameters. > + > \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device > Types / Network Device / Legacy Interface: Framing Requirements} > > -- > 2.32.0 > --------------------------------------------------------------------- To unsubscribe, e-mail: virtio-dev-unsubscr...@lists.oasis-open.org For additional commands, e-mail: virtio-dev-h...@lists.oasis-open.org