[PATCH v2] network device: document VIRTIO_NET_F_CTRL_RX_EXTRA

VIRTIO-124  Signed-off-by: Michael S. Tsirkin <> ---  content.tex
84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++

------

1 file changed, 76 insertions(+), 8 deletions(-)  diff --git a/content.tex b/content.tex index b287f5f..86500be 100644 --- a/content.tex +++ b/content.tex @@ -3643,32 +3643,93 @@ do except issue a diagnostic if field{ack} is not  VIRTIO_NET_OK.
paragraph{Packet Receive Filtering}label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Packet Receive Filtering} +label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Setting Promiscuous Mode}%old label for latexdiff
If the VIRTIO_NET_F_CTRL_RX feature is negotiated, the driver can -send control commands for promiscuous mode, multicast receiving, -and filtering of MAC addresses. +send control commands for promiscuous mode, multicast,unicast +and broadcast receiving.
egin{note}  In general, these commands are best-effort: unwanted  packets could still arrive.  end{note}
-paragraph{Setting Promiscuous Mode}label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Setting Promiscuous Mode} -  egin{lstlisting}  #define VIRTIO_NET_CTRL_RX
0
#define VIRTIO_NET_CTRL_RX_PROMISC
0
#define VIRTIO_NET_CTRL_RX_ALLMULTI
1 + #define VIRTIO_NET_CTRL_RX_ALLUNI
2 + #define VIRTIO_NET_CTRL_RX_NOMULTI
3 + #define VIRTIO_NET_CTRL_RX_NOUNI
4 + #define VIRTIO_NET_CTRL_RX_NOBCAST
5  end{lstlisting}
-The class VIRTIO_NET_CTRL_RX has two commands: -VIRTIO_NET_CTRL_RX_PROMISC turns promiscuous mode on and off, and -VIRTIO_NET_CTRL_RX_ALLMULTI turns all-multicast receive on and + +devicenormative{subparagraph}{Packet Receive Filtering}{Device Types / Network Device / Device Operation / Control Virtqueue / Packet Receive Filtering} + +If the VIRTIO_NET_F_CTRL_RX_EXTRA feature has been negotiated, +the device MUST support the following VIRTIO_NET_CTRL_RX class +commands: +egin{itemize} +item VIRTIO_NET_CTRL_RX_PROMISC turns promiscuous mode on and +off. The command-specific-data is one byte containing 0 (off) or +1 (on). If promiscous mode is on, the device SHOULD receive all +incoming packets. +This SHOULD take effect even if one of the other modes set by +a VIRTIO_NET_CTRL_RX class command is on. +item VIRTIO_NET_CTRL_RX_ALLMULTI turns all-multicast receive on and  off. The command-specific-data is one byte containing 0 (off) or -1 (on). +1 (on). When all-multicast receive is on the device SHOULD allow +all incoming multicast packets. +end{itemize} + +If the VIRTIO_NET_F_CTRL_RX_EXTRA feature has been negotiated, +the device MUST support the following VIRTIO_NET_CTRL_RX class +commands: +egin{itemize} +item VIRTIO_NET_CTRL_RX_ALLUNI turns all-unicast receive on and +off. The command-specific-data is one byte containing 0 (off) or +1 (on). When all-unicast receive is on the device SHOULD allow +all incoming unicast packets. +item VIRTIO_NET_CTRL_RX_NOMULTI suppresses multicast receive. +The command-specific-data is one byte containing 0 (multicast +receive allowed) or 1 (multicast receive suppressed). +When multicast receive is suppressed, the device SHOULD NOT +send multicast packets to the driver. +This SHOULD take effect even if VIRTIO_NET_CTRL_RX_ALLMULTI is on. +This filter SHOULD NOT apply to broadcast packets. +item VIRTIO_NET_CTRL_RX_NOUNI suppresses unicast receive. +The command-specific-data is one byte containing 0 (unicast +receive allowed) or 1 (unicast receive suppressed). +When unicast receive is suppressed, the device SHOULD NOT +send unicast packets to the driver. +This SHOULD take effect even if VIRTIO_NET_CTRL_RX_ALLUNI is on. +item VIRTIO_NET_CTRL_RX_NOBCAST suppresses broadcast receive. +The command-specific-data is one byte containing 0 (broadcast +receive allowed) or 1 (broadcast receive suppressed). +When broadcast receive is suppressed, the device SHOULD NOT +send broadcast packets to the driver. +This SHOULD take effect even if VIRTIO_NET_CTRL_RX_ALLMULTI is on. +end{itemize} + +drivernormative{subparagraph}{Packet Receive Filtering}{Device Types / Network Device / Device Operation / Control Virtqueue / Packet Receive Filtering} + +If the VIRTIO_NET_F_CTRL_RX feature has not been negotiated, +the driver MUST NOT issue commands VIRTIO_NET_CTRL_RX_PROMISC or +VIRTIO_NET_CTRL_RX_ALLMULTI. + +If the VIRTIO_NET_F_CTRL_RX_EXTRA feature has not been negotiated, +the driver MUST NOT issue commands + VIRTIO_NET_CTRL_RX_ALLUNI, + VIRTIO_NET_CTRL_RX_NOMULTI, + VIRTIO_NET_CTRL_RX_NOUNI or + VIRTIO_NET_CTRL_RX_NOBCAST.
paragraph{Setting MAC Address Filtering}label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Setting MAC Address Filtering}
+If the VIRTIO_NET_F_CTRL_RX feature is negotiated, the driver can +send control commands for MAC address filtering. +  egin{lstlisting}  struct virtio_net_ctrl_mac {
le32 entries; @@ -3715,6 +3776,13 @@ nor the MAC filtering table.
drivernormative{subparagraph}{Setting MAC Address Filtering}{Device Types / Network Device / Device Operation / Control Virtqueue / Setting MAC Address Filtering}
+If VIRTIO_NET_F_CTRL_RX has not been negotiated, +the driver MUST NOT issue VIRTIO_NET_CTRL_MAC class commands. + +If VIRTIO_NET_F_CTRL_RX has been negotiated, +the driver SHOULD issue VIRTIO_NET_CTRL_MAC_ADDR_SET +to set the default mac if that's different from field{mac}. +  The driver MUST follow the VIRTIO_NET_CTRL_MAC_TABLE_SET command  by a le32 number, followed by that number of non-multicast  MAC addresses, followed by another le32 number, followed by

--
MST