[PATCH v2 2/2] net: document VIRTIO_NET_F_MAC_ADDR

["Michael S. Tsirkin" <mst@redhat.com>]

VIRTIO_50

commit f058954d131e3dc73058778ad23b241a235ae8e1
    virtio-spec: set mac address by a new vq command

Reported-by: Francesco Fusco <ffusco@redhat.com>
Signed-off-by: Amos Kong <akong@redhat.com>
Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
 content.tex                              | 34 ++++++++++++++++++++++++++++++++
 virtio-v1.0-wd01-part1-specification.txt | 34 ++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+)

diff --git a/content.tex b/content.tex
index 637ca2b..b3575bd 100644
--- a/content.tex
+++ b/content.tex
@@ -2279,6 +2279,9 @@ features.
   VIRTIO_NET_F_MQ(22) Device supports multiqueue with automatic
     receive steering.
 
+  VIRTIO_NET_F_CTRL_MAC_ADDR(23) Set MAC address through control
+    channel.
+
 \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network Device / Feature bits / Legacy Interface: Feature bits}
 VIRTIO_NET_F_GSO (6) Device handles packets with any GSO type.
 
@@ -2612,6 +2615,7 @@ off. The command-specific-data is one byte containing 0 (off) or
 
 	#define VIRTIO_NET_CTRL_MAC    1
 	 #define VIRTIO_NET_CTRL_MAC_TABLE_SET        0
+	 #define VIRTIO_NET_CTRL_MAC_ADDR_SET         1
 \end{lstlisting}
 
 The device can filter incoming packets by any number of destination
@@ -2625,10 +2629,40 @@ command-specific-data is two variable length tables of 6-byte MAC
 addresses. The first table contains unicast addresses, and the second
 contains multicast addresses.
 
+When VIRTIO_NET_F_MAC_ADDR is not negotiated, the mac field in
+config space is writeable and is used to set the default MAC
+address which rx filtering accepts.
+When VIRTIO_NET_F_MAC_ADDR is negotiated, the mac field in
+config space becomes read-only.
+The VIRTIO_NET_CTRL_MAC_ADDR_SET command is used to set the
+default MAC address which rx filtering
+accepts
+
+Depending on whether VIRTIO_NET_F_MAC_ADDR has been negotiated,
+the mac field in config space or the VIRTIO_NET_CTRL_MAC_ADDR_SET
+is used to set the default MAC address which rx filtering
+accepts.
+The command-specific-data for VIRTIO_NET_CTRL_MAC_ADDR_SET is
+the 6-byte MAC address.
+
+The
+VIRTIO_NET_CTRL_MAC_ADDR_SET command is atomic whereas the
+mac field in config space is not, therefore drivers
+MUST negotiate VIRTIO_NET_F_MAC_ADDR if they change
+mac address when device is accepting incoming packets.
+
 \subparagraph{Legacy Interface: Setting MAC Address Filtering}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Setting MAC Address Filtering / Legacy Interface: Setting MAC Address Filtering}
 For legacy devices, the entries field in struct virtio_net_ctrl_mac is the
 native endian of the guest rather than (necessarily) little-endian.
 
+Legacy drivers that didn't negotiate VIRTIO_NET_F_MAC_ADDR
+changed the mac field in config space when NIC is accepting
+incoming packets. These drivers always wrote the mac value from
+first to last byte, therefore after detecting such drivers,
+a transitional device CAN defer MAC update, or CAN defer
+processing incoming packets until driver writes the last byte
+of the mac field in config space.
+
 \paragraph{VLAN Filtering}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / VLAN Filtering}
 
 If the driver negotiates the VIRTION_NET_F_CTRL_VLAN feature, it
diff --git a/virtio-v1.0-wd01-part1-specification.txt b/virtio-v1.0-wd01-part1-specification.txt
index bfbece3..160b4d3 100644
--- a/virtio-v1.0-wd01-part1-specification.txt
+++ b/virtio-v1.0-wd01-part1-specification.txt
@@ -2361,6 +2361,9 @@ features.
   VIRTIO_NET_F_MQ(22) Device supports multiqueue with automatic
     receive steering.
 
+  VIRTIO_NET_F_CTRL_MAC_ADDR(23) Set MAC address through control
+    channel.
+
 2.4.1.3.1. Legacy Interface: Feature bits
 --------------------
 VIRTIO_NET_F_GSO (6) Device handles packets with any GSO type.
@@ -2661,6 +2664,7 @@ off. The command-specific-data is one byte containing 0 (off) or
 
 	#define VIRTIO_NET_CTRL_MAC    1
 	 #define VIRTIO_NET_CTRL_MAC_TABLE_SET        0
+	 #define VIRTIO_NET_CTRL_MAC_ADDR_SET         1
 
 The device can filter incoming packets by any number of destination
 MAC addresses.[21] This table is set using the class
@@ -2669,11 +2673,41 @@ command-specific-data is two variable length tables of 6-byte MAC
 addresses. The first table contains unicast addresses, and the second
 contains multicast addresses.
 
+When VIRTIO_NET_F_MAC_ADDR is not negotiated, the mac field in
+config space is writeable and is used to set the default MAC
+address which rx filtering accepts.
+When VIRTIO_NET_F_MAC_ADDR is negotiated, the mac field in
+config space becomes read-only.
+The VIRTIO_NET_CTRL_MAC_ADDR_SET command is used to set the
+default MAC address which rx filtering
+accepts
+
+Depending on whether VIRTIO_NET_F_MAC_ADDR has been negotiated,
+the mac field in config space or the VIRTIO_NET_CTRL_MAC_ADDR_SET
+is used to set the default MAC address which rx filtering
+accepts.
+The command-specific-data for VIRTIO_NET_CTRL_MAC_ADDR_SET is
+the 6-byte MAC address.
+
+The
+VIRTIO_NET_CTRL_MAC_ADDR_SET command is atomic whereas the
+mac field in config space is not, therefore drivers
+MUST negotiate VIRTIO_NET_F_MAC_ADDR if they change
+mac address when device is accepting incoming packets.
+
 2.4.1.5.3.2.1.  Legacy Interface: Setting MAC Address Filtering
 -----------------------------------------
 For legacy devices, the entries field in struct virtio_net_ctrl_mac is the
 native endian of the guest rather than (necessarily) little-endian.
 
+Legacy drivers that didn't negotiate VIRTIO_NET_F_MAC_ADDR
+changed the mac field in config space when NIC is accepting
+incoming packets. These drivers always wrote the mac value from
+first to last byte, therefore after detecting such drivers,
+a transitional device CAN defer MAC update, or CAN defer
+processing incoming packets until driver writes the last byte
+of the mac field in config space.
+
 2.4.1.5.3.3. VLAN Filtering
 --------------------------
 
-- 
MST