Chapter 163. Configuration

Chapter 163. Configuration
	Part XLIV. lwIP - the lightweight IP stack for eCosPro

Chapter 163. Configuration

Table of Contents

163.1. Configuration Overview

163.2. Configuring the lwIP stack

163.3. Performance and Footprint Tuning

163.3.1. Performance
163.3.2. Optimizations
163.3.3. Memory Footprint

This chapter shows how to include the lwIP networking support into an eCos configuration, and how to configure it once installed. This subject was briefly covered in Section 161.7, “Quick Start”.

163.1. Configuration Overview

The lwIP networking stack is contained in a single eCos package CYGPKG_NET_LWIP. However, it depends on the services of a collection of other packages for complete functionality:

CYGPKG_KERNEL: The main eCos kernel package. This provides the main run-time infrastructure as needed by the lwIP stack. For example, support for threads, semaphores, mailboxes, etc.
CYGPKG_ISOINFRA: ISO C and POSIX standards infrastructure package. This provides access to many run-time utility routines. For example rand_r().
CYGPKG_ERROR: Error package. This provides access to the common eCos error and status codes.
CYGPKG_LIBC_STDLIB: General support library. This provides general ISO C utility functions to the lwIP system.
CYGPKG_LIBC_STRING: Strings library. This provides the string and memory move and compare routines used by the lwIP system.
CYGPKG_LIBC_I18N: Internationalization library. This provides character interpretation support routines.
CYGPKG_IO_ETH_DRIVERS: The common ethernet device driver support package. This is only required when lwIP is being configured for ethernet support.
CYGPKG_IO_SERIAL_DEVICES: The serial device driver support package. This is only required when lwIP is being configured for SLIP or PPPoS support.

To add the lwIP support to a configuration, it is necessary to add the packages listed above as appropriate. This is best done by using a template file. Two examples of such templates files are provided:

lwip_eth: Provides a current.ect file containing the packages necessary to add ethernet lwIP support to any configuration.
lwip_ppp: Provides a current.ect file containing the packages necessary to add lwIP serial-based interface support to any configuration.

In addition to the packages listed above, hardware-specific device driver packages will be needed for ethernet devices to be used. These device drivers are usually part of the target description in the eCos database and will be enabled if the CYGPKG_IO_ETH_DRIVERS package is included.

For some target platforms a choice of device driver will be available. The lwIP driver model section of the CYGPKG_IO_ETH_DRIVERS_LWIP option may allow either a Direct or Standard driver to be selected. Direct are lwIP only device drivers designed for better performance on lower resource systems, but with some limitations on features supported (for example remote network debugging as mentioned in Section 166.1.4, “GDB/RedBoot”). The Standard drivers use the eCos standard ethernet driver interface allowing the device driver to be used for configurations using other TCP/IP stacks (e.g. FreeBSD) as well as for lwIP configurations.

Note: If lwIP is being configured to provide POSIX-style names for some socket support operations then the eCos package CYGPKG_IO_FILEIO should not normally be enabled in the eCos configuration at the same time, since care needs to be taken to avoid name-space clashes.

163.2. Configuring the lwIP stack

Note: For a low-level brief overview of how the lwIP source accesses the configured features see Section 162.2.1, “System Configuration”.

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 configure the interface addresses.

The application will need to supply a cyg_lwip_eth_init_manual() function implementation, which will be called from the common IO layer lwIP Ethernet initialisation.

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 Section 161.2, “Application Programming Interfaces (APIs)” 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 Section 163.3.2.1, “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.

Internal lwIP callback hook definition header (CYGBLD_LWIP_HOOK_H)

This option allows a specific configuration (i.e. application) to provide its own optional lwIP hook callback definitions if required. Some hooks extend functionality (e.g. LWIP_HOOK_VLAN_SET) whilst others are useful for diagnostics or tracking (e.g. LWIP_HOOK_IP4_INPUT). If enabling this functionality the developer should be conversant with the internals of lwIP and understand how to declare the specific hook macros as well as how they will be called.

