lwIP Wiki

This guide should help you to get a quick reply to your problem (issue) during developing application using the LWIP. It will be focused more or less required information included in your question instead of chosen language, politeness, etc. How to ask in the smart way is aptly explained on this site Smart questions

However this guide does not guarantee you will receive reply in any case but it increases a chance to get the right one.

Where to ask?[]

The LWIP provides a mailing list LWIP mailing list This list discusses general topics about using lwIP in your applications. Subscribing is easy via the web interface.

The following paragraphs describe a recommended content of your questions. Where possible, an example is shown to justify or give a reason why this part should be included.

Problem description[]

This is the alpha and omega of every question. You should be capable of somehow describing the problem, behaviour when you think that there is a problem, instead of “It does not work”. But it is not always possible of course. You have to specify a situation when the error occurs based on your observation. Be as talkative as possible to the topic. A brief description of the long description should turn up in the email subject.

Subject: Non-blocking socket does not block

Problem description: I am trying to use the socket in a non-blocking mode but when I call lwip_recv the function blocks and does not return until some data is received from the socket.

Even this relatively accurate description does not help you so much without further information.

Lwip version[]

The used LWIP version helps to focus on previous version which could contain a bug described in the question. General rule of thumb in open-source is to use the latest released (intended in 1.4.x family) version because most of users will be familiar with it. If you are forced to use a different version, always mention it. From my point of view that writing version without further details means the stable releases. For example the version 1.4.1 is a stable tagged in the source repository. If you are using source code from code repository, write also the commit related to.

Toolchain brand and version[]

In fact it does not matter what toolchain you are using. The IAR, GCC or MPLAB C, all of them should generate a correct binary code at the end. With this information you can preliminary filter out answers not exactly related to the error. Here is an example how can the toolchain version help.

Subject: LWIP causes stack overflow

Problem description: I am using LWIP 1.4.1 and when any packet is sent the exception stack overflow is reported caused by the tcpip task (thread). I have set the stack size to 1024. I am not using any LWIP functionality, it fails after a while the LWIP is initialized, my code is not executed at all. RTOS FreeRTOS v8.0.0 Microcontroller NXP LPC1788 Toolchain arm-none-eabi-gcc, gcc version 4.8.3 20140228 (release) [ARM/embedded-4_8-branch revision 208322] (GNU Tools for ARM Embedded Processors) …

Let's stop here to to inspect the problem from someones point of view who is willing to answer. We know that the asking user is using RTOS, GCC, the stack size is enough for safe operation of the tcpip task (I am using FreeRTOS, gcc, NXP LPC1788 and the stack size is 1024, everything works ok). I also know that the user has to use some own code because of the device driver is not delivered with the LWIP. Maybe there could be the error. Because of gcc and version 4.8.3 I would suggest to recompile the code using “-fstack-usage”. Without specifying the compiler and version the reply would be useless.

Later on (a hypothetical answer): Hi, I have recompiled the source code and discovered that the function low_level_output uses an array on stack to complete the frame. It took about 2x1514 bytes of stack. I have rewritten the output and it works fine.

Author of a device driver[]

The device driver or better Ethernet network interface drivers for LWIP is the only demanding component you have to write by yourselves (except some initialization calling). This driver makes a contraction between the LWIP and the Ethernet peripheral. Most microcontroller vendors provide a source code of the driver for particular microcontroller. Some of them are written well, some badly. You should definitely write what kind of driver you are using. In case of your own consider to attach it to the email. Microcontroller type Although it could seem that this is not relevant information (I am using the C language after all) but the opposite is true. Many problems arise from misunderstanding the microcontroller's Ethernet peripheral architecture. As a nice example follows the NXP LPC1788. The Ethernet peripheral has automatic frame transmission and reception with scatter-gather DMA. The DMA can access only some parts of the memory area, peripheral SRAM and Static/Dynamic Memory Controller (LPC1788 User Manual Fig 2. LPC178x/177x block diagram, CPU and buses ). Thus, sending data from on-chip FLASH memory (pbuf allocated with PBUF_REF) will fail if the device driver does not support packet buffering. Some microcontrollers support also numerous functions to support fault detection, such as access to undefined memory, division by zero, etc with the fault source locating. You can receive answer that will point you out such feature at least.


The information about using RTOS is occasionally very significant and valuable. Most of error when using RTOS is using one socket in multiple threads (tasks). Let's take example. Your application is running fine but sometimes crashes inside the kernel under certain circumstances that you describes. You are using the RTOS FreeRTOS v8.0.0, NXP LPC1788 microcontroller. You have also attached the source code of the Ethernet network interface driver.

Later on (a hypothetical answer): Hi, on the line XY in your driver, you assign very high priority to your Ethernet ISR. Check this site http://www.freertos.org/RTOS-Cortex-M3-M4.html.

More later: Hi, thank you for pointing me out. The priority of kernel was lower than the Ethernet ISR and I was calling FreeRTOS functions inside my ISR.

Affected source code[]

This activity is sometimes the most difficult part in your question. The affected source code helps to to reproduce the errors. It allows others to run the code on theirs platforms on which they are familiar. The result can be a discovered bug instead of your failure. But there are many pitfalls. It is not always possible, either the code is not public accessible or from other reasons, to locate the area of the error in project. The worst cases are sometimes errors, it works but sometimes it hangs exclusively when debugger is not connected.

Enabling debug, assert and stats[]

By enabling debug is not intended to compile the code with a toolchain debug switch enabled but printing debug messages inside the LWIP. The debug functionality is very extensive and covers all parts of LWIP. A searching in LWIP source code returns over 800 occurrences of LWIP_DEBUGF macro. You can even track the program flow of LWIP internals. A short introduction to LWIP debug is on this site: http://lwip.wikia.com/wiki/Debugging_lwIP. The log is a viable attachment of your email. However be aware that the log can be very talkative and printing over serial port in heavy network traffic environment can slow down the performance. To prevent this, use a separate network with small traffic if you can reproduce the error. The assert functionality should be used during developing phase. Usually if the LWIP_ASSERT or LWIP_ERROR expression evaluates to 0 a serious error has occurred and you have not chance to recover from this situation. It will happen very rare and denotes that the fault is mostly on your side. Such thing must appear in your question. The LWIP also supports of gathering statistical data during the LWIP runtime. You should enable it in the lwipopts.h. The statistical data, in the time of error, should be printed and attached in your question as well.

Network analyzer[]

Such tools are a Swiss knife in analyzing and debugging network communication. E.g. the Wireshark [1] is a network protocol analyzer. Does not afraid to use it. If you encounter a problem related to network communication, the dump (or log) of communication should appear in your message. Be carefull to attach a saved full communication. Logs as the following from tcpdump usually does not help.

16:28:00.508046 IP pc.domain.com.domain > zemanhpq.domain.com.48546: 46513* 1/3/3 PTR dimmpc9.domain.com.
16:28:00.508160 IP zemanhpq.domain.com.19912 > pc.domain.com.domain: 48849+ PTR? (43)
16:28:00.508804 IP pc.domain.com.domain > zemanhpq.domain.com.19912: 48849* 1/3/3 PTR zemanhpq.domain.com. (196)

Time synchronization[]

Do not forget to keep time synchronized between computer and your embedded device, at least second resolution. The worst scenario is a different timing in log messages from your device and the PC.


This guide summarizes required parts of your questions to help you to get a quick reply to your problem (issue) during developing.