Quick Start

Incorporating lwIP into your application is straightforward. The essential starting point is to incorporate the lwIP eCos package (CYGPKG_NET_LWIP) into your configuration.

This may be achieved directly using ecosconfig add on the command line, or the Build->Packages... menu item within the eCos Configuration Tool. If you wish to support Ethernet devices, you will also need to include the “Common Ethernet Support” (CYGPKG_IO_ETH_DRIVERS) eCos package. For SLIP/PPP support, you will need to enable the “Hardware serial device drivers” (CYGPKG_IO_SERIAL_DEVICES) configuration option within the “Serial device drivers” (CYGPKG_IO_SERIAL) eCos package.

Alternatively, as a convenience, configuration templates have been provided to permit an easy starting point for creating a configuration incorporating lwIP. Two templates are provided: lwip_eth for those intending to use lwIP with Ethernet; and lwip_ppp for those intending to use lwIP with PPP. These may be used either by providing the template name as an extra argument on the command line to ecosconfig add; or with the Build->Templates... menu item within the eCos Configuration Tool. Both these templates are basic, incorporating only those packages which are essential for lwIP operation.

At this stage it would be appropriate to tailor the lwIP package configuration to the application requirements. At a minimum it would be appropriate to consider whether a static IP address, or a dynamic IP address served from a DHCP server, is required. Note that if RedBoot is used on the target and incorporates network support, then you must not give lwIP and RedBoot the same IP address. For the same reason, you must not configure both lwIP and RedBoot to obtain an IP address via DHCP.

If obtaining an address via DHCP it can be convenient to enable the network interface debugging configuration option within lwIP (CYGDBG_LWIP_DEBUG_NETIF). This will allow the IP address which was set to be viewed on the diagnostic output console.

Prior to coding your application to perform lwIP stack operations using its APIs, the stack must be initialised. This does not happen automatically, and instead a C function must be called:

The function declaration can be obtained by including the network.h header file:

#include <network.h>

cyg_lwip_init returns 0 on success and non-zero on failure. Note that 0 may be returned even if no network interfaces were successfully initialised. This is because in some cases interfaces are brought up asynchronously in any case, devaluing such an error indication; and because an interface not coming up may be expected. If the application needs to determine the status of interfaces, it should query the stack using the netif_* functions using the <lwip/netif.h> header file.

The cyg_lwip_init function must be called from a thread context. Raw API users need not call this function, although they instead will be required to perform their own stack initialisation. Consult the raw API documentation for more information.