Transcription
UM1713User manualDeveloping applications on STM32Cube with LwIP TCP/IP stackIntroductionSTMCube is an STMicroelectronics original initiative to ease developers life by reducingdevelopment efforts, time and cost. STM32Cube covers STM32 portfolio.STM32Cube Version 1.x includes: The STM32CubeMX, a graphical software configuration tool that allows to generate Cinitialization code using graphical wizards. A comprehensive embedded software platform, delivered per series (such asSTM32CubeF4 for STM32F4 series)–The STM32Cube HAL, an STM32 abstraction layer embedded software, ensuringmaximized portability across STM32 portfolio–A consistent set of middleware components such as RTOS, USB, TCP/IP,Graphics–All embedded software utilities coming with a full set of examples.Some STM32 microcontrollers feature a high-quality 10/100 Mbit/s Ethernet peripheral thatsupports both Media Independent Interface (MII) and Reduced Media Independent Interface(RMII) to interface with the Physical Layer (PHY).When working with an Ethernet communication interface, a TCP/IP stack is mostly used tocommunicate over a local or a wide area network.This user manual is intended for developers who use STM32Cube firmware on STM32microcontrollers. It provides a full description of how to integrate a free middleware TCP/IPstack using STM32Cube HAL drivers into an embedded application based on STM32microcontroller.The middleware TCP/IP stack is the LwIP (Lightweight IP) which is an open source stackintended for embedded devices.A dedicated STM32Cube firmware package is provided for each series. It includes EthernetHAL driver, LwIP middleware and application examples with and without RTOS running onST evaluation boards.Note:May 2015This document is applicable to all STM32 series featuring an Ethernet peripheral. However,or simplicity reason, STM32F4xx and STM32CubeF4 are used as reference platform. Thesame description, file names and screenshot are applicable as well to other series offeringEthernet connectivity, such as STM32F107xx, STM32F2x7xx and STM32F7xx. To knowmore about the Ethernet examples implementation on your STM32 series, refer to thedocumentation provided within the associated STM32Cube firmware package.DocID025731 Rev 41/41www.st.com1
ContentsUM1713Contents1LwIP TCP/IP stack description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.1Stack features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.2License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.3LwIP architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.4LwIP stack folder organization of the1.5LwIP API overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.6. 81.5.1Raw API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.5.2Netconn API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.5.3Socket API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11LwIP buffer management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111.6.1Packet buffer structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.6.2pbuf management APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Interfacing LwIP with STM32Cube Ethernet HAL driver . . . . . . . . . . . 143LwIP configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1643.1Modules support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163.2Memory configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Developing applications with LwIP stack . . . . . . . . . . . . . . . . . . . . . . . 184.14.252/41Developing in standalone mode using the Raw API . . . . . . . . . . . . . . . . 184.1.1Operation model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184.1.2Example of TCP echo server demonstration . . . . . . . . . . . . . . . . . . . . . 19Developing with an RTOS using Netconn or Socket API . . . . . . . . . . . . . 224.2.1Operation model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224.2.2Example of a TCP echoserver demonstration using the Netconn API . 23LwIP package description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265.1LwIP package directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265.2Applications settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265.2.1PHY interface configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265.2.2MAC and IP address settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275.2.3Firmware features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27DocID025731 Rev 4
UM1713Contents5.36Evaluation boards settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Using the LwIP applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286.16.26.3Getting started applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286.1.1TCP echo client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286.1.2TCP Echo server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296.1.3UDP echo client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306.1.4UDP echo server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316.1.5UDP TCP echo server based on netconn AP . . . . . . . . . . . . . . . . . . . . 32Features applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336.2.1Web server based on raw API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336.2.2Web server based on netconn API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356.2.3Web server based on socket API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Integrated applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376.3.17TFTP server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Appendix A FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398A.1How do I choose between static or dynamic (DHCP)IP address allocation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39A.2How does the application behave when the Ethernet cableis disconnected? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39A.3How can the application be ported on a different hardware? . . . . . . . . . . 39Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40DocID025731 Rev 43/413
List of tablesUM1713List of tablesTable 1.Table 2.Table 3.Table 4.Table 5.Table 6.Table 7.Table 8.Table 9.4/41TCP Raw API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9UDP Raw API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Netconn API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Socket API functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Pbuf API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Ethernet interface functions description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14LwIP memory configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16LwIP applications categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Document revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40DocID025731 Rev 4
UM1713List of figuresList of figuresFigure 1.Figure 2.Figure 3.Figure 4.Figure 5.Figure 6.Figure 7.Figure 8.Figure 9.Figure 10.Figure 11.Figure 12.Figure 13.LwIP architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Figure 2 LwIP folder organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Pbuf structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Standalone operation model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18LwIP operation model with RTOS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22TCP echo client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29TCP echo server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30UDP echo client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31UDP echo server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Web server home page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34SSI use in HTTP server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Web server list of task page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36TFTP tool (tftpd32) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37DocID025731 Rev 45/415
LwIP TCP/IP stack descriptionUM17131LwIP TCP/IP stack description1.1Stack featuresLwIP is a free TCP/IP stack developed by Adam Dunkels at the Swedish Institute ofComputer Science (SICS) and licensed under a modified BSD license.The focus of the LwIP TCP/IP implementation is to reduce RAM usage while keeping a fullscale TCP/IP stack. This makes LwIP suitable for use in embedded systems.LwIP comes with the following protocols: IPv4 and IPv6 (Internet Protocol v4 and v6) ICMP (Internet Control Message Protocol) for network maintenance and debugging IGMP (Internet Group Management Protocol) for multicast traffic management UDP (User Datagram Protocol) TCP (Transmission Control Protocol) DNS (Domain Name Server) SNMP (Simple Network Management Protocol) DHCP (Dynamic Host Configuration Protocol) PPP (Point to Point Protocol) ARP (Address Resolution Protocol)LwIP has three application programming interfaces (APIs): Raw API is the native LwIP API. It enables the development of applications using eventcallbacks. This API provides the best performance and optimized code size, but addssome complexity to application development. Netconn API is a high-level sequential API that requires a real-time operating system(RTOS). The Netconn API enables multithreaded operations. BSD Socket API: Berkeley-like Socket API (developed on top of the Netconn API)The source code for the LwIP stack can be downloaded from http://savannah.nongnu.org.1.2LicenseLwIP is licensed under the BSD license. Below is a copy of the LwIP license document thatis included in the source codes:/** Copyright (c) 2001-2004 Swedish Institute of Computer Science.* All rights reserved.** Redistribution and use in source and binary forms, with or withoutmodification,* are permitted provided that the following conditions are met:** 1. Redistributions of source code must retain the above copyright notice,*6/41this list of conditions and the following disclaimer.DocID025731 Rev 4
UM1713LwIP TCP/IP stack description* 2. Redistributions in binary form must reproduce the above copyrightnotice,*this list of conditions and the following disclaimer in thedocumentation*and/or other materials provided with the distribution.* 3. The name of the author may not be used to endorse or promote products*derived from this software without specific prior written permission.** THIS SOFTWARE IS PROVIDED BY THE AUTHOR AS IS'' AND ANY EXPRESS ORIMPLIED* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. INNO EVENT* SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,PROCUREMENT* OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; ORBUSINESS* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)ARISING* IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THEPOSSIBILITY* OF SUCH DAMAGE.** This file is part of the lwIP TCP/IP stack.**/1.3LwIP architectureLwIP complies with the TCP/IP model architecture which specifies how data should beformatted, transmitted, routed and received to provide end-to-end communications.This model includes four abstraction layers which are used to sort all related protocolsaccording to the scope of networking involved (see Figure 1). From lowest to highest, thelayers are: The link layer contains communication technologies for a single network segment(link) of a local area network. The internet layer (IP) connects independent networks, thus establishinginternetworking. The transport layer handles host-to-host communications. The application layer contains all protocols for specific data communications serviceson a process-to-process level.DocID025731 Rev 47/4140
LwIP TCP/IP stack descriptionUM1713Figure 1. LwIP architecture1.4LwIP stack folder organization of theWhen unzipped, the LwIP stack files can be found under \Middlewares\Third Party\LwIP.Figure 2. Figure 2 LwIP folder organizationwheredoc contains documentation text filessrc contains source files of the LwIP stackapi contains Netconn and Socket API filescore contains LwIP core filesinclude contains LwIP include filesnetif contains Network interface filessystem contains LwIP port hardware implementation filesarch contains STM32 architecture port files (used data types,.)OS contains LwIP port hardware implementation files using an operating systemnoOS contains LwIP port hardware implementation files in Standalone mode8/41DocID025731 Rev 4
UM17131.5LwIP TCP/IP stack descriptionLwIP API overviewAs mentioned above, three types of APIs are offered by LwIP stack:1.5.1 Raw API Netconn API Socket APIRaw APIThe Raw API is based on the native LwIP API. It is used to develop callback-basedapplications.When initializing the application, the user needs to register callback functions to differentcore events (such as TCP Sent, TCP error,.). The callback functions are called from theLwIP core layer when the corresponding event occurs.Table 1 provides a summary of the Raw API functions for TCP applications.Table 1. TCP Raw API functionsAPI functionsTCP connectionsetupSending TCP dataDescriptiontcp newCreates a new TCP PCB (protocol controlblock).tcp bindBinds a TCP PCB to a local IP address and port.tcp listenStarts the listening process on the TCP PCBtcp acceptAssigns a callback function that will be calledwhen new TCP connection arrives.tcp acceptedInforms the LwIP stack that an incoming TCPconnection has been accepted.tcp connectConnects to a remote TCP host.tcp writeQueues up data to be sent.tcp sentAssigns a callback function that will be calledwhen data are acknowledged by the remotehost.tcp outputForces queued data to be sent.tcp recvSets the callback function that will be calledwhen new data arrives.tcp recvedMust be called when the application hasprocessed the incoming data packet (for TCPwindow management).tcp pollAssigns a callback functions that will be calledperiodically. It can be used by the application tocheck if there are remaining application data thatneeds to be sent or if there are connections thatneed to be closed.Receiving TCPApplication pollingDocID025731 Rev 49/4140
LwIP TCP/IP stack descriptionUM1713Table 1. TCP Raw API functions (continued)API functionsClosing and abortingconnectionsDescriptiontcp closeCloses a TCP connection with a remote host.tcp errAssigns a callback function for handlingconnections aborted by the LwIP due to errors(such as memory shortage errors).tcp abortAborts a TCP connection.Table 2 provides a summary of the Raw API functions for UDP applications.Table 2. UDP Raw API functionsAPI functions1.5.2Descriptionudp newCreates a new UDP PCB.udp removeRemoves and de-allocates a UDP PCB.udp bindBinds a UDP PCB with a local IP address and port.udp connectSets up a UDP PCB remote IP address and port.udp disconnectRemoves a UDP PCB remote IP and port.udp sendSends UDP data.udp recvSpecifies a callback function which is called when a datagram is received.Netconn APIThe Netconn API is a high-level sequential API which model of execution is based on theblocking open-read-write-close paradigm.To operate correctly, this API must run in a multithreaded operating mode implementing adedicated thread for the LwIP TCP/IP stack and/or multiple threads for the application.Table 3 provides a summary of the Netconn API functions.Table 3. Netconn API functionsAPI functions10/41Descriptionnetconn newCreates a new connection.netconn deleteDeletes an existing connection.netconn bindBinds a connection to a local IP address and port.netconn connectConnects to a remote IP address and port.netconn sendSends data to the currently connected remote IP/port (not applicable forTCP connections).netconn recvReceives data from a netconn.DocID025731 Rev 4
UM1713LwIP TCP/IP stack descriptionTable 3. Netconn API functions (continued)API functions1.5.3Descriptionnetconn listenSets a TCP connection to a listening mode.netconn acceptAccepts an incoming connection on a listening TCP connection.netconn writeSends data on a connected TCP netconn.netconn closeCloses a TCP connection without deleting it.Socket APILwIP offers the standard BSD socket API. This is a sequential API which is internally built ontop of the Netconn API.Table 4 provides a summary of the main socket API functions.Table 4. Socket API functionsAPI functionsDescriptionsocketCreates a new socket.bindBinds a socket to an IP address and port.listenListens for socket connections.connectConnects a socket to a remote host IP address and port.acceptAccepts a new connection on a socket.readReads data from a socket.writeWrites data on a socket.closeCloses a socket (socket is deleted).1.6LwIP buffer management1.6.1Packet buffer structureLwIP manages packet buffers using a data structure called pbuf. The pbuf structure enablesthe allocation of a dynamic memory to hold a packet content and lets packets reside in thestatic memory.Pbufs can be linked together in a chain, thus enabling packets to span over several pbufs.DocID025731 Rev 411/4140
LwIP TCP/IP stack descriptionUM1713Figure 3. Pbuf structureQH[W SEXI VWUXFWXUHQH[WSD\ORDGOHQWRWBOHQIODJVUHI5RRP IRU SDFNHW KHDGHUV06 9 wherenext contains the pointer to the next pbuf in a pbuf chainpayload contains the pointer to the packet data payloadlen is the length of the data content of the pbuftot len is the sum of pbuf len plus all the len fields of the next pbufs in the chainref is the 4-bit reference count that indicates the number of pointers that point to thepbuf. A pbuf can be released from memory only when its reference count is zero.flags (on 4 bits) indicate the type of pbuf.LwIP defines three types of pbufs, depending on the allocation type: PBUF POOLpbuf allocation is performed from a pool of statically preallocated pbufs of predefinedsize. Depending on the data size that needs to be allocated, one or multiple chainedpbufs are required. PBUF RAMpbuf is dynamically allocated in memory (one contiguous chunk of memory for the fullpbuf) PBUF ROMNo memory space allocation is required for user payload: the pbuf payload pointerpoints to data in ROM memory that can be used only for sending constant data.For packet reception, the suitable pbuf type is PBUF POOL. It allows to quickly allocatememory for the packet received from the pool of pbufs. Depending on the size of thereceived packet, one or multiple chained pbufs are allocated. The PBUF RAM is notsuitable for packet reception because dynamic allocation takes some delay. It may also leadto memory fragmentation.For packet transmission, the user can choose the most suitable pbuf type according to thedata to be transmitted,.1.6.2pbuf management APIsLwIP has a specific API for working with pbufs. This API is implemented in the pbuf.c corefile.12/41DocID025731 Rev 4
UM1713LwIP TCP/IP stack descriptionTable 5. Pbuf API functionsAPI functionsNote:Descriptionpbuf allocAllocates a new pbuf.pbuf reallocResizes a pbuf (shrink size only).pbuf refIncrements the reference count field of a pbuf.pbuf freeDecrements the pbuf reference count. If it reaches zero, the pbuf isdeallocated.pbuf clenReturns the count number of pbufs in a pbuf chain.pbuf catChains two pbufs together (but does not change the reference count of thetail pbuf chain).pbuf chainChains two pbufs together (tail chain reference count is incremented).pbuf dechainUnchains the first pbuf from its succeeding pbufs in the chain.pbuf headerAdjusts the payload pointer to hide or reveal headers in the payload.pbuf copy partialCopies (part of) the contents of a packet buffer to an application suppliedbuffer.pbuf takeCopies application supplied data into a pbuf.pbuf coalesceCreates a single pbuf out of a queue of pbufs.pbuf memcmpCompare pbuf contents at specified offset with other memorypbuf memfindFind occurrence of memory in pbuf, starting from an offsetpbuf strstrFind occurrence of a string in pbuf, starting from an offset‘pbuf’ can be a single pbuf or a chain of pbufs.When working with the Netconn API, netbufs (network buffers) are used forsending/receiving data.A netbuf is simply a wrapper for a pbuf structure. It can accommodate both allocated andreferenced data.A dedicated API (implemented in file netbuf.c) is provided for managing netbufs (allocating,freeing, chaining, extracting data,.).DocID025731 Rev 413/4140
Interfacing LwIP with STM32Cube Ethernet HAL driver2UM1713Interfacing LwIP with STM32Cube Ethernet HALdriverThis package includes two implementations: Implementation without operating system (standalone) Implementation with an operating system using CMSIS-RTOS APIFor both implementations, the ethernetif.c file is used to link the LwIP stack to the STM32Ethernet network interface.The port of LwIP stack that must be connected to STM32F4xx is located in the “lwip/system”folder.The Ethernet handle of the HAL (ETH HandleTypeDef) should be declared in theethernetif.c file, as well as the Ethernet DMA descriptors (ETH DMADescTypeDef) and theRx/Tx buffers of the Ethernet driver.Table 6 provides a description of the LwIP interface API.Table 6. Ethernet interface functions descriptionFunctionDescriptionlow level initCalls the Ethernet driver functions to initialize the STM32F4xxEthernet peripherallow level outputCalls the Ethernet driver functions to send an Ethernet packetlow level inputCalls the Ethernet driver functions to receive an Ethernet packet.ethernetif initInitializes the network interface structure (netif) and callslow level init to initialize the Ethernet peripheralethernet inputCalls low level input to receive a packet then provide it to theLwIP stackThe following example shows how to initialize the Ethernet peripheral, using HAL API, intothe interface API:static void low level init(struct netif *netif){uint8 t macaddress[6] {MAC ADDR0, MAC ADDR1, MAC ADDR2, MAC ADDR3,MAC ADDR4,MAC ADDR5};EthHandle.Instance ETH;EthHandle.Init.MACAddr macaddress;EthHandle.Init.AutoNegotiation ETH AUTONEGOTIATION ENABLE;EthHandle.Init.Speed ETH SPEED 100M;EthHandle.Init.DuplexMode ETH MODE FULLDUPLEX;EthHandle.Init.MediaInterface ETH MEDIA INTERFACE MII;EthHandle.Init.RxMode ETH RXINTERRUPT MODE;EthHandle.Init.ChecksumMode ETH CHECKSUM BY HARDWARE;EthHandle.Init.PhyAddress DP83848 PHY ADDRESS;14/41DocID025731 Rev 4
UM1713Interfacing LwIP with STM32Cube Ethernet HAL driver/* configure ethernet peripheral (GPIOs, clocks, MAC, DMA) */HAL ETH Init(&EthHandle) ;/* Initialize Tx Descriptors list: Chain Mode */HAL ETH DMATxDescListInit(&EthHandle, DMATxDscrTab, &Tx Buff[0][0],ETH TXBUFNB);/* Initialize Rx Descriptors list: Chain Mode */HAL ETH DMARxDescListInit(&EthHandle, DMARxDscrTab, &Rx Buff[0][0],ETH RXBUFNB);./* Enable MAC and DMA transmission and reception */HAL ETH Start(&EthHandle);}The ethernet input() function implementation differs between standalone and RTOS modes: In standalone applications, this function must be inserted into the main loop of theapplication to poll for any received packet. In RTOS applications, this function is implemented as a thread waiting for a semaphoreto handle a received packet. The semaphore is given when the Ethernet peripheralgenerates an interrupt for a received packet.The ethernetif.c file also implements the Ethernet peripheral MSP routines for low layerinitialization (GPIO, CLK ) and interrupts callbacks.In case of RTOS implementation, an additional file is used (sys arch.c). This file implementsan emulation layer for the RTOS services (message passing through RTOS mailbox,semaphores, etc.). This file should be tailored according to the current RTOS, that isFreeRTOS for this package.DocID025731 Rev 415/4140
LwIP configuration3UM1713LwIP configurationLwIP provides a file named lwipopts.h that allows the user to fully configure the stack and allits modules. The user does not need to define all the LwIP options: if an option is notdefined, a default value defined in opt.h file is used. Therefore, lwipopts.h provides a way tooverride much of the lwIP behavior.3.1Modules supportThe user can choose the modules he needs for his application, so that the code size will beoptimized by compiling only the selected features.As an example, to disable UDP and enable DHCP, the following code must be implementedin lwipopts.h file:/* Disable UDP */#define LWIP UDP 0/* Enable DHCP */#define LWIP DHCP 13.2Memory configurationLwIP provides a flexible way to manage memory pool sizes and organization.It reserves a fixed-size static memory area in the data segment. It is subdivided into thevarious pools that lwIP uses for the various data structures. As an example, there is a poolfor struct tcp pcb, and another pool for struct udp pcb. Each pool can be configured to holda fixed number of data structures. This number can be changed in the lwipopts.h file. Forexample, MEMP NUM TCP PCB and MEMP NUM UDP PCB define the maximumnumber of tcp pcb and udb pcb structures that can be active in the system at a given time.The user options can be changed in lwipopts.h. Table 7 provides a summary of the mainRAM memory options.Table 7. LwIP memory configurationLwIP memory option16/41DefinitionMEM SIZELwIP heap memory size: used for all LwIP dynamic memoryallocations.MEMP NUM PBUFTotal number of MEM REF and MEM ROM pbufs.MEMP NUM UDP PCBTotal number of UDP PCB structures.MEMP NUM TCP PCBTotal number of TCP PCB structures.MEMP NUM TCP PCB LISTENTotal number of listening TCP PCBs.MEMP NUM TCP SEGMaximum number of simultaneously queued TCP segments.PBUF POOL SIZETotal number of PBUF POOL type pbufs.DocID025731 Rev 4
UM1713LwIP configurationTable 7. LwIP memory configuration (continued)LwIP memory optionDefinitionPBUF POOL BUFSIZESize of a PBUF POOL type pbufs.TCP MSSTCP maximum segment size.TCP SND BUFTCP send buffer space for a connection.TCP SND QUEUELENMaximum number of pbufs in the TCP send queue.TCP WNDAdvertised TCP receive window size.DocID025731 Rev 417/4140
Developing applications with LwIP stackUM17134Developing applications with LwIP stack4.1Developing in standalone mode using the Raw API4.1.1Operation modelIn standalone mode, the operation model is based on continuous software polling to check ifa packet has been received.When a packet has been received, it is first copied from the Ethernet driver buffers into theLwIP buffers. To copy the packet as fast as possible, the LwIP buffers (pbufs) should beallocated from the pool of buffers (PBUF POOL).When a packet has been copied, it is handed to the LwIP stack for processing. Dependingon the received packet, the stack may or may not notify the application layer.LwIP communicates with the application layer using event callback functions. Thesefunctions should be assigned before starting the communication process.Refer to Figure 4 for a description of the standalone operation model flowchart.Figure 4. Standalone operation model0OLL FOR PACKET RECEPTION.O.EW PACKET RECEIVED9ES#OPY PACKET FROM DRIVERBUFFERS TO LWI0 BUFFERS0ROCESSING OF THE PACKET BYTHE LW)0 STACK.O!PPLICATIONNOTIFICATION NEEDED9ES0ROCESSING OF APPLICATIONASSIGNED CALLBACK FUNCTION-3 6 18/41DocID025731 Rev 4
UM1713Developing applications with LwIP stackFor TCP applications, the following common callback functions must be assigned:4.1.2 Callback for incoming TCP c
core contains LwIP core files include contains LwIP include files netif contains Network interface files system contains LwIP port hardware implementation files arch contains STM32 architecture port files (used data types,.) OS contains LwIP port hardware implementation files using an operating system
