[PATCH 1/1] doc: describe QEMU networking

[Heinrich Schuchardt]

Add a chapter about networking to the QEMU board documentation.

Describe both different types of networking as well as different emulated
NICs.

Suggested-by: Manjae Cho <manjae.cho at samsung.com>
Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
---
 doc/board/emulation/index.rst   |   1 +
 doc/board/emulation/network.rst | 152 ++++++++++++++++++++++++++++++++
 2 files changed, 153 insertions(+)
 create mode 100644 doc/board/emulation/network.rst

diff --git a/doc/board/emulation/index.rst b/doc/board/emulation/index.rst
index f8908166276..896f44c8087 100644
--- a/doc/board/emulation/index.rst
+++ b/doc/board/emulation/index.rst
@@ -8,6 +8,7 @@ Emulation
 
    acpi
    blkdev
+   network
    qemu-arm
    qemu-mips
    qemu-ppce500
diff --git a/doc/board/emulation/network.rst b/doc/board/emulation/network.rst
new file mode 100644
index 00000000000..e997265c297
--- /dev/null
+++ b/doc/board/emulation/network.rst
@@ -0,0 +1,152 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Emulation of network devices
+============================
+
+Networking types
+----------------
+
+QEMU can emulate different types of networks:
+
+User networking
+'''''''''''''''
+
+User networking is the easiest to use. QEMU provides NAT translation and a DHCP
+server.
+
+.. code-block:: bash
+
+    -netdev user,id=eth0 \
+    -device virtio-net,netdev=eth0
+
+Port forwarding
+~~~~~~~~~~~~~~~
+
+The emulated device can access the outside network but cannot be reached from
+outside by default. Forwarding rules can be added.
+
+In the example the SSH port 22 of the default interface of the emulated device
+is forwarded to port 2222 of the loopback interface of the host.
+
+.. code-block:: bash
+
+    -netdev user,id=eth0,hostfwd=tcp:127.0.0.1:2222-:22 \
+    -device virtio-net,netdev=eth0
+
+TFTP
+~~~~
+
+A TFTP server can be added by specifying a file path.
+
+.. code-block:: bash
+
+    -netdev user,id=eth0,tftp=/path/to/tftpdir \
+    -device virtio-net,netdev=eth0
+
+Bridge networking
+'''''''''''''''''
+
+The emulated NIC is connected to an existing bridge device.
+
+.. code-block:: bash
+
+    -netdev bridge,id=eth0,br=virbr0 \
+    -device virtio-net,netdev=eth0
+
+The emulated device becomes part of the same local network as the bridge.
+
+Tap networking
+''''''''''''''
+
+With tap networking a tap device is created on the host.
+
+.. code-block:: bash
+
+    -netdev tap,id=eth0 \
+    -device virtio-net,netdev=eth0
+
+Emulated network interface controllers
+--------------------------------------
+
+QEMU can emulate different NICs. For best performance choose ``virtio-net``.
+
+Intel E1000
+'''''''''''
+
+U-Boot's E1000 driver supports a number of Intel PCI NICs. This includes the
+QEMU devices ``e1000``, ``e1000-82544gc``, and ``e1000-82545em``.
+
+.. code-block:: bash
+
+    -netdev user,id=eth0 \
+    -device e1000,netdev=eth0
+
+Configuration:
+
+* CONFIG_PCI=y
+* CONFIG_E1000=y
+
+Realtek RTL8139
+'''''''''''''''
+
+The RTL8139 is a PCI network card.
+The U-Boot driver only supports the i386 archtitecture.
+
+.. code-block:: bash
+
+    -netdev user,id=eth0 \
+    -device rtl8139,netdev=eth0
+
+Configuration:
+
+* CONFIG_PCI=y
+* CONFIG_NET_RANDOM_ETHADDR=y
+* CONFIG_RTL8139
+
+Virtio
+''''''
+
+U-Boot's virtio network driver supports ``virtio-net``, ``virtio-net-device``,
+and ``virtio-net-pci`` devices. ``virtio-net-device`` uses MMIO, while
+``virtio-net-pci`` uses PCI.
+
+For best performance use ``virtio-net``.
+
+.. code-block:: bash
+
+    -netdev user,id=eth0 \
+    -device virtio-net,netdev=eth0
+
+Configuration:
+
+* CONFIG_PCI=y (only for ``virtio-net-pci``)
+* CONFIG_NET_VIRTIO=y
+
+Network device options
+----------------------
+
+The network adapters provide different configuration parameters.
+Here are some common ones.
+
+mac
+    set MAC address
+
+    .. code-block:: bash
+
+        -netdev user,id=eth0 \
+        -device virtio-net-pci,netdev=eth0,mac=00:00:00:00:01:01
+
+romfile
+    provide the ROM file of the NIC
+
+    .. code-block:: bash
+
+        -netdev user,id=eth0 \
+        -device virtio-net-pci,netdev=eth0,romfile=pxe-virtio.rom
+
+    or provide none
+
+    .. code-block:: bash
+
+        -netdev user,id=eth0 \
+        -device virtio-net-pci,netdev=eth0,romfile=
-- 
2.51.0