4.5.3.1. lwIP User’s Guide¶

4.5.3.1.1.1. Enet LLD-based lwIP Network Interface Driver¶

Enet LLD based lwIP network interface driver has been integrated into PDK starting in Processor SDK 8.0 release. This driver enables lwIP TCP/IP stack on FreeRTOS for CPSW peripherals (such as CPSW_2G, CPSW_5G and CPSW_9G) and ICSSG MAC peripheral.

lwIP network interface driver plays an equivalent role to the NIMU adaptation layer in TI NDK stack, so often times in this document, lwIP network interface driver will be referred to as lwIP adaptation layer to convey that similarity, as readers may be familiar with TI NDK stack supported in previous SDK releases.

The diagram below shows a layered view of the relevant components in the lwIP integration. The lwIP network interface driver (shown as lwipif in the digram) sits on top of Enet LLD, using Enet’s DMA APIs to build a lwIP network driver layer that acts as a glue between Enet LLD and stack, which seamlessly supports the Ethernet peripherals natively supported by Enet LLD.

As shown in the diagram, an Enet LLD example application is provided as part of the SDK. This example application is based on lwIP contrib’s example located at lwip-contrib/examples/example_app/test.c, so it enables lwIP contrib’s applications such as TCP echo, UDP echo and lwIP iperf apps. The Enet LLD lwip example can be found at: <pdk>/packages/ti/drv/enet/examples/enet_lwip_example.

4.5.3.1.1.2. Inter-core lwIP Virtual Network Interface Driver¶

Starting with SDK 8.1, the Enet LLD includes an inter-core virtual Ethernet driver. The virtual Ethernet driver uses a software based shared memory packet transport which is integrated with lwIP stack to allow TCP/IP communication between cores.

The diagram below shows a layered view of the inter-core virtual Ethernet driver. At the bottom is the inter-core layer which provides a shared memory based packet transport. This packet transport is implented using lock-less circular queues and requires no synchronization between the sender and receiver cores. A dedicated pair of TX and RX queues are used between each pair of particpating cores to provide a full duplex communication channel.

Sitting above the packet transport, the inter-core lwIP interface layer (shown as lwipific in the digram) acts as the adaptation layer between the lwIP stack and the shared memory packet transport. This adaptation layer implements the primitives needed by the inter-core lwIP network interface (netif) to send and receive Ethernet packets using the shared memory transport.

Finally, the lwIP stack sits on top of the lwIP interface layer and allows cores to use standard TCP/IP protocols to communicate with each other without using the CPSW_nG switch.

4.5.3.1.1.3. Directory Structure¶

4.5.3.1.1.4. PHY Management¶

Enet LLD supports independent PHY drivers, which gives the ability to enable different PHY models in the same system and/or configure them with different parameters (i.e. auto-negotiation or manual mode, auto-negotiation advertise capabilities, etc).

Each PHY has its own state machine in the driver in order to handle the lifecycle of each Ethernet PHY independently. The state machine runs every time that the application calls Enet_periodicTick() function. Application can query the link status of any PHY using ENET_PER_IOCTL_IS_PORT_LINK_UP IOCTL command. Please refer to the Ethernet PHY Integration Guide in PDK API Guide for further information about Enet LLD PHY.

The PHY configuration is not in the scope of the lwIP driver, but the link status query is. Enet LLD provides a hook for application to register the function that lwIP-to-Enet layer should call periodically to query for link status: LwipifEnetAppIf_IsPhyLinkedCbFxn. This allows Enet lwIP driver to remain agnostic of PHY specific status query mechanism.

4.5.3.1.2.1. FreeRTOS Port¶

TI SDK FreeRTOS port includes implementation of OS services abstraction layer (OSAL) which is used by most drivers.

lwIP needs basic OS services as outlined in the table below. For these, we leverage the lwIP contrib’s FreeRTOS binding for required OS services.

Enet LLD’s FreeRTOS port can be located at <pdk>/packages/ti/drv/enet/lwipif/ports/freertos/sys_arch.c.

The following table summarizes the mapping of lwIP port functions to FreeRTOS.

Note that lwIP is supported only on FreeRTOS.

4.5.3.1.2.2. Initialization Sequence¶

The sequence diagram below shows the most important functions involved during the initialization of the lwIP stack of an application that enables DHCP client.

1. The stack initialization begins when the application calls tcpip_init() functions and passes an initialization function which lwIP will call once it’s done with the tcpip_thread initialization.
2. The application must add the Enet LLD network interface to lwIP list of network interfaces (netifs in lwIP parlance) by calling netif_add(), which takes the interface initialization function which is called LWIPIF_LWIP_init() in Enet LLD.
3. lwIP adaptation layer delegates the TX and RX DMA channel allocation and initialization to the application as the application is best fit to determine the intended channel and its parameters. This will be covered in the Opening DMA channels section.
4. The application can designate one of the registered network interfaces as the default network interface, this is then used by lwIP to route packets when the right interface cannot be found.
   • Note: For the sake of simplicity, netif_add() and netif_set_default() are shown as being explicitly called by the application in the initialization sequence diagram, but application can call init_default_netif() which in turn will call those two functions internally, making Enet LLD-based interface as the default netif.
