lwIP internals

Native API (RAW) (see also lwip-1.4.1/doc/rawapi.txt)
LwIP IPv4/IPv6 stacks
Available device drivers
LwIP with or without an operating system
Porting For Bare Metal
Porting for an OS

Nios updated port and demo for NiosEDS 11.0 and up (includes LwIP)
Using Lightweight IP with the Nios II Processor Tutorial



The Big eCommerce Conference: Simon Goldschmidt
Facebook: Simon Goldschmidt



Add support for outgoing VLAN tags?
from Simon Goldschmidt
from address@hidden
from Dance, Brian
from web


task #9033 Support IEEE 802.1q tagged frame (VLAN) (Commited: 21.012.2009, Done: 25.08.2009)
task #11620 Add outgoing VLAN PCP support for Ethernet level QoS (Commited: 01.12.2011, Done: 01.12.2011)


patch #7993 Add support for transmitting packets with VLAN headers (Commited: 03.04.2013, Done: 20.02.2014)


 * ETHARP_SUPPORT_VLAN==1: support receiving and sending ethernet packets with
 * VLAN header. See the description of LWIP_HOOK_VLAN_CHECK and
 * LWIP_HOOK_VLAN_SET hooks to check/set VLAN headers.
 * Additionally, you can define ETHARP_VLAN_CHECK to an u16_t VLAN ID to check.
 * If ETHARP_VLAN_CHECK is defined, only VLAN-traffic for this VLAN is accepted.
 * If ETHARP_VLAN_CHECK is not defined, all traffic is accepted.
 * Alternatively, define a function/define ETHARP_VLAN_CHECK_FN(eth_hdr, vlan)
 * that returns 1 to accept a packet or 0 to drop a packet.
