Brief Introduction to LwIP stack in MCUXpresso SDK

[#1]

LwIP is a small independent implementations of the TCP/IP protocol suite that has been initially developed by Adam Dunkels . The focus of the lwIP TCP/IP implementation is to reduce resource usage while still having a full scale TCP. This makes lwIP suitable for use in embedded systems with tens of kilobytes of free RAM and room for around 40 kilobytes of code ROM. 

Currently LwIP 2.1.2 is ported to Kinetis and I.MX RT families in MCUXpresso SDK 2.6 .

Features:

LwIP comes with the following protocols:

IPv4 and IPv6, including packet forwarding over multiple network interfaces.

ICMP for network maintenance and debugging

IGMP for multicast traffic management

MLD (Multicast listener discovery for IPv6). 

ND (Neighbor discovery and stateless address autoconfiguration for IPv6)

DHCP and DHCPv6.

UDP (User Datagram Protocol)

TCP (Transmission Control Protocol)

Raw/native API for enhanced performance

Optional Berkeley -  like socket API.

TLS: optional layered TCP for nearly transparent TLS for any TCP-based protocol

PPPoS and PPPoE

DNS (Domain name resolver incl. mDNS)

6LoWPAN

Organization of the LwIP stack

Let’s take SDK_2.6.1_EVKB-IMXRT1050 for example,

LwIP code in under SDK_2.6.1_EVKB-IMXRT1050\middleware\lwip

Port: This folder includes the adapter code which can make the LwIP stack run on the bare metal and FreeRTOS.

Enet_ethernetif.c/h: Adapt the LwIP stack to the underlying MCUXpresso SDK ethernet driver, provides ethernet interfaces , like  phy init and  ethernetif_input.

cc.c/h: provide typedefs, compiler hints for packing and platform specific diagnostic output.

Perf.h: architecture specific performance measurement, current the definitions is NULL, reserve for future use.

Src: This folder includes the latest stable LwIP 2.1.2 source code which can be downloaded from below link download.savannah.gnu.org/releases/lwip/

--api: netconn and socket API files

--core: LwIP core files

--include: LwIP include files

--netif:  network interface files

LwIP APIs overview

LwIP provides three application programming interfaces (API) for programmers to use for communication with the TCP/IP code:

Raw APIs:   Non thread-safe APIs, callback style for maximum performance and minimum memory footprint. Program execution is driven by callbacks functions, which are then invoked by the lwIP core when activity related to that application occurs. A particular application may register to be notified via a callback function for events such as incoming data available, outgoing data sent, error notifications, poll timer expiration, connection closed, etc. An application can provide a callback function to perform processing for any or all of these events.

Sequential-style APIs:    blocking functions. More overhead, but can be called from any thread except TCPIP thread. 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).

Socket API: BSD-style socket API.  The socket API is a compatibility API for existing applications, currently it is built on top of the sequential API. It is meant to provide all functions needed to run socket API applications running on other platforms.

TCP Raw API

	API function	Description
TCP connection setup	tcp_new()	Creates a new TCP PCB
	tcp_bind()	Binds a TCP PCB to a local IP address and port
	tcp_listen()	Starts the listening process on the TCP PCB.
	tcp_accept()	Assigns a callback function that will be called when a new TCP connection arrives.
	tcp_connect()	Used to connect to a remote TCP host.
Sending TCP data	tcp_write()	Queues up data to be sent.
	tcp_output()	Forces queued data to be sent
	tcp_sent()	Assigns a callback function that will be called when sent data is acknowledged by the remote host.
Receiving TCP data	tcp_recv()	Sets the callback function that will be called when new data arrives.
	tcp_recved()	Must be called when the application has processed the incoming data packet (for TCP window management).
Application polling	tcp_poll()	Assigns a callback functions that will be called periodically. It can be used by the application to check if there is remaining application data that needs to be sent or if there are connections that need to be closed.
Closing and aborting connections	tcp_close()	Closes a TCP connection with a remote host.
	tcp_abort()	Aborts a TCP connection.
	tcp_err()	Assigns a callback function for handling connections aborted by the lwIP due to errors (such as memory shortage errors).

