source: rtems-docs/networking/testing_the_driver.rst @ 735de5f

4.115
Last change on this file since 735de5f was ca49bfd, checked in by Amar Takhar <verm@…>, on 01/16/16 at 23:26:00

Split document.

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