1.. SPDX-License-Identifier: GPL-2.0 2 3Running driver tests 4==================== 5 6Networking driver tests are executed within kselftest framework like any 7other tests. They support testing both real device drivers and emulated / 8software drivers (latter mostly to test the core parts of the stack). 9 10SW mode 11~~~~~~~ 12 13By default, when no extra parameters are set or exported, tests execute 14against software drivers such as netdevsim. No extra preparation is required 15the software devices are created and destroyed as part of the test. 16In this mode the tests are indistinguishable from other selftests and 17(for example) can be run under ``virtme-ng`` like the core networking selftests. 18 19HW mode 20~~~~~~~ 21 22Executing tests against a real device requires external preparation. 23The netdevice against which tests will be run must exist, be running 24(in UP state) and be configured with an IP address. 25 26Refer to list of :ref:`Variables` later in this file to set up running 27the tests against a real device. 28 29Both modes required 30~~~~~~~~~~~~~~~~~~~ 31 32All tests in drivers/net must support running both against a software device 33and a real device. SW-only tests should instead be placed in net/ or 34drivers/net/netdevsim, HW-only tests in drivers/net/hw. 35 36Variables 37========= 38 39The variables can be set in the environment or by creating a net.config 40file in the same directory as this README file. Example:: 41 42 $ NETIF=eth0 ./some_test.sh 43 44or:: 45 46 $ cat tools/testing/selftests/drivers/net/net.config 47 # Variable set in a file 48 NETIF=eth0 49 50Local test (which don't require endpoint for sending / receiving traffic) 51need only the ``NETIF`` variable. Remaining variables define the endpoint 52and communication method. 53 54NETIF 55~~~~~ 56 57Name of the netdevice against which the test should be executed. 58When empty or not set software devices will be used. 59 60LOCAL_V4, LOCAL_V6, REMOTE_V4, REMOTE_V6 61~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 62 63Local and remote endpoint IP addresses. 64 65LOCAL_PREFIX_V4, LOCAL_PREFIX_V6 66~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 67 68Local IP prefix/subnet which can be used to allocate extra IP addresses (for 69network name spaces behind macvlan, veth, netkit devices). DUT must be 70reachable using these addresses from the endpoint. 71 72REMOTE_TYPE 73~~~~~~~~~~~ 74 75Communication method used to run commands on the remote endpoint. 76Test framework has built-in support for ``netns`` and ``ssh`` channels. 77``netns`` assumes the "remote" interface is part of the same 78host, just moved to the specified netns. 79``ssh`` communicates with remote endpoint over ``ssh`` and ``scp``. 80Using persistent SSH connections is strongly encouraged to avoid 81the latency of SSH connection setup on every command. 82 83Communication methods are defined by classes in ``lib/py/remote_{name}.py``. 84It should be possible to add a new method without modifying any of 85the framework, by simply adding an appropriately named file to ``lib/py``. 86 87REMOTE_ARGS 88~~~~~~~~~~~ 89 90Arguments used to construct the communication channel. 91Communication channel dependent:: 92 93 for netns - name of the "remote" namespace 94 for ssh - name/address of the remote host 95 96Example 97======= 98 99Build the selftests:: 100 101 # make -C tools/testing/selftests/ TARGETS="drivers/net drivers/net/hw" 102 103"Install" the tests and copy them over to the target machine:: 104 105 # make -C tools/testing/selftests/ TARGETS="drivers/net drivers/net/hw" \ 106 install INSTALL_PATH=/tmp/ksft-net-drv 107 108 # rsync -ra --delete /tmp/ksft-net-drv root@192.168.1.1:/root/ 109 110On the target machine, running the tests will use netdevsim by default:: 111 112 [/root] # ./ksft-net-drv/run_kselftest.sh -t drivers/net:ping.py 113 TAP version 13 114 1..1 115 # timeout set to 45 116 # selftests: drivers/net: ping.py 117 # TAP version 13 118 # 1..3 119 # ok 1 ping.test_v4 120 # ok 2 ping.test_v6 121 # ok 3 ping.test_tcp 122 # # Totals: pass:3 fail:0 xfail:0 xpass:0 skip:0 error:0 123 ok 1 selftests: drivers/net: ping.py 124 125Create a config with remote info:: 126 127 [/root] # cat > ./ksft-net-drv/drivers/net/net.config <<EOF 128 NETIF=eth0 129 LOCAL_V4=192.168.1.1 130 REMOTE_V4=192.168.1.2 131 REMOTE_TYPE=ssh 132 REMOTE_ARGS=root@192.168.1.2 133 EOF 134 135Run the test:: 136 137 [/root] # ./ksft-net-drv/drivers/net/ping.py 138 TAP version 13 139 1..3 140 ok 1 ping.test_v4 141 ok 2 ping.test_v6 # SKIP Test requires IPv6 connectivity 142 ok 3 ping.test_tcp 143 # Totals: pass:2 fail:0 xfail:0 xpass:0 skip:1 error:0 144