July 2013DocID022105 Rev 21/48
AN3966
Application note
LwIP TCP/IP stack demonstration for STM32F4x7 microcontrollers
Introduction
STM32F4x7 microcontrollers feature a high-quality 10/100 Mbit/s Ethernet peripheral that supports 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 to communicate over a local or a wide area network.
This application note presents a demonstration package built on top of the LwIP
(Lightweight IP) TCP/IP stack which is an open source stack intended for embedded devices.
This demonstration package contains nine applications running on top of the LwIP stack:?
Applications running in standalone mode (without an RTOS):–A Web server – A TFTP server
– A TCP echo client application – A TCP echo server application – A UDP echo client application – A UDP echo server application ?
Applications running with the FreeRTOS operating system:
– A Web server based on netconn API – A Web server based on socket API
–
A TCP/UDP echo server application based on netconn API
Note:
In this document STM32F4x7 refers to STM32F407xx, STM32F417xx, STM32F427xx and STM32F437xx devices.
Table 1. Applicable products
Type Product series
Microcontroller
STM32F407xx, STM32F417xx, STM32F427xx, STM32F437xx
https://www.sodocs.net/doc/d74662267.html,
Contents AN3966
Contents
1LwIP stack overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.1Stack features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2Folder organization of the LwIP stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3LwIP API overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3.1Raw API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3.2Netconn API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.3.3Socket API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4LwIP buffer management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.4.1Packet buffer structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.4.2API for managing pbufs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.5Interfacing LwIP to STM32F4x7 Ethernet network interface . . . . . . . . . . 12
2STM32F4x7 low level driver overview . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.1Global Ethernet MAC/DMA functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.1.1Ethernet MAC/DMA configuration parameters . . . . . . . . . . . . . . . . . . . 14
2.2DMA descriptor handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.2.1DMA descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.2.2DMA descriptor handling functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.3PHY control functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.4Hardware checksum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3Developing applications with LwIP stack . . . . . . . . . . . . . . . . . . . . . . . 22
3.1Developing in standalone mode using the Raw API . . . . . . . . . . . . . . . . 22
3.1.1Model of operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.1.2Example of the TCP echo server demo . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.2Developing with an RTOS using Netconn or Socket API . . . . . . . . . . . . . 26
3.2.1Model of operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.2.2Example of a TCP echoserver demo using the Netconn API . . . . . . . . 27
3.3LwIP memory configuration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4Description of the demonstration package . . . . . . . . . . . . . . . . . . . . . 31
4.1Package directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.2Demonstration settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 2/48DocID022105 Rev 2
AN3966Contents
4.2.1PHY interface configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.2.2MAC and IP address settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.2.3STM324xx-EVAL settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5Using the demos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
5.1Standalone demos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
5.1.1Httpserver demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
5.1.2TCP echo client demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.1.3TCP echo server demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5.1.4UDP echo client demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
5.1.5UDP echo server demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
5.1.6TFTP server demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.2FreeRTOS demos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
5.2.1HTTP server netconn demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
5.2.2HTTP server socket demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5.2.3UDP TCP echo server netconn demo . . . . . . . . . . . . . . . . . . . . . . . . . . 43
6Footprint information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
6.1HTTP server demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
6.2HTTP server netconn demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 7Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 8Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
DocID022105 Rev 23/48
List of tables AN3966 List of tables
Table 1.Applicable products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Table 2.TCP Raw API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Table 3.UDP Raw API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Table https://www.sodocs.net/doc/d74662267.html,conn API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Table 5.Socket API functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Table 6.Pbuf API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Table 7.ethernet_if.c functions description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Table 8.Global Ethernet MAC/DMA functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Table 9.MAC configuration parameters of an ETH_InitTypeDef structure. . . . . . . . . . . . . . . . . . . . 14 Table 10.DMA configuration parameters of an ETH_InitTypeDef structure. . . . . . . . . . . . . . . . . . . . 16 Table 11.DMA descriptor functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Table 12.PHY control functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Table 13.LwIP memory configuration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Table 14.STM324xx-EVAL jumper configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Table 15.HTTP server demo footprint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Table 16.Httpserver netconn demo footprint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Table 17.Document revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 4/48DocID022105 Rev 2
AN3966List of figures List of figures
Figure 1.LwIP folder organization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Figure 2.Pbuf structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Figure 3.Ethernet DMA descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Figure 4.Ethernet DMA descriptor chaining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Figure 5.STM32F4x7 Ethernet driver buffers and descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Figure 6.Tracking DMA Rx/Tx descriptors to Get/Set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Figure 7.Standalone operation model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Figure 8.LwIP operation model with RTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Figure 9.Demonstration package structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Figure 10.Home page of the HTTP server demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Figure 11.SSI use in HTTP server demo application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Figure 12.TCP echo client demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Figure 13.TCP echo server demo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Figure 14.UDP echo client demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Figure 15.UDP echo server demon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Figure 16.TFTP tool (tftpd32) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
DocID022105 Rev 25/48
LwIP stack overview AN3966
6/48DocID022105 Rev 2
1 LwIP stack overview
1.1 Stack features
LwIP is a free TCP/IP stack developed by Adam Dunkels at the Swedish Institute of
Computer Science (SICS) and licensed under a modified BSD license.
The focus of the LwIP TCP/IP implementation is to reduce the RAM use while still having a full scale 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 interface (API) sets:
?
Raw API is the native API of LwIP . It enables the development of applications using event callbacks. This API provides the best performance and code size, but adds some complexity for application development.
?Netconn API is a high-level sequential API that requires the services of a real-time operating system (RTOS). The Netconn API enables multi-threaded 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 at the following link: https://www.sodocs.net/doc/d74662267.html,/projects/LwIP
Note:
This application note is based on LwIP v1.4.1
AN3966LwIP stack overview
1.2 Folder organization of the LwIP stack
When unzipped, the LwIP stack files can be found under “\Utilities\Third_Party\LwIP-1.4.1”
as shown in Figure1.
Figure 1. LwIP folder organization
?doc: documentation text files
?port/STM32F4x7: files implementing the LwIP port to STM32F4x7
–arch: STM32 architecture port files (used data types,...)
–FreeRTOS: LwIP port to STM32F4x7 using FreeRTOS
–Standalone: LwIP port to STM32F4x7 in Standalone mode
?src: source files of the LwIP stack
–api: Netconn and Socket API files
–core: LwIP core files
–include: LwIP include files
–netif: Network interface files
1.3 LwIP API overview
As mentioned above, three types of APIs are offered by LwIP stack:
?Raw API
?Netconn API
?Socket API
API
1.3.1 Raw
The Raw API is based on the native API of LwIP. It is used to develop callback-based
applications.
When initializing the application, the user needs to register callback functions to different
core events (such as TCP_Sent, TCP_error,...) . The callback functions will be called from
the LwIP core layer when the corresponding event occurs.
DocID022105 Rev 27/48
LwIP stack overview
AN3966
8/48DocID022105 Rev 2
Table 2 provides a summary of the Raw API functions for TCP applications.
Table 3 provides a summary of the Raw API functions for UDP applications.
Table 2. TCP Raw API functions
API function Description
TCP connection setup
tcp_new Creates a new TCP PCB (protocol control block).tcp_bind Binds a TCP PCB to a local IP address and port.tcp_listen
Starts the listening process on the TCP PCB.tcp_accept Assigns a callback function that will be called when a new TCP connection arrives.
tcp_accepted Informs the LwIP stack that an incoming TCP connection has been accepted.tcp_connect Connects to a remote TCP host.Sending TCP data tcp_write
Queues up data to be sent.
tcp_sent Assigns a callback function that will be called when sent data is acknowledged by the remote host.tcp_output Forces queued data to be sent.
Receiving TCP data
tcp_recv
Sets the callback function that will be called when new data arrives.
tcp_recved
Must be called when the application has processed the incoming data packet (for TCP window management).Application polling tcp_poll
Assigns a callback functions that will be called
periodically. It can be used by the application to check if there is remaining application data that needs to be sent or if there are connections that need to be closed.Closing and aborting
connections
tcp_close
Closes a TCP connection with a remote host.tcp_err
Assigns a callback function for handling connections aborted by the LwIP due to errors (such as memory shortage errors).tcp_abort
Aborts a TCP connection.
Table 3. UDP Raw API functions
API function
Description
udp_new Creates a new UDP PCB.
udp_remove Removes and de-allocates a UDP PCB.
udp_bind Binds a UDP PCB with a local IP address and port.udp_connect Sets up a UDP PCB remote IP address and port.udp_disconnect Removes a UDP PCB remote IP and port.udp_send Sends UDP data.
udp_recv
Specifies a callback function which is called when a datagram is received.
DocID022105 Rev 29/48
AN3966LwIP stack overview
1.3.2 Netconn API
The Netconn API is a high-level sequential API which has a model of execution based on
the blocking open-read-write-close paradigm.
To function correctly, this API must run in a multi-threaded operation mode where there is a separate thread for the LwIP TCP/IP stack and one or multiple threads for the application.Table 4 provides a summary of the Netconn API functions.
1.3.3 Socket API
LwIP offers the standard BSD socket API. This is a sequential API which is internally built on
top of the netconn.
Table 4 provides a summary of the main socket API functions.
Table 4. Netconn API functions
API function
Description
netconn_new Creates a new https://www.sodocs.net/doc/d74662267.html,conn_delete Deletes an existing connection.
netconn_bind Binds a connection to a local IP address and https://www.sodocs.net/doc/d74662267.html,conn_connect Connects to a remote IP address and port.
netconn_send Sends data to the currently connected remote IP/port (not applicable for TCP connections).
netconn_recv Receives data from a netconn.
netconn_listen Sets a TCP connection into a listening mode.
netconn_accept Accepts an incoming connection on a listening TCP https://www.sodocs.net/doc/d74662267.html,conn_write Sends data on a connected TCP https://www.sodocs.net/doc/d74662267.html,conn_close
Closes a TCP connection without deleting it.
Table 5. Socket API functions
API function
Description
socket Creates a new socket.
bind Binds a socket to an IP address and port.listen Listens for socket connections.
connect Connects a socket to a remote host IP address and port.accept Accepts a new connection on a socket.read Reads data from a socket.write Writes data on a socket.
close
Closes a socket (socket is deleted).
LwIP stack overview AN3966
10/48DocID022105 Rev 2
1.4 LwIP buffer management
1.4.1
Packet buffer structure
LwIP manages packet buffers using a data structure called pbuf. The pbuf structure enables
the allocation of a dynamic memory to hold a packet content and lets packets reside in the
static memory.
Pbufs can be linked together in a chain. This enables packets to span over several pbufs.
?payload : pointer to packet data payload ?len : length of the data content of the pbuf
?tot_len : sum of pbuf len plus all the len fields of the next pbufs in the chain
?ref : (on 4 bits) reference count that indicates the number of pointers that reference the pbuf. 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_POOL : pbuf allocation is performed from a pool of statically pre-allocated pbufs that have a predefined size. Depending on the data size that needs to be allocated, one or multiple chained pbufs are allocated.
?PBUF_RAM : pbuf is dynamically allocated in memory (one contiguous chunk of memory for the full pbuf)
?
PBUF_ROM : there is no allocation for memory space for user payload, the pbuf payload pointer points to data in the ROM memory (it can be used only for sending constant data).
For packet reception, the suitable pbuf type is PBUF_POOL; it allows to rapidly allocate memory for the received packet from the pool of pbufs. Depending on the size of the received packet, one or multiple chained pbufs are allocated. The PBUF_RAM is not
suitable for packet reception because dynamic allocation takes some delay. It may also lead to memory fragmentation.
For packet transmission, depending on the data to be transmitted, the user can choose the most suitable pbuf type.
DocID022105 Rev 211/48
AN3966LwIP stack overview
1.4.2 API for managing pbufs
LwIP has a specific API for working with pbufs. This API is implemented in the pbuf.c core file.
Note:1“pbuf” can be a single pbuf or a chain of pbufs.
2When working with the Netconn API, netbufs (network buffers) are used for sending/receiving data.
3 A netbuf is simply a wrapper for a pbuf structure. It can accommodate both allocated and referenced data.
4
A dedicated API (implemented in file netbuf.c) is provided for managing netbufs (allocating, freeing, chaining, extracting data,...).
Table 6. Pbuf API functions
API function
Description
pbuf_alloc Allocates a new pbuf.
pbuf_realloc Resizes a pbuf (shrink size only).
pbuf_ref Increments the reference count field of a pbuf.
pbuf_free Decrements the pbuf reference count. If it reaches zero, the pbuf is de-allocated.
pbuf_clen Returns the count number of pbufs in a pbuf chain.
pbuf_cat Chains two pbufs together (but does not change the reference count of the tail pbuf chain).
pbuf_chain Chains two pbufs together (tail chain reference count is incremented).pbuf_dechain Unchains the first pbuf from its succeeding pbufs in the chain.pbuf_copy_partial Copies (part of) the contents of a packet buffer to an application supplied buffer.
pbuf_take Copies application supplied data into a pbuf.pbuf_coalesce
Creates a single pbuf out of a queue of pbufs.
LwIP stack overview AN3966
12/48DocID022105 Rev 2
1.5 Interfacing LwIP to STM32F4x7 Ethernet network interface
The port of LwIP stack to STM32F4x7 is located in folder “/port/STM32F4x7”.This demonstration package provides two implementations:?Implementation without RTOS (standalone)
?
Implementation with an RTOS using FreeRTOS (https://www.sodocs.net/doc/d74662267.html,/)
For both implementations, the ethernet_if.c file is used to link the LwIP stack to the STM32F4x7 Ethernet network interface.
Table 7 provides a summary of the ethernet_if.c functions.
In case of an RTOS implementation, an additional file is used (sys_arch.c ). This file implements an emulation layer for the RTOS services (message passing through RTOS mailbox, semaphores,etc.). This file should be tailored according to the current RTOS, which is FreeRTOS in this package.
Table 7. ethernet_if.c functions description
Function
Description
low_level_init Calls the Ethernet driver functions to initialize the STM32F4x7 Ethernet peripheral.
low_level_output Calls the Ethernet driver functions to send an Ethernet packet.low_level_input Calls the Ethernet driver functions to receive an Ethernet packet.ethernetif_init Calls low_level_init to initialize the Ethernet peripheral and network interface structure (netif).
ethernet_input
Calls low_level_input to receive a packet and provide it to the LwIP stack.
2 STM32F4x7 low level driver overview
The STM32F4x7 Ethernet low level driver is located in the
\Libraries\STM32F4x7_ETH_Driver\ folder.
The set of functions provided in the driver can be divided into the following categories:
?Global Ethernet MAC/DMA configuration/control functions
?DMA descriptors handling functions
?DMA configuration/control functions
?PHY control functions
?Power Management (PMT) functions
?MAC Management Counters (MMC) functions
2.1 Global Ethernet MAC/DMA functions
Table16 provides a summary of the Global Ethernet MAC/DMA functions used for the
configuration of the media access control (MAC) and direct memory access (DMA) features.
Table 8. Global Ethernet MAC/DMA functions
Function Description
ETH_DeInit Resets the Ethernet peripheral.
ETH_StructInit Fills a configuration structure for an Ethernet peripheral with the
default config (see below).
ETH_Init Initializes the Ethernet peripheral (MAC/DMA) registers with the
required configuration.
ETH_Start Starts the Ethernet MAC/DMA operation.
ETH_Stop Stops the Ethernet MAC/DMA operation.
ETH_MACTransmissionCmd Enables or disables MAC transmission.
ETH_MACReceptionCmd Enables or disables MAC reception.
ETH_GetFlowControlBusyStatus Checks flow control Busy flag.
ETH_InitiatePauseControlFrame Initiates a Pause frame (full-duplex only).
ETH_BackPressureActivationCmd Enables or disables Back pressure mechanism (half duplex mode). ETH_GetMACFlagStatus Gets MAC flags status.
ETH_GetMACITStatus Gets MAC interrupts status.
ETH_MACITConfig Configures MAC interrupts.
ETH_MACAddressConfig Configures a MAC address.
ETH_GetMACAddress Gets configured MAC address.
ETH_MACAddressPerfectFilterCmd Enables or disables MAC perfect filtering for a selected MAC
address.
DocID022105 Rev 213/48
14/48DocID022105 Rev 2
2.1.1 Ethernet MAC/DMA configuration parameters
The configuration structure for an Ethernet MAC/DMA is ETH_InitTypeDef.This
structure is composed of the following MAC and DMA configuration parameters.
ETH_MACAddressFilterConfig
Configures the MAC address filtering mode.
ETH_MACAddressMaskBytesFilterConf ig
Selects MAC address bytes on which filtering will be performed.
Table 8. Global Ethernet MAC/DMA functions (continued)
Function
Description
Table 9. MAC configuration parameters of an ETH_InitTypeDef structure
Parameter
Description
Default value (1)
ETH_AutoNegotiation
Enables PHY Auto-Negotiation.
ETH_AutoNegotiation_Ena ble
ETH_Watchdog
Enables or disables Watchdog timer during frame reception.
–When enabled, the MAC allows no more than
2048 bytes to be received.
–When disabled, the MAC can receive up to 16384 bytes.
ETH_Watchdog_Enable
ETH_Jabber
–When enabled, the MAC allows no more than 2048 bytes to be sent.
–When disabled, the MAC can send up to 16384 bytes.
ETH_Jabber_Enable
ETH_InterFrameGap Selects the minimum IFG between frames during transmission.ETH_InterFrameGap_96Bit ETH_CarrierSense Enables the Carrier Sense.
ETH_CarrierSense_Enable ETH_Speed
Sets the Ethernet speed: 10/100 Mbps ETH_Speed_100M
ETH_ReceiveOwn Enables the ReceiveOwn.
ReceiveOwn enables the reception of frames when the TX_EN signal is asserted in Half-Duplex mode.
ETH_ReceiveOwn_Enable
ETH_LoopbackMode Enables the internal MAC MII Loopback mode.ETH_LoopbackMode_Disabl e
ETH_Mode
Selects the MAC duplex mode: Half-Duplex or Full-Duplex mode
ETH_Mode_FullDuplex ETH_ChecksumOffload
Enables the IPv4 checksum checking for received frame payloads for TCP/UDP/ICMP packets.
ETH_ChecksumOffload_Dis able
ETH_RetryTransmission
Enables the MAC attempt retries transmission when a collision occurs (Half-Duplex mode).
ETH_RetryTransmission_E nable
ETH_AutomaticPadCRCStri
p
Enables the Automatic MAC Pad/CRC Stripping.
ETH_AutomaticPadCRCStri p_Disable ETH_BackOffLimit
Selects the BackOff limit value.
ETH_BackOffLimit_10
DocID022105 Rev 215/48
ETH_DeferralCheck Enables the deferral check function (Half-Duplex mode).ETH_DeferralCheck_Disab le ETH_ReceiveAll Enables the reception of all frames by the MAC
(No filtering).
ETH_ReceiveAll_Disable
ETH_SourceAddrFilter Enables Source Address Filter mode.
ETH_SourceAddrFilter_Di sable
ETH_PassControlFrames
Sets the forwarding mode of the control frames (including unicast and multicast Pause frames).
ETH_PassControlFrames_B lockAll
ETH_BroadcastFramesRece
ption
Enables the reception of Broadcast frames.
ETH_BroadcastFramesRece ption_Disable
ETH_DestinationAddrFilt er Sets the destination filter mode for both unicast and multicast frames.ETH_DestinationAddrFilt er_Normal ETH_PromiscuousMode
Enables Promiscuous filtering mode.
ETH_PromiscuousMode_Dis
able
ETH_MulticastFramesFilt
er
Selects the Multicast frames filter mode:
None/HashTableFilter/PerfectFilter/PerfectHash
TableFilter.
ETH_MulticastFramesFilt er_Perfect
ETH_UnicastFramesFilter Selects the Unicast frames filter mode:
HashTableFilter/PerfectFilter/PerfectHashTableF
ilter ETH_UnicastFramesFilter
_Perfect
ETH_HashTableHigh This field holds the higher 32 bits of Hash table.0x0ETH_HashTableLow This field holds the lower 32 bits of Hash table.0x0ETH_PauseTime
This field holds the value to be used in the Pause Time field in the transmit of a control frame.
0x0
ETH_ZeroQuantaPause
Enables the automatic generation of Zero-Quanta Pause control frames.
ETH_ZeroQuantaPause_Dis able
ETH_PauseLowThreshold
Configures the threshold of the Pause to be checked for automatic retransmission of Pause frame.
ETH_PauseLowThreshold_M inus4
ETH_UnicastPauseFrameDe tect Enables the MAC detection of the Pause frames
(with MAC Address0 unicast address and
unique multicast address).ETH_UnicastPauseFrameDe
tect_Disable
ETH_ReceiveFlowControl
Enables the MAC to decode the received Pause
frame and disables its transmitter for a specified
time (Pause Time).
ETH_ReceiveFlowControl_
Disable
ETH_TransmitFlowControl
Enables the MAC to transmit Pause frames (Full-Duplex mode) or the MAC back-pressure operation (Half-Duplex mode).
ETH_TransmitFlowControl _Disable
ETH_VLANTagComparison Selects the 12-bit VLAN identifier or the
complete 16-bit VLAN tag for comparison and filtering.
ETH_VLANTagComparison_16Bit
ETH_VLANTagIdentifier
Holds the VLAN tag identifier for receive frames.0x0
1.
The Default Value is the value configured by calling the ETH_StructInit function .
Table 9. MAC configuration parameters of an ETH_InitTypeDef structure (continued)
Parameter
Description
Default value (1)
Table 10. DMA configuration parameters of an ETH_InitTypeDef structure Parameter Description Default value
ETH_DropTCPIPChecksumEr rorFrame Enables the dropping of TCP/IP Checksum Error
Frames.
ETH_DropTCPIPChecksumEr
rorFrame_Disable
ETH_ReceiveStoreForward Enables the Receive store and forward mode.ETH_ReceiveStoreForward _Enable
ETH_FlushReceivedFrame Enables the flushing of received frames.ETH_FlushReceivedFrame_ Enable
ETH_TransmitStoreForwar d Enables Transmit store and forward mode.
ETH_TransmitStoreForwar
d_Enable
ETH_TransmitThresholdCo ntrol Selects of the threshold level of the Transmit
FIFO.
ETH_TransmitThresholdCo
ntrol_64Bytes
ETH_ForwardErrorFrames Enables the forward to the DMA of erroneous
frames.
ETH_ForwardErrorFrames_
Disable
ETH_ForwardUndersizedGo odFrames Enables the Rx FIFO to forward Undersized
frames (frames with no Error and length less
than 64 bytes) including pad-bytes and CRC).
ETH_ForwardUndersizedGo
odFrames_Disable
ETH_ReceiveThresholdCon trol Selects the threshold level of the Receive FIFO.
ETH_ReceiveThresholdCon
trol_64Bytes
ETH_SecondFrameOperate Enables the Operate on second frame mode,
which enables the DMA to process a second
frame of Transmit data even before obtaining the
status for the first frame.
ETH_SecondFrameOperate_
Disable
ETH_AddressAlignedBeats Enables address-aligned beats.ETH_AddressAlignedBeats _Enable
ETH_FixedBurst Enables AHB Master interface fixed burst
transfers.
ETH_FixedBurst_Enable
ETH_RxDMABurstLength Indicates the number of beats in an Rx DMA
burst transfer.
ETH_RxDMABurstLength_32
Beat
ETH_TxDMABurstLength Indicates the number of beats in a Tx DMA burst
transfer.
ETH_TxDMABurstLength_32
Beat
ETH_DescriptorSkipLengt h Specifies the number of words to skip between
two unchained descriptors (Ring mode).
0x0
ETH_DMAArbitration Selects the DMA Tx/Rx arbitration.ETH_DMAArbitration_Roun dRobin_RxTx_1_1
16/48DocID022105 Rev 2
2.2 DMA descriptor handling
descriptors
2.2.1 DMA
The transfer of Ethernet packets between Transmit/Receive FIFOs and memory is
performed by direct memory access (DMA) using transfer descriptors.
Figure3 illustrates the format of an Ethernet DMA descriptor.
Note:The following description does not apply to enhanced DMA descriptors.
As shown in Figure3, the DMA descriptor can have two formats:
?The descriptor points to one data buffer only and the Next Descriptor field points on next DMA descriptor for allowing descriptors chaining mechanism
?The descriptor can point to two data buffers, Buffer1 and Buffer2
In the STM32F4x7 Ethernet driver, the selected DMA descriptor format is the one allowing
descriptor chaining as shown in Figure4.
Note:1An Ethernet packet can span over one or multiple DMA descriptors.
2One DMA descriptor can be used for one Ethernet packet only.
3The last descriptor in the chain points to the first descriptor for forming a ring of descriptors.
DocID022105 Rev 217/48
Figure5 illustrates the buffer and descriptor allocation model in memory for the STM32F4x7
Ethernet driver.
As shown in Figure5, the following arrays are statically allocated in the STM32F4x7
Ethernet driver:
?Two arrays for the DMA descriptors, one for DMA Rx and another for DMA Tx:
ETH_DMADESCTypeDef DMARxDscrTab[ETH_RXBUFNB],
DMATxDscrTab[ETH_TXBUFNB];
?Two arrays of driver buffers, one array for receive buffers and another array for transmit buffers:
uint8_t Rx_Buff[ETH_RXBUFNB][ETH_RX_BUF_SIZE];
uint8_t Tx_Buff[ETH_TXBUFNB][ETH_TX_BUF_SIZE];
where:
–ETH_RXBUFNB: number of driver receive buffers
–ETH_TXBUFNB: number of driver transmit buffers
–ETH_RX_BUF_SIZE: size in bytes of a receive buffer
–ETH_TX_BUF_SIZE: size in bytes of a transmit buffer
The default values for these parameters as defined in file stm32f4x7_eth.h are:
–ETH_RXBUFNB = 4
–ETH_TXBUFNB = 2
–ETH_RX_BUF_SIZE = 1524 (max size of Ethernet packet (1522) + 2 bytes for
32-bit alignment)
–ETH_TX_BUF_SIZE = 1524 (max size of Ethernet packet (1522) + 2 bytes for
32-bit alignment)
The above parameter values can be changed depending on user specific application
needs. This can be done by enabling CUSTOM_DRIVER_BUFFERS_CONFIG and writing
custom values in the stm32f4x7_eth_conf.h configuration file.
18/48DocID022105 Rev 2
DocID022105 Rev 219/48
Note:
The Ethernet driver allows to have a buffer size (ETH_RX_BUF_SIZE or
ETH_TX_BUF_SIZE ) that does not exceed the maximum Ethernet packet size (1522 bytes). Ethernet packets (received or to be transmitted) exceeding the configured buffer size will span over multiple buffers (or descriptors).
2.2.2 DMA descriptor handling functions
Table 11 provides a summary of the main driver functions used for handling DMA descriptors.
Table 11. DMA descriptor functions
Function
Description
ETH_DMARxDescChainInit Initializes DMA Rx Descriptor chain (as shown in Figure 5).
ETH_DMATxDescChainInit Initializes DMA Tx Descriptor chain (as shown in Figure 5)
ETH_CheckFrameReceived
Checks if the frame is received (polling method on OWN bit and other flags of DMA RX descriptor).
ETH_Get_Received_Frame
Gets received frame (when using a polling method).
ETH_Get_Received_Frame_interrupt Gets received frame (when using an interrupt method for detecting received packets).ETH_Prepare_Transmit_Descriptors
Prepares DMA TX descriptors for transmitting a packet (data should already be copied in driver buffers).
ETH_GetRxPktSize
Gets the size of a received packet.ETH_GetDMATxDescFlagStatus Gets flag status of a DMA TX descriptor.ETH_GetDMARxDescFlagStatus Gets flag status of a DMA RX descriptor.ETH_DMATxDescTransmitITConfig Configures Interrupts for a DMA TX descriptor.ETH_DMARxDescReceiveITConfig Configures Interrupts for a DMA RX descriptor.ETH_EnhancedDescriptorCmd (1)
1.Enhanced descriptors must be used if IPv4 checksum offload is activated. The enhanced descriptor format
is enabledeither by: uncommenting USE_ENHANCED_DMA_DESCRIPTORS in stm32f4x7_eth_conf.h file, or, by calling the ETH_EnhancedDescriptorCmd() function.
Enables or disables the Enhanced descriptor structure.
ETH_DMATxDescChecksumInsertionCon fig
Enables or disables TCP/UDP/ICMP checksum
insertion for transmitted packets.ETH_DMATxDescCRCCmd
Enables or disables CRC generation for transmitted packets.ETH_DMATxDescShortFramePaddingCmd Enables or disables adding padding to short
frame to be transmitted.
Note:The Ethernet driver maintains two global pointers for Rx/Tx DMA descriptor tracking, for the next packet to be received or to be transmitted:
__IO ETH_DMADESCTypeDef *DMATxDescToSet;
__IO ETH_DMADESCTypeDef *DMARxDescToGet;
2.3 PHY control functions
Table12 provides a summary of the functions implemented for PHY control by the
STM32F4x7 Ethernet driver.
Note:The PHY configuration options (Reset delay, Configuration delay, Status register Speed and Duplex mask values) are defined in the stm32f4x7_eth_conf.h configuration file. These
values change from a PHY to another, so the user has to update this value depending on
the external PHY used.
Table 12. PHY control functions
Function Description
ETH_ReadPHYRegister Reads a PHY register.
ETH_WritePHYRegister Writes a data into a PHY register.
ETH_PHYLoopBackCmd Enables or disables the PHY loopback mode.
20/48DocID022105 Rev 2