Skip to contentSkip to conversation

docs: stop documenting the e1000 NIC model as the default

PATCH In review Daniel P. Berrangé 3 participants 3 messages Jan 9, 2020

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: stop documenting the e1000 NIC model as the default

The default NIC model for QEMU varies per machine type, and is liable to change across machine type versions. Documenting e1000 NIC as the default for PC/i386 is thus misleading to users at best. In particular the PC q35 machine type switched to use e1000e, but only in machine type versions after 2.11.

Rather than try to explain which NIC model is used for each machine type version, remove mention of e1000 as the default, and steer users towards always specifying their desired model.

---
 qemu-options.hx | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)
qemu-options.hx +7 -5
index e9d6231438..ca57145126 100644
@@ -2344,8 +2344,7 @@ Use @option{model=help} to list the available device types.
 The hardware MAC address can be set with @option{mac=@var{macaddr}}.
 
 The following two example do exactly the same, to show how @option{-nic} can
-be used to shorten the command line length (note that the e1000 is the default
-on i386, so the @option{model=e1000} parameter could even be omitted here, too):
+be used to shorten the command line length:
 @example
 @value{qemu_system} -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
 @value{qemu_system} -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
@@ -2759,9 +2758,12 @@ netdev with ID @var{nd} by using the @option{netdev=@var{nd}} option.
 Legacy option to configure or create an on-board (or machine default) Network
 Interface Card(NIC) and connect it either to the emulated hub with ID 0 (i.e.
 the default hub), or to the netdev @var{nd}.
-The NIC is an e1000 by default on the PC target. Optionally, the MAC address
-can be changed to @var{mac}, the device address set to @var{addr} (PCI cards
-only), and a @var{name} can be assigned for use in monitor commands.
+If @var{model} is omitted, then the default NIC model associated with
+the machine type is used. Note that the default NIC model may change in
+future QEMU releases, so it is highly recommended to always specify a model.
+Optionally, the MAC address can be changed to @var{mac}, the device
+address set to @var{addr} (PCI cards only), and a @var{name} can be
+assigned for use in monitor commands.
 Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
 that the card should have; this option currently only affects virtio cards; set
 @var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
Signature · 1 line
2.23.0
#1 lore raw
Quoted 6 lines · Daniel P. Berrangé

The default NIC model for QEMU varies per machine type, and is liable to change across machine type versions. Documenting e1000 NIC as the default for PC/i386 is thus misleading to users at best. In particular the PC q35 machine type switched to use e1000e, but only in machine type versions after 2.11.

Quoted 10 lines

Rather than try to explain which NIC model is used for each machine type version, remove mention of e1000 as the default, and steer users towards always specifying their desired model.

---
 qemu-options.hx | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

Reviewed by: Aleksandar Markovic <[email protected]>

Quoted 49 lines
qemu-options.hx +0 -0
index e9d6231438..ca57145126 100644
@@ -2344,8 +2344,7 @@ Use @option{model=help} to list the available device

types.
The hardware MAC address can be set with @option{mac=@var{macaddr}}.

The following two example do exactly the same, to show how @option{-nic}
can
-be used to shorten the command line length (note that the e1000 is the default
-on i386, so the @option{model=e1000} parameter could even be omitted here, too):
+be used to shorten the command line length:
@example
@value{qemu_system} -netdev user,id=n1,ipv6=off -device
e1000,netdev=n1,mac=52:54:98:76:54:32
@value{qemu_system} -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32

qemu-options.hx +0 -0
@@ -2759,9 +2758,12 @@ netdev with ID @var{nd} by using the

@option{netdev=@var{nd}} option.
Legacy option to configure or create an on-board (or machine default)
Network
Interface Card(NIC) and connect it either to the emulated hub with ID 0
(i.e.
the default hub), or to the netdev @var{nd}.
-The NIC is an e1000 by default on the PC target. Optionally, the MAC address
-can be changed to @var{mac}, the device address set to @var{addr} (PCI cards

qemu-options.hx +3 -1
-only), and a @var{name} can be assigned for use in monitor commands.
+If @var{model} is omitted, then the default NIC model associated with
+the machine type is used. Note that the default NIC model may change in
+future QEMU releases, so it is highly recommended to always specify a

model.

qemu-options.hx +3 -0
+Optionally, the MAC address can be changed to @var{mac}, the device
+address set to @var{addr} (PCI cards only), and a @var{name} can be
+assigned for use in monitor commands.
 Optionally, for PCI cards, you can specify the number @var{v} of MSI-X

vectors
that the card should have; this option currently only affects virtio
cards; set
@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a
single
--
2.23.0

Reviewed-by on v1 1/1
#2 lore raw
In reply to Daniel P. Berrangé
Quoted 6 lines · Daniel P. Berrangé

The default NIC model for QEMU varies per machine type, and is liable to change across machine type versions. Documenting e1000 NIC as the default for PC/i386 is thus misleading to users at best. In particular the PC q35 machine type switched to use e1000e, but only in machine type versions after 2.11.

Quoted 8 lines

Rather than try to explain which NIC model is used for each machine type version, remove mention of e1000 as the default, and steer users towards always specifying their desired model.

---
 qemu-options.hx | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)