Configuring the lwIP stack

Note: For a low-level brief overview of how the lwIP source accesses the configured features see the Section called System Configuration in Chapter 151.

Once added to the configuration, the lwIP package has a large number of configuration options. There are too many configuration options to go into full detail in this section, though the major eCos port specific options and fundamental support options are detailed. The configuration tool can be used to examine the hierarchy of the complete set of lwIP configuration options.

Stack size for system threads (CYGNUM_LWIP_THREAD_STACK_SIZE)

The eCos lwIP implementation uses this fixed value as the stack size for all the lwIP system threads.

If this value is set too low then incorrect operation can result due to stack overflow. The value should be configured to be large enough to cover the target platform worst-case stack requirement. The Thread Information documentation provides an overview of the cyg_thread_measure_stack_usage() that can be used to monitor and tune the stack requirements of the network application.

Network thread priority (CYGNUM_LWIP_NETWORK_THREAD_PRIORITY)

This value defines the main lwIP network thread priority, and also, if the feature is used, the default thread priority assigned to lwIP system threads.

Loop interface (CYGFUN_LWIP_LOOPIF)

This option controls whether support is included for the standard loopback network interface. The interface is created with the IPv4 address 127.0.0.1 and the IPv6 address ::1. The interface can be used for testing purposes, or where compatibility with existing code is required.

Ethernet support (CYGPKG_LWIP_ETH)

This boolean option defines whether support for ethernet interfaces is enabled, and if enabled provides access to a variety of configuration options for the ethernet interfaces.

By default the eCos configuration provides support for defining up to 3 ethernet network interfaces. If more interfaces are required then the CDL source in cdl/lwip_net.cdl will need to be manually edited. For the following descriptions the n suffix should one of 0, 1 or 2.

Interface n config (CYGPKG_LWIP_ETH_DEVn)

If this boolean option is enabled then it provides the set of configuration options for the specific ethernet network interface. The following STATIC, DHCP, AUTOIP and MANUAL options are mutually exclusive, with only one being actively configured at any point.

Static IPv4 address (CYGPKG_LWIP_ETH_DEV_ADDR_STATICn)

If this boolean option is enabled then the ethernet interface will be configured during initialization to use the supplied IPv4 addresses.

IP address (CYGPKG_LWIP_ETH_DEV_ADDR_STATIC_IPn)

This option provides the hard-coded IPv4 address for the interface.

Netmask (CYGPKG_LWIP_ETH_DEV_ADDR_STATIC_NETMASKn)

This option provides the hard-coded subnet IPv4 netmask for the interface.

Gateway (CYGPKG_LWIP_ETH_DEV_ADDR_STATIC_GWn)

This option provides the hard-coded gateway router IPv4 address to be used for the default route for packets sent via the interface that are not destined for the directly connected subnet.

IPv4 address from DHCP (CYGPKG_LWIP_ETH_DEV_ADDR_DHCPn)

If the lwIP DHCP (Dynamic Host Configuration Protocol) support is configured then this option can be enabled for the interface to obtain its IPv4 address, netmask and gateway values from a suitable DHCP server present on the network.

IPv4 address from AutoIP (CYGPKG_LWIP_ETH_DEV_ADDR_AUTOIPn)

This option if enabled configures the interface to obtain a link-local IPv4 address using the AutoIP feature.

Set address manually (CYGPKG_LWIP_ETH_DEV_ADDR_MANUALn)

This option if enabled indicates that the application code will itself be calling the lwIP functions required to configured the interface addresses.

Set as default interface (CYGPKG_LWIP_ETH_IS_DEFAULTn)

This option, if enabled, selects the respective interface as the default to be used when the network stack needs to communicate with an address which is not part of a network directly associated with a specific interface.

TCP (CYGPKG_LWIP_TCP)

This option controls whether the TCP protocol is supported by the lwIP configuration. If enabled, a set of configuration options are available to tune the lwIP TCP implementation.

IPv4 (CYGFUN_LWIP_IPV4)

This option enables the IPv4 support. If enabled, a set of configuration options are available to control IPv4 specific features.

IPv6 (CYGFUN_LWIP_IPV6)

This option enables the IPv6 support. If enabled, a set of configuration options are available to control IPv6 specific features.

UDP (CYGPKG_LWIP_UDP)

This option controls whether the UDP protocol is supported by the lwIP configuration. If enabled, a set of configuration options are available to tune the lwIP UDP implementation.

SNMP Agent (CYGFUN_LWIP_SNMP)

If enabled the lwIP world will provide a SNMP (Simple Network Management Protocol) MIB-II agent.

Due to the stated lightweight and simple nature of lwIP, with it mainly being targeted at resource limited embedded targets, the SNMP features available are constrained (e.g. lwIP has a limited notion of IP routing, only pre-compiled MIBs, etc.). Objects located above the “.iso.org.dod.internet” hierarchy are not supported. By default only the “.mgmt” sub-tree is available, though if the CDL option CYGFUN_LWIP_SNMP_PRIVATE_MIB is enabled then the “.private” sub-tree becomes available too via the application supplied private_mib.h header file.

