- Note: Version 1.3.0 has been finalized and released.
Please refer to the CHANGELOG for a complete list of all changes made in version 1.3.0. The file netif/ethernetif.c
provides a "good practice" example of an ethernet interface driver written for the 1.3.0 code base. The following are some particular notes and gotchas that you should be aware of if you are updating your code from 1.2.0 to 1.3.0. Bear in mind that these notes only cover the differences between 1.2.0 and 1.3.0.
- ARP
- New
LWIP_ARP
option in lwipopts.h. ARP can now be disabled completely. - New
NETIF_FLAG_ETHARP
flag for Ethernet netifs. - New
ETHARP_TRUST_IP_MAC
option in lwipopts.h. Enable this to allow any incoming IP packet to update the ARP table. - New
LWIP_NETIF_HWADDRHINT
option in lwipopts.h. Enable this to allow each pcb (i.e. connection) to maintain a cache pointing into the ARP table, instead of having to scan the whole ARP table each time. ARP_QUEUEING
option in lwipopts.h. Previous problems with this option have been fixed.- The
netif_set_up
function now generates a "gratuitous ARP" when the netif is brought up. Your driver should (probably) no longer need to do this. etharp.c
now requires a MAC address to be 6 bytes since our ARP is currently only used with Ethernet.- You should no longer call
etharp_init
in your port's initilization sequence if you usetcpip.c
, because this call is done intcpip_init
function.
- New
- IP Fragmentation
- New
IP_FRAG_USES_STATIC_BUF
option in lwipopts.h. In 1.2.0 and earlier, lwIP always used a static buffer to split packets into fragments, but now it is possible to disable this, and instead pbufs are allocated and referenced for each fragment in order to send the fragmented packet data.
- New
- UDP Lite
- New
LWIP_UDPLITE
option in lwipopts.h. Enable UDP Lite support for all API layers.
- New
- ICMP
- New
LWIP_ICMP
option in lwipopts.h. Enable/disable ICMP support. As with many options in lwIP, disabling this is not RFC compliant, but may not be useful depending on your application.
- New
- IGMP
- New
LWIP_IGMP
option in lwipopts.h. Enable IGMP support for all API layers (IP_ADD_MEMBERSHIP, IP_DROP_MEMBERSHIP, IP_MULTICAST_TTL, and IP_MULTICAST_IF). A newIGMP_STATS
option enables specific statistics. You have to set theNETIF_FLAG_IGMP
flag for any netifs which should process IGMP messages. You also have to set MEMP_NUM_IGMP_GROUP large enough to support all needed IGMP groups.
- New
- SNMP
- The default SNMP ports are now configurable at build time (using the
SNMP_IN_PORT
and/orSNMP_TRAP_PORT
defines in lwipopts.h). - New
NETIF_INIT_SNMP()
macro to help SNMP initialization (seeethernetif.c
for a sample). - You can define a
SNMP_GET_SYSUPTIME
macro in your lwipopts.h or your port to provide the system uptime information for MIB-II only when the module needs it. You can also usesnmp_add_sysuptime
to increase the uptime in large amounts, avoiding the need for a timer to increase the "sysuptime" every 10ms.
- The default SNMP ports are now configurable at build time (using the
- DHCP
- New
LWIP_NETIF_HOSTNAME
option in lwipopts.h. Enable this to initialize ahostname
field in the netif, which DHCP can then use and pass to the DHCP server to register a client hostname. You can also choose to use it forsnmp_set_sysname
.
- New
- AUTOIP
- New
LWIP_AUTOIP
option in lwipopts.h. Enable AUTOIP support with or without DHCP cooperation mode (LWIP_DHCP_AUTOIP_COOP
). - The random part for AUTOIP is done by the
LWIP_AUTOIP_RAND
macro. But you can redefine it in your lwipopts.h if you want to use therand()
function from the C runtime.
- New
- Memory Management
- New
MEM_USE_POOLS
option in lwipopts.h. Enable to use memp module to avoid fragmentation problems. Need to defineMEM_POOL_NUM_1/4
pool size, andMEM_POOL_SIZE_1/4
bytes size, in lwipopts.h). (FIXME: This isn't right. what option is meant here? -Jifl) - New
MEM_LIBC_MALLOC
option in lwipopts.h. Enable to use C runtime malloc in the place ofmem.c
. - New
MEMP_OVERFLOW_CHECK
option in lwipopts.h. Enable to add runtime checks for memory overflow (this is recommended during development). - New
MEMCPY/SMEMCPY
option in lwipopts.h. Enable to use different memory copy functions for normal (MEMCPY
) and small (SMEMCPY
) copies in place of the C runtimememcpy
function. - New
MEMP_NUM_TCPIP_MSG_API
andMEMP_NUM_TCPIP_MSG_INPKT
replace olderMEMP_NUM_TCPIP_MSG
.
- New
- System
- New
sys_mbox_tryfetch
function should be implemented in yoursys_arch.c
. This must not block on a fetch from an mbox (seesys_arch.txt
). ReturnSYS_MBOX_EMPTY
if no message in the mbox.sys_arch_mbox_tryfetch
can be implemented as a function-like macro by the port insys_arch.h
if desired. - New parameters for
sys_thread_new
function:name
, andstacksize
. For this last parameter, since it's system dependant, you can define xxx_THREAD_STACKSIZE macro in your lwipopts.h.
- New
- Network interfaces
- The order of the argument list for
etharp_output
has been changed to match the order fornetif->output
. Please verify that your driver uses the right order if your driver uses ARP. - Both ARP and IP incoming packets are now passed to the
tcpip_input
function. This means that the payload should point to theethhdr
). - There are new callback features on netifs:
LWIP_NETIF_STATUS_CALLBACK
sets a callback function to invoke when the netif status changes. For example, you can now get a callback when DHCP acquires a new IP address.LWIP_NETIF_LINK_CALLBACK
enables a callback that drivers should now call when the physical link status changes.
- New
NETIF_FLAG_ETHARP
flag for Ethernet netifs. - New
NETIF_FLAG_IGMP
flag for IGMP netifs. - You should set
NETIF_FLAG_LINK_UP
by default for your netifs to be compatible for future uses. - Thread-safe functions to add/remove netif in list, and to start/stop dhcp, provided via
LWIP_NETIF_API
in netifapi.c. - New
LWIP_LOOPIF_MULTITHREADING
should be enabled if you usetcpip.c
and the loopback interface (inloopif.c
) together. - New
PPPOE_SUPPORT
option, to enable PPP over Ethernet support.
- The order of the argument list for
- Raw API
- A new
tcp_output_nagle
macro is available intcp.h
to allow raw API users to easily use the Nagle algorithm. - New
pbuf_copy_partial
function is now available for raw api users.
- A new
- Sockets/Netconn API
- Ports need to call
lwip_socket_init()
now for socket layer initialization (integrated inlwip_init
). - Implementation of
netconn_sendto
function for netconn layer. - Implementation of
MSG_PEEK
flag forlwip_recv/recvfrom
functions. - Implementation of
SO_NO_CHECK
option for UDP sockets to disable UDP checksum generation on transmit. - Implementation of UDP lite for sockets layer (use
IPPROTO_UDPLITE
forprotocol
inlwip_socket
call, and use optionsUDPLITE_SEND_CSCOV/UDPLITE_RECV_CSCOV
to define checksum coverage). - New
LWIP_TCP_KEEPALIVE
option in lwipopts.h. If enabled, it allows use of new socket/netconn options forTCP_KEEPIDLE/TCP_KEEPINTVL/TCP_KEEPCNT
- New
LWIP_SO_RCVTIMEO
option in lwipopts.h. If enabled, it allows socket/netconn receive with timeout operations usingSO_RCVTIMEO
- New
LWIP_POSIX_SOCKETS_IO_NAMES
option in lwipopts.h to enable/disable POSIX-like defines names to avoid collision with some OS functions. - New
LWIP_SOCKET
&LWIP_NETCONN
options in lwipopts.h. Enable to reduce footprint in some cases when these APIs are not used. - Improvement of
lwip_recv
to bypass internal netbuf boundaries in onelwip_recv
call. - VERY IMPORTANT: There is an API breakage for
netconn_addr()
, since its parameters list has now changed. Your compiler should report an error if your application callsnetconn_addr()
with the old form of arguments, so it should not fail silently.
- Ports need to call
- Other
- New files to add to your makefile/project (if necessary):
init.c, netbuf.c, igmp.c, autoip.c, ppp_oe.c
- New
lwip_init()
function to initialize all modules. This function in directly called bytcpip_init()
.lwip_init()
includes some sanity checks of user-configurable values (at build time and runtime). - New
LWIP_STATS_LARGE
option, which can be enabled to get 32-bit statistics (instead of 16 bit) - New
LWIP_UNUSED_ARG
macro to avoid warnings at build time. You can override it in yourcc.h
if the default version is insufficient. - Some macros have been renamed to avoid some name collisions with some OS macros:
MEM_ALIGN
inLWIP_MEM_ALIGN
andMEM_ALIGN_SIZE
inLWIP_MEM_ALIGN_SIZE
. Most of the debug macros have also been renamed:DBG_LEVEL_OFF
toLWIP_DBG_LEVEL_OFF
,DBG_ON
toLWIP_DBG_ON
, etc... - New
LWIP_ERROR
macro in debug.h. This macro can be overriden in yourcc.h
file to define what should be done when a fatal error is encountered. You can choose whether or not to enable this in your production release - it has lower overhead than other debug assertions and checks. - You should remove some obsolete definitions from your lwipopts.h file, including
MEMP_NUM_API_MSG, SYS_STATS, RAW_STATS
, etc... (compare with currentopt.h
). - Some limited sanity checking of user-configurable values is done in
init.c
. It is good practice to only rebuildinit.c
when you change your lwipopts.h file.
- New files to add to your makefile/project (if necessary):