Chapter 166. Debug and Test
Table of Contents
- 166.1. Debugging
- 166.2. Testing
Some explicit lwIP configuration items exist to aid with debugging problems. These, along with some other suggestions, are documented in the sections below.
An initial starting point for checking valid operation is to enable lwIP
CYGDBG_LWIP_ASSERTS option turns on run-time
asserts that can usually detect problems before they reach a fatal
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
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
- If enabled lwIP will perform extra sanity checking of the memory pools every time an item is released.
Memory pool overflow checks
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_AFTERrespectively define the size (in bytes) of the catch areas placed before and after all allocations.
The lwIP stack provides support for tracking statistics via enabling the
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.
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.
Some test applications are built if the active eCos lwIP configuration is suitable:
If the configuration
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
192.168.1.200. 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.
This is a simple test to exercise the SNMP agent when enabled via
CYGFUN_LWIP_SNMP option. It relies on
hostsnmp.sh script being executed on a host
system to exercise a set of SNMP operations agsinst the target
executing this application.
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
This test can be used to exercise the iPerf2 server provided by lwIP
when it is enabled in the configuration using
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.
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.
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 192.168.1.200 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.
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.
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 192.168.1.200 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.
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.
This test provides a client for use with the host
application. The host side test code must be manually built within
When the UUT is started it will initially perform some slave performance calculations before it will start listening for connections.
This is a very simple HTTP daemon that will listen for two
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.
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
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.
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.
This is a simple stand-alone test of the lwIP internal timeout handling. No external interaction is required.
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
For eCos the
|2023-08-15||LWIP Documentation Notices|