One caveat to be aware of is that since the hooks are compiled-into the lwIP stack they may be called from the very beginning of the network stack startup, which may be before the main application code is fully initialised. Care should be taken in the called hooks to ensure a valid state exists. This also means that any hooks that are defined to call application code, the relevant functions need to be available to all code linked against the lwIP stack built with the hooks included.

Any private state needed must be referenced via the netif descriptor. However we currently use the netif->state pointer internally for eCos. The exact interpretation of the state field depends on the actual eCos configuration. For standard driver worlds it is normally a reference to the driver struct eth_drv_sc descriptor.

So for any other private application context that needs to be referenced we can use the client_data vector held in each netif descriptor. The lwIP stack internally has fixed slots allocated for its internal functionality, so we need to ensure that CYGNUM_LWIP_NETIF_CLIENT_DATA is configured with the number of extra slots needed by any application code. The application is responsible for managing the indexing from LWIP_NETIF_CLIENT_DATA_INDEX_MAX onwards.

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.

ALTCP abstraction layer (CYGFUN_LWIP_ALTCP)

This option enables the TCP abstraction layer that replaces the internal TCP function references with indirect calls allowing the support for SSL/TLS or proxy-connect support to applications written against the lwIP TCP callback API without the application layer requiring knowledge of the underlying protocol details.

When the ALTCP functionality is enabled the option CYGFUN_LWIP_ALTCP_TLS controls whether the ALTCP TLS API is available.

For eCos, in conjunction with the Mbed TLS (CYGPKG_MBEDTLS) package, the CYGFUN_LWIP_MBEDTLS configuration option uses the lwIP Mbed TLS wrapper for the lwIP CYGFUN_LWIP_ALTCP_TLS controlled TLS API.

	Note
	If the `CYGFUN_LWIP_ALTCP_TLS` option is enabled, but the `CYGFUN_LWIP_MBEDTLS` option is not enabled, then the developer is responsible for providing the ALTCP wrapper functions required. The lwIP package sub-directory `src/apps/altcp_tls/altcp_tls_mbedtls` contains the Mbed TLS wrapper which can be used as a reference if required.

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 Section 163.3.3, “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.

163.3. Performance and Footprint Tuning

163.3.1. Performance
163.3.2. Optimizations
163.3.3. Memory Footprint

163.3.1. Performance

There are many changes in configuration that can affect performance. For example, the number and size of buffers, how checksum calculations are implementated, etc.

The CYGDBG_LWIP_STATS option can be enabled to allow for a variety of statistics counts to be gathered during execution. The various options are all prefixed with CYGDBG_LWIP_STATS_, and a sub-system specific suffix.

These statistics can help with the tuning of the lwIP world during development, since monitoring the minimum and maximum usage counts of resources along with the error counts can indicate resource starvation issues. Note: Some error counts are indicative of a temporary inability to claim a resource, and are not necessarily a fatal error for the stack, just a potential slowdown.

In order to determine the number of resources used in practice, during development it is recommended that testing is performed under the expected maximum load expected to need to be handled, in order to understand the resource requirements at that load. To get useful information for this, temporarily configure lwIP with a higher number of resources than would be expected to be needed, memory permitting. Then the application should be tested under the expected network load, at the end of which, the statistics can be inspected, and attention paid to the "max" fields which show the maximum number of each resource used in practice in that sample scenario. This can then be used to inform decisions into the appropriate allocation of reduced resources set in the configuration of lwIP for the final product, without unduly compromising performance.

If CYGDBG_LWIP_STATS is enabled then the function:

#include <lwip/stats.h>

void stats_display (void);

can be used to dump all of the statistics gathered via the output routine defined by the LWIP_PLATFORM_DIAG function wrapper (currently defined to use diag_printf() in the eCos specific arch/cc.h header file).

See Section 163.3.3, “Memory Footprint” for more information about tuning the lwIP memory footprint.

163.3.1.1. TCP

