lwIP Wiki

There are a couple of different methods typically used for debugging lwIP, printf-style and external debugging.

External Debugger[]

Probably the most familiar method is to fire up a debugger and start single-stepping through the code. However, since lwIP is typically used on embedded targets you can't just light up a debugger and start debugging. There has to be some way to communicate with the embedded target. Under normal circumstances there is a network stack running and gdbserver, or some other debug server daemon, running that enables the debugger to talk to the target debug daemon.

Since the network stack itself is being debugged, the debugger obviously won't be able to use it to talk to the target, so some other route needs to be used. There are a couple of different ways to get around this. Probably the best, in terms of performance, is to run either another stable instance of lwIP, or another network stack, next to the lwIP stack under development. This can be convoluted to setup, depending on the particular architecture of the target, but is doable and is useful for working through problems when doing the initial port. Once the stack is up and running, the debugger is less useful since most of the problems you will run into will be induced by interdependencies with other external components, and there will usually be a time related component to the problem, which eliminates the debugger as a useful tool for tracking the problem down. That's where we get old-school with the built-in printf style debugging.

printf/built-in debugging[]

lwIP is developed with some nice support for enabling various debug print options. The debug options are enabled at build time with the use of various xxx_DEBUG options, which are enumerated in the opt.h file. Override the defaults (no debugging) in opts.h by adding in lwipopts.h:

#define LWIP_DEBUG 1

#define xxx_DEBUG LWIP_DBG_ON

for the subsystem xxx of your choice (e.g., IP_DEBUG, DHCP_DEBUG, ....)

Configuring debug message types[]

lwIP supports different types of debug messages. Symbolic constant LWIP_DBG_TYPES_ON can be modified in lwipopts.h file for the purposes to enable or disable some kind of messages. There are 4 values that can be ORed and assigned to LWIP_DBG_TYPES_ON:

/* flag for LWIP_DEBUGF indicating a tracing message
 * (to follow program flow)
#define LWIP_DBG_TRACE         0x40U

/* flag for LWIP_DEBUGF indicating a state debug message
 * (to follow module states)
#define LWIP_DBG_STATE         0x20U

/* flag for LWIP_DEBUGF indicating newly added code,
 * not thoroughly tested yet
#define LWIP_DBG_FRESH         0x10U

/* flag for LWIP_DEBUGF to halt after printing
 * this debug message
#define LWIP_DBG_HALT          0x08U