Chapter 155. Debug and Test

Table of Contents


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 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.

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.


The lwIP stack provides support for tracking statistics via enabling the “Traffic statistics” CYGDBG_LWIP_STATS option. These statistics have been briefly covered in the Section called Performance in Chapter 152. 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).

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.

Documentation license for this page: eCosPro License