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 65REMOTE_TYPE 66~~~~~~~~~~~ 67 68Communication method used to run commands on the remote endpoint. 69Test framework has built-in support for ``netns`` and ``ssh`` channels. 70``netns`` assumes the "remote" interface is part of the same 71host, just moved to the specified netns. 72``ssh`` communicates with remote endpoint over ``ssh`` and ``scp``. 73Using persistent SSH connections is strongly encouraged to avoid 74the latency of SSH connection setup on every command. 75 76Communication methods are defined by classes in ``lib/py/remote_{name}.py``. 77It should be possible to add a new method without modifying any of 78the framework, by simply adding an appropriately named file to ``lib/py``. 79 80REMOTE_ARGS 81~~~~~~~~~~~ 82 83Arguments used to construct the communication channel. 84Communication channel dependent:: 85 86 for netns - name of the "remote" namespace 87 for ssh - name/address of the remote host 88 89Example 90======= 91 92Build the selftests:: 93 94 # make -C tools/testing/selftests/ TARGETS="drivers/net drivers/net/hw" 95 96"Install" the tests and copy them over to the target machine:: 97 98 # make -C tools/testing/selftests/ TARGETS="drivers/net drivers/net/hw" \ 99 install INSTALL_PATH=/tmp/ksft-net-drv 100 101 # rsync -ra --delete /tmp/ksft-net-drv root@192.168.1.1:/root/ 102 103On the target machine, running the tests will use netdevsim by default:: 104 105 [/root] # ./ksft-net-drv/run_kselftest.sh -t drivers/net:ping.py 106 TAP version 13 107 1..1 108 # timeout set to 45 109 # selftests: drivers/net: ping.py 110 # KTAP version 1 111 # 1..3 112 # ok 1 ping.test_v4 113 # ok 2 ping.test_v6 114 # ok 3 ping.test_tcp 115 # # Totals: pass:3 fail:0 xfail:0 xpass:0 skip:0 error:0 116 ok 1 selftests: drivers/net: ping.py 117 118Create a config with remote info:: 119 120 [/root] # cat > ./ksft-net-drv/drivers/net/net.config <<EOF 121 NETIF=eth0 122 LOCAL_V4=192.168.1.1 123 REMOTE_V4=192.168.1.2 124 REMOTE_TYPE=ssh 125 REMOTE_ARGS=root@192.168.1.2 126 EOF 127 128Run the test:: 129 130 [/root] # ./ksft-net-drv/drivers/net/ping.py 131 KTAP version 1 132 1..3 133 ok 1 ping.test_v4 134 ok 2 ping.test_v6 # SKIP Test requires IPv6 connectivity 135 ok 3 ping.test_tcp 136 # Totals: pass:2 fail:0 xfail:0 xpass:0 skip:1 error:0 137