diff options
Diffstat (limited to 'networking/testing_the_driver.rst')
| -rw-r--r-- | networking/testing_the_driver.rst | 283 |
1 files changed, 133 insertions, 150 deletions
diff --git a/networking/testing_the_driver.rst b/networking/testing_the_driver.rst index 9a064e7..24134fb 100644 --- a/networking/testing_the_driver.rst +++ b/networking/testing_the_driver.rst @@ -1,3 +1,8 @@ +.. COMMENT: Text Written by Jake Janovetz +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Testing the Driver ################## @@ -6,89 +11,84 @@ Preliminary Setup The network used to test the driver should include at least: -- The hardware on which the driver is to run. - It makes testing much easier if you can run a debugger to control - the operation of the target machine. +- The hardware on which the driver is to run. It makes testing much easier if + you can run a debugger to control the operation of the target machine. -- An Ethernet network analyzer or a workstation with an - 'Ethernet snoop' program such as ``ethersnoop`` or``tcpdump``. +- An Ethernet network analyzer or a workstation with an 'Ethernet snoop' + program such as ``ethersnoop`` or ``tcpdump``. - A workstation. -During early debug, you should consider putting the target, workstation, -and snooper on a small network by themselves. This offers a few -advantages: +During early debug, you should consider putting the target, workstation, and +snooper on a small network by themselves. This offers a few advantages: -- There is less traffic to look at on the snooper and for the target - to process while bringing the driver up. +- There is less traffic to look at on the snooper and for the target to process + while bringing the driver up. -- Any serious errors will impact only your small network not a building - or campus network. You want to avoid causing any unnecessary problems. +- Any serious errors will impact only your small network not a building or + campus network. You want to avoid causing any unnecessary problems. - Test traffic is easier to repeatably generate. -- Performance measurements are not impacted by other systems on - the network. +- Performance measurements are not impacted by other systems on the network. Debug Output ============ -There are a number of sources of debug output that can be enabled -to aid in tracing the behavior of the network stack. The following -is a list of them: +There are a number of sources of debug output that can be enabled to aid in +tracing the behavior of the network stack. The following is a list of them: - mbuf activity - There are commented out calls to ``printf`` in the file``sys/mbuf.h`` in the network stack code. Uncommenting - these lines results in output when mbuf's are allocated - and freed. This is very useful for finding memory leaks. + There are commented out calls to ``printf`` in the file ``sys/mbuf.h`` in the + network stack code. Uncommenting these lines results in output when mbuf's + are allocated and freed. This is very useful for finding memory leaks. - TX and RX queuing - There are commented out calls to ``printf`` in the file``net/if.h`` in the network stack code. Uncommenting - these lines results in output when packets are placed - on or removed from one of the transmit or receive packet - queues. These queues can be viewed as the boundary line - between a device driver and the network stack. If the - network stack is enqueuing packets to be transmitted that - the device driver is not dequeuing, then that is indicative - of a problem in the transmit side of the device driver. - Conversely, if the device driver is enqueueing packets - as it receives them (via a call to ``ether_input``) and - they are not being dequeued by the network stack, - then there is a problem. This situation would likely indicate - that the network server task is not running. + There are commented out calls to ``printf`` in the file ``net/if.h`` in the + network stack code. Uncommenting these lines results in output when packets + are placed on or removed from one of the transmit or receive packet queues. + These queues can be viewed as the boundary line between a device driver and + the network stack. If the network stack is enqueuing packets to be + transmitted that the device driver is not dequeuing, then that is indicative + of a problem in the transmit side of the device driver. Conversely, if the + device driver is enqueueing packets as it receives them (via a call to + ``ether_input``) and they are not being dequeued by the network stack, then + there is a problem. This situation would likely indicate that the network + server task is not running. - TCP state transitions - In the unlikely event that one would actually want to see - TCP state transitions, the ``TCPDEBUG`` macro can be defined - in the file ``opt_tcpdebug.h``. This results in the routine``tcp_trace()`` being called by the network stack and - the state transitions logged into the ``tcp_debug`` data - structure. If the variable ``tcpconsdebug`` in the file``netinet/tcp_debug.c`` is set to 1, then the state transitions - will also be printed to the console. + + In the unlikely event that one would actually want to see TCP state + transitions, the ``TCPDEBUG`` macro can be defined in the file + ``opt_tcpdebug.h``. This results in the routine ``tcp_trace()`` being called + by the network stack and the state transitions logged into the ``tcp_debug`` + data structure. If the variable ``tcpconsdebug`` in the file + ``netinet/tcp_debug.c`` is set to ``1``, then the state transitions will also + be printed to the console. Monitor Commands ================ -There are a number of command available in the shell / monitor -to aid in tracing the behavior of the network stack. The following -is a list of them: +There are a number of command available in the shell / monitor to aid in +tracing the behavior of the network stack. The following is a list of them: - ``inet`` - This command shows the current routing information for the TCP/IP stack. Following is an - example showing the output of this command. + This command shows the current routing information for the TCP/IP + stack. Following is an example showing the output of this command. - .. code:: c + .. code-block:: shell Destination Gateway/Mask/Hw Flags Refs Use Expire Interface 10.0.0.0 255.0.0.0 U 0 0 17 smc1 127.0.0.1 127.0.0.1 UH 0 0 0 lo0 - In this example, there is only one network interface with an IP address of 10.8.1.1. This - link is currently not up. - Two routes that are shown are the default routes for the Ethernet interface (10.0.0.0) and the - loopback interface (127.0.0.1). - Since the stack comes from BSD, this command is very similar to the netstat command. For more - details on the network routing please look the following - URL: (http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-routing.html) + In this example, there is only one network interface with an IP address of + 10.8.1.1. This link is currently not up. Two routes that are shown are the + default routes for the Ethernet interface (10.0.0.0) and the loopback + interface (127.0.0.1). Since the stack comes from BSD, this command is very + similar to the netstat command. For more details on the network routing + please look the following URL: + (http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-routing.html) For a quick reference to the flags, see the table below: '``U``' @@ -98,43 +98,44 @@ is a list of them: Host: The route destination is a single host. '``G``' - Gateway: Send anything for this destination on to this remote system, which - will figure out from there where to send it. + Gateway: Send anything for this destination on to this remote system, + which will figure out from there where to send it. '``S``' - Static: This route was configured manually, not automatically generated by the - system. + Static: This route was configured manually, not automatically generated + by the system. '``C``' - Clone: Generates a new route based upon this route for machines we connect - to. This type of route is normally used for local networks. + Clone: Generates a new route based upon this route for machines we + connect to. This type of route is normally used for local networks. '``W``' - WasCloned: Indicated a route that was auto-configured based upon a local area - network (Clone) route. + WasCloned: Indicated a route that was auto-configured based upon a local + area network (Clone) route. '``L``' Link: Route involves references to Ethernet hardware. - ``mbuf`` + This command shows the current MBUF statistics. An example of the command is + shown below: - This command shows the current MBUF statistics. An example of the command is shown below: - - .. code:: c + .. code-block:: shell ************ MBUF STATISTICS \************ mbufs:4096 clusters: 256 free: 241 drops: 0 waits: 0 drains: 0 free:4080 data:16 header:0 socket:0 - pcb:0 rtable:0 htable:0 atable:0 - soname:0 soopts:0 ftable:0 rights:0 - ifaddr:0 control:0 oobdata:0 + pcb:0 rtable:0 htable:0 atable:0 + soname:0 soopts:0 ftable:0 rights:0 + ifaddr:0 control:0 oobdata:0 - ``if`` + 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: - 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: - - .. code:: c + .. code-block:: shell ************ INTERFACE STATISTICS \************ \***** smc1 \***** @@ -144,11 +145,11 @@ is a list of them: Send queue limit:50 length:0 Dropped:0 SMC91C111 RTEMS driver A0.01 11/03/2002 Ian Caddy (ianc@microsol.iinet.net.au) Rx Interrupts:0 Not First:0 Not Last:0 - Giant:0 Runt:0 Non-octet:0 - Bad CRC:0 Overrun:0 Collision:0 + Giant:0 Runt:0 Non-octet:0 + Bad CRC:0 Overrun:0 Collision:0 Tx Interrupts:2 Deferred:0 Missed Hearbeat:0 - No Carrier:0 Retransmit Limit:0 Late Collision:0 - Underrun:0 Raw output wait:0 Coalesced:0 + No Carrier:0 Retransmit Limit:0 Late Collision:0 + Underrun:0 Raw output wait:0 Coalesced:0 Coalesce failed:0 Retries:0 \***** lo0 \***** Address:127.0.0.1 Net mask:255.0.0.0 @@ -176,15 +177,12 @@ The network demonstration program ``netdemo`` may be used for these tests. - Start with ``RTEMS_USE_BOOTP`` not defined. -- Edit ``networkconfig.h`` to configure the driver - with an - explicit Ethernet and Internet address and with reception of - broadcast packets disabled: - Verify that the program continues to run once the driver has been attached. +- Edit ``networkconfig.h`` to configure the driver with an explicit Ethernet + and Internet address and with reception of broadcast packets disabled: Verify + that the program continues to run once the driver has been attached. -- Issue a '``u``' command to send UDP - packets to the 'discard' port. - Verify that the packets appear on the network. +- Issue a '``u``' command to send UDP packets to the 'discard' port. Verify + that the packets appear on the network. - Issue a '``s``' command to print the network and driver statistics. @@ -193,124 +191,109 @@ The network demonstration program ``netdemo`` may be used for these tests. - On that same workstation try to 'ping' the target system. Verify that the ICMP echo request and reply packets appear on the net. -- Remove the static route to the target system. - Modify ``networkconfig.h`` to attach the driver - with reception of broadcast packets enabled. - Try to 'ping' the target system again. - Verify that ARP request/reply and ICMP echo request/reply packets appear - on the net. +- Remove the static route to the target system. Modify ``networkconfig.h`` to + attach the driver with reception of broadcast packets enabled. Try to 'ping' + the target system again. Verify that ARP request/reply and ICMP echo + request/reply packets appear on the net. -- Issue a '``t``' command to send TCP - packets to the 'discard' port. - Verify that the packets appear on the network. +- Issue a '``t``' command to send TCP packets to the 'discard' port. Verify + that the packets appear on the network. - Issue a '``s``' command to print the network and driver statistics. -- Verify that you can telnet to ports 24742 - and 24743 on the target system from one or more - workstations on your network. +- Verify that you can telnet to ports 24742 and 24743 on the target system from + one or more workstations on your network. BOOTP/DHCP operation ==================== -Set up a BOOTP/DHCP server on the network. -Set define ``RTEMS USE_BOOT`` in ``networkconfig.h``. -Run the ``netdemo`` test program. -Verify that the target system configures itself from the BOOTP/DHCP server and -that all the above tests succeed. +Set up a BOOTP/DHCP server on the network. Set define ``RTEMS USE_BOOT`` in +``networkconfig.h``. Run the ``netdemo`` test program. Verify that the target +system configures itself from the BOOTP/DHCP server and that all the above +tests succeed. Stress Tests ============ -Once the driver passes the tests described in the previous section it should -be subjected to conditions which exercise it more -thoroughly and which test its error handling routines. +Once the driver passes the tests described in the previous section it should be +subjected to conditions which exercise it more thoroughly and which test its +error handling routines. Giant packets ------------- -- Recompile the driver with ``MAXIMUM_FRAME_SIZE`` set to - a smaller value, say 514. +- Recompile the driver with ``MAXIMUM_FRAME_SIZE`` set to a smaller value, + say 514. -- 'Ping' the driver from another workstation and verify - that frames larger than 514 bytes are correctly rejected. +- 'Ping' the driver from another workstation and verify that frames larger than + 514 bytes are correctly rejected. - Recompile the driver with ``MAXIMUM_FRAME_SIZE`` restored to 1518. Resource Exhaustion ------------------- -- Edit ``networkconfig.h`` - so that the driver is configured with just two receive and transmit descriptors. +- Edit ``networkconfig.h`` so that the driver is configured with just two + receive and transmit descriptors. - Compile and run the ``netdemo`` program. -- Verify that the program operates properly and that you can - still telnet to both the ports. +- Verify that the program operates properly and that you can still telnet to + both the ports. -- Display the driver statistics (Console '``s``' command or telnet - 'control-G' character) and verify that: +- Display the driver statistics (Console '``s``' command or telnet 'control-G' + character) and verify that: - # The number of transmit interrupts is non-zero. - This indicates that all transmit descriptors have been in use at some time. + #. The number of transmit interrupts is non-zero. This indicates that all + transmit descriptors have been in use at some time. - # The number of missed packets is non-zero. - This indicates that all receive descriptors have been in use at some time. + #. The number of missed packets is non-zero. This indicates that all receive + descriptors have been in use at some time. Cable Faults ------------ - Run the ``netdemo`` program. -- Issue a '``u``' console command to make the target machine transmit - a bunch of UDP packets. +- Issue a '``u``' console command to make the target machine transmit a bunch + of UDP packets. -- While the packets are being transmitted, disconnect and reconnect the - network cable. +- While the packets are being transmitted, disconnect and reconnect the network + cable. -- Display the network statistics and verify that the driver has - detected the loss of carrier. +- Display the network statistics and verify that the driver has detected the + loss of carrier. - Verify that you can still telnet to both ports on the target machine. Throughput ---------- -Run the ``ttcp`` network benchmark program. -Transfer large amounts of data (100's of megabytes) to and from the target -system. - -The procedure for testing throughput from a host to an RTEMS target -is as follows: +Run the ``ttcp`` network benchmark program. Transfer large amounts of data +(100's of megabytes) to and from the target system. -# Download and start the ttcp program on the Target. +The procedure for testing throughput from a host to an RTEMS target is as +follows: -# In response to the ``ttcp`` prompt, enter ``-s -r``. The - meaning of these flags is described in the ``ttcp.1`` manual page - found in the ``ttcp_orig`` subdirectory. + #. Download and start the ttcp program on the Target. -# On the host run ``ttcp -s -t <<insert the hostname or IP address of the Target here>>`` + #. In response to the ``ttcp`` prompt, enter ``-s -r``. The meaning of these + flags is described in the ``ttcp.1`` manual page found in the ``ttcp_orig`` + subdirectory. -The procedure for testing throughput from an RTEMS target -to a Host is as follows: + #. On the host run ``ttcp -s -t <<insert the hostname or IP address of the Target here>>`` -# On the host run ``ttcp -s -r``. +The procedure for testing throughput from an RTEMS target to a Host is as +follows: -# Download and start the ttcp program on the Target. + #. On the host run ``ttcp -s -r``. -# In response to the ``ttcp`` prompt, enter ``-s -t <<insert the hostname or IP address of the Target here>>``. You need to type the - IP address of the host unless your Target is talking to your Domain Name - Server. + #. Download and start the ttcp program on the Target. -To change the number of buffers, the buffer size, etc. you just add the -extra flags to the ``-t`` machine as specified in the ``ttcp.1`` -manual page found in the ``ttcp_orig`` subdirectory. - -.. COMMENT: Text Written by Jake Janovetz - -.. COMMENT: COPYRIGHT (c) 1988-2002. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. + #. In response to the ``ttcp`` prompt, enter ``-s -t <<insert the hostname or + IP address of the Target here>>``. You need to type the IP address of the + host unless your Target is talking to your Domain Name Server. +To change the number of buffers, the buffer size, etc. you just add the extra +flags to the ``-t`` machine as specified in the ``ttcp.1`` manual page found in +the ``ttcp_orig`` subdirectory. |