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 <[email protected]> Signed-off-by: Heinrich Schuchardt <[email protected]> --- 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