If the CYGPKG_LWIP_TCP option is configured then various TCP specific options are available for tuning the performance. The main options are covered in the subsections below.

163.3.1.1.1. Receive Window

The CYGNUM_LWIP_TCP_WND option defines the maximum TCP receive window size. This size is advertised to remote peers to indicate how much data they can send. While larger values are faster, you should not advertise more than you can receive, which means you must have sufficient capacity in the pbuf pool used for received data for all your connections.

163.3.1.1.2. Maximum Segment Size

The CYGNUM_LWIP_TCP_MSS option defines the Maximum Segment Size (MSS) advertised to peers to constrain the amount of TCP data they send in each packet. This is recommended not to be more than the interface MTU less 40 bytes. The 40 bytes are the sum of a TCP header and IP header, neither with any options. If any options are used regularly, this value should be reduced further.

If the MSS has been set too large, it will result in IP fragmentation and consequent inefficient network operation. If the MSS is too large and IP fragmentation has been disabled (CYGFUN_LWIP_IP_FRAG), incorrect stack operation will likely result including oversize packets never getting sent, or even a failure in the ethernet driver. The most common MTU size is 1500 bytes (leading to a recommended MSS of up to 1460 bytes) but is certainly not universal: some routers, and especially VPNs, can have lower MTUs and will in turn fragment packets leading to lower efficiency. For best resource utilisation by lwIP, it is a good idea for the MSS to be set so that incoming packets can fit into a whole number of pbufs from the packet buffer pool. As such the default MSS is that of the pbuf pool packet buffer size (CYGNUM_LWIP_PBUF_POOL_BUFSIZE), less 40 bytes to allow room for TCP and IP headers without options.

163.3.1.1.3. Sending Data

The CYGNUM_LWIP_TCP_SND_BUF option defines the amount of buffer space in bytes allowed for outstanding (unacked) sent data for each TCP connection. This option is complementary to CYGNUM_LWIP_TCP_SND_QUEUELEN which defines the number of packet buffers allowed for outstanding (unacked) sent data for each TCP connection. The TCP layer will refuse to queue a buffer to be sent if either the total quantity of data in bytes waiting to be sent would then exceed CYGNUM_LWIP_TCP_SND_BUF, or there are already at least CYGNUM_LWIP_TCP_SND_QUEUELEN buffers in the queue waiting to be sent.

163.3.2. Optimizations

The following sections detail some optimization hints that could be useful on certain target platforms to maximise lwIP data throughput.

163.3.2.1. Checksums

A major performance bottle-neck for lwIP is the software checksum code, since it is executed frequently. If the underlying ethernet device driver provides hardware checksum support then the appropriate CHECKSUM_GEN_* and CHECKSUM_CHECK_* options can be disabled. However if software checksums are needed then you may want to override the standard checksum implementation. This can be achieved by adding a LWIP_CHKSUM definition to a header file included by lwIP, e.g. adding the following to lwipopts.h:

#define LWIP_CHKSUM your_checksum_routine

The standard lwip_standard_chksum() implementations from src/core/inet_chksum.c provide some C examples, though you might want to craft an assembly function for this specific case. RFC#1071 is a good introduction to this subject. A highly optimized assembler routine will provide the greatest improvement in overall lwIP performance for software checksum based systems.

If the CYGIMP_LWIP_CHECKSUM_ON_COPY functionality is enabled then support for calculating checksums when data is copied into the stack (from application buffers into packet buffers) and can result in fewer checksum calculations if a packet buffer is going to be used multiple times, or if pre-calculated checksums are available for pre-built packets.

The memcpy()-alike function:

u16_t lwip_chksum_copy (void *dest , const void *src , u16_tlen );

can be used to copy data, and return the checksum of the data copied. The extra TCP TF_SEG_DATA_CHECKSUMMED flag is used internally by the lwIP TCP support to track whether a checksum has been set on the payload data.

163.3.2.2. Network-vs-Host

Since network byte order is big-endian, other significant improvements can be made by supplying assembly or inline replacements for htons() and htonl() if you're using a little-endian architecture.