The supplied private_mib.h must contain a struct mib_array_node mib_private definition which is referenced by the lwIP SNMP agent, and describes the private MIB hierarchy. As an example the main struct min_array_node mgmt provided in the source file src/core/snmp/mib2.c can be referenced.

Note: The SNMP agent has a sizeable code and data footprint, so may not be suitable for targets with limited resources.

SLIP (CYGPKG_LWIP_SLIP)

If enabled lwIP will provide support for the SLIP (Serial Line IP) subsystem. This will provide a network interface to encapsulate IP packets and to send and receive them to a remote system using eCos serial drivers. This option enables a set of SLIP specific configuration options. Note: Though basic functionality has been tested, the SLIP functionality is not supported under the terms of the incident support in eCosPro.

PPP (CYGPKG_LWIP_PPP)

If enabled lwIP will provide support for the PPP (Point-to-Point Protocol) subsystem. This option enables a set of PPP specific configuration options.

PPP-over-Ethernet (CYGPKG_LWIP_PPPOE_SUPPORT)

If this PPP sub-option is enabled then support for PPPoE (PPP-over-Ethernet) is provided. This provides support for encapsulating PPP frames inside ethernet frames, and is mainly used where a secure point-to-point connection is required, for example, to avoid IP, MAC and DHCP issues.

Note: Support for PPPoE is not yet tested or supported for eCosPro.

PPP-over-Serial (CYGPKG_LWIP_PPPOS_SUPPORT)

If this PPP sub-option is enabled then support is provided to encapsulate IP packets and to send and receive them to a remote system using eCos serial drivers.

Note: PPP is more sophisticated than SLIP, and is therefore larger. It does however provide extra features, such as authentication, better link management, option negotion and header compression.

Note: Though basic PPPoS functionality has been tested, the PPPoS functionality is not supported under the terms of the incident support in eCosPro.

RAW sockets (CYGPKG_LWIP_RAW)

This option enables support for raw sockets. These allow the transmission or reception of packets over IP but using protocols other than TCP or UDP; or in order to construct packets that cannot be constructed with the lwIP API directly. Raw sockets can be used by selecting a connection type of NETCONN_RAW with the lwIP sequential API. This support is also used by the BSD socket API when creating a socket of type SOCK_RAW

Provide sequential API (CYGPKG_LWIP_SEQUENTIAL_API)

This option enables support for the lwIP sequential API (see the Section called Application Programming Interfaces (APIs) in Chapter 150 for an overview).

Provide BSD-style socket API (CYGFUN_LWIP_COMPAT_SOCKETS)

This option enables the lwIP support for BSD-style socket operations. This can be useful for adapting existing software to be able to use the lwIP stack.

The socket functions in the API have the form lwip_accept(), lwip_bind(), lwip_listen() etc. Enabling this option causes macros to be defined to map these functions to the BSD function names (accept(), bind(), listen(), etc.). If this causes naming conflicts for the application, then you may wish to disable this option. Particular care is required if this option is enabled at the same time as the File I/O CYGPKG_IO_FILEIO package is used since a single source file will be unlikely to be able to use the File I/O APIs and the lwIP BSD compatible socket API.

Provide POSIX-style socket API (CYGFUN_LWIP_POSIX_SOCKETS_IO_NAMES)

This option enables the lwIP support for POSIX-style socket operations, useful for adapting existing software to be able to use the lwIP stack. The socket functions in the API have the form lwip_read(), lwip_write(), etc. Enabling this option causes macros to be defined to map the POSIX function names (read(), write(), etc.) to these lwIP functions. If this causes naming conflicts for the application you may want to disable this option.

Generate proto checksums (CYGIMP_LWIP_CHECKSUM_GEN_proto), Verify proto checksums (CYGIMP_LWIP_CHECKSUM_CHECK_proto)

There are a set of configuration options to control checksum generation and calculation support. The IP suffix deals with the generic ethernet IP packet checksum, and the UDP and TCP suffixes with the specific protocol packet checksums. The ICMP6 suffix (CHECK only) performs verification of IPv6 ICMPv6 packets.

See the Section called Checksums for more information regarding the implications of these options.

Checksum on copy (CYGIMP_LWIP_CHECKSUM_ON_COPY)

This option if enabled implements code to calculate checksums when copying data from application buffers to packet buffers.

Hardware driver override header (CYGBLD_LWIP_HW_DRIVER_OVERRIDE_HEADER)

This option is not normally set by the user, but is provided to allow device drivers to specify a target specific header file that can be used to influence the lwIP configuration.

For example, the lwIP direct ethernet drivers use a header file configured via this option to influence the way the lwIP packet buffer pool is created.

Memory pool sizes (CYGNUM_LWIP_MEMP_NUM_pool)

The lwIP configuration contains the ability to set many memory related options. The major configuration being the number of pool entries for the different types of memory buffer and descriptors used within the various lwIP subsystems, and these are prefixed CYGNUM_LWIP_MEMP_NUM_ with a usage specific pool suffix.

See the Section called Memory Footprint for more information about tuning the lwIP memory footprint.

Normally the configuration options should be left at their default values unless you have a specific need to change them, e.g. memory requirements. Once the configuration has been created, it should be possible to compile eCos and link it with the application without any errors.

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