lwIP Wiki

lwIP provides three Application Program's Interfaces (APIs) for programs to use for communication with the TCP/IP code:

  • low-level "core" / "callback" or "raw" API. This is the only API available when not using an OS.
  • two higher-level "sequential" APIs:

The sequential API provides a way for ordinary, sequential, programs to use the lwIP stack. It is quite similar to the BSD socket API. The model of execution is based on the blocking open-read-write-close paradigm. Since the TCP/IP stack is event based by nature, the TCP/IP code and the application program must reside in different execution contexts (threads).

You have to be careful when mixing raw and sequential APIs: raw API functions really only may be called from the main tcpip_thread. Also, registering the callbacks (or initializing a pcb) must be done in that context (e.g. at startup time in tcpip_init_callback or at runtime using tcpip_callback).

Some more facts on the APIs to help you to decide which one to use in your application:

  • netconn- and raw-API are lwIP-only: code written in these APIs isn't portable to be re-used with other stacks
  • the socket API in contrast is targeted at portability with other posix OSes/stacks at the cost of lower throughput
  • socket- and netconn-API are sequential APIs that require threading (one thread for the application that uses the API, one thread for the stack to handle timers, incoming packets, etc.)
  • the raw API uses a callback mechanism (e.g. your application's callback is called when new data arrives). If you are used to program in a sequential way, this may be harder to implement.
  • the raw API gives the best performance since it does not require thread-changes
  • raw- and netconn-API support zero-copy both for TX and RX (although DMA-enabled MACs can prevent zero-copy-RX)