Chapter 166. Debug and Test

166.1. Debugging

Some explicit lwIP configuration items exist to aid with debugging problems. These, along with some other suggestions, are documented in the sections below.

166.1.1. Asserts

An initial starting point for checking valid operation is to enable lwIP asserts. The CYGDBG_LWIP_ASSERTS option turns on run-time asserts that can usually detect problems before they reach a fatal target/platform exception.

The lwIP asserts are based on the standard eCos assertion support, so will normally stop the code in a busy loop if triggered. Normally when debugging it is usual to set a breakpoint on the entry to the cyg_assert_fail() function so that debugger access to application state can be performed.

166.1.2. Memory Allocations

Run-time validation of the memory pools can be enabled in the lwIP configuration by setting one or more of the following options:

Sanity check memory pools (CYGDBG_LWIP_MEMP_SANITY_CHECK)
If enabled lwIP will perform extra sanity checking of the memory pools every time an item is released.
Memory pool overflow checks (CYGDBG_LWIP_MEMP_OVERFLOW_CHECK)

This configuration option can currently be set to the value 0, 1 or 2.

If set to 0 then the feature is disabled (the default configuration), with the non-zero values enabling code to perform MEMP under-/over-flow checking.

If set to 1 then a buffer boundary check is performed when an item is released.

If set to 2 then the code performs the buffer boundary check on every item, in every pool, every time an allocation or release operation is performed. This, obviously, will be slow. However, it will normally provide quicker detection of buffer problems.

For the non-zero configurations the options CYGDBG_LWIP_MEMP_SANITY_REGION_BEFORE and CYGDBG_LWIP_MEMP_SANITY_REGION_AFTER respectively define the size (in bytes) of the catch areas placed before and after all allocations.

166.1.3. Statistics

The lwIP stack provides support for tracking statistics via enabling the Trafficstatistics CYGDBG_LWIP_STATS option. These statistics have been briefly covered in Section 163.3.1, “Performance”. For debugging the error count (normally the err field of the relevant statistics structure) can be useful in indicating resource issues, some of which will result in the stack failing to operate correctly.

166.1.4. GDB/RedBoot

Some standard platforms may, by default, provide the RedBoot debug monitor, which in turn may be configured to allow remote network GDB debugging connections. It should be noted that a limitation exists where an eCos application configured to use a lwIP Direct driver CANNOT be debugged via such a remote network GDB connection due to interaction between the RedBoot use of a Standard device driver and the application Direct device driver models. Using GDB via a UART or hardware debug connection is not affected.

In practice this is not normally an issue since low-level debugging, when developing for such low resource platforms that require the use of the lwIP Direct device driver, is normally performed via a hardware debug interface (e.g. JTAG).

166.1.5. Host Tools

An invaluable tool to aid debugging of both network protocol stack problems and application level network interaction is WireShark. It can be used to log packets, and to trace connection streams, whilst providing human readable data dumps.

The eCos synthetic ethernet target support can be a useful aid in separating application level networking problems from issues with the under-lying network transport stack (e.g. lwIP). It can usefully be used to debug higher-level network applications in a resource rich environment, before tuning the code for the resource-restricted lwIP target platform.

166.2. Testing

Some test applications are built if the active eCos lwIP configuration is suitable:

  • lwipsnmp
  • lwipsntp
  • lwiperf
  • unitwrap

If the configuration option CYGBLD_NET_LWIP_BUILD_MANUAL_TESTS is enabled then a further set of simple tests are built. Note: The option is disabled by default. These manually executed are just basic verification tests and are not designed to be an exhaustive test of all lwIP or TCP/IP networking features.

For the manual tests frag and udpecho the host tool nc (netcat) can be used to interface with the test. In the following sections any examples given of using the tests assume that the Unit Under Test (UUT) is at the local network IPv4 address The actual local addresses for the UUT should be ascertained and substituted accordingly.


Most of the manual tests are currently limited to accepting IPv4 connections. The exceptions are socket and tcpecho which will accept IPv4 or IPv6 connections.

166.2.1. lwipsnmp

This is a simple test to exercise the SNMP agent when enabled via the CYGFUN_LWIP_SNMP option. It relies on the script being executed on a host system to exercise a set of SNMP operations agsinst the target executing this application.

166.2.2. lwipsntp

This application tests the use of the lwIP SNTP client implementation when enabled via the CYGFUN_LWIP_SNTP option. It initialises the SNTP client code and then waits to receive a valid time.

166.2.3. lwiperf

