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/PPPoS 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.

Note: When using serial devices it is important to ensure the I/O driver configuration provides the necessary buffers and/or hardware flow-control to avoid the possibility of PPPoS/SLIP RX data loss.

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 new; 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.

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:

int cyg_lwip_init(void);

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 initialization. Consult the raw API documentation for more information.

Note: The cyg_lwip_init function, depending on the configuration, may block for some time waiting for interfaces to acquire network addresses. Alternatively the:

int cyg_lwip_init_nowait(void);

function can be called to perform just the necessary low-level initialisation, without the extra “address wait” functionality. The cyg_lwip_init function itself uses the cyg_lwip_init_nowait routine prior to waiting for network addresses to be assigned.

Alternatively, the (weak) helper function:

void init_all_network_interfaces(void);

is provided. By default it just calls the lwIP specific cyg_lwip_init initialisation, but it may be overridden by drivers or run-time support if alternative initialisation strategies are required.

Note: The init_all_network_interfaces name is the same as used by the alternative CYGPKG_NET BSD networking world.

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. Similarly the helper function:

int cyg_lwip_netif_print_info(struct netif *netif, cyg_lwip_printf *pf);

can be called after cyg_lwip_init to output specific interface address information via the supplied printf-alike routine. For example using diag_printf for the pf parameter will display the address information on the diagnostic output console without having to enable the network interface debugging feature.

2017-02-09
Documentation license for this page: eCosPro License