source: rtems-docs/networking/testing_the_driver.rst @ 489740f

4.115am
Last change on this file since 489740f was 489740f, checked in by Chris Johns <chrisj@…>, on 05/20/16 at 02:47:09

Set SPDX License Identifier in each source file.

  • Property mode set to 100644
File size: 11.2 KB
Line 
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
8Testing the Driver
9##################
10
11Preliminary Setup
12=================
13
14The 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
24During early debug, you should consider putting the target, workstation, and
25snooper 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
37Debug Output
38============
39
40There are a number of sources of debug output that can be enabled to aid in
41tracing 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
71Monitor Commands
72================
73
74There are a number of command available in the shell / monitor to aid in
75tracing 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
173Driver basic operation
174======================
175
176The 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
209BOOTP/DHCP operation
210====================
211
212Set 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
214system configures itself from the BOOTP/DHCP server and that all the above
215tests succeed.
216
217Stress Tests
218============
219
220Once the driver passes the tests described in the previous section it should be
221subjected to conditions which exercise it more thoroughly and which test its
222error handling routines.
223
224Giant 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
235Resource 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
255Cable 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
271Throughput
272----------
273
274Run the ``ttcp`` network benchmark program.  Transfer large amounts of data
275(100's of megabytes) to and from the target system.
276
277The procedure for testing throughput from a host to an RTEMS target is as
278follows:
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
288The procedure for testing throughput from an RTEMS target to a Host is as
289follows:
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
299To change the number of buffers, the buffer size, etc. you just add the extra
300flags to the ``-t`` machine as specified in the ``ttcp.1`` manual page found in
301the ``ttcp_orig`` subdirectory.
Note: See TracBrowser for help on using the repository browser.