#define LWIP_PLATFORM_BYTESWAP 1
#define LWIP_PLATFORM_HTONS(x) your_htons
#define LWIP_PLATFORM_HTONL(x) your_htonl

If the lwIP CYGIMP_LWIP_HAL_BYTESWAP configuration option is enabled then lwIP will use the HAL supplied support. The CYGIMP_LWIP_HAL_BYTESWAP option is enabled by default if the architecture indicates that optimised byte-swap implementations are available, otherwise the option is disabled by default and for little-endian architectures lwIP will provide byte-swap functions.

163.3.2.3. Device Driver

The ethernet MAC device driver should ideally use interrupts and DMA to avoid busy loops wherever possible. Hardware support for scatter-gather DMA should be used if available, since multiple packet buffers can then be used to hold the different sections of a frame, allowing for zero-copy of payload data.

163.3.2.4. Release Builds

For a production release it is highly recommended to disable CYGDBG_LWIP_STATS.

163.3.3. Memory Footprint

The setting of the CYGNUM_LWIP_THREAD_STACK_SIZE configuration option and the memory configuration options described in Section 163.3.1, “Performance” will all affect the overall RAM footprint required by lwIP.

However, as long as the option to use the standard run-time allocator (CYGFUN_LWIP_MEM_LIB_MALLOC) is NOT enabled, the memory footprint of lwIP is deterministic and fixed by the selected configuration.

The major memory configuration options are listed below. Setting these configuration values is usually a compromise between the amount of physical RAM available on the target platform, and the lwIP throughput (performance) requirements.

Heap size (CYGNUM_LWIP_MEM_SIZE)

This option defines the size of the heap that lwIP maintains separate from the system heap so that the resource requirements of one do not affect the other. It is primarily (although not exclusively) used as the memory pool from which packet buffers for transmission are allocated, when the data to be sent needs to be copied (type PBUF_RAM). It is also used to allocate space for dynamically created messages boxes and semaphores. This option can be increased to improve performance when sending large amounts of data.

Packet buffer size (CYGNUM_LWIP_PBUF_POOL_BUFSIZE)

This option specifies the maximum size of data which a single packet buffer (pbuf) allocated from the packet buffer pool for incoming packets can contain. The overall memory footprint of each packet buffer is slightly larger to account for metadata. Incoming packets larger than this size are chained together, using additional packet buffers. If only short packets are usually received, memory efficiency may be improved by reducing the packet buffer size, even if this is accompanied by an increase in the number of packets in the pool using the CYGNUM_LWIP_PBUF_POOL_SIZE option. If larger packets tend to be received, the converse is true.

Note: Some network drivers set constraints on the value of this option, in order to better integrate with hardware properties.

Incoming packet messages (CYGNUM_LWIP_MEMP_NUM_TCPIP_MSG) , API messages (CYGNUM_LWIP_MEMP_NUM_API_MSG)

When using the sequential API these options define the simultaneous number of, respectively, the packet input and API messages. These messages are used for communicating between external threads and the core lwIP network stack.

Netbufs (CYGNUM_LWIP_MEMP_NUM_NETBUF)

This option defines the maximum number of netbuf structures which may be in use simultaneously with the sequential API (which in turn are used by the BSD sockets API). Each netbuf structure corresponds to a chain of packet buffers to be used for sending or receiving data. This option may be set to 0 if the application will only be using the raw API.

Netconns (CYGNUM_LWIP_MEMP_NUM_NETCONNS)

This option defines the maximum number of netconn structures which may be in use simultaneously with the sequential API. Each netconn structure corresponds to a connection, whether active or inactive. This option may be set to 0 if the application will only be using the raw API.

Packet buffer pool size (CYGNUM_LWIP_PBUF_POOL_SIZE)