This test can be used to exercise the iPerf2 server provided by lwIP when it is enabled in the configuration using the CYGFUN_LWIP_LWIPERF option. It requests the test host to exercise a iperf-c against the target executing this application as a simple demonstration of measuring the achievable network bandwidth.

166.2.4. unitwrap

If the eCos lwip configuration meets the requirements (re. memory configuration, TCP options, etc.) for the standard lwIP checkframework unit tests then this test application is built. The application is a wrapper to support the lwIP unit tests and allows verification of some lwIP features.

166.2.5. socket

This is a very simple TCP protocol test using the BSD-alike socket API. The test will listen for two IPv4 or IPV6 connections on port 7. For each connection established the test will continue to echo the data received on the TCP stream until the particular connection is closed.

The nc utility can be used to communicate with the test program.

nc 7

After starting nc the UUT will acknowledge the connection by displaying:

PASS:<Received connection OK>

As this point it will wait for a line of text to be input and completed by pressing the Enter key. Multiple lines of text can be entered, and should be echoed back to indicate that the UUT has received and responded OK. Entering Ctrl-D will terminate the nc connection.

Another execution of nc as above will complete the test.

166.2.6. tcpecho

This is a very simple TCP protocol test. See Section 166.2.5, “socket” for a description of the test, since it has identical requirements to that example.

166.2.7. udpecho

This is a very simple UDP protocol test, listening for two connections on port 7 and echo-ing back the data received.

The nc utility can be used to communicate with the test program.

nc -u 7

After starting nc it will wait for a line of text to be input and completed by pressing the Enter key. The nc will then perform the necessary UDP connection to the specified port, transmit the data and output any reply. Another line of text can then be entered to complete the test. Unlike the tcpecho a single nc execution can be used for the test, since each line transmitted counts as a single UDP connection test.

166.2.8. frag

This is a simple test that should result in fragmented TCP packets being transmitted. The test can be exercised like Section 166.2.7, “udpecho” since it listens for two UDP connections on port 7.

The major difference being that after echoing the received data the UUT will transmit a large amount of data to the host nc.

166.2.9. nc_test_slave

This test provides a client for use with the host side CYGPKG_NET nc_test_master application. The host side test code must be manually built within the packages/net/common/vsn/tests directory.

When the UUT is started it will initially perform some slave performance calculations before it will start listening for connections.

166.2.10. httpd

This is a very simple HTTP daemon that will listen for two HTTP GET connections on port 80. Currently only IPv4 socket connections are listened for. The test when started will display some information on the diagnostic channel, including:

PASS:<Listening on TCP port 80>
INFO:<Will wait for two HTTP connections>

When it is has displayed the Will wait … message the UUT is ready to be accessed from the test host. The following example uses the host tool wget to perform such a page fetch, and can be executed twice to perform the test. e.g.


After the second GET operation the test will exit.

166.2.11. httpd2

This is a slightly more realistic HTTP daemon test, that will execute indefinitely. This test is a useful example of using the raw API, and could form the basis of a simple, lightweight, webserver.

Currently it will only accept IPv4 socket connections on port 80. On startup it will not display any diagnostic output other than the cyg_lwip_netif_print_info( netif_default, diag_printf ) output displaying the default network interface address information.

A standard web browser can be used to access the pages served by the daemon, returning a simple demonstration page as the root document. The test has been designed to be extendible to easily support multiple pages.

166.2.12. lookup

If IPv4 DNS support is configured then this test performs some simple verification using some known lookups against the locally configured DNS address (e.g. obtained via DHCP), and then again using a known fixed DNS server.

166.2.13. sys_timeout

This is a simple stand-alone test of the lwIP internal timeout handling. No external interaction is required.

166.2.14. lwiphttpd

This is a build of the standard lwIP example HTTPD application provided when the option CYGFUN_LWIP_HTTPD is enabled. It provides a static (built-in) web-page.

If the lwIP configuration option CYGFUN_LWIP_MBEDTLS is enabled then the test also provides a TLS daemon (port 443) using a built-in self-signed certificate as a basic example of the lwIP ALTCP TLS support.


For eCos the CYGFUN_LWIP_MBEDTLS option is only available when the CYGFUN_LWIP_ALTCP_TLS option is enabled, in turn controlled by the support for the lwIP ALTCP being enabled by the CYGFUN_LWIP_ALTCP feature. The developer should be aware that you need to provide your own ALTCP wrapper functions if LWIP_ALTCP_TLS is defined but not the CYGPKG_MBEDTLS integration option LWIP_ALTCP_TLS_MBEDTLS.