1 | .. comment SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. COMMENT: Text Written by Jake Janovetz |
---|
4 | .. COMMENT: COPYRIGHT (c) 1988-2002. |
---|
5 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
6 | .. COMMENT: All rights reserved. |
---|
7 | |
---|
8 | Testing the Driver |
---|
9 | ################## |
---|
10 | |
---|
11 | Preliminary Setup |
---|
12 | ================= |
---|
13 | |
---|
14 | The network used to test the driver should include at least: |
---|
15 | |
---|
16 | - The hardware on which the driver is to run. It makes testing much easier if |
---|
17 | you can run a debugger to control the operation of the target machine. |
---|
18 | |
---|
19 | - An Ethernet network analyzer or a workstation with an 'Ethernet snoop' |
---|
20 | program such as ``ethersnoop`` or ``tcpdump``. |
---|
21 | |
---|
22 | - A workstation. |
---|
23 | |
---|
24 | During early debug, you should consider putting the target, workstation, and |
---|
25 | snooper on a small network by themselves. This offers a few advantages: |
---|
26 | |
---|
27 | - There is less traffic to look at on the snooper and for the target to process |
---|
28 | while bringing the driver up. |
---|
29 | |
---|
30 | - Any serious errors will impact only your small network not a building or |
---|
31 | campus network. You want to avoid causing any unnecessary problems. |
---|
32 | |
---|
33 | - Test traffic is easier to repeatably generate. |
---|
34 | |
---|
35 | - Performance measurements are not impacted by other systems on the network. |
---|
36 | |
---|
37 | Debug Output |
---|
38 | ============ |
---|
39 | |
---|
40 | There are a number of sources of debug output that can be enabled to aid in |
---|
41 | tracing the behavior of the network stack. The following is a list of them: |
---|
42 | |
---|
43 | - mbuf activity |
---|
44 | There are commented out calls to ``printf`` in the file ``sys/mbuf.h`` in the |
---|
45 | network stack code. Uncommenting these lines results in output when mbuf's |
---|
46 | are allocated and freed. This is very useful for finding memory leaks. |
---|
47 | |
---|
48 | - TX and RX queuing |
---|
49 | There are commented out calls to ``printf`` in the file ``net/if.h`` in the |
---|
50 | network stack code. Uncommenting these lines results in output when packets |
---|
51 | are placed on or removed from one of the transmit or receive packet queues. |
---|
52 | These queues can be viewed as the boundary line between a device driver and |
---|
53 | the network stack. If the network stack is enqueuing packets to be |
---|
54 | transmitted that the device driver is not dequeuing, then that is indicative |
---|
55 | of a problem in the transmit side of the device driver. Conversely, if the |
---|
56 | device driver is enqueueing packets as it receives them (via a call to |
---|
57 | ``ether_input``) and they are not being dequeued by the network stack, then |
---|
58 | there is a problem. This situation would likely indicate that the network |
---|
59 | server task is not running. |
---|
60 | |
---|
61 | - TCP state transitions |
---|
62 | |
---|
63 | In the unlikely event that one would actually want to see TCP state |
---|
64 | transitions, the ``TCPDEBUG`` macro can be defined in the file |
---|
65 | ``opt_tcpdebug.h``. This results in the routine ``tcp_trace()`` being called |
---|
66 | by the network stack and the state transitions logged into the ``tcp_debug`` |
---|
67 | data structure. If the variable ``tcpconsdebug`` in the file |
---|
68 | ``netinet/tcp_debug.c`` is set to ``1``, then the state transitions will also |
---|
69 | be printed to the console. |
---|
70 | |
---|
71 | Monitor Commands |
---|
72 | ================ |
---|
73 | |
---|
74 | There are a number of command available in the shell / monitor to aid in |
---|
75 | tracing the behavior of the network stack. The following is a list of them: |
---|
76 | |
---|
77 | - ``inet`` |
---|
78 | This command shows the current routing information for the TCP/IP |
---|
79 | stack. Following is an example showing the output of this command. |
---|
80 | |
---|
81 | .. code-block:: shell |
---|
82 | |
---|
83 | Destination Gateway/Mask/Hw Flags Refs Use Expire Interface |
---|
84 | 10.0.0.0 255.0.0.0 U 0 0 17 smc1 |
---|
85 | 127.0.0.1 127.0.0.1 UH 0 0 0 lo0 |
---|
86 | |
---|
87 | In this example, there is only one network interface with an IP address of |
---|
88 | 10.8.1.1. This link is currently not up. Two routes that are shown are the |
---|
89 | default routes for the Ethernet interface (10.0.0.0) and the loopback |
---|
90 | interface (127.0.0.1). Since the stack comes from BSD, this command is very |
---|
91 | similar to the netstat command. For more details on the network routing |
---|
92 | please look the following URL: |
---|
93 | (http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-routing.html) |
---|
94 | For a quick reference to the flags, see the table below: |
---|
95 | |
---|
96 | '``U``' |
---|
97 | Up: The route is active. |
---|
98 | |
---|
99 | '``H``' |
---|
100 | Host: The route destination is a single host. |
---|
101 | |
---|
102 | '``G``' |
---|
103 | Gateway: Send anything for this destination on to this remote system, |
---|
104 | which will figure out from there where to send it. |
---|
105 | |
---|
106 | '``S``' |
---|
107 | Static: This route was configured manually, not automatically generated |
---|
108 | by the system. |
---|
109 | |
---|
110 | '``C``' |
---|
111 | Clone: Generates a new route based upon this route for machines we |
---|
112 | connect to. This type of route is normally used for local networks. |
---|
113 | |
---|
114 | '``W``' |
---|
115 | WasCloned: Indicated a route that was auto-configured based upon a local |
---|
116 | area network (Clone) route. |
---|
117 | |
---|
118 | '``L``' |
---|
119 | Link: Route involves references to Ethernet hardware. |
---|
120 | |
---|
121 | - ``mbuf`` |
---|
122 | This command shows the current MBUF statistics. An example of the command is |
---|
123 | shown below: |
---|
124 | |
---|
125 | .. code-block:: shell |
---|
126 | |
---|
127 | ************ MBUF STATISTICS \************ |
---|
128 | mbufs:4096 clusters: 256 free: 241 |
---|
129 | drops: 0 waits: 0 drains: 0 |
---|
130 | free:4080 data:16 header:0 socket:0 |
---|
131 | pcb:0 rtable:0 htable:0 atable:0 |
---|
132 | soname:0 soopts:0 ftable:0 rights:0 |
---|
133 | ifaddr:0 control:0 oobdata:0 |
---|
134 | |
---|
135 | - ``if`` |
---|
136 | This command shows the current statistics for your Ethernet driver as long as |
---|
137 | the ioctl hook ``SIO_RTEMS_SHOW_STATS`` has been implemented. Below is an |
---|
138 | example: |
---|
139 | |
---|
140 | .. code-block:: shell |
---|
141 | |
---|
142 | ************ INTERFACE STATISTICS \************ |
---|
143 | \***** smc1 \***** |
---|
144 | Ethernet Address: 00:12:76:43:34:25 |
---|
145 | Address:10.8.1.1 Broadcast Address:10.255.255.255 Net mask:255.0.0.0 |
---|
146 | Flags: Up Broadcast Running Simplex |
---|
147 | Send queue limit:50 length:0 Dropped:0 |
---|
148 | SMC91C111 RTEMS driver A0.01 11/03/2002 Ian Caddy (ianc@microsol.iinet.net.au) |
---|
149 | Rx Interrupts:0 Not First:0 Not Last:0 |
---|
150 | Giant:0 Runt:0 Non-octet:0 |
---|
151 | Bad CRC:0 Overrun:0 Collision:0 |
---|
152 | Tx Interrupts:2 Deferred:0 Missed Hearbeat:0 |
---|
153 | No Carrier:0 Retransmit Limit:0 Late Collision:0 |
---|
154 | Underrun:0 Raw output wait:0 Coalesced:0 |
---|
155 | Coalesce failed:0 Retries:0 |
---|
156 | \***** lo0 \***** |
---|
157 | Address:127.0.0.1 Net mask:255.0.0.0 |
---|
158 | Flags: Up Loopback Running Multicast |
---|
159 | Send queue limit:50 length:0 Dropped:0 |
---|
160 | |
---|
161 | - ``ip`` |
---|
162 | This command show the IP statistics for the currently configured interfaces. |
---|
163 | |
---|
164 | - ``icmp`` |
---|
165 | This command show the ICMP statistics for the currently configured interfaces. |
---|
166 | |
---|
167 | - ``tcp`` |
---|
168 | This command show the TCP statistics for the currently configured interfaces. |
---|
169 | |
---|
170 | - ``udp`` |
---|
171 | This command show the UDP statistics for the currently configured interfaces. |
---|
172 | |
---|
173 | Driver basic operation |
---|
174 | ====================== |
---|
175 | |
---|
176 | The network demonstration program ``netdemo`` may be used for these tests. |
---|
177 | |
---|
178 | - Edit ``networkconfig.h`` to reflect the values for your network. |
---|
179 | |
---|
180 | - Start with ``RTEMS_USE_BOOTP`` not defined. |
---|
181 | |
---|
182 | - Edit ``networkconfig.h`` to configure the driver with an explicit Ethernet |
---|
183 | and Internet address and with reception of broadcast packets disabled: Verify |
---|
184 | that the program continues to run once the driver has been attached. |
---|
185 | |
---|
186 | - Issue a '``u``' command to send UDP packets to the 'discard' port. Verify |
---|
187 | that the packets appear on the network. |
---|
188 | |
---|
189 | - Issue a '``s``' command to print the network and driver statistics. |
---|
190 | |
---|
191 | - On a workstation, add a static route to the target system. |
---|
192 | |
---|
193 | - On that same workstation try to 'ping' the target system. |
---|
194 | Verify that the ICMP echo request and reply packets appear on the net. |
---|
195 | |
---|
196 | - Remove the static route to the target system. Modify ``networkconfig.h`` to |
---|
197 | attach the driver with reception of broadcast packets enabled. Try to 'ping' |
---|
198 | the target system again. Verify that ARP request/reply and ICMP echo |
---|
199 | request/reply packets appear on the net. |
---|
200 | |
---|
201 | - Issue a '``t``' command to send TCP packets to the 'discard' port. Verify |
---|
202 | that the packets appear on the network. |
---|
203 | |
---|
204 | - Issue a '``s``' command to print the network and driver statistics. |
---|
205 | |
---|
206 | - Verify that you can telnet to ports 24742 and 24743 on the target system from |
---|
207 | one or more workstations on your network. |
---|
208 | |
---|
209 | BOOTP/DHCP operation |
---|
210 | ==================== |
---|
211 | |
---|
212 | Set up a BOOTP/DHCP server on the network. Set define ``RTEMS USE_BOOT`` in |
---|
213 | ``networkconfig.h``. Run the ``netdemo`` test program. Verify that the target |
---|
214 | system configures itself from the BOOTP/DHCP server and that all the above |
---|
215 | tests succeed. |
---|
216 | |
---|
217 | Stress Tests |
---|
218 | ============ |
---|
219 | |
---|
220 | Once the driver passes the tests described in the previous section it should be |
---|
221 | subjected to conditions which exercise it more thoroughly and which test its |
---|
222 | error handling routines. |
---|
223 | |
---|
224 | Giant packets |
---|
225 | ------------- |
---|
226 | |
---|
227 | - Recompile the driver with ``MAXIMUM_FRAME_SIZE`` set to a smaller value, |
---|
228 | say 514. |
---|
229 | |
---|
230 | - 'Ping' the driver from another workstation and verify that frames larger than |
---|
231 | 514 bytes are correctly rejected. |
---|
232 | |
---|
233 | - Recompile the driver with ``MAXIMUM_FRAME_SIZE`` restored to 1518. |
---|
234 | |
---|
235 | Resource Exhaustion |
---|
236 | ------------------- |
---|
237 | |
---|
238 | - Edit ``networkconfig.h`` so that the driver is configured with just two |
---|
239 | receive and transmit descriptors. |
---|
240 | |
---|
241 | - Compile and run the ``netdemo`` program. |
---|
242 | |
---|
243 | - Verify that the program operates properly and that you can still telnet to |
---|
244 | both the ports. |
---|
245 | |
---|
246 | - Display the driver statistics (Console '``s``' command or telnet 'control-G' |
---|
247 | character) and verify that: |
---|
248 | |
---|
249 | #. The number of transmit interrupts is non-zero. This indicates that all |
---|
250 | transmit descriptors have been in use at some time. |
---|
251 | |
---|
252 | #. The number of missed packets is non-zero. This indicates that all receive |
---|
253 | descriptors have been in use at some time. |
---|
254 | |
---|
255 | Cable Faults |
---|
256 | ------------ |
---|
257 | |
---|
258 | - Run the ``netdemo`` program. |
---|
259 | |
---|
260 | - Issue a '``u``' console command to make the target machine transmit a bunch |
---|
261 | of UDP packets. |
---|
262 | |
---|
263 | - While the packets are being transmitted, disconnect and reconnect the network |
---|
264 | cable. |
---|
265 | |
---|
266 | - Display the network statistics and verify that the driver has detected the |
---|
267 | loss of carrier. |
---|
268 | |
---|
269 | - Verify that you can still telnet to both ports on the target machine. |
---|
270 | |
---|
271 | Throughput |
---|
272 | ---------- |
---|
273 | |
---|
274 | Run the ``ttcp`` network benchmark program. Transfer large amounts of data |
---|
275 | (100's of megabytes) to and from the target system. |
---|
276 | |
---|
277 | The procedure for testing throughput from a host to an RTEMS target is as |
---|
278 | follows: |
---|
279 | |
---|
280 | #. Download and start the ttcp program on the Target. |
---|
281 | |
---|
282 | #. In response to the ``ttcp`` prompt, enter ``-s -r``. The meaning of these |
---|
283 | flags is described in the ``ttcp.1`` manual page found in the ``ttcp_orig`` |
---|
284 | subdirectory. |
---|
285 | |
---|
286 | #. On the host run ``ttcp -s -t <<insert the hostname or IP address of the Target here>>`` |
---|
287 | |
---|
288 | The procedure for testing throughput from an RTEMS target to a Host is as |
---|
289 | follows: |
---|
290 | |
---|
291 | #. On the host run ``ttcp -s -r``. |
---|
292 | |
---|
293 | #. Download and start the ttcp program on the Target. |
---|
294 | |
---|
295 | #. In response to the ``ttcp`` prompt, enter ``-s -t <<insert the hostname or |
---|
296 | IP address of the Target here>>``. You need to type the IP address of the |
---|
297 | host unless your Target is talking to your Domain Name Server. |
---|
298 | |
---|
299 | To change the number of buffers, the buffer size, etc. you just add the extra |
---|
300 | flags to the ``-t`` machine as specified in the ``ttcp.1`` manual page found in |
---|
301 | the ``ttcp_orig`` subdirectory. |
---|