This option specifies the number of packet buffers (pbufs) present in the packet buffer pool. This pool is used to provide space for incoming data packets, and so this option limits the number of incoming data packets being processed, or pending (including those not yet read out from the stack by the application). It is also used to hold packet fragments if the option CYGFUN_LWIP_IP_REASS is enabled, and so must be large enough to cover the CYGNUM_LWIP_IP_REASS_MAX_PBUFS requirement. Note that additional buffers are used in a chain when incoming packets are received which exceed the maximum size of each packet buffer. This option may be adjusted depending on the anticipated peak network traffic. Incoming packets are dropped when the pool is depleted.

Number of memp packet buffers (CYGNUM_LWIP_MEMP_NUM_PBUF)

The lwIP API allows packets to be transmitted which only contain a reference to the data being sent, instead of copying the data into a separate buffer. This can be useful when sending a lot of data out of ROM (or other static memory). This option specifies the number of such packets that can be used simultaneously. You may wish to increase the value of this option if the application sends a lot of such data, or reduce if not sending any of this form. These buffers are also used when IP fragmentation support is enabled, but a static buffer is not used (CYGIMP_LWIP_IP_FRAG_USES_STATIC_BUF disabled), so may also need increasing if fragmentation is common.

RAW protocol control blocks (CYGNUM_LWIP_MEMP_NUM_RAW_PCB)

This option defines the number of RAW protocol control blocks that may be used simultaneously. One is required for each active RAW connection.

UDP control blocks (CYGNUM_LWIP_MEMP_NUM_UDP_PCB)

This option defines the number of UDP protocol control blocks that may be used simultaneously. One is required for each active UDP connection.

TCP control blocks (CYGNUM_LWIP_MEMP_NUM_TCP_PCB)

This option defines the number of TCP protocol control blocks that may be used simultaneously. One is required for each TCP connection. Hence this option defines the maximum number of TCP connections that may be open simultaneously. Increase the value of this option if more simultaneous TCP connections are required.

Listening TCP control blocks (CYGNUM_LWIP_MEMP_NUM_TCP_PCB_LISTEN)

This option defines the number of protocol control blocks dedicated to listening for incoming TCP connection requests. This corresponds to the maximum number of TCP ports which may be simultaneously listened on.

Queued TCP segments (CYGNUM_LWIP_MEMP_NUM_TCP_SEG)

This option defines the maximum number of TCP segments which may be simultaneously queued. This option may need to be adjusted if the stack reports memory failure errors when attempting to send large quantities of data through TCP connections simultaneously, or when individual TCP writes are so large that the number of MSS-sized segments exceeds the value of this option. If the option to allow out-of-order incoming packets (CYGIMP_LWIP_TCP_QUEUE_OOSEQ) is enabled, then such segments may also be dropped if the maximum number of TCP segments specified in this option has been reached.

Queued packets for ARP resolve (CYGNUM_LWIP_MEMP_NUM_ARP_QUEUE)

The number of simultaneously queued outgoing packet buffers that are waiting for an ARP request to finish to resolve their destination address.

Queued IP reassembly packets (CYGNUM_LWIP_MEMP_NUM_REASSDATA) , Simultaneous IP fragments (CYGNUM_LWIP_MEMP_NUM_FRAG_PBUF)

These options provide respectively the number of packets that can simultaneously be queued for reassembly, and the number of fragments (not packets) that can be simultaneously queued for sending.

System timeouts (CYGNUM_LWIP_MEMP_NUM_INTERNAL_TIMEOUTS) , User timeouts (CYGNUM_LWIP_MEMP_NUM_USER_TIMEOUTS)

The INTERNAL value is the number of timeout objects required to support the configured lwIP features. The USER value defines the maximum number of user timeouts that may be pending simultaneously. The value of this option may need to be increased if there are more threads using the raw API, or if there are more threads calling the select() BSD compatibility function.

Multicast group members (CYGNUM_LWIP_MEMP_NUM_IGMP_GROUP)

This option defines the number of multicast groups whose network interfaces can be members at the same time. This value must be at least twice the number of active network interfaces active in the configuration.

