source: rtems-docs/networking/testing_the_driver.rst @ fb72a00

5am
Last change on this file since fb72a00 was e52906b, checked in by Sebastian Huber <sebastian.huber@…>, on 01/09/19 at 15:14:06

Simplify SPDX-License-Identifier comment

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