5. The application should register a function that will be called when interface is brought up or down via netif_set_status_callback(). Application can use this callback to notify the user about the interface status change.
6. Bring up the Enet LLD interface by calling netif_set_up() with default netif pointer.
7. Application can call dhcp_start() to start the DHCP negotiation.

4.5.3.1.2.3. Opening DMA channels¶

The DMA channels opening process is delegated to the application in order to keep the lwIP adaptation layer agnostic of DMA-specific paramters, such as channel number or channel parameters (i.e. descriptor count, cache configuration, etc).

Applications using Enet LLD’s lwIP network driver must implement the following functions:

void LwipifEnetAppCb_getHandle(LwipifEnetAppIf_GetHandleInArgs *inArgs,
                               LwipifEnetAppIf_GetHandleOutArgs *outArgs)

void LwipifEnetAppCb_releaseHandle(LwipifEnetAppIf_ReleaseHandleInfo *releaseInfo)

lwIP adaptation layer will pass the intended number of packets to allocate, callback function to be called when packet is received or transmitted, etc., via inArgs of LwipifEnetAppCb_getHandle(). Application must open a TX and RX channel with the requested parameters and return the channel handles via outArgs.

Similarly, when the adaptation layer is being shutdown, it will call LwipifEnetAppCb_releaseHandle() which application must implement and close the DMA channels opened in LwipifEnetAppCb_getHandle().

4.5.3.1.2.4. lwIP Configuration¶

#define LWIP_DEBUG               1

#define MEM_DEBUG                LWIP_DBG_ON
#define MEMP_DEBUG               LWIP_DBG_ON
#define PBUF_DEBUG               LWIP_DBG_ON
#define TCPIP_DEBUG              LWIP_DBG_ON
#define NETIF_DEBUG              LWIP_DBG_ON

diff --git a/lwipif/ports/freertos/include/arch/cc.h b/lwipif/ports/freertos/include/arch/cc.h
--- a/lwipif/ports/freertos/include/arch/cc.h
+++ b/lwipif/ports/freertos/include/arch/cc.h
@@ -34,6 +34,8 @@

 /* std.h functions required */
 #include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>

 /* Define byte order of the system */
 #define BYTE_ORDER LITTLE_ENDIAN
 @@ -55,6 +57,21 @@
   handler;}} while(0)
 #endif

+#ifdef printf
+#undef printf
+#define printf EnetAppUtils_print
+#endif
+
+extern void EnetAppUtils_print(const char *pcString, ...);
+#define LWIP_PLATFORM_DIAG(x) do {EnetAppUtils_print x;} while(0)
+#define LWIP_PLATFORM_ASSERT(x)                                          \
+    do {                                                                 \
+        volatile static int gEnetAssertWaitInLoop = 1;                   \
+        EnetAppUtils_print("Assertion \"%s\" failed at line %d in %s\n", \
+                           x, __LINE__, __FILE__);                       \
+        while (gEnetAssertWaitInLoop);                                   \
+    } while(0)
+
 struct sio_status_s;
 typedef struct sio_status_s sio_status_t;
 #define sio_fd_t sio_status_t*

PBUF_POOL_SIZE = LWIP2ENET_TX_PACKETS + ((2 * LWIP2ENET_RX_PACKETS) * n)

PBUF_POOL_SIZE = 64 + ((2 * 64) * 2)
PBUF_POOL_SIZE = 320

4.5.3.1.2.5. Tasking Model¶

TI SDK implementation will support running lwIP in a multi-thread OS environment. This implies that the core stack will be run in an independent task context and other application threads interact with it through the stack API (Netconn, Socket API - refer details below).

With core part of the stack not being re-entrant, application should stick to using Netconn/Socket API. Mixed usage with RAW API though possible, would require carefully constructed protection mechanism and is best avoided for common usage.

As part of the stack initialization, a separate thread “tcp_ip_thread” is created and all stack handling of the packets is managed from this context.

In the final system, ensure that the priority of the tcp_ip_thread, application thread and driver thread for packet handling are set in accordance with use case requirements.

On possible approach is to assign priority as networking_app_thread > tcp_ip_thread > driver_thread, with the intent that if we are not able to keep with the packet rate, the packets are dropped in the HW/driver itself.

4.5.3.1.3.1. lwIP vs NDK Feature Comparison¶

4.5.3.1.3.2. lwIP Application Interface¶

lwIP provides multiple Application Programming Interfaces as described in the table below.

For most part, applications are run in multi-threaded OS environment and are written to make use of BSD Socket like API.

NDK also includes support for BSD socket API and applications written for BSD socket API should be easily portable to lwIP.

lwIP supports BSD socket API (defined under posix/sys/socket.h), and socket API mapping is summarized in the table below. In this section we will look specifically at mapping for NDK native socket API to lwIP BSD socket interface.