[ca49bfd] | 1 | Testing the Driver |
---|
| 2 | ################## |
---|
| 3 | |
---|
| 4 | Preliminary Setup |
---|
| 5 | ================= |
---|
| 6 | |
---|
| 7 | The 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 |
---|
[d389819] | 14 | 'Ethernet snoop' program such as ``ethersnoop`` or``tcpdump``. |
---|
[ca49bfd] | 15 | |
---|
| 16 | - A workstation. |
---|
| 17 | |
---|
| 18 | During early debug, you should consider putting the target, workstation, |
---|
| 19 | and snooper on a small network by themselves. This offers a few |
---|
| 20 | advantages: |
---|
| 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 | |
---|
| 33 | Debug Output |
---|
| 34 | ============ |
---|
| 35 | |
---|
| 36 | There are a number of sources of debug output that can be enabled |
---|
| 37 | to aid in tracing the behavior of the network stack. The following |
---|
| 38 | is 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 |
---|
[d389819] | 42 | these lines results in output when mbuf's are allocated |
---|
[ca49bfd] | 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 | |
---|
| 68 | Monitor Commands |
---|
| 69 | ================ |
---|
| 70 | |
---|
| 71 | There are a number of command available in the shell / monitor |
---|
| 72 | to aid in tracing the behavior of the network stack. The following |
---|
| 73 | is 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 | |
---|
[d389819] | 94 | '``U``' |
---|
[ca49bfd] | 95 | Up: The route is active. |
---|
| 96 | |
---|
[d389819] | 97 | '``H``' |
---|
[ca49bfd] | 98 | Host: The route destination is a single host. |
---|
| 99 | |
---|
[d389819] | 100 | '``G``' |
---|
[ca49bfd] | 101 | Gateway: Send anything for this destination on to this remote system, which |
---|
| 102 | will figure out from there where to send it. |
---|
| 103 | |
---|
[d389819] | 104 | '``S``' |
---|
[ca49bfd] | 105 | Static: This route was configured manually, not automatically generated by the |
---|
| 106 | system. |
---|
| 107 | |
---|
[d389819] | 108 | '``C``' |
---|
[ca49bfd] | 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 | |
---|
[d389819] | 112 | '``W``' |
---|
[ca49bfd] | 113 | WasCloned: Indicated a route that was auto-configured based upon a local area |
---|
| 114 | network (Clone) route. |
---|
| 115 | |
---|
[d389819] | 116 | '``L``' |
---|
[ca49bfd] | 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 | |
---|
| 170 | Driver basic operation |
---|
| 171 | ====================== |
---|
| 172 | |
---|
| 173 | The 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 | |
---|
[d389819] | 185 | - Issue a '``u``' command to send UDP |
---|
| 186 | packets to the 'discard' port. |
---|
[ca49bfd] | 187 | Verify that the packets appear on the network. |
---|
| 188 | |
---|
[d389819] | 189 | - Issue a '``s``' command to print the network and driver statistics. |
---|
[ca49bfd] | 190 | |
---|
| 191 | - On a workstation, add a static route to the target system. |
---|
| 192 | |
---|
[d389819] | 193 | - On that same workstation try to 'ping' the target system. |
---|
[ca49bfd] | 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. |
---|
[d389819] | 199 | Try to 'ping' the target system again. |
---|
[ca49bfd] | 200 | Verify that ARP request/reply and ICMP echo request/reply packets appear |
---|
| 201 | on the net. |
---|
| 202 | |
---|
[d389819] | 203 | - Issue a '``t``' command to send TCP |
---|
| 204 | packets to the 'discard' port. |
---|
[ca49bfd] | 205 | Verify that the packets appear on the network. |
---|
| 206 | |
---|
[d389819] | 207 | - Issue a '``s``' command to print the network and driver statistics. |
---|
[ca49bfd] | 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 | |
---|
| 213 | BOOTP/DHCP operation |
---|
| 214 | ==================== |
---|
| 215 | |
---|
| 216 | Set up a BOOTP/DHCP server on the network. |
---|
| 217 | Set define ``RTEMS USE_BOOT`` in ``networkconfig.h``. |
---|
| 218 | Run the ``netdemo`` test program. |
---|
| 219 | Verify that the target system configures itself from the BOOTP/DHCP server and |
---|
| 220 | that all the above tests succeed. |
---|
| 221 | |
---|
| 222 | Stress Tests |
---|
| 223 | ============ |
---|
| 224 | |
---|
| 225 | Once the driver passes the tests described in the previous section it should |
---|
| 226 | be subjected to conditions which exercise it more |
---|
| 227 | thoroughly and which test its error handling routines. |
---|
| 228 | |
---|
| 229 | Giant packets |
---|
| 230 | ------------- |
---|
| 231 | |
---|
| 232 | - Recompile the driver with ``MAXIMUM_FRAME_SIZE`` set to |
---|
| 233 | a smaller value, say 514. |
---|
| 234 | |
---|
[d389819] | 235 | - 'Ping' the driver from another workstation and verify |
---|
[ca49bfd] | 236 | that frames larger than 514 bytes are correctly rejected. |
---|
| 237 | |
---|
| 238 | - Recompile the driver with ``MAXIMUM_FRAME_SIZE`` restored to 1518. |
---|
| 239 | |
---|
| 240 | Resource 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 | |
---|
[d389819] | 251 | - Display the driver statistics (Console '``s``' command or telnet |
---|
| 252 | 'control-G' character) and verify that: |
---|
[ca49bfd] | 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 | |
---|
| 260 | Cable Faults |
---|
| 261 | ------------ |
---|
| 262 | |
---|
| 263 | - Run the ``netdemo`` program. |
---|
| 264 | |
---|
[d389819] | 265 | - Issue a '``u``' console command to make the target machine transmit |
---|
[ca49bfd] | 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 | |
---|
| 276 | Throughput |
---|
| 277 | ---------- |
---|
| 278 | |
---|
| 279 | Run the ``ttcp`` network benchmark program. |
---|
[d389819] | 280 | Transfer large amounts of data (100's of megabytes) to and from the target |
---|
[ca49bfd] | 281 | system. |
---|
| 282 | |
---|
| 283 | The procedure for testing throughput from a host to an RTEMS target |
---|
| 284 | is 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 | |
---|
| 294 | The procedure for testing throughput from an RTEMS target |
---|
| 295 | to 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 | |
---|
| 305 | To change the number of buffers, the buffer size, etc. you just add the |
---|
| 306 | extra flags to the ``-t`` machine as specified in the ``ttcp.1`` |
---|
| 307 | manual 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 | |
---|