CYGPKGKERNELThe main eCos kernel package. This provides the main run-time infrastructure asneeded by the lwIP stack. For example, support for threads, semaphores,mailboxes, etc.CYGPKGISOINFRAISO C and POSIX standards infrastructure package. This provides access to manyrun-time utility routines. For example randr.CYGPKGERRORError package. This provides access to the common eCos error and status codes.CYGPKGLIBCSTDLIBGeneral support library. This provides general ISO C utility functions to thelwIP system.CYGPKGLIBCSTRINGStrings library.
This provides the string and memory move and compare routinesused by the lwIP system.CYGPKGLIBCI18NInternationalization library. This provides character interpretation support routines.CYGPKGIOETHDRIVERSThe common ethernet device driver support package. This is only required whenlwIP is being configured for ethernet support.CYGPKGIOSERIALDEVICESThe serial device driver support package. This is only required when lwIP isbeing configured for SLIP or PPPoS support.To add the lwIP support to a configuration, it is necessary to add the packageslisted above as appropriate.
This is best done by using a template file. Twoexamples of such templates files are provided. LwipethProvides a current.ect file containing the packages necessary toadd ethernet lwIP support to any configuration.lwippppProvides a current.ect file containing the packagesnecessary to add lwIP serial-based interface support to any configuration.In addition to the packages listed above, hardware-specific device driverpackages will be needed for ethernet devices to be used. These device driversare usually part of the target description in the eCos database and will beenabled if theCYGPKGIOETHDRIVERS package is included.For some target platforms a choice of device driver will beavailable. The lwIP driver model section ofthe CYGPKGIOETHDRIVERSLWIP option may alloweither a Direct or Standard driver to be selected. Direct are lwIPonly device drivers designed for better performance on lower resourcesystems, but with some limitations on features supported (for exampleremote network debugging as mentioned in). The Standard drivers use the eCosstandard ethernet driver interface allowing the device driver to beused for configurations using other TCP/IP stacks (e.g.
FreeBSD) aswell as for lwIP configurations.Note: If lwIP is being configured to provide POSIX-style names for some socketsupport operations then the eCos package CYGPKGIOFILEIOshould not normally be enabled in the eCos configuration at the same time, sincecare needs to be taken to avoid name-space clashes. 158.2. Configuring the lwIP stackNote: For a low-level brief overview of how the lwIP source accesses theconfigured features see.Once added to the configuration, the lwIP package has a large number ofconfiguration options. There are too many configuration options to go into fulldetail in this section, though the major eCos port specific options andfundamental support options are detailed. The configuration tool can be used toexamine the hierarchy of the complete set of lwIP configuration options.
Stack size for system threads( CYGNUMLWIPTHREADSTACKSIZE)The eCos lwIP implementation uses this fixed value as the stack size for all thelwIP system threads.If this value is set too low then incorrect operation can result due to stackoverflow. The value should be configured to be large enough to cover the targetplatform worst-case stack requirement.
Thedocumentation provides an overview ofthe cygthreadmeasurestackusage that can be used tomonitor and tune the stack requirements of the network application.Network thread priority( CYGNUMLWIPNETWORKTHREADPRIORITY)This value defines the main lwIP network thread priority, and also, if thefeature is used, the default thread priority assigned to lwIP system threads.Loop interface( CYGFUNLWIPLOOPIF)This option controls whether support is included for the standard loopbacknetwork interface. The interface is created with the IPv4address 127.0.0.1 and the IPv6address::1. The interface can be used for testingpurposes, or where compatibility with existing code is required.Ethernet support( CYGPKGLWIPETH)This boolean option defines whether support for ethernet interfaces is enabled,and if enabled provides access to a variety of configuration options for theethernet interfaces.By default the eCos configuration provides support for defining up to 3 ethernetnetwork interfaces.
If more interfaces are required then the CDL sourcein cdl/lwipnet.cdl will need to be manually edited. Forthe following descriptions the n suffix should oneof 0, 1 or 2. NoteSupport for PPPoE is not yet tested or supported for eCosPro.PPP-over-Serial( CYGPKGLWIPPPPOSSUPPORT)If this PPP sub-option is enabled then support is provided to encapsulate IPpackets and to send and receive them to a remote system using eCos serialdrivers.Note: PPP is more sophisticated than SLIP, and is therefore larger. It doeshowever provide extra features, such as authentication, better link management,option negotion and header compression.Note: Though basic PPPoS functionality has been tested, the PPPoS functionalityis not supported under the terms of the incident supportin eCosPro.RAW sockets( CYGPKGLWIPRAW)This option enables support for raw sockets. These allow the transmission orreception of packets over IP but using protocols other than TCP or UDP; or inorder to construct packets that cannot be constructed with the lwIP APIdirectly.
Lwip Documentation
Raw sockets can be used by selecting a connection type of NETCONNRAWwith the lwIP sequential API. This support is also used by the BSD socket APIwhen creating a socket of type SOCKRAWProvide sequential API( CYGPKGLWIPSEQUENTIALAPI)This option enables support for the lwIP sequential API(see for an overview).Provide BSD-style socket API( CYGFUNLWIPCOMPATSOCKETS)This option enables the lwIP support for BSD-style socket operations. This canbe useful for adapting existing software to be able to use the lwIP stack.The socket functions in the API have theform lwipaccept, lwipbind, lwiplistenetc. Enabling this option causes macros to be defined to map these functions tothe BSD function names( accept, bind, listen,etc.). If this causes naming conflicts for the application, then you may wish todisable this option. Particular care is required if this option is enabled atthe same time as the File I/O CYGPKGIOFILEIO package isused since a single source file will be unlikely to be able to use the File I/OAPIs and the lwIP BSD compatible socket API.Provide POSIX-style socket API( CYGFUNLWIPPOSIXSOCKETSIONAMES)This option enables the lwIP support for POSIX-style socket operations, usefulfor adapting existing software to be able to use the lwIP stack. The socketfunctions in the API have theform lwipread, lwipwrite,etc.
Enabling this option causes macros to be defined to map the POSIX functionnames ( read, write, etc.) to theselwIP functions. If this causes naming conflicts for the application you may wantto disable this option.Generate proto checksums( CYGIMPLWIPCHECKSUMGEN proto),Verify proto checksums( CYGIMPLWIPCHECKSUMCHECK proto)There are a set of configuration options to control checksum generation andcalculation support. The IP suffix deals with the genericethernet IP packet checksum, and the UDPand TCP suffixes with the specific protocol packetchecksums. 158.3.1. PerformanceThere are many changes in configuration that can affect performance. Forexample, the number and size of buffers, how checksum calculations areimplementated, etc.The CYGDBGLWIPSTATS option can be enabled to allow for avariety of statistics counts to be gathered during execution.
The variousoptions are all prefixed with CYGDBGLWIPSTATS, and asub-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 withthe error counts can indicate resource starvation issues. Note: Some errorcounts are indicative of a temporary inability to claim a resource, and are notnecessarily a fatal error for the stack, just a potential slowdown.In order to determine the number of resources used in practice, duringdevelopment it is recommended that testing is performed under the expectedmaximum load expected to need to be handled, in order to understand the resourcerequirements at that load.
To get useful information for this, temporarilyconfigure lwIP with a higher number of resources than would be expected to beneeded, memory permitting. Then the application should be tested under theexpected network load, at the end of which, the statistics can be inspected, andattention paid to the 'max' fields which show the maximum number of eachresource used in practice in that sample scenario. This can then be used toinform decisions into the appropriate allocation of reduced resources set in theconfiguration of lwIP for the final product, without unduly compromisingperformance.If CYGDBGLWIPSTATS is enabled then the function. 158.3.1.1.2. Maximum Segment SizeThe CYGNUMLWIPTCPMSS option defines the Maximum SegmentSize (MSS) advertised to peers to constrain the amount of TCP data they send ineach packet.
This is recommended not to be more than the interface MTU less 40bytes. The 40 bytes are the sum of a TCP header and IP header, neither with anyoptions.
If any options are used regularly, this value should be reducedfurther.If the MSS has been set too large, it will result in IP fragmentation andconsequent inefficient network operation. If the MSS is too large and IPfragmentation has been disabled ( CYGFUNLWIPIPFRAG),incorrect stack operation will likely result including oversize packets nevergetting sent, or even a failure in the ethernet driver. The most common MTU sizeis 1500 bytes (leading to a recommended MSS of up to 1460 bytes) but iscertainly not universal: some routers, and especially VPNs, can have lower MTUsand will in turn fragment packets leading to lower efficiency. For best resourceutilisation by lwIP, it is a good idea for the MSS to be set so that incomingpackets can fit into a whole number of pbufs from the packet buffer pool. Assuch the default MSS is that of the pbuf pool packet buffer size( CYGNUMLWIPPBUFPOOLBUFSIZE), less 40 bytes to allowroom for TCP and IP headers without options.
158.3.1.1.3. Sending DataThe CYGNUMLWIPTCPSNDBUF option defines the amount ofbuffer space in bytes allowed for outstanding (unacked) sent data for each TCPconnection. This option is complementaryto CYGNUMLWIPTCPSNDQUEUELEN which defines the number ofpacket buffers allowed for outstanding (unacked) sent data for each TCPconnection. The TCP layer will refuse to queue a buffer to be sent if either thetotal quantity of data in bytes waiting to be sent would thenexceed CYGNUMLWIPTCPSNDBUF, or there are already atleast CYGNUMLWIPTCPSNDQUEUELEN buffers in the queuewaiting to be sent. 158.3.2.1. ChecksumsA major performance bottle-neck for lwIP is the software checksum code, since itis executed frequently. If the underlying ethernet device driver provideshardware checksum support then theappropriate CHECKSUMGEN.and CHECKSUMCHECK.
options can be disabled. However ifsoftware checksums are needed then you may want to override the standardchecksum implementation. This can be achieved by addinga LWIPCHKSUM definition to a header file included by lwIP,e.g. Adding the following to lwipopts.h:#define LWIPCHKSUM yourchecksumroutineThe standard lwipstandardchksum implementationsfrom src/core/inetchksum.c provide some C examples, thoughyou might want to craft an assembly function for this specificcase. RFC#1071 is a good introduction to this subject. Ahighly optimized assembler routine will provide the greatest improvement inoverall lwIP performance for software checksum based systems.If the CYGIMPLWIPCHECKSUMONCOPY functionality isenabled then support for calculating checksums when data is copied into thestack (from application buffers into packet buffers) and can result in fewerchecksum calculations if a packet buffer is going to be used multiple times, orif pre-calculated checksums are available for pre-built packets.The memcpy-alike function. 158.3.2.2. Network-vs-HostSince network byte order is big-endian, other significant improvementscan be made by supplying assembly or inline replacements for htonsand htonl if you're using a little-endian architecture.#define LWIPPLATFORMBYTESWAP 1#define LWIPPLATFORMHTONS(x) yourhtons#define LWIPPLATFORMHTONL(x) yourhtonlIf the lwIP CYGIMPLWIPHALBYTESWAP configurationoption is enabled then lwIP will use the HAL suppliedsupport.
The CYGIMPLWIPHALBYTESWAP option isenabled by default if the architecture indicates that optimisedbyte-swap implementations are available, otherwise the option isdisabled by default and for little-endian architectures lwIP willprovide byte-swap functions. 158.3.3. Memory FootprintThe setting of the CYGNUMLWIPTHREADSTACKSIZEconfiguration option and the memory configuration options describedin will all affect theoverall RAM footprint required by lwIP.However, as long as the option to use the standard run-time allocator( CYGFUNLWIPMEMLIBMALLOC) is NOTenabled, the memory footprint of lwIP is deterministic and fixed by the selectedconfiguration.The major memory configuration options are listed below.
Setting theseconfiguration values is usually a compromise between the amount of physical RAMavailable on the target platform, and the lwIP throughput (performance)requirements. Heap size ( CYGNUMLWIPMEMSIZE)This option defines the size of the heap that lwIP maintains separate from thesystem heap so that the resource requirements of one do not affect the other.
Itis primarily (although not exclusively) used as the memory pool from whichpacket buffers for transmission are allocated, when the data to be sent needs tobe copied (type PBUFRAM). It is also used to allocate space for dynamicallycreated messages boxes and semaphores. This option can be increased to improveperformance when sending large amounts of data.Packet buffer size( CYGNUMLWIPPBUFPOOLBUFSIZE)This option specifies the maximum size of data which a single packet buffer(pbuf) allocated from the packet buffer pool for incoming packets cancontain.
The overall memory footprint of each packet buffer is slightly largerto account for metadata. Incoming packets larger than this size are chainedtogether, using additional packet buffers. If only short packets are usuallyreceived, 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 poolusing the CYGNUMLWIPPBUFPOOLSIZE option.
If largerpackets tend to be received, the converse is true.Note: Some network drivers set constraints on the value of this option, in orderto better integrate with hardware properties.Incoming packet messages( CYGNUMLWIPMEMPNUMTCPIPMSG),API messages( CYGNUMLWIPMEMPNUMAPIMSG)When using the sequential API these options define the simultaneous number of,respectively, the packet input and API messages. These messages are used forcommunicating between external threads and the core lwIP network stack.Netbufs( CYGNUMLWIPMEMPNUMNETBUF)This option defines the maximum number of netbuf structures which may be in usesimultaneously with the sequential API (which in turn are used by the BSDsockets API). Each netbuf structure corresponds to a chain of packet buffers tobe used for sending or receiving data. This option may be set to 0 if theapplication will only be using the raw API.Netconns( CYGNUMLWIPMEMPNUMNETCONNS)This option defines the maximum number of netconn structures which may be in usesimultaneously with the sequential API.
Each netconn structure corresponds to aconnection, whether active or inactive. This option may be set to 0 if theapplication will only be using the raw API.Packet buffer pool size( CYGNUMLWIPPBUFPOOLSIZE)This option specifies the number of packet buffers (pbufs) present in the packetbuffer pool. This pool is used to provide space for incoming data packets, andso this option limits the number of incoming data packets being processed, orpending (including those not yet read out from the stack by the application). Itis also used to hold packet fragments if theoption CYGFUNLWIPIPREASS is enabled, and so must belarge enough to cover the CYGNUMLWIPIPREASSMAXPBUFSrequirement. Note that additional buffers are used in a chain when incomingpackets are received which exceed the maximum size of each packet buffer. Thisoption may be adjusted depending on the anticipated peak networktraffic.
Incoming packets are dropped when the pool is depleted.Number of memp packet buffers( CYGNUMLWIPMEMPNUMPBUF)The lwIP API allows packets to be transmitted which only contain a reference tothe data being sent, instead of copying the data into a separate buffer. Thiscan be useful when sending a lot of data out of ROM (or other staticmemory). This option specifies the number of such packets that can be usedsimultaneously. You may wish to increase the value of this option if theapplication sends a lot of such data, or reduce if not sending any of thisform.
These buffers are also used when IP fragmentation support is enabled, buta static buffer is not used( CYGIMPLWIPIPFRAGUSESSTATICBUF disabled), so may alsoneed increasing if fragmentation is common.RAW protocol control blocks( CYGNUMLWIPMEMPNUMRAWPCB)This option defines the number of RAW protocol control blocks that may be usedsimultaneously. One is required for each active RAW connection.UDP control blocks( CYGNUMLWIPMEMPNUMUDPPCB)This option defines the number of UDP protocol control blocks that may be usedsimultaneously. One is required for each active UDP connection.TCP control blocks( CYGNUMLWIPMEMPNUMTCPPCB)This option defines the number of TCP protocol control blocks that may be usedsimultaneously. One is required for each TCP connection. Hence this optiondefines the maximum number of TCP connections that may be opensimultaneously.
Increase the value of this option if more simultaneous TCPconnections are required.Listening TCP control blocks( CYGNUMLWIPMEMPNUMTCPPCBLISTEN)This option defines the number of protocol control blocks dedicated to listeningfor incoming TCP connection requests. This corresponds to the maximum number ofTCP ports which may be simultaneously listened on.Queued TCP segments( CYGNUMLWIPMEMPNUMTCPSEG)This option defines the maximum number of TCP segments which may besimultaneously queued. This option may need to be adjusted if the stack reportsmemory failure errors when attempting to send large quantities of data throughTCP connections simultaneously, or when individual TCP writes are so large thatthe number of MSS-sized segments exceeds the value of this option. 158.3.3.1. lwIP FootprintThe following size information was gathered from a CortexM3 targetedconfiguration using the eCosCentricGNU tools (version 4.4.5c)with gcc -O2 optimizationselected. The byte sizes are provided to give an exampleoverview of the lwIP footprint that can be expected, and are purely forinformational purposes.In the following builds Basic refers to asequential API configuration with UDP and TCP support, but with most optionsdisabled (no fragmentation or reassembly support, static address, no SNMP agent,no IGMP, etc.).
The builds marked Reassemblyrefers to the addition of fragmented packet reassembly code to theBasic builds. TheFull entry is a configuration with all thelwIP ethernet features enabled (excluding SNMP, SLIP and PPP) to give an idea ofthe upper footprint for a fully-featured ethernet build.The values given are for the complete lwIP library package, sospecific application linkage (due to the eCos useof -ffunction-sections) means that not all of the codeand data measured in the sizes given below may actually be included in the finalexecutable. The footprint can be made even smaller by explicit use of the rawAPI.Note: The bss values below do NOTinclude the stack requirement for the sequential API thread, nor the mainconfigurable lwIP heap space. This is because the aim is topresent an example of the base lwIP requirement, independent of the configuredheap and stack space required for a particular application or targetenvironment. CortexM3 (STM32F2xx)text + rodatadatabssBasic IPv4 staticBasic IPv4 AutoIPBasic IPv4 DHCPBasic IPv4 IPv3Reassembly IPv4 staticReassembly IPv4 IPv7Full IPv4 IPv43Note: Configurations built with theoptions CYGDBGLWIPDEBUG, CYGDBGLWIPASSERTSor CYGDBGLWIPSTATS enabled will have a significantlylarger code footprint. Similarly configurations built withthe CYGPKGINFRADEBUG option or thecompiler -O0 optimisation flag will also have asignificant effect on the footprint.
Lwip Udp Example
158.3.3.1.1. Example 'small' footprintThe example described in this section targets the STM3220G-EVALplatform, but similar figures have also been obtained for otherplatforms (e.g. AT91SAM7XEK).With careful tuning it is possible to implement a simple raw APIwebserver using the httpd2 test example in32K of ROM and 10K of RAM. This is for the complete application,thread stacks, network buffers, etc.Even though httpd2 is a simple applicationit does provide a real-world useful working data point for a minimalfootprint system.
Note: For this example buildthe httpd2.c source was modified to use theminimal STACKSIZE definition.The smallromstm3220ghttpd2.ecm exampletemplate used is provided in the lwIPpackage doc directory. The stepsneeded to build the minimal example binary are:$ mkdir smallhttpd2$ cd smallhttpd2$ ecosconfig new stm3220geval ecosconfig output elided $ ecosconfig import $ECOSREPOSITORY/net/lwiptcpip/ VERSION/doc/smallromstm3220ghttpd2.ecm$ ecosconfig resolve$ ecosconfig tree$ make tests make output elided $ arm-eabi-objcopy -O binary install/tests/net/lwiptcpip/ VERSION/tests/httpd2 httpd2.binThe produced httpd2.bin binary can then be loadedinto the flash of the STM3220G-EVAL ataddress 0x08000000.