Chapter 141. Tests and Demonstrations

141.1. Loopback tests

By default, only tests which can execute on any target will be built. These therefore do not actually use external network interfaces (though they may configure and initialize them) but are limited to testing via the loopback interface.

ping_lo_test     - ping test of the loopback address
tcp_lo_select    - simple test of select with TCP via loopback
tcp_lo_test      - trivial TCP test via loopback
udp_lo_test      - trivial UDP test via loopback
multi_lo_select  - test of multiple select() calls simultaneously

141.2. Building the Network Tests

To build further network tests, ensure that the configuration option CYGPKG_NET_BUILD_TESTS is set in your build and then make the tests in the usual way. Alternatively (with that option set) use the following command after building the eCos library, if you wish to build only the network tests:

make -C net/common/VERSION/ tests 

This should give test executables in install/tests/net/common/VERSION/tests including the following:

socket_test      - trivial test of socket creation API
mbuf_test        - trivial test of mbuf allocation API
ftp_test         - simple FTP test, connects to “server”
ping_test        - pings “server” and non-existent host to test timeout
dhcp_test        - ping test, but also relinquishes and
                   reacquires DHCP leases periodically
flood            - a flood ping test; use with care
tcp_echo         - data forwarding program for performance test
nc_test_master   - network characterization master
nc_test_slave    - network characterization slave
server_test      - a very simple server example
tftp_client_test - performs a tftp get and put from/to “server”
tftp_server_test - runs a tftp server for a short while
set_mac_address  - set MAC address(es) of interfaces in NVRAM
bridge           - contributed network bridge code
nc6_test_master  - IPv4/IPv6 network characterization master
nc6_test_slave   - IPv4/IPv6 network characterization slave
ga_server_test   - a very simple IPv4/IPv6 server example

141.3. Standalone Tests

socket_test      - trivial test of socket creation API
mbuf_test        - trivial test of mbuf allocation API

These two do not communicate over the net; they just perform simple API tests then exit.

ftp_test         - simple FTP test, connects to “server”

This test initializes the interface(s) then connects to the FTP server on the “server” machine for for each active interface in turn, confirms that the connection was successful, disconnects and exits. This tests interworking with the server.

ping_test        - pings “server” and non-existent host to test timeout

This test initializes the interface(s) then pings the server machine in the standard way, then pings address “32 up” from the server in the expectation that there is no machine there. This confirms that the successful ping is not a false positive, and tests the receive timeout. If there is such a machine, of course the 2nd set of pings succeeds, confirming that we can talk to a machine not previously mentioned by configuration or by bootp. It then does the same thing on the other interface, eth1.

If IPv6 is enabled, the program will also ping to the address it last received a router advertisement from. Also a ping will be made to that address plus 32, in a similar way the the IPv4 case.

dhcp_test        - ping test, but also manipulates DHCP leases

This test is very similar to the ping test, but in addition, provided the network package is not configured to do this automatically, it manually relinquishes and reclaims DHCP leases for all available interfaces. This tests the external API to DHCP. See section below describing this.

flood            - a flood ping test; use with care

This test performs pings on all interfaces as quickly as possible, and only prints status information periodically. Flood pinging is bad for network performance; so do not use this test on general purpose networks unless protected by a switch.

141.4. Performance Test

tcp_echo         - data forwarding program for performance test

tcp_echo is one part of the standard performance test we use. The other parts are host programs tcp_source and tcp_sink. To make these (under your HOST system) cd to the tests source directory in the eCos repository and type “make -f make.host” - this should build tcp_source and tcp_sink.

The host program “tcp_source” sends data to the target. On the target, “tcp_echo” sends it onwards to “tcp_sink” running on your host. So the target must receive and send on all the data that tcp_source sends it; the time taken for this is measured and the data rate is calculated.

To invoke the test, first start tcp_echo on the target board and wait for it to become quiescent - it will report work to calibrate a CPU load which can be used to simulate real operating conditions for the stack.

Then on your host machine, in one terminal window, invoke tcp_sink giving it the IP address (or hostname) of one interface of the target board. For example “tcp_sink 10.130.39.66”. tcp_echo on the target will print something like “SINK connection from 10.130.39.13:1143” when tcp_sink is correctly invoked.

Next, in another host terminal window, invoke tcp_source, giving it the IP address (or hostname) of an interface of the target board, and optionally a background load to apply to the target while the test runs. For example, “tcp_source 194.130.39.66” to run the test with no additional target CPU load, or “tcp_source 194.130.39.66 85” to load it up to 85% used. The target load must be a multiple of 5. tcp_echo on the target will print something like “SOURCE connection from 194.130.39.13:1144” when tcp_source is correctly invoked.

