1 .. SPDX-License-Identifier: GPL-2.0
2
3 Running driver tests
4 ====================
5
6 Networking driver tests are executed within kselftest framework like any
7 other tests. They support testing both real device drivers and emulated /
8 software drivers (latter mostly to test the core parts of the stack).
9
10 SW mode
11 ~~~~~~~
12
13 By default, when no extra parameters are set or exported, tests execute
14 against software drivers such as netdevsim. No extra preparation is required
15 the software devices are created and destroyed as part of the test.
16 In 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
19 HW mode
20 ~~~~~~~
21
22 Executing tests against a real device requires external preparation.
23 The netdevice against which tests will be run must exist, be running
24 (in UP state) and be configured with an IP address.
25
26 Refer to list of :ref:`Variables` later in this file to set up running
27 the tests against a real device.
28
29 Both modes required
30 ~~~~~~~~~~~~~~~~~~~
31
32 All tests in drivers/net must support running both against a software device
33 and a real device. SW-only tests should instead be placed in net/ or
34 drivers/net/netdevsim, HW-only tests in drivers/net/hw.
35
36 Variables
37 =========
38
39 The variables can be set in the environment or by creating a net.config
40 file in the same directory as this README file. Example::
41
42 $ NETIF=eth0 ./some_test.sh
43
44 or::
45
46 $ cat tools/testing/selftests/drivers/net/net.config
47 # Variable set in a file
48 NETIF=eth0
49
50 Local test (which don't require endpoint for sending / receiving traffic)
51 need only the ``NETIF`` variable. Remaining variables define the endpoint
52 and communication method.
53
54 NETIF
55 ~~~~~
56
57 Name of the netdevice against which the test should be executed.
58 When empty or not set software devices will be used.
59
60 LOCAL_V4, LOCAL_V6, REMOTE_V4, REMOTE_V6
61 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
62
63 Local and remote endpoint IP addresses.
64
65 REMOTE_TYPE
66 ~~~~~~~~~~~
67
68 Communication method used to run commands on the remote endpoint.
69 Test framework has built-in support for ``netns`` and ``ssh`` channels.
70 ``netns`` assumes the "remote" interface is part of the same
71 host, just moved to the specified netns.
72 ``ssh`` communicates with remote endpoint over ``ssh`` and ``scp``.
73 Using persistent SSH connections is strongly encouraged to avoid
74 the latency of SSH connection setup on every command.
75
76 Communication methods are defined by classes in ``lib/py/remote_{name}.py``.
77 It should be possible to add a new method without modifying any of
78 the framework, by simply adding an appropriately named file to ``lib/py``.
79
80 REMOTE_ARGS
81 ~~~~~~~~~~~
82
83 Arguments used to construct the communication channel.
84 Communication channel dependent::
85
86 for netns - name of the "remote" namespace
87 for ssh - name/address of the remote host
88
89 Example
90 =======
91
92 Build 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
103 On 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
118 Create 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
128 Run 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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.