UDP Raw API

API	Description
udp_bind	Binds a UDP PCB with a local IP address and port.
udp_new	Creates a new UDP PCB.
udp_send	Sends UDP data.
udp_recv	Specifies a callback function which is called when a datagram is received
udp_remove	Removes and de-allocates a UDP PCB.
udp_connect	Sets up a UDP PCB remote IP address and port
udp_disconnect	Removes a UDP PCB remote IP and port.

Netconn API

netconn_new	Creates a new connection
netconn_listen	Sets a TCP connection into a listening mode
netconn_write	Sends data on a connected TCP netconn
netconn_accept	Accepts an incoming connection on a listening TCP connection
netconn_close	Closes a TCP connection without deleting it.
netconn_send	Sends data to the currently connected remote IP/port (not applicable for TCP connections).
netconn_bind	Binds a connection to a local IP address and port.
netconn_recv	Receives data from a netconn.
netconn_connect	Connects to a remote IP address and port.
…

Socket API

Macro	API	description
accept	lwip_accept	Accepts a new connection on a socket
bind	lwip_bind	Binds a socket to an IP address and port
shutdown	lwip_shutdown
getpeername	lwip_getpeername
getsockname	lwip_getsockname
setsockopt	lwip_setsockopt
closesocket	lwip_close
connect	lwip_connect	Connects a socket to a remote host IP address and port.
listen	lwip_listen	Listens for socket connections
recv	lwip_recv
recvmsg	lwip_recvmsg
recvfrom	lwip_recvfrom
send	lwip_send
sendmsg	lwip_sendmsg
sendto	lwip_sendto
socket	lwip_socket	Creates an new socket.
poll	lwip_poll
ioctlsocket	lwip_ioctl
inet_ntop	lwip_inet_ntop
inet_pton	lwip_inet_pton
read	lwip_read	Reads data from a socket
readv	lwip_readv
write	lwip_write	Writes data on a socket
writev	lwip_writev
close	lwip_close	Closes a socket (socket is deleted).
fcntl	lwip_fcntl
ioctl	lwip_ioctl

LwIP Configure

Configuration file is placed in application source folder: Lwipopts.h:

Lwipopts.h is a user file that you can use to fully configure LwIP and all of it’s modules. You do not need to define every option that LwIP provides; if you do not define an option, a default value will be used. Therefore, your lwipopts.h provides a way to override much of the behavior of LwIP.

LwIP Demos in MCUXpresso SDK

MCUXpresso SDK comes with lots of demos that use different API sets.

Name	Description
Lwip_tcpecho	a TCP echo demo on the lwIP TCP/IP stack with bare metal KSDK or FreeRTOS. The demo uses the TCP protocol and acts as an echo server
Lwip_udpecho	a UDP echo demo on the lwIP TCP/IP stack with bare metal KSDK or FreeRTOS, which uses the UDP protocol and acts as an echo server.
Lwip_ping	a Ping Demo on the lwIP TCP/IP stack which using the ICMP protocol
lwip_nghttp2cli_mbedTLS	an NGHTTP2 client set up on lwIP TCP/IP and the MbedTLS stack with FreeRTOS
lwip_mqtt	MQTT client connecting to MQTT broker via unsecured socket
lwip_iperf	check your bandwidth using the network performance measurement IPerf application on a PC as a client or a server
lwip_httpsrv	an HTTPServer on the lwIP TCP/IP stack with bare metal SDK or FreeRTOS
lwip_httpscli_mbedTLS	an HTTPS client set up on lwIP TCP/IP and the MbedTLS stack with FreeRTOS
lwip_dhcp_usb	a DHCP and ping demo on the lwIP TCP/IP and USB stack
lwip_dhcp	a DHCP client and prints the status as it is progressing