You can connect tcp_sink to one target interface and tcp_source to another, or both to the same interface. Similarly, you can run tcp_sink and tcp_source on the same host machine or different ones. TCP/IP and ARP look after them finding one another, as intended.

nc_test_master   - network characterization master
nc_test_slave    - network characterization slave

These tests talk to each other to measure network performance. They can each run on either a test target or a host computer given some customization to your local environment. As provided, nc_test_slave must run on the test target, and nc_test_master must be run on a host computer, and be given the test target's IP address or hostname.

The tests print network performance for various packet sizes over UDP and TCP, versus various additional CPU loads on the target.

The programs below are additional forms which support both IPv4 and IPv6 addressing:

        nc6_test_slave
        nc6_test_master

141.5. Interactive Tests

server_test - a very simple server example

This test simply awaits a connection on port 7734 and after accepting a connection, gets a packet (with a timeout of a few seconds) and prints it.

The connection is then closed. We then loop to await the next connection, and so on. To use it, telnet to the target on port 7734 then type something (quickly!)

% telnet 172.16.19.171 7734
Hello target board

and the test program will print something like:

connection from 172.16.19.13:3369
buf = "Hello target board"
ga_server_test - another very simple server example

This is a variation on the ga_server_test test with the difference being that it uses the getaddrinfo function to set up its addresses. On a system with IPv6 enabled, it will listen on port 7734 for a TCP connection via either IPv4 or IPv6.

tftp_client_test - performs a tftp get and put from/to “server”

This is only partially interactive. You need to set things up on the “server” in order for this to work, and you will need to look at the server afterwards to confirm that all was well.

For each interface in turn, this test attempts to read by tftp from the server, a file called tftp_get and prints the status and contents it read (if any). It then writes the same data to a file called tftp_put on the same server.

In order for this to succeed, both files must already exist. The TFTP protocol does not require that a WRQ request _create_ a file, just that it can write it. The TFTP server on Linux certainly will only allow writes to an existing file, given the appropriate permission. Thus, you need to have these files in place, with proper permission, before running the test.

The conventional place for the tftp server to operate in LINUX is /tftpboot/; you will likely need root privileges to create files there. The data contents of tftp_get can be anything you like, but anything very large will waste lots of time printing it on the test’s stdout, and anything above 32kB will cause a buffer overflow and unpredictable failure.

Creating an empty tftp_put file (eg. by copying /dev/null to it) is neatest. So before the test you should have something like:

-rw-rw-rw- 1 root        1076 May  1 11:39 tftp_get
-rw-rw-rw- 1 root           0 May  1 15:52 tftp_put 

note that both files have public permissions wide open. After running the test, tftp_put should be a copy of tftp_get.

-rw-rw-rw-  1 root       1076 May  1 11:39 tftp_get
-rw-rw-rw-  1 root       1076 May  1 15:52 tftp_put

If the configuration contains IPv6 support, the test program will also use IPv6. It will attempt to put/get the files listed above from the address it last received a routers solicit from.

tftp_server_test - runs a tftp server for a short while

This test is truly interactive, in that you can use a standard tftp application to get and put files from the server, during the 5 minutes that it runs. The dummy filesystem which underlies the server initially contains one file, called “uu” which contains part of a familiar text and some padding. It also accommodates creation of 3 further files of up to 1Mb in size and names of up to 256 bytes. Exceeding these limits will cause a buffer overflow and unpredictable failure.

The dummy filesystem is an implementation of the generic API which allows a true filesystem to be attached to the tftp server in the network stack.

We have been testing the tftp server by running the test on the target board, then using two different host computers connecting to the different target interfaces, putting a file from each, getting the “uu” file, and getting the file from the other computer. This verifies that data is preserved during the transfer as well as interworking with standard tftp applications.

141.6. Maintenance Tools

set_mac_address - set MAC address(es) of interfaces in NVRAM

This program makes an example ioctl() call SIOCSIFHWADDR “Socket IO Set InterFace HardWare ADDRess” to set the MAC address on targets where this is supported and enabled in the configuration. You must edit the source to choose a MAC address and further edit it to allow this very dangerous operation. Not all ethernet drivers support this operation, because most ethernet hardware does not support it — or it comes pre-set from the factory. Do not use this program.