diff --git a/boards/arm/qemu_cortex_m3/doc/index.rst b/boards/arm/qemu_cortex_m3/doc/index.rst index 48048163d2a..6fcdfef0705 100644 --- a/boards/arm/qemu_cortex_m3/doc/index.rst +++ b/boards/arm/qemu_cortex_m3/doc/index.rst @@ -114,6 +114,10 @@ The board supports SLIP networking over an emulated serial port (``CONFIG_NET_SLIP_TAP=y``). The detailed setup is described in :ref:`networking_with_qemu`. +It is also possible to use the QEMU built-in Ethernet adapter to connect +to the host system. This is faster than using SLIP and is also the preferred +way. See :ref:`networking_with_eth_qemu` for details. + References ********** diff --git a/boards/x86/qemu_x86/doc/index.rst b/boards/x86/qemu_x86/doc/index.rst index b50f6c1ad21..fcd9afa4125 100644 --- a/boards/x86/qemu_x86/doc/index.rst +++ b/boards/x86/qemu_x86/doc/index.rst @@ -122,3 +122,7 @@ Networking The board supports SLIP networking over an emulated serial port (``CONFIG_NET_SLIP_TAP=y``). The detailed setup is described in :ref:`networking_with_qemu`. + +It is also possible to use the QEMU built-in Ethernet adapter to connect +to the host system. This is faster than using SLIP and is also the preferred +way. See :ref:`networking_with_eth_qemu` for details. diff --git a/doc/guides/networking/index.rst b/doc/guides/networking/index.rst index 6afb31acc97..8d5cb116b9d 100644 --- a/doc/guides/networking/index.rst +++ b/doc/guides/networking/index.rst @@ -13,6 +13,8 @@ operation of the stacks and how they were implemented. overview.rst ip-stack-architecture.rst networking-api-usage.rst - qemu_setup.rst + networking_with_host.rst native_posix_setup.rst + qemu_eth_setup.rst + qemu_setup.rst usbnet_setup.rst diff --git a/doc/guides/networking/networking_with_host.rst b/doc/guides/networking/networking_with_host.rst new file mode 100644 index 00000000000..3ff9d51bbc2 --- /dev/null +++ b/doc/guides/networking/networking_with_host.rst @@ -0,0 +1,37 @@ +.. _networking_with_host: + +Networking with the host system +############################### + +While developing networking software, it is usually necessary to connect and +exchange data with the host system like a Linux desktop computer. +Depending on what board is used for development, the following options are +possible: + +* QEMU using SLIP (Serial Line Internet Protocol). + + * Here IP packets are exchanged between Zephyr and the host system via serial + port. This is the legacy way of transferring data. It is also quite slow so + use it only when necessary. See :ref:`networking_with_qemu` for details. + +* QEMU using built-in Ethernet driver. + + * Here IP packets are exchanged between Zephyr and the host system via QEMU's + built-in Ethernet driver. Not all QEMU boards support built-in Ethernet so + in some cases, you might need to use the SLIP method for host connectivity. + See :ref:`networking_with_eth_qemu` for details. + +* native_posix board. + + * The Zepher instance can be executed as a user space process in the host + system. This is the most convenient way to debug the Zephyr system as one + can attach host debugger directly to the running Zephyr instance. This + requires that there is an adaptation driver in Zephyr for interfacing + with the host system. An Ethernet driver exists in Zephyr for this purpose. + See :ref:`networking_with_native_posix` for details. + +* USB device networking. + + * Here, the Zephyr instance is run on a real board and the connectivity to + the host system is done via USB. + See :ref:`usb_device_networking_setup` for details. diff --git a/doc/guides/networking/qemu_eth_setup.rst b/doc/guides/networking/qemu_eth_setup.rst new file mode 100644 index 00000000000..239365ee8ed --- /dev/null +++ b/doc/guides/networking/qemu_eth_setup.rst @@ -0,0 +1,78 @@ +.. _networking_with_eth_qemu: + +Networking with QEMU Ethernet +############################# + +This page describes how to set up a virtual network between a (Linux) host +and a Zephyr application running in QEMU. + +In this example, the :ref:`sockets-echo-server-sample` sample application from +the Zephyr source distribution is run in QEMU. The Zephyr instance is +connected to a Linux host using a tuntap device which is modeled in Linux as +an Ethernet network interface. + +Prerequisites +************* + +On the Linux Host, fetch the Zephyr ``net-tools`` project, which is located +in a separate Git repository: + +.. code-block:: console + + git clone https://github.com/zephyrproject-rtos/net-tools + + +Basic Setup +*********** + +For the steps below, you will need two terminal windows: + +* Terminal #1 is terminal window with net-tools being the current + directory (``cd net-tools``) +* Terminal #2 is your usual Zephyr development terminal, + with the Zephyr environment initialized. + +When configuring the Zephyr instance, you must select the correct Ethernet +driver for QEMU connectivity: + +* For ``qemu_x86``, select ``Intel(R) PRO/1000 Gigabit Ethernet driver`` + Ethernet driver. Driver is called ``e1000`` in Zephyr source tree. +* For ``qemu_cortex_m3``, select ``TI Stellaris MCU family ethernet driver`` + Ethernet driver. Driver is called ``stellaris`` in Zephyr source tree. +* For ``mps2_an385``, select ``SMSC911x/9220 Ethernet driver`` Ethernet driver. + Driver is called ``smsc911x`` in Zephyr source tree. + +Step 1 - Create Ethernet interface +================================== + +Before starting QEMU with network connectivity, a network interface +should be created in the host system. + +In terminal #1, type: + +.. code-block:: console + + ./net-setup.sh + +You can tweak the behavior of the ``net-setup.sh`` script. See various options +by running ``net-setup.sh`` like this: + +.. code-block:: console + + ./net-setup.sh --help + + +Step 2 - Start app in QEMU board +================================ + +Build and start the :ref:`sockets-echo-server-sample` sample application. +In this example, the qemu_x86 board is used. + +In terminal #2, type: + +.. zephyr-app-commands:: + :zephyr-app: samples/net/sockets/echo_server + :host-os: unix + :board: qemu_x86 + :goals: run + :compact: diff --git a/samples/net/dhcpv4_client/README.rst b/samples/net/dhcpv4_client/README.rst index accce4c554f..4d3bf530501 100644 --- a/samples/net/dhcpv4_client/README.rst +++ b/samples/net/dhcpv4_client/README.rst @@ -13,7 +13,7 @@ information to a serial console. Requirements ************ -- :ref:`networking_with_qemu` +- :ref:`networking_with_host` Building and Running ******************** diff --git a/samples/net/dns_resolve/README.rst b/samples/net/dns_resolve/README.rst index 6318bf7f2f1..178252322d2 100644 --- a/samples/net/dns_resolve/README.rst +++ b/samples/net/dns_resolve/README.rst @@ -29,7 +29,7 @@ For more information about DNS configuration variables, see: Requirements ************ -- :ref:`networking_with_qemu` +- :ref:`networking_with_host` - screen terminal emulator or equivalent. diff --git a/samples/net/gptp/README.rst b/samples/net/gptp/README.rst index 0a0d2c28e87..bcbd2301ed8 100644 --- a/samples/net/gptp/README.rst +++ b/samples/net/gptp/README.rst @@ -17,7 +17,8 @@ The source code for this sample application can be found at: Requirements ************ -- :ref:`networking_with_native_posix` +For generic host connectivity, that can be used for debugging purposes, see +:ref:`networking_with_native_posix` for details. Building and Running ******************** diff --git a/samples/net/ipv4_autoconf/README.rst b/samples/net/ipv4_autoconf/README.rst index 0078dca519d..1ee783cbe41 100644 --- a/samples/net/ipv4_autoconf/README.rst +++ b/samples/net/ipv4_autoconf/README.rst @@ -14,7 +14,7 @@ parties try to allocate an identical address. Requirements ************ -- :ref:`networking_with_qemu` +- :ref:`networking_with_host` Building and Running ******************** diff --git a/samples/net/lldp/README.rst b/samples/net/lldp/README.rst index 5d3c91fc3de..192a12c754f 100644 --- a/samples/net/lldp/README.rst +++ b/samples/net/lldp/README.rst @@ -15,7 +15,7 @@ The source code for this sample application can be found at: Requirements ************ -- :ref:`networking_with_qemu` +- :ref:`networking_with_host` Building and Running ******************** diff --git a/samples/net/sockets/big_http_download/README.rst b/samples/net/sockets/big_http_download/README.rst index ff5ea51a030..aa831f5911b 100644 --- a/samples/net/sockets/big_http_download/README.rst +++ b/samples/net/sockets/big_http_download/README.rst @@ -20,7 +20,7 @@ The source code for this sample application can be found at: Requirements ************ -- :ref:`networking_with_qemu` +- :ref:`networking_with_host` - or, a board with hardware networking - NAT/routing should be set up to allow connections to the Internet - DNS server should be available on the host to resolve domain names diff --git a/samples/net/sockets/coap_client/README.rst b/samples/net/sockets/coap_client/README.rst index dee27b2aab9..fedea647b3c 100644 --- a/samples/net/sockets/coap_client/README.rst +++ b/samples/net/sockets/coap_client/README.rst @@ -28,8 +28,8 @@ be obtained by using a tool such as tcpdump or wireshark. See the `net-tools`_ project for more details. -This sample can be built and executed on QEMU as described -in :ref:`networking_with_qemu`. +This sample can be built and executed on QEMU or native_posix board as described +in :ref:`networking_with_host`. Sample output ============= diff --git a/samples/net/sockets/coap_server/README.rst b/samples/net/sockets/coap_server/README.rst index 298e611b92e..5159c66b989 100644 --- a/samples/net/sockets/coap_server/README.rst +++ b/samples/net/sockets/coap_server/README.rst @@ -38,8 +38,8 @@ or wireshark. See the `net-tools`_ project for more details -This sample can be built and executed on QEMU as described -in :ref:`networking_with_qemu`. +This sample can be built and executed on QEMU or native_posix board as +described in :ref:`networking_with_host`. Use this command on the host to run the `libcoap`_ implementation of the ETSI test cases: diff --git a/samples/net/sockets/dumb_http_server/README.rst b/samples/net/sockets/dumb_http_server/README.rst index 70d8ed5f3e6..fb5eac7a601 100644 --- a/samples/net/sockets/dumb_http_server/README.rst +++ b/samples/net/sockets/dumb_http_server/README.rst @@ -23,7 +23,7 @@ The source code for this sample application can be found at: Requirements ************ -- :ref:`networking_with_qemu` +- :ref:`networking_with_host` - or, a board with hardware networking Building and Running diff --git a/samples/net/sockets/echo/README.rst b/samples/net/sockets/echo/README.rst index 66b7c74c280..111e03628b7 100644 --- a/samples/net/sockets/echo/README.rst +++ b/samples/net/sockets/echo/README.rst @@ -17,7 +17,7 @@ The source code for this sample application can be found at: Requirements ************ -- :ref:`networking_with_qemu` +- :ref:`networking_with_host` - or, a board with hardware networking Building and Running diff --git a/samples/net/sockets/echo_async/README.rst b/samples/net/sockets/echo_async/README.rst index 9bfafff1871..a91ead280b1 100644 --- a/samples/net/sockets/echo_async/README.rst +++ b/samples/net/sockets/echo_async/README.rst @@ -19,7 +19,7 @@ The source code for this sample application can be found at: Requirements ************ -- :ref:`networking_with_qemu` +- :ref:`networking_with_host` - or, a board with hardware networking (including 6LoWPAN) Building and Running diff --git a/samples/net/sockets/echo_async_select/README.rst b/samples/net/sockets/echo_async_select/README.rst index 49766114a2c..70bd8ee896e 100644 --- a/samples/net/sockets/echo_async_select/README.rst +++ b/samples/net/sockets/echo_async_select/README.rst @@ -17,7 +17,7 @@ The source code for this sample application can be found at: Requirements ************ -- :ref:`networking_with_qemu` +- :ref:`networking_with_host` - or, a board with hardware networking (including 6LoWPAN) Building and Running diff --git a/samples/net/sockets/echo_client/README.rst b/samples/net/sockets/echo_client/README.rst index edef38759a0..d8f4ec65b45 100644 --- a/samples/net/sockets/echo_client/README.rst +++ b/samples/net/sockets/echo_client/README.rst @@ -16,7 +16,7 @@ The source code for this sample application can be found at: Requirements ************ -- :ref:`networking_with_qemu` +- :ref:`networking_with_host` Building and Running ******************** diff --git a/samples/net/sockets/echo_server/README.rst b/samples/net/sockets/echo_server/README.rst index af1f6d39ebb..2e68b565bfc 100644 --- a/samples/net/sockets/echo_server/README.rst +++ b/samples/net/sockets/echo_server/README.rst @@ -17,7 +17,7 @@ The source code for this sample application can be found at: Requirements ************ -- :ref:`networking_with_qemu` +- :ref:`networking_with_host` Building and Running ******************** diff --git a/samples/net/sockets/http_get/README.rst b/samples/net/sockets/http_get/README.rst index eb4a9d89b77..a2d9faeb4bd 100644 --- a/samples/net/sockets/http_get/README.rst +++ b/samples/net/sockets/http_get/README.rst @@ -18,7 +18,7 @@ The source code for this sample application can be found at: Requirements ************ -- :ref:`networking_with_qemu` +- :ref:`networking_with_host` - or, a board with hardware networking - NAT/routing should be set up to allow connections to the Internet - DNS server should be available on the host to resolve domain names diff --git a/samples/net/sockets/packet/README.rst b/samples/net/sockets/packet/README.rst index 93ec4bf5f72..fe6ce34c7cd 100644 --- a/samples/net/sockets/packet/README.rst +++ b/samples/net/sockets/packet/README.rst @@ -22,7 +22,7 @@ sent and received packets. See the `net-tools`_ project for more details. -This sample can be built and executed on QEMU as described -in :ref:`networking_with_qemu`. +This sample can be built and executed on QEMU or native_posix board as +described in :ref:`networking_with_host`. .. _`net-tools`: https://github.com/zephyrproject-rtos/net-tools diff --git a/samples/net/sockets/sntp_client/README.rst b/samples/net/sockets/sntp_client/README.rst index b283b95b3ad..9515ca3158c 100644 --- a/samples/net/sockets/sntp_client/README.rst +++ b/samples/net/sockets/sntp_client/README.rst @@ -23,7 +23,7 @@ printed. See the `net-tools`_ project for more details. -This sample can be built and executed on QEMU as described -in :ref:`networking_with_qemu`. +This sample can be built and executed on QEMU or native_posix board as +described in :ref:`networking_with_qemu`. .. _`net-tools`: https://github.com/zephyrproject-rtos/net-tools diff --git a/samples/net/stats/README.rst b/samples/net/stats/README.rst index 81b47bbe65d..26831c3bd4d 100644 --- a/samples/net/stats/README.rst +++ b/samples/net/stats/README.rst @@ -15,13 +15,13 @@ The source code for this sample application can be found at: Requirements ************ -- :ref:`networking_with_qemu` +- :ref:`networking_with_host` Building and Running ******************** -A good way to run this sample application is with QEMU as described in -:ref:`networking_with_qemu`. +A good way to run this sample application is with QEMU or native_posix board +as described in :ref:`networking_with_host`. Follow these steps to build the network statistics sample application: diff --git a/samples/net/syslog_net/README.rst b/samples/net/syslog_net/README.rst index 4b2cd2126a6..2a3d4a0ef35 100644 --- a/samples/net/syslog_net/README.rst +++ b/samples/net/syslog_net/README.rst @@ -17,7 +17,7 @@ The source code for this sample application can be found at: Requirements ************ -- :ref:`networking_with_qemu` +- :ref:`networking_with_host` Building and Running ******************** diff --git a/samples/net/vlan/README.rst b/samples/net/vlan/README.rst index a1190a5b73f..3a43f7ec901 100644 --- a/samples/net/vlan/README.rst +++ b/samples/net/vlan/README.rst @@ -15,7 +15,7 @@ The source code for this sample application can be found at: Requirements ************ -- :ref:`networking_with_qemu` +- :ref:`networking_with_host` Building and Running ********************