1*f8ac9b0fSJakub Kicinski.. SPDX-License-Identifier: GPL-2.0 2b4db9f84SJakub Kicinski 3*f8ac9b0fSJakub KicinskiRunning driver tests 4*f8ac9b0fSJakub Kicinski==================== 5b4db9f84SJakub Kicinski 6*f8ac9b0fSJakub KicinskiNetworking driver tests are executed within kselftest framework like any 7*f8ac9b0fSJakub Kicinskiother tests. They support testing both real device drivers and emulated / 8*f8ac9b0fSJakub Kicinskisoftware drivers (latter mostly to test the core parts of the stack). 9*f8ac9b0fSJakub Kicinski 10*f8ac9b0fSJakub KicinskiSW mode 11*f8ac9b0fSJakub Kicinski~~~~~~~ 12*f8ac9b0fSJakub Kicinski 13*f8ac9b0fSJakub KicinskiBy default, when no extra parameters are set or exported, tests execute 14*f8ac9b0fSJakub Kicinskiagainst software drivers such as netdevsim. No extra preparation is required 15*f8ac9b0fSJakub Kicinskithe software devices are created and destroyed as part of the test. 16*f8ac9b0fSJakub KicinskiIn this mode the tests are indistinguishable from other selftests and 17*f8ac9b0fSJakub Kicinski(for example) can be run under ``virtme-ng`` like the core networking selftests. 18*f8ac9b0fSJakub Kicinski 19*f8ac9b0fSJakub KicinskiHW mode 20*f8ac9b0fSJakub Kicinski~~~~~~~ 21*f8ac9b0fSJakub Kicinski 22*f8ac9b0fSJakub KicinskiExecuting tests against a real device requires external preparation. 23*f8ac9b0fSJakub KicinskiThe netdevice against which tests will be run must exist, be running 24*f8ac9b0fSJakub Kicinski(in UP state) and be configured with an IP address. 25*f8ac9b0fSJakub Kicinski 26*f8ac9b0fSJakub KicinskiRefer to list of :ref:`Variables` later in this file to set up running 27*f8ac9b0fSJakub Kicinskithe tests against a real device. 28*f8ac9b0fSJakub Kicinski 29*f8ac9b0fSJakub KicinskiBoth modes required 30*f8ac9b0fSJakub Kicinski~~~~~~~~~~~~~~~~~~~ 31*f8ac9b0fSJakub Kicinski 32*f8ac9b0fSJakub KicinskiAll tests in drivers/net must support running both against a software device 33*f8ac9b0fSJakub Kicinskiand a real device. SW-only tests should instead be placed in net/ or 34*f8ac9b0fSJakub Kicinskidrivers/net/netdevsim, HW-only tests in drivers/net/hw. 35b4db9f84SJakub Kicinski 36b4db9f84SJakub KicinskiVariables 37b4db9f84SJakub Kicinski========= 38b4db9f84SJakub Kicinski 39*f8ac9b0fSJakub KicinskiThe variables can be set in the environment or by creating a net.config 40b4db9f84SJakub Kicinskifile in the same directory as this README file. Example:: 41b4db9f84SJakub Kicinski 42b4db9f84SJakub Kicinski $ NETIF=eth0 ./some_test.sh 43b4db9f84SJakub Kicinski 44b4db9f84SJakub Kicinskior:: 45b4db9f84SJakub Kicinski 46b4db9f84SJakub Kicinski $ cat tools/testing/selftests/drivers/net/net.config 47b4db9f84SJakub Kicinski # Variable set in a file 48b4db9f84SJakub Kicinski NETIF=eth0 49b4db9f84SJakub Kicinski 50*f8ac9b0fSJakub KicinskiLocal test (which don't require endpoint for sending / receiving traffic) 51*f8ac9b0fSJakub Kicinskineed only the ``NETIF`` variable. Remaining variables define the endpoint 52*f8ac9b0fSJakub Kicinskiand communication method. 531880f272SJakub Kicinski 54b4db9f84SJakub KicinskiNETIF 55b4db9f84SJakub Kicinski~~~~~ 56b4db9f84SJakub Kicinski 57b4db9f84SJakub KicinskiName of the netdevice against which the test should be executed. 58b4db9f84SJakub KicinskiWhen empty or not set software devices will be used. 591880f272SJakub Kicinski 601880f272SJakub KicinskiLOCAL_V4, LOCAL_V6, REMOTE_V4, REMOTE_V6 611880f272SJakub Kicinski~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 621880f272SJakub Kicinski 631880f272SJakub KicinskiLocal and remote endpoint IP addresses. 641880f272SJakub Kicinski 651880f272SJakub KicinskiREMOTE_TYPE 661880f272SJakub Kicinski~~~~~~~~~~~ 671880f272SJakub Kicinski 681880f272SJakub KicinskiCommunication method used to run commands on the remote endpoint. 691880f272SJakub KicinskiTest framework has built-in support for ``netns`` and ``ssh`` channels. 701880f272SJakub Kicinski``netns`` assumes the "remote" interface is part of the same 711880f272SJakub Kicinskihost, just moved to the specified netns. 721880f272SJakub Kicinski``ssh`` communicates with remote endpoint over ``ssh`` and ``scp``. 731880f272SJakub KicinskiUsing persistent SSH connections is strongly encouraged to avoid 741880f272SJakub Kicinskithe latency of SSH connection setup on every command. 751880f272SJakub Kicinski 761880f272SJakub KicinskiCommunication methods are defined by classes in ``lib/py/remote_{name}.py``. 771880f272SJakub KicinskiIt should be possible to add a new method without modifying any of 781880f272SJakub Kicinskithe framework, by simply adding an appropriately named file to ``lib/py``. 791880f272SJakub Kicinski 801880f272SJakub KicinskiREMOTE_ARGS 811880f272SJakub Kicinski~~~~~~~~~~~ 821880f272SJakub Kicinski 831880f272SJakub KicinskiArguments used to construct the communication channel. 841880f272SJakub KicinskiCommunication channel dependent:: 851880f272SJakub Kicinski 861880f272SJakub Kicinski for netns - name of the "remote" namespace 871880f272SJakub Kicinski for ssh - name/address of the remote host 88*f8ac9b0fSJakub Kicinski 89*f8ac9b0fSJakub KicinskiExample 90*f8ac9b0fSJakub Kicinski======= 91*f8ac9b0fSJakub Kicinski 92*f8ac9b0fSJakub KicinskiBuild the selftests:: 93*f8ac9b0fSJakub Kicinski 94*f8ac9b0fSJakub Kicinski # make -C tools/testing/selftests/ TARGETS="drivers/net drivers/net/hw" 95*f8ac9b0fSJakub Kicinski 96*f8ac9b0fSJakub Kicinski"Install" the tests and copy them over to the target machine:: 97*f8ac9b0fSJakub Kicinski 98*f8ac9b0fSJakub Kicinski # make -C tools/testing/selftests/ TARGETS="drivers/net drivers/net/hw" \ 99*f8ac9b0fSJakub Kicinski install INSTALL_PATH=/tmp/ksft-net-drv 100*f8ac9b0fSJakub Kicinski 101*f8ac9b0fSJakub Kicinski # rsync -ra --delete /tmp/ksft-net-drv root@192.168.1.1:/root/ 102*f8ac9b0fSJakub Kicinski 103*f8ac9b0fSJakub KicinskiOn the target machine, running the tests will use netdevsim by default:: 104*f8ac9b0fSJakub Kicinski 105*f8ac9b0fSJakub Kicinski [/root] # ./ksft-net-drv/run_kselftest.sh -t drivers/net:ping.py 106*f8ac9b0fSJakub Kicinski TAP version 13 107*f8ac9b0fSJakub Kicinski 1..1 108*f8ac9b0fSJakub Kicinski # timeout set to 45 109*f8ac9b0fSJakub Kicinski # selftests: drivers/net: ping.py 110*f8ac9b0fSJakub Kicinski # KTAP version 1 111*f8ac9b0fSJakub Kicinski # 1..3 112*f8ac9b0fSJakub Kicinski # ok 1 ping.test_v4 113*f8ac9b0fSJakub Kicinski # ok 2 ping.test_v6 114*f8ac9b0fSJakub Kicinski # ok 3 ping.test_tcp 115*f8ac9b0fSJakub Kicinski # # Totals: pass:3 fail:0 xfail:0 xpass:0 skip:0 error:0 116*f8ac9b0fSJakub Kicinski ok 1 selftests: drivers/net: ping.py 117*f8ac9b0fSJakub Kicinski 118*f8ac9b0fSJakub KicinskiCreate a config with remote info:: 119*f8ac9b0fSJakub Kicinski 120*f8ac9b0fSJakub Kicinski [/root] # cat > ./ksft-net-drv/drivers/net/net.config <<EOF 121*f8ac9b0fSJakub Kicinski NETIF=eth0 122*f8ac9b0fSJakub Kicinski LOCAL_V4=192.168.1.1 123*f8ac9b0fSJakub Kicinski REMOTE_V4=192.168.1.2 124*f8ac9b0fSJakub Kicinski REMOTE_TYPE=ssh 125*f8ac9b0fSJakub Kicinski REMOTE_ARGS=root@192.168.1.2 126*f8ac9b0fSJakub Kicinski EOF 127*f8ac9b0fSJakub Kicinski 128*f8ac9b0fSJakub KicinskiRun the test:: 129*f8ac9b0fSJakub Kicinski 130*f8ac9b0fSJakub Kicinski [/root] # ./ksft-net-drv/drivers/net/ping.py 131*f8ac9b0fSJakub Kicinski KTAP version 1 132*f8ac9b0fSJakub Kicinski 1..3 133*f8ac9b0fSJakub Kicinski ok 1 ping.test_v4 134*f8ac9b0fSJakub Kicinski ok 2 ping.test_v6 # SKIP Test requires IPv6 connectivity 135*f8ac9b0fSJakub Kicinski ok 3 ping.test_tcp 136*f8ac9b0fSJakub Kicinski # Totals: pass:2 fail:0 xfail:0 xpass:0 skip:1 error:0 137