summaryrefslogtreecommitdiffstats
path: root/networking/testing_the_driver.rst
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-04-11 13:53:58 +1000
committerAmar Takhar <verm@darkbeer.org>2016-05-02 20:51:27 -0400
commitb41203897a7bfc7ab4a446808494e6216eff7c56 (patch)
tree86d36928e7650e679d5bc65d6fdd0d4adc45ac67 /networking/testing_the_driver.rst
parentea0777e4ee35c7a67274771200233efabd2797b0 (diff)
downloadrtems-docs-b41203897a7bfc7ab4a446808494e6216eff7c56.tar.bz2
Clean up and review of Networking User Guide.
Diffstat (limited to 'networking/testing_the_driver.rst')
-rw-r--r--networking/testing_the_driver.rst283
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.