Active lwip_addrinfo() calls (CYGNUM_LWIP_MEMP_NUM_NETDB) , Local host list entries (CYGNUM_LWIP_MEMP_NUM_LOCALHOSTLIST)

If DNS support is enabled then these options respectively control the number of concurrent lwip_addrinfo() calls supported, and the number of host entries in the dynamic local host list.

Simultaneous PPP connections (CYGNUM_LWIP_MEMP_NUM_PPP_PCB) , Concurrent PPPoE interfaces (CYGNUM_LWIP_MEMP_NUM_PPPOE_INTERFACES)

These options respectively control the number of simultaneously active PPP connections, and the number of concurrently active PPPoE connections.

163.3.3.1. lwIP Footprint

The following size information was gathered from a CortexM3 targeted configuration using the eCosCentric GNU tools (version 4.4.5c) with gcc -O2 optimization selected. The byte sizes are provided to give an example overview of the lwIP footprint that can be expected, and are purely for informational purposes.

In the following builds Basic refers to a sequential API configuration with UDP and TCP support, but with most options disabled (no fragmentation or reassembly support, static address, no SNMP agent, no IGMP, etc.). The builds marked Reassembly refers to the addition of fragmented packet reassembly code to the Basic builds. The Full entry is a configuration with all the lwIP ethernet features enabled (excluding SNMP, SLIP and PPP) to give an idea of the upper footprint for a fully-featured ethernet build.

The values given are for the complete lwIP library package, so specific application linkage (due to the eCos use of -ffunction-sections) means that not all of the code and data measured in the sizes given below may actually be included in the final executable. The footprint can be made even smaller by explicit use of the raw API.

Note: The bss values below do NOT include the stack requirement for the sequential API thread, nor the main configurable lwIP heap space. This is because the aim is to present an example of the base lwIP requirement, independent of the configured heap and stack space required for a particular application or target environment.

CortexM3 (STM32F2xx)	text + rodata	data	bss
Basic IPv4 static	40224	16	516
Basic IPv4 AutoIP	41660	16	516
Basic IPv4 DHCP	46712	16	520
Basic IPv4 IPv6	58680	24	613
Reassembly IPv4 static	41928	16	526
Reassembly IPv4 IPv6	60488	24	627
Full IPv4 IPv6	80512	24	1843

Note: Configurations built with the options CYGDBG_LWIP_DEBUG, CYGDBG_LWIP_ASSERTS or CYGDBG_LWIP_STATS enabled will have a significantly larger code footprint. Similarly configurations built with the CYGPKG_INFRA_DEBUG option or the compiler -O0 optimisation flag will also have a significant effect on the footprint.

163.3.3.1.1. Example "small" footprint

The example described in this section targets the STM3220G-EVAL platform, but similar figures have also been obtained for other platforms (e.g. AT91SAM7XEK).

With careful tuning it is possible to implement a simple raw API webserver using the httpd2 test example in ~32K of ROM and ~10K of RAM. This is for the complete application, thread stacks, network buffers, etc.

Even though httpd2 is a simple application it does provide a real-world useful working data point for a minimal footprint system. Note: For this example build the httpd2.c source was modified to use the minimal STACK_SIZE definition.

The small_rom_stm3220g_httpd2.ecm example template used is provided in the lwIP package doc directory. The steps needed to build the minimal example binary are:

$ mkdir small_httpd2
$ cd small_httpd2
$ ecosconfig new stm3220g_eval
[  ecosconfig output elided  ]
$ ecosconfig import $ECOS_REPOSITORY/net/lwip_tcpip/VERSION/doc/small_rom_stm3220g_httpd2.ecm
$ ecosconfig resolve
$ ecosconfig tree
$ make tests
[  make output elided  ]
$ arm-eabi-objcopy -O binary install/tests/net/lwip_tcpip/VERSION/tests/httpd2 httpd2.bin

The produced httpd2.bin binary can then be loaded into the flash of the STM3220G-EVAL at address 0x08000000.


cyg_lwip_statistics		Chapter 164. Sequential API

2024-12-10

LWIP Documentation Notices