#define ETHARP_SUPPORT_VLAN             1

 * LWIP_HOOK_VLAN_CHECK(netif, eth_hdr, vlan_hdr):
 * - called from ethernet_input() if VLAN support is enabled
 * - netif: struct netif on which the packet has been received
 * - eth_hdr: struct eth_hdr of the packet
 * - vlan_hdr: struct eth_vlan_hdr of the packet
 * Return values:
 * - 0: Packet must be dropped.
 * - != 0: Packet must be accepted.

 * LWIP_HOOK_VLAN_SET(netif, eth_hdr, vlan_hdr):
 * - called from etharp_raw() and etharp_send_ip() if VLAN support is enabled
 * - netif: struct netif that the packet will be sent through
 * - eth_hdr: struct eth_hdr of the packet
 * - vlan_hdr: struct eth_vlan_hdr of the packet
 * Return values:
 * - 0: Packet shall not contain VLAN header.
 * - != 0: Packet shall contain VLAN header.
 * Hook can be used to set prio_vid field of vlan_hdr.
  if (type == PP_HTONS(ETHTYPE_VLAN)) {
    struct eth_vlan_hdr *vlan = (struct eth_vlan_hdr*)(((char*)ethhdr) + SIZEOF_ETH_HDR);
    if (p->len <= SIZEOF_ETH_HDR + SIZEOF_VLAN_HDR) {
      /* a packet with only an ethernet/vlan header (or less) is not valid for us */
      goto free_and_return;
#if defined(LWIP_HOOK_VLAN_CHECK) || defined(ETHARP_VLAN_CHECK) || defined(ETHARP_VLAN_CHECK_FN) /* if not, allow all VLANs */
    if (!LWIP_HOOK_VLAN_CHECK(netif, ethhdr, vlan)) {
#elif defined(ETHARP_VLAN_CHECK_FN)
    if (!ETHARP_VLAN_CHECK_FN(ethhdr, vlan)) {
#elif defined(ETHARP_VLAN_CHECK)
    if (VLAN_ID(vlan) != ETHARP_VLAN_CHECK) {
      /* silently ignore this packet: not for our VLAN */
      return ERR_OK;
#endif /* defined(LWIP_HOOK_VLAN_CHECK) || defined(ETHARP_VLAN_CHECK) || defined(ETHARP_VLAN_CHECK_FN) */
    type = vlan->tpid;
    ip_hdr_offset = SIZEOF_ETH_HDR + SIZEOF_VLAN_HDR;

STM32 & FreeRTOS

lwIP replies ping request with reply of an earlier request (packages out off sync)

Nios II


IPv4 (deprecated)


/* This is the aligned version of ip_addr_t,
   used as local variable, on the stack, etc. */
struct ip_addr {
  u32_t addr;

/* This is the packed version of ip_addr_t,
   used in network headers that are itself packed */
struct ip_addr_packed {
  PACK_STRUCT_FIELD(u32_t addr);

 * struct ipaddr2 is used in the definition of the ARP packet format in
 * order to support compilers that don't have structure packing.
struct ip_addr2 {
  PACK_STRUCT_FIELD(u16_t addrw[2]);

/** ip_addr_t uses a struct for convenience only, so that the same defines can
 * operate both on ip_addr_t as well as on ip_addr_p_t. */
typedef struct ip_addr ip_addr_t;
typedef struct ip_addr_packed ip_addr_p_t;
 * This function is called by the network interface device driver when
 * an IP packet is received. The function does the basic checks of the
 * IP header such as packet size being at least larger than the header
 * size etc. If the packet was not destined for us, the packet is
 * forwarded (using ip_forward). The IP checksum is always checked.
 * Finally, the packet is sent to the upper layer protocol input function.
 * @param p the received IP packet (p->payload points to IP header)
 * @param inp the netif on which this packet was received
 * @return ERR_OK if the packet was processed (could return ERR_* if it wasn't
 *         processed, but currently always returns ERR_OK)
ip_input(struct pbuf *p, struct netif *inp)


Neighbor Discovery Protocol (NDP)

/** Router advertisement message header. */
struct ra_header {
  PACK_STRUCT_FIELD(u8_t         type);
  PACK_STRUCT_FIELD(u8_t         code);
  PACK_STRUCT_FIELD(u16_t        chksum);
  PACK_STRUCT_FIELD(u8_t         current_hop_limit);
  PACK_STRUCT_FIELD(u8_t         flags);
  PACK_STRUCT_FIELD(u16_t        router_lifetime);
  PACK_STRUCT_FIELD(u32_t        reachable_time);
  PACK_STRUCT_FIELD(u32_t        retrans_timer);
  /* Options follow. */


#define ND6_PREFIX_FLAG_ON_LINK        (0x80)
#define ND6_PREFIX_FLAG_AUTONOMOUS     (0x40)
#define ND6_PREFIX_FLAG_SITE_PREFIX    (0x10)

struct prefix_option {
  PACK_STRUCT_FIELD(u8_t         type);
  PACK_STRUCT_FIELD(u8_t         length);
  PACK_STRUCT_FIELD(u8_t         prefix_length);
  PACK_STRUCT_FIELD(u8_t         flags);
  PACK_STRUCT_FIELD(u32_t        valid_lifetime);
  PACK_STRUCT_FIELD(u32_t        preferred_lifetime);
  PACK_STRUCT_FIELD(u8_t         reserved2[3]);
  PACK_STRUCT_FIELD(u8_t         site_prefix_length);
  PACK_STRUCT_FIELD(ip6_addr_p_t prefix);

struct lladdr_option {
  PACK_STRUCT_FIELD(u8_t         type);
  PACK_STRUCT_FIELD(u8_t         length);

enum nd6_neighbor_cache_entry_state {
  ND6_NO_ENTRY = 0,

/* Struct for tables. */
struct nd6_neighbor_cache_entry {
  ip6_addr_t           next_hop_address;
  struct netif        *netif;
  u8_t                 lladdr[NETIF_MAX_HWADDR_LEN];
  /** Pointer to queue of pending outgoing packets on this entry. */
  struct nd6_q_entry  *q;
  u8_t                 state;
  u8_t                 isrouter;
  union {
    u32_t              reachable_time;
    u32_t              delay_time;
    u32_t              probes_sent;
    u32_t              stale_time;
  }                    counter;


static void nd6_send_q(s8_t i)
Thread [1] (Suspended)	
	12 nd6_new_onlink_prefix() nd6.c:1401 0x100277c8	
	11 nd6_input() nd6.c:466 0x10024570

Thread [1] (Suspended)	
	12 nd6_new_router() nd6.c:1333 0x10027464	
	11 nd6_input() nd6.c:386 0x1002413c	
	10 icmp6_input() icmp6.c:116 0x1001dd40	
	9 ip6_input() ip6.c:689 0x1001f9b0	
	8 ethernet_input() etharp.c:1465 0x1003da38	
	7 lwip_enet_input() lwip_enet.c:74 0x10015d48	
	6 ptp2_port_receive() ptp2_port.c:315 0x10011f90	
	5 ptp2_port_task_rx() ptp2_port.c:239 0x10011bf8	
	4 ptp2_master_mainloop() ptp2_master.c:142 0x1000d6b4	
	3 main() main.c:73 0x1003dbfc	
	2 alt_main() alt_main.c:154 0x1004f77c	
	1 _start() crt0.S:437 0x10000204	

Ping / ICMP

Is there and ‘ping’ function?
ICMP ping send/receive


RFC 826: An Ethernet Address Resolution Protocol

 * LWIP_ARP==1: Enable ARP functionality.
#ifndef LWIP_ARP
#define LWIP_ARP                        1

 * ARP_TABLE_SIZE: Number of active MAC-IP address pairs cached.
#define ARP_TABLE_SIZE                  10

 * ARP_QUEUEING==1: Multiple outgoing packets are queued during hardware address
 * resolution. By default, only the most recent packet is queued per IP address.
 * This is sufficient for most protocols and mainly reduces TCP connection
 * startup time. Set this to 1 if you know your application sends more than one
 * packet in a row to an IP address that is not in the ARP cache.
#define ARP_QUEUEING                    1

 * ETHARP_TRUST_IP_MAC==1: Incoming IP packets cause the ARP table to be
 * updated with the source MAC and IP addresses supplied in the packet.
 * You may want to disable this if you do not trust LAN peers to have the
 * correct addresses, or as a limited approach to attempt to handle
 * spoofing. If disabled, lwIP will need to make a new ARP request if
 * the peer is not already in the ARP table, adding a little latency.
 * The peer *is* in the ARP table if it requested our address before.
 * Also notice that this slows down input processing of every IP packet!
#define ETHARP_TRUST_IP_MAC             1

 * ETHARP_SUPPORT_VLAN==1: support receiving ethernet packets with VLAN header.
 * Additionally, you can define ETHARP_VLAN_CHECK to an u16_t VLAN ID to check.
 * If ETHARP_VLAN_CHECK is defined, only VLAN-traffic for this VLAN is accepted.
 * If ETHARP_VLAN_CHECK is not defined, all traffic is accepted.
 * Alternatively, define a function/define ETHARP_VLAN_CHECK_FN(eth_hdr, vlan)
 * that returns 1 to accept a packet or 0 to drop a packet.
#define ETHARP_SUPPORT_VLAN             0
/** the ARP message, see RFC 826 ("Packet format") */
struct etharp_hdr {
  PACK_STRUCT_FIELD(u16_t hwtype);
  PACK_STRUCT_FIELD(u16_t proto);
  PACK_STRUCT_FIELD(u8_t  hwlen);
  PACK_STRUCT_FIELD(u8_t  protolen);
  PACK_STRUCT_FIELD(u16_t opcode);
  PACK_STRUCT_FIELD(struct eth_addr shwaddr);
  PACK_STRUCT_FIELD(struct ip_addr2 sipaddr);
  PACK_STRUCT_FIELD(struct eth_addr dhwaddr);
  PACK_STRUCT_FIELD(struct ip_addr2 dipaddr);
 * Update (or insert) a IP/MAC address pair in the ARP cache.
 * If a pending entry is resolved, any queued packets will be sent
 * at this point.
 * @param netif netif related to this entry (used for NETIF_ADDRHINT)
 * @param ipaddr IP address of the inserted ARP entry.
 * @param ethaddr Ethernet address of the inserted ARP entry.
 * @param flags @see definition of ETHARP_FLAG_*
 * @return
 * - ERR_OK Succesfully updated ARP cache.
 * - ERR_MEM If we could not add a new ARP entry when ETHARP_FLAG_TRY_HARD was set.
 * - ERR_ARG Non-unicast address given, those will not appear in ARP cache.
 * @see pbuf_free()
static err_t
etharp_update_arp_entry(struct netif *netif, ip_addr_t *ipaddr, struct eth_addr *ethaddr, u8_t flags)
  /* ARP message directed to us?
      -> add IP address in ARP cache; assume requester wants to talk to us,
         can result in directly sending the queued packets for this host.
     ARP message not directed to us?
      ->  update the source IP address in the cache, if present */
  etharp_update_arp_entry(netif, &sipaddr, &(hdr->shwaddr),
                   for_us ? ETHARP_FLAG_TRY_HARD : ETHARP_FLAG_FIND_ONLY);
Thread [1] (Suspended)	
	10 lwip_enet_low_level_output() lwip_enet.c:131 0x1002e640 [via netif->linkoutput()]
	9 etharp_arp_input() etharp.c:807 0x1002d374	
	8 ethernet_input() etharp.c:1372 0x1002e38c [via netif->input()]
	7 lwip_enet_input() lwip_enet.c:74 0x1002e4d0	
	6 ptp2_port_receive() ptp2_port.c:301 0x10011f48	
	5 ptp2_port_task_rx() ptp2_port.c:214 0x10011bac	
	4 ptp2_master_mainloop() ptp2_master.c:142 0x1000d6f8	
	3 main() main.c:73 0x1002e92c	
	2 alt_main() alt_main.c:154 0x10040340	
	1 _start() crt0.S:437 0x10000204	

Memory Pools – Dynamic pool memory manager

lwIP has dedicated pools for many structures (netconn, protocol control blocks, packet buffers, …). All these pools are managed here.

 * MEM_LIBC_MALLOC==1: Use malloc/free/realloc provided by your C-library
 * instead of the lwip internal allocator. Can save code size if you
 * already use it.
#define MEM_LIBC_MALLOC                 0

* MEMP_MEM_MALLOC==1: Use mem_malloc/mem_free instead of the lwip pool allocator.
* Especially useful with MEM_LIBC_MALLOC but handle with care regarding execution
* speed and usage from interrupts!
#define MEMP_MEM_MALLOC                 0

 * MEMP_SEPARATE_POOLS: if defined to 1, each pool is placed in its own array.
 * This can be used to individually change the location of each pool.
 * Default is one big array for all pools
#define MEMP_SEPARATE_POOLS             0
 * MEM_USE_POOLS==1: Use an alternative to malloc() by allocating from a set
 * of memory pools of various sizes. When mem_malloc is called, an element of
 * the smallest pool that can provide the length needed is returned.
 * To use this, MEMP_USE_CUSTOM_POOLS also has to be enabled.
#define MEM_USE_POOLS                   0

On the fly enum memp_t { MEMP_ARP_QUEUE, […] }

/* Create the list of all memory pools managed by memp. MEMP_MAX represents a NULL pool at the end */
typedef enum {
#define LWIP_MEMPOOL(name,num,size,desc)  MEMP_##name,
#include "lwip/memp_std.h"
} memp_t;

/* it not defines macros, but uses it */
LWIP_MEMPOOL(RAW_PCB,        MEMP_NUM_RAW_PCB,         sizeof(struct raw_pcb),        "RAW_PCB")
LWIP_MEMPOOL(UDP_PCB,        MEMP_NUM_UDP_PCB,         sizeof(struct udp_pcb),        "UDP_PCB")
LWIP_MEMPOOL(TCP_PCB,        MEMP_NUM_TCP_PCB,         sizeof(struct tcp_pcb),        "TCP_PCB")
LWIP_MEMPOOL(TCP_SEG,        MEMP_NUM_TCP_SEG,         sizeof(struct tcp_seg),        "TCP_SEG")
LWIP_MEMPOOL(REASSDATA,      MEMP_NUM_REASSDATA,       sizeof(struct ip_reassdata),   "REASSDATA")
LWIP_MEMPOOL(ARP_QUEUE,      MEMP_NUM_ARP_QUEUE,       sizeof(struct etharp_q_entry), "ARP_QUEUE")
LWIP_MEMPOOL(SYS_TIMEOUT,    MEMP_NUM_SYS_TIMEOUT,     sizeof(struct sys_timeo),      "SYS_TIMEOUT")
 * A list of pools of pbuf's used by LWIP.
 * LWIP_PBUF_MEMPOOL(pool_name, number_elements, pbuf_payload_size, pool_description)
 *     creates a pool name MEMP_pool_name. description is used in stats.c
 *     This allocates enough space for the pbuf struct and a payload.
 *     (Example: pbuf_payload_size=0 allocates only size for the struct)
LWIP_PBUF_MEMPOOL(PBUF,      MEMP_NUM_PBUF,            0,                             "PBUF_REF/ROM")

#if !MEMP_MEM_MALLOC /* don't build if not configured for use in lwipopts.h */

struct memp {
  struct memp *next;

/*====== re-defines LWIP_MEMPOOL each time  ======*/

/** This array holds the first free element of each pool.
 *  Elements form a linked list. */
static struct memp *memp_tab[MEMP_MAX];

/** This array holds the element sizes of each pool. */
static const u16_t memp_sizes[MEMP_MAX] = {
#define LWIP_MEMPOOL(name,num,size,desc)  LWIP_MEM_ALIGN_SIZE(size),
#include "lwip/memp_std.h"

/** This array holds the number of elements in each pool. */
static const u16_t memp_num[MEMP_MAX] = {
#define LWIP_MEMPOOL(name,num,size,desc)  (num),
#include "lwip/memp_std.h"

/** This is the actual memory used by the pools (all pools in one big block). */
static u8_t memp_memory[MEM_ALIGNMENT - 1 
#define LWIP_MEMPOOL(name,num,size,desc) + ( (num) * (MEMP_SIZE + MEMP_ALIGN_SIZE(size) ) )
#include "lwip/memp_std.h"

 * Get an element from a specific pool.
 * @param type the pool to get an element from
 * @return a pointer to the allocated memory or a NULL pointer on error
void *
memp_malloc(memp_t type)

Mutexes and Semaphores

 * SYS_LIGHTWEIGHT_PROT==1: if you want inter-task protection for certain
 * critical regions during buffer allocation, deallocation and memory
 * allocation and deallocation.
#define SYS_LIGHTWEIGHT_PROT            0

 * declare a protection variable. This macro will default to defining a variable of
 * type sys_prot_t. If a particular port needs a different implementation, then
 * this macro may be defined in sys_arch.h.
#define SYS_ARCH_DECL_PROTECT(lev) sys_prot_t lev
 * Perform a "fast" protect. This could be implemented by
 * disabling interrupts for an embedded system or by using a semaphore or
 * mutex. The implementation should allow calling SYS_ARCH_PROTECT when
 * already protected. The old protection level is returned in the variable
 * "lev". This macro will default to calling the sys_arch_protect() function
 * which should be implemented in sys_arch.c. If a particular port needs a
 * different implementation, then this macro may be defined in sys_arch.h
#define SYS_ARCH_PROTECT(lev) lev = sys_arch_protect()
 * Perform a "fast" set of the protection level to "lev". This could be
 * implemented by setting the interrupt level to "lev" within the MACRO or by
 * using a semaphore or mutex.  This macro will default to calling the
 * sys_arch_unprotect() function which should be implemented in
 * sys_arch.c. If a particular port needs a different implementation, then
 * this macro may be defined in sys_arch.h
#define SYS_ARCH_UNPROTECT(lev) sys_arch_unprotect(lev)


#define SYS_ARCH_PROTECT(lev)


Leave a Reply

Your email address will not be published. Required fields are marked *