📄 emSecure-ECDSA User Guide & Reference Manual
📄 emSecure-RSA User Guide & Reference Manual
📄 emSSH User Guide & Reference Manual
📄 emSSL User Guide & Reference Manual
📄 emUSB-Device User Guide & Reference Manual
📄 emUSB-Host User Guide & Reference Manual
📄 emWeb User Guide & Reference Manual
📄 IoT Toolkit User Guide & Reference Manual
📄 SEGGER Assembler User Guide & Reference Manual
📄 SEGGER Floating-point Library User Guide & Reference Manual
📄 SEGGER Linker User Guide & Reference Manual
📄 SEGGER Runtime Library User Guide & Reference Manual
📄 embOS & embOS-MPU Real-Time Operating System User Guide & Reference Manual
📄 emCompress-Embed User Guide & Reference Manual
📄 emCompress-Flex User Guide & Reference Manual
📄 emCompress-ToGo User Guide & Reference Manual
📄 emCrypt User Guide & Reference Manual
📄 emDropbox User Guide & Reference Manual
📄 emFile User Guide & Reference Manual
📄 emNet User Guide & Reference Manual

emNet User Guide & Reference Manual

Software Version: 3.40a

CPU independent TCP/IP stack for embedded applications.

Introduction to emNet

This chapter provides an introduction to using emNet. It explains the basic concepts behind emNet.

What is emNet

emNet is a CPU-independent TCP/IP stack.

emNet is a high-performance library that has been optimized for speed, versatility and small memory footprint.

Features

emNet is written in ANSI C and can be used on virtually any CPU.

Some features of emNet:

Basic concepts

emNet structure

emNet is organized in different layers, as shown in the following illustration.

Protocol stack

A short description of each layer’s functionality follows below.

Application layer

The application layer is the interface between emNet and the user application. It uses the emNet API to transmit data over an TCP/IP network. The emNet API provides functions in BSD (Berkeley Software Distribution) socket style, such as connect(), bind(), listen(), etc.

Transport layer

The transport layer provides end-to-end communication services for applications. The two relevant protocols of the Transport layer protocol are the Transmission Control Protocol (TCP) and the User Datagram Protocol (UDP). TCP is a reliable connection-oriented transport service. It provides end-to-end reliability, resequencing, and flow control. UDP is a connectionless transport service.

Internet layer

All protocols of the transport layer use the Internet Protocol (IP) to carry data from source host to destination host. IP is a connectionless service, providing no end-to-end delivery guarantees. IP datagrams may arrive at the destination host damaged, duplicated, out of order, or not at all. The transport layer is responsible for reliable delivery of the datagrams when it is required. The IP protocol includes provision for addressing, type-of-service specification, fragmentation and reassembly, and security information.

Link layer

The link layer provides the implementation of the communication protocol used to interface to the directly-connected network. A variety of communication protocols have been developed and standardized. The most commonly used protocol is Ethernet (IEEE 802.3). In this version of emNet only Ethernet is supported.

Encapsulation

The four layers structure is defined in [RFC 1122]. The data flow starts at the application layer and goes over the transport layer, the network layer, and the link layer. Every protocol adds a protocol-specific header and encapsulates the data and header from the layer above as data. On the receiving side, the data will be extracted in the complementary direction. The opposed protocols do not know which protocol on the above and below layers are used.

The following illustration shows the encapsulation of data within an UDP datagram within an IP packet.

Packet layer encapsulation

Tasks and interrupt usage

emNet can be used in an application in three different ways.

The default task structure is one task dedicated to the stack. The priority of the management task IP_Task should be higher then the priority of all application tasks that use the stack to allow optimal performance. The IP_RxTask (if available) should run at the highest single task priority of all IP related task as it is an interrupt moved into a task.

Task priorities

IP task priorities are independent from other (non IP) task priorities. However as soon as a task calls an IP API it should follow these priority rules for the best performance of the stack:

Task priorities for tasks not using the IP API can be freely chosen.

One task dedicated to the stack

Using one task dedicated to the stack is the simplest way to use the TCP/IP stack. It is called IP_Task and handles housekeeping operations, resending and handling of incoming packets. The “Read packet” operation is performed from within the ISR. Because the “Read packet” operation is called directly from the ISR, no additional task is required. The length of the interrupt latency will be extended for the time period which is required to process the “Read packet” operation. Refer to IP_Task for more information and an example about how to include the IP_Task into your project.

emNet task and interrupt usage. One task dedicated to the stack.

Two tasks dedicated to the stack

The first task is called the IP_Task and handles housekeeping operations, resends, and handling of incoming packets. The second is called IP_RxTask and handles the “Read packet” operation. IP_RxTask is woken up from the interrupt service routine if new packets are available. The interrupt latency is not extended, because the “Read packet” operation has been moved from the interrupt service routine to IP_RxTask. Refer to IP_Task and IP_RxTask for more information. IP_RxTask should have a higher priority than IP_Task as it is treated as interrupt in task form and should not be interrupted by IP_Task or any other IP task.

emNet task and interrupt usage. Two tasks dedicated to the stack.

Note

Initializing the IP stack with two task concept from main()

Packets might receive as soon as Ethernet is initialized by IP_Init() and the (receive) interrupt is enabled. The internal switch between the single task and two task concept gets set automatically upon the first execution of IP_RxTask() . Initializing the stack from main() typically means to initialize it before a task scheduler is active.

If a packet is received between IP_Init() and the first run of IP_RxTask() the packet will be processed like in the single task concept. This should typically cause no problem to the application and the mode is automatically switched to the two task concept as soon as IP_RxTask() has run for the first time.

If it is desired to completely avoid this to happen, the following steps need to be taken care of:

Zero tasks dedicated to the stack (Superloop)

emNet can also be used without any additional task for the stack if an application task calls IP_Exec() periodically. The “Read packet” operation is performed from within the ISR. Because the “Read packet” operation is called directly from the ISR, no additional task is required. The length of the interrupt latency will be extended for the time period which is required to process the “Read packet” operation.

emNet task and interrupt usage. Superloop.

Background information

Components of an Ethernet system

Main parts of an Ethernet system are the Media Access Controller (MAC) and the Physical device (PHY). The MAC handles generating and parsing physical frames and the PHY handles how this data is actually moved to or from the wire.

MCUs with integrated MAC

Some modern MCUs (for example, the ATMEL SAM7X or the ST STR912) include the MAC and use the internal RAM to store the Ethernet data. The following block diagram illustrates such a configuration.

MCU with integrated MAC

External Ethernet controllers with MAC and PHY

Chips without integrated MAC can use fully integrated single chip Ethernet MAC controller with integrated PHY and a general processor interface. The following schematic illustrates such a configuration.

External Ethernet controller with MAC and PHY

MII / RMII: Interface between MAC and PHY

The MAC communicates with the PHY via the Media Independent Interface (MII) or the Reduced Media Independent Interface (RMII). The MII is defined in IEEE 802.3u. The RMII is a subset of the MII and is defined in the RMI specification. The MII/RMII can handle control over the PHY which allows for selection of such transmission criteria as line speed, duplex mode, etc.

In theory, up to 32 PHYs can be connected to a single MAC. In praxis, this is never done; only one PHY is connected. In order to allow multiple PHYs to be connected to a single MAC, individual 5-bit addresses have to be assigned to the different PHYs. If only one PHY is connected, the emNet driver automatically finds the address of it.

The standard defines 32 16-bit PHY registers. The first 6 are defined by the standard.

Register Description
BMCR Basic Mode Control Register
BSR Basic Mode Status Register
PHYSID1 PHYS ID 1
PHYSID2 PHYS ID 2
ANAR Auto-Negotiation Advertisement Register
LPAR Link Partner Ability register

The drivers automatically recognize any PHY connected, no manual configuration of PHY address is required.

The MII and RMII interface are capable of both 10Mb/s and 100Mb/s data rates as described in the IEEE 802.3u standard.

MII/RMII interface

The intent of the RMII is to provide a reduced pin count alternative to the IEEE 802.3u MII. It uses 2 bits for transmit (TXD0 and TXD1) and two bits for receive (RXD0 and RXD1). There is a Transmit Enable (TX_EN), a Receive Error (RX_ER), a Carrier Sense (CRS), and a 50 MHz Reference Clock (TX_CLK) for 100Mb/s data rate. The pins used by the MII and RMII interfaces are described in the following table.

Signal MII RMII
TX_CLK Transmit Clock (25 MHz) Reference Clock (50 MHz)
TX_EN Transmit Enable Transmit Enable
TXD[0:1] 4-bit Transmit Data 2-bit Transmit Data
TXD[2:3] 4-bit Transmit Data (cont’d) N/A
PHYCLK PHY Clock Output PHY Clock Output
CRS Carrier Sense N/A
COL Collision Detect N/A
MDIO Management data I/O Management data I/O
MDC Data Transfer Timing Reference Clock Data Transfer Timing Reference Clock
RX_CLK Receive Clock N/A
RXD[0:1] 4-bit Receive Data 2-bit Receive Data
RXD[2:3] 4-bit Receive Data (cont’d) N/A
RX_DV Data Valid Carrier Sense/Data Valid
RX_ER Receive Error Receive Error

Further reading

This guide explains the usage of the emNet protocol stack. It describes all functions which are required to build a network application. For a deeper understanding about how the protocols of the Internet protocol suite works use the following references.

The following Request for Comments (RFC) define the relevant protocols of the Internet protocol suite and have been used to build the protocol stack. They contain all required technical specifications. The listed books are simpler to read as the RFCs and give a general survey about the interconnection of the different protocols.

Request for Comments (RFC)

RFC# Description
[RFC 768] UDP - User Datagram Protocol Direct download: ftp://ftp.rfc-editor.org/in-notes/rfc768.txt
[RFC 791] IP - Internet Protocol Direct download: ftp://ftp.rfc-editor.org/in-notes/rfc791.txt
[RFC 792] ICMP - Internet Control Message Protocol Direct download: ftp://ftp.rfc-editor.org/in-notes/rfc792.txt
[RFC 793] TCP - Transmission Control Protocol Direct download: ftp://ftp.rfc-editor.org/in-notes/rfc793.txt
[RFC 821] SMTP - Simple Mail Transfer Protocol Direct download: ftp://ftp.rfc-editor.org/in-notes/rfc826.txt
[RFC 826] ARP - Ethernet Address Resolution Protocol Direct download: ftp://ftp.rfc-editor.org/in-notes/rfc826.txt
[RFC 951] BOOTP - Bootstrap Protocol Direct download: ftp://ftp.rfc-editor.org/in-notes/rfc951.txt
[RFC 959] FTP - File Transfer Protocol Direct download: ftp://ftp.rfc-editor.org/in-notes/rfc959.txt
[RFC 1034] DNS - Domain names - concepts and facilities Direct download: ftp://ftp.rfc-editor.org/in-notes/rfc1034.txt
[RFC 1035] DNS - Domain names - implementation and specification Direct download: ftp://ftp.rfc-editor.org/in-notes/rfc1035.txt
[RFC 1042] IE-EEE - Transmission of IP datagrams over IEEE 802 networks Direct download: ftp://ftp.rfc-editor.org/in-notes/rfc1042.txt
[RFC 1122] Requirements for Internet Hosts - Communication Layers Direct download: ftp://ftp.rfc-editor.org/in-notes/rfc1122.txt
[RFC 1123] Requirements for Internet Hosts - Application and Support Direct download: ftp://ftp.rfc-editor.org/in-notes/rfc1123.txt
[RFC 1661] PPP - Point-to-Point Protocol Direct download: ftp://ftp.rfc-editor.org/in-notes/rfc1661.txt
[RFC 1939] POP3 - Post Office Protocol - Version 3 Direct download: ftp://ftp.rfc-editor.org/in-notes/rfc1939.txt
[RFC 2131] DHCP - Dynamic Host Configuration Protocol Direct download: ftp://ftp.rfc-editor.org/in-notes/rfc2131.txt
[RFC 2616] HTTP - Hypertext Transfer Protocol -- HTTP/1.1 Direct download: ftp://ftp.rfc-editor.org/in-notes/rfc2616.txt

Development environment (compiler)

The CPU used is of no importance; only an ANSI-compliant C compiler complying with at least one of the following international standard is required:

If your compiler has some limitations, let us know and we will inform you if these will be a problem when compiling the software. Any compiler for 16/32/64-bit CPUs or DSPs that we know of can be used; most 8-bit compilers can be used as well.

A C++ compiler is not required, but can be used. The application program can therefore also be programmed in C++ if desired.

Running emNet on target hardware

This chapter explains how to integrate and run emNet on your target hardware. It explains this process step-by-step.

Integrating emNet

The emNet default configuration is preconfigured with valid values, which matches the requirements of the most applications. emNet is designed to be used with embOS, SEGGER’s real-time operating system. We recommend to start with an embOS sample project and include emNet into this project. We assume that you are familiar with the tools you have selected for your project (compiler, project manager, linker, etc.). You should therefore be able to add files, add directories to the include search path, and so on. In this document the SEGGER Embedded Studio is used for all examples and screenshots, but every other ANSI C toolchain can also be used. It is also possible to use make files; in this case, when we say “add to the project”, this translates into “add to the make file”.

Procedure to follow

Integration of emNet is a relatively simple process, which consists of the following steps:

Step 1: Open an embOS start project

We recommend that you use one of the supplied embOS start projects for your target system. Compile the project and run it on your target hardware.

embOS start project

Step 2: Adding emNet to the start project

Add all IP source files as in the IP release delivery to your project.

The Config folder includes all configuration files of emNet. The configuration files are preconfigured with valid values, which match the requirements of most applications. Add the hardware configuration IP_Config_<TargetName>.c supplied with the driver shipment.

If your hardware is currently not supported, use the example configuration file and the driver template to write your own driver. The example configuration file and the driver template is located in the Sample folder.

The IP\ASM folder contains files for various CPUs and toolchains with routines optimized in assembler code. Typically only one of these files needs to be added to your project and the rest should be excluded. The optimized routines are used by overwriting a specific macro that typically can be found in Config\IP_Conf.h.

The SEGGER folder is an optional component of the emNet shipment. It contains optimized MCU and/or compiler specific files, for example a special memcopy function.

BSP support

IP drivers need hardware setting from the BSP file (like port settings for example). Some older driver are supplied with BSP.c and BSP.h that need to replace the one supplied with embOS shipment.

Newer and updated drivers have a separate BSP_IP.c file instead.

Depending on your case, either replace BSP.c and BSP.h of your embOS start project or add BSP_IP.c.

Configuring the include path

The include path is the path in which the compiler looks for include files. In cases where the included files (typically header files, .h ) do not reside in the same directory as the C file to compile, an include path needs to be set. In order to build the project with all added files, you will need to add the IP directories to your include path.

Select the start application

For quick and easy testing of your emNet integration, start with the code found in the folder Application. Add one of the applications to your project (for example IP_SimpleServer.c).

Include emNet in embOS project

Step 3: Build the project and test it

Build the project. It should compile without errors and warnings. If you encounter any problem during the build process, check your include path and your project configuration settings. To test the project, download the output into your target and start the application.

By default, ICMP is activated. This means that you could ping your target. Open the command line interface of your operating system and enter ping <TargetAddress>, to check if the stack runs on your target. The target should answer all pings without any error.

Ping emNet target

Example applications

In this chapter, you will find a description of each emNet example application.

Overview

Various example applications for emNet are supplied. These can be used for testing the correct installation and proper function of the device running emNet.

The following start application files are provided:

File Description
IP_DNSClient.c Demonstrates the use of the integrated DNS client.
IP_NonBlockingConnect.c Demonstrates how to connect to a server using non-blocking sockets.
IP_Ping.c Demonstrates how to send ICMP echo requests and how to process ICMP replies in application.
IP_SHELL_Start.c Demonstrates using the IP-shell to diagnose the IP stack.
IP_SimpleServer.c Demonstrates setup of a simple server which simply sends back the target system tick for every character received.
IP_SpeedClient_TCP.c Demonstrates the TCP send and receive performance of the device running emNet.
IP_Start.c Demonstrates use of the IP stack without any server or client program. To ping the target, use the command line: ping <target-ip> where <target-ip> represents the IP address of the target, which depends on the configuration and is usually 192.168.2.252 if the DHCP client is not enabled.
IP_UDPDiscover.c Demonstrates setup of a simple UDP application which replies to UDP broadcasts. The application sends an answer for every received discover packet. The related host application sends discover packets as UDP broadcasts and waits for the feedback of the targets which are available in the subnet.
IP_UDPDiscover_ZeroCopy.c Demonstrates setup of a simple UDP application which replies to UDP broadcasts. The application uses the the emNet zero-copy interface. It sends an answer for every received discover packet. The related host application sends discover packets as UDP broadcasts and waits for the feedback of the targets which are available in the subnet.

The example applications for the target-side are supplied in source code in the Application directory.

emNet DNS client (IP_DNSClient.c)

The emNet DNS client resolves a hostname (for example, segger.com) to an IP address and outputs the resolved address via terminal I/O.

emNet non-blocking connect (IP_NonBlockingConnect.c)

The emNet non-blocking connect sample demonstrates how to connect to a server using non-blocking sockets. The target tries to connect to TCP server with an non-blocking socket. The sample can be used with any TCP server independent of the application which is listening on the port. The client only opens a TCP connection to the server and closes it without any further communication. The terminal I/O output in your debugger should be similar to the following out:

Connecting using non-blocking socket...
Successfully connected after 2ms!
1 of 1 tries were successful.

Connecting using non-blocking socket...
Successfully connected after 1ms!
2 of 2 tries were successful.

emNet ping (IP_Ping.c)

The emNet ping sample demonstrates how to send ICMP echo requests and how to process received ICMP packets in your application. A callback function is implemented which outputs a message if an ICMP echo reply or an ICMP echo request has been received.

To test the emNet ICMP implementation, you have to perform the following steps:

ping [IP_ADDRESS _OF_YOUR_TARGET_RUNNING_EMNET]

The terminal I/O output in your debugger should be similar to the following out:

ICMP echo reply received!
ICMP echo request received!
ICMP echo reply received!
ICMP echo reply received!
ICMP echo reply received!
ICMP echo reply received!
ICMP echo request received!
ICMP echo reply received!
ICMP echo reply received!
ICMP echo reply received!

emNet shell (IP_SHELL_Start.c)

The emNet shell server is a task which opens TCP-port 23 (telnet) and waits for a connection. The actual shell server is part of the stack, which keep the application program nice and small. The shell server task can be added to any application and should be used to retrieve status information while the target is running. To connect to the target, use the command line: telnet <target-ip> where <target-ip> represents the IP address of the target, which depends on the configuration and is usually 192.168.2.252 if the DHCP client is not enabled.

emNet Shell sample

emNet simple server (IP_SimpleServer.c)

Demonstrates setup of a simple server which simply sends back the target system tick for every character received. It opens TCP-port 23 (telnet) and waits for a connection. To connect to the target, use the command line: telnet <target-ip> where <target-ip> represents the IP address of the target, which depends on the configuration and is usually 192.168.2.252 if the DHCP client is not enabled.

emNet speed client (IP_SpeedClient_TCP.c)

The emNet speed client is a small application to detect the TCP send and receive performance of emNet on your hardware.

Running the emNet speed client

To test the emNet performance, you have to perform the following steps:

emNet performance test application SpeedClient

emNet start (IP_Start.c)

Demonstrates use of the IP stack without any server or client program. To ping the target, use the command line: ping <target-ip> where <target-ip> represents the IP address of the target, which depends on the configuration and is usually 192.168.2.252 if the DHCP client is not enabled.

emNet UDP discover (IP_UDPDiscover.c / IP_UDPDiscover_ZeroCopy.c)

To test the emNet UDP discover example, you have to perform the following steps:

Core functions

In this chapter, you will find a description of each emNet core function.

API functions

The table below lists the available API functions within their respective categories.

Function Description
Configuration functions
IP_AddBuffers() Adds buffers to the TCP/IP stack.
IP_AddEtherInterface() Adds an Ethernet interface to the stack.
IP_AddVirtEtherInterface() Adds a virtual interface to the stack that uses a hardware interface for communication.
IP_AddLoopbackInterface() Adds a loopback interface to the stack.
IP_AddMemory() This function is called from the application to add additional memory to the stack.
IP_AllowBackPressure() Allows back pressure if the driver supports this feature.
IP_AssignMemory() Assigns memory to the stack.
IP_ARP_ConfigAgeout() Configures the timeout for cached ARP entries.
IP_ARP_ConfigAgeoutNoReply() Configures the timeout for an ARP entry that has been added due to sending an ARP request to the network that has not been answered yet.
IP_ARP_ConfigAgeoutSniff() Configures the age out value for ARP entries, which we have created by looking up addresses of received IP packets.
IP_ARP_ConfigAllowGratuitousARP() Configures if gratuitous ARP packets from other network members are allowed to update the ARP cache.
IP_ARP_ConfigMaxPending() Configures the maximum number packets that can be queued waiting for an ARP reply.
IP_ARP_ConfigMaxRetries() Configures how often an ARP request is resent before considering the request failed.
IP_ARP_ConfigNumEntries() Configures the maximum number of possible entries in the ARP cache.
IP_BSP_SetAPI() Sets an API to be used for BSP related abstraction like initializing hardware and installing interrupt handlers.
IP_ConfigMaxIFaces() Configures the maximum number of interfaces that can be added to the system.
IP_ConfigNumLinkDownProbes() Configures the number of continuous link down probes to take before the stack accepts the link down status.
IP_ConfigNumLinkUpProbes() Configures the number of continuous link up probes to take before the stack accepts the link up status.
IP_ConfigOffCached2Uncached() Configures the offset from a cached memory area to its uncached equivalent for uncached access.
IP_ConfigReportSameMacOnNet() Configures if the stack warns about receiving an Ethernet packet from the same HW address as the interface the packet came in.
IP_ConfigTCPSpace() Configures the size of the TCP send and receive window size.
IP_DisableIPRxChecksum() Disables checksum verification of the checksum in the IP header for incoming packets.
IP_DisableIPv4() Disables IPv4 in the stack as good as possible.
IP_CACHE_SetConfig() Configures cache related functionality that might be required by the stack for several purposes such as cache handling in drivers.
IP_DNS_GetServer() Retrieves the first DNS server configured of the first interface.
IP_DNS_GetServerEx() Retrieves a DNS server configured for an interface.
IP_DNS_ResolveHostEx() Sends a query to the DNS server.
IP_DNS_SendDynUpdate() Build a dynamic update request.
IP_DNS_SetTSIGContext() Set the TSIG signature context with the parameters needed to perform Secured Dynamic Updates signed with TSIG.
IP_DNS_SetMaxTTL() Sets the maximum Time To Live (TTL) of a DNS entry in seconds.
IP_DNS_SetServer() Sets the DNS server address of the first interface.
IP_DNS_SetServerEx() Sets the IP address of the available DNS servers for an interface.
IP_MDNS_ResolveHost() Sends a query using Multicast DNS.
IP_MDNS_ResolveHostSingleIP() Sends a query using Multicast DNS.
IP_EnableIPRxChecksum() Enables the IP Rx checksum calculation in the IP header for incoming packets.
IP_GetMaxAvailPacketSize() Asks the stack for the maximum available free packet size that can then be allocated.
IP_GetMTU() Retrieves the configured TCP MTU size for an interface.
IP_GetPrimaryIFace() Retrieves the currently set primary interface index.
IP_ICMP_Add() Adds ICMP Protocol function to the stack.
IP_ICMP_DisableRxChecksum() Disables the ICMP Rx checksum calculation.
IP_ICMP_EnableRxChecksum() Enables the ICMP Rx checksum calculation.
IP_IGMP_Add() Adds IGMP Protocol function to stack for interface 0.
IP_IGMP_AddEx() Adds IGMP Protocol function to the stack for a specified interface.
IP_IGMP_JoinGroup() Joins an IGMP group.
IP_IGMP_LeaveGroup() Leaves an IGMP group.
IP_RAW_Add() Adds RAW socket function to stack.
IP_SetAddrMask() Sets the IP address and subnet mask of an interface.
IP_SetAddrMaskEx() Sets the IP address and subnet mask of an interface.
IP_SetGWAddr() Sets the default gateway address of the selected interface.
IP_SetHWAddr() Sets the Media Access Control address (MAC) of the interface 0.
IP_SetHWAddrEx() Sets the Media Access Control address (MAC) of the selected interface.
IP_SetMTU() Allows to set the maximum transmission unit (MTU) of an interface.
IP_SetMicrosecondsCallback() Sets a callback that is used to get a timestamp in microseconds.
IP_SetNanosecondsCallback() Sets a callback that is used to get a timestamp in nanoseconds.
IP_SetPrimaryIFace() Sets the primary interface index.
IP_SetSupportedDuplexModes() Allows to set the allowed duplex mode of the device.
IP_SetTTL() Sets the default value for the Time-To-Live IP header field.
IP_SetGlobalMcTTL() Sets the default value for the Time-To-Live IP header field for global mulicast packets.
IP_SetLocalMcTTL() Sets the default value for the Time-To-Live IP header field for local mulicast packets.
IP_SetUseRxTask() Sets the internal flag for using the IP_RxTask() manually.
IP_SOCKET_ConfigSelectMultiplicator() Configures the multiplicator for the timeout parameter of select().
IP_SOCKET_SetDefaultOptions() Sets the socket options enabled by default.
IP_SOCKET_SetLimit() Sets the maximum number of allowed sockets.
IP_SYSVIEW_Init() Initializes the profile instrumentation of the stack and SystemView as profiling implementation.
IP_TCP_Add() Adds TCP Protocol function to the stack.
IP_TCP_DisableRxChecksum() Disables the TCP Rx checksum calculation.
IP_TCP_EnableRxChecksum() Enables checksum verification of the checksum in the TCP header for incoming packets.
IP_TCP_Set2MSLDelay() Sets the maximum segment lifetime (MSL).
IP_TCP_SetConnKeepaliveOpt() Sets the keepalive options.
IP_TCP_SetRetransDelayRange() Sets retransmission delay range.
IP_UDP_Add() Adds UDP Protocol support to the stack.
IP_UDP_AddEchoServer() Adds a simple echo server for UDP packets that can be used for UDP pings and other tests.
IP_UDP_DisableRxChecksum() Disables checksum verification of the checksum in the UDP header for incoming packets.
IP_UDP_EnableRxChecksum() Enables checksum verification of the checksum in the TCP header for incoming packets.
Configuration functions (IP fragmentation)
IP_FRAGMENT_ConfigRx() Modifies the default settings for IPv4 fragmentation.
IP_FRAGMENT_Enable() Initializes the required variables and adds a timer to the stack to handle outdated fragment queues.
IP_IPV6_FRAGMENT_ConfigRx() Modifies the default settings for IPv6 fragmentation.
IP_IPV6_FRAGMENT_Enable() Initializes the required variables and adds a timer to the stack to handle outdated fragment queues.
Management functions
IP_DeInit() Deinitializes the TCP/IP stack.
IP_Init() Initializes the TCP/IP stack.
IP_Task() Main task for starting the stack.
IP_RxTask() The task reads all available packets from the network interface and sleeps until a new packet is received.
IP_Exec() Checks if the driver has received a packet and handles timers.
Network interface configuration and handling functions
IP_NI_AddPTPDriver() Adds an NI specific PTP driver for HW timestamp support.
IP_NI_ClrBPressure() Disables usage of back pressure (sending a jam signal to signal when we run into a shortage where the hardware can not receive more data).
IP_NI_ConfigPoll() Select polled mode for the network interface.
IP_NI_ForceCaps() Allows to force capabilities to be set for an interface.
IP_NI_SetBPressure() Enables usage of back pressure (sending a jam signal to signal when we run into a shortage where the hardware can not receive more data).
IP_NI_SetTxBufferSize() Sets the size of the Tx buffer of the network interface.
PHY configuration functions
IP_NI_ConfigPHYAddr() Configure the PHY Addr.
IP_NI_ConfigPHYMode() Configure the PHY mode.
IP_PHY_AddDriver() Adds a PHY driver and assigns it to an interface.
IP_PHY_AddResetHook() This function adds a hook function to the IP_HOOK_ON_PHY_RESET list.
IP_PHY_ConfigAddr() Configures the PHY address to use.
IP_PHY_ConfigAltAddr() Sets a list of PHY addresses that can alternately be checked for the link state.
IP_PHY_ConfigGigabitSupport() Configures if the MAC supports Gigabit Ethernet.
IP_PHY_ConfigSupportedModes() Configures the duplex and speed modes that shall be supported.
IP_PHY_ConfigUseStaticFilters() Tells the stack if using PHY static MAC filter is allowed.
IP_PHY_DisableCheck() Disables PHY checks for all interfaces.
IP_PHY_DisableCheckEx() Disables PHY checks for one interface.
IP_PHY_ReInit() Re-initializes the PHY.
IP_PHY_SetWdTimeout() Sets the watchdog timeout for watching if the PHY reached an unstable state.
Statistics functions
IP_STATS_EnableIFaceCounters() Enables statistic counters for a specific interface.
IP_STATS_GetIFaceCounters() Retrieves a pointer to the statistic counters for a specific interface.
IP_STATS_GetLastLinkStateChange() Retrieves the tick count when an interface entered its current state.
IP_STATS_GetRxBytesCnt() Retrieves the number of bytes received on an interface.
IP_STATS_GetRxDiscardCnt() Retrieves the number of packets received but discarded although they were O.K.
IP_STATS_GetRxErrCnt() Retrieves the number of receive errors.
IP_STATS_GetRxNotUnicastCnt() Retrieves the number of packets received on an interface that were not unicasts.
IP_STATS_GetRxUnicastCnt() Retrieves the number of unicast packets received on an interface.
IP_STATS_GetRxUnknownProtoCnt() Retrieves the number of unknown protocols received.
IP_STATS_GetTxBytesCnt() Retrieves the number of bytes sent on an interface.
IP_STATS_GetTxDiscardCnt() Retrieves the number of packets to send but discarded although they were O.K.
IP_STATS_GetTxErrCnt() Retrieves the number of send errors on an interface.
IP_STATS_GetTxNotUnicastCnt() Retrieves the number of packets sent on an interface that were not unicasts.
IP_STATS_GetTxUnicastCnt() Retrieves the number of unicast packets sent on an interface.
Other IP stack functions
IP_AddAfterInitHook() Adds a hook to a callback that is executed at the end of IP_Init() to allow adding initializations to be executed right after the stack itself has been initialized and all API can be used.
IP_AddEtherTypeHook() This function registers a callback to be called for received packets with the registered Ethernet type.
IP_AddLinkChangeHook() Adds a callback that gets executed each time the link state changes.
IP_AddOnPacketFreeHook() This function adds a hook function to the IP_HOOK_ON_PACKET_FREE list.
IP_AddStateChangeHook() Adds a hook to a callback that is executed when the AdminState or HWState of an interface changes.
IP_Alloc() Thread safe memory allocation from main IP stack memory pool.
IP_AllocEtherPacket() Allocates a packet to store the raw data of an Ethernet packet of up to NumBytes at the location returned by ppBuffer.
IP_AllocEx() Thread safe memory allocation from a specific memory pool managed by the stack that has been added using IP_AddMemory().
IP_ARP_CleanCache() Cleans all ARP entries that are not static entries.
IP_ARP_CleanCacheByInterface() Cleans all ARP entries that are known to belong to a specific interface and are not static entries.
IP_Connect() Calls a previously registered hook for the interface if any was set using IP_SetIFaceConnectHook().
IP_Disconnect() Calls a previously registered hook for the interface if any was set using IP_SetIFaceDisconnectHook().
IP_Err2Str() Converts IP stack error code to a readable string by simply using the defines name.
IP_FindIFaceByIP() Tries to find out the interface number when only the IP address is known.
IP_Free() Thread safe memory free to IP stack memory pools.
IP_FreePacket() Frees a packet back to the stack.
IP_GetAddrMask() Retrieves the IP address and subnet mask of an interface.
IP_GetCurrentLinkSpeed() Returns the current link speed of the first interface (interface ID 0).
IP_GetCurrentLinkSpeedEx() Returns the current link speed of the requested interface.
IP_GetFreePacketCnt() Checks how many packets for a specific size or greater are currently available in the system.
IP_GetIFaceHeaderSize() Retrieves the size of the header necessary for the transport medium that is used by a specific interface.
IP_GetGWAddr() Returns the gateway address of the interface in host endianess.
IP_GetHWAddr() Returns the hardware address (Media Access Control address) of the interface.
IP_GetIPAddr() Returns the IP address of the interface in host endianess.
IP_GetIPPacketInfo() Returns the start address of the data part of an IP_PACKET.
IP_GetRawPacketInfo() Returns the start address of the raw data of an IP_PACKET.
IP_GetVersion() Returns the version of the stack.
IP_ICMP_SetRxHook() Sets a hook function which will be called if target receives a ping packet.
IP_IFaceIsReady() Checks if the interface is ready for usage.
IP_IFaceIsReadyEx() Checks if the specified interface is ready for usage.
IP_IsAllZero() Checks if there are zeros at the given pointer.
IP_IsExpired() Checks if the given system timestamp has already expired.
IP_NI_ConfigLinkCheckMultiplier() Configures the multiplier of the period between interface link checks typically executed each second.
IP_NI_ConfigUsePromiscuousMode() Configures if the driver tries to use its hardware precise and hash filters as available before switching to promiscuous mode or if promiscuous mode will be used in any case.
IP_NI_GetAdminState() Retrieves the admin state of the given interface.
IP_NI_GetIFaceType() Retrieves a short textual description of the interface type.
IP_NI_GetState() Returns the hardware state of the interface.
IP_NI_SetAdminState() Sets the AdminState of the interface.
IP_NI_GetTxQueueLen() Retrieves the current length of the Tx queue of an interface.
IP_NI_PauseRx() Pauses the Rx handling of an interface by disabling it temporary.
IP_NI_PauseRxInt() Pauses the Rx interrupt of an interface by disabling it temporary.
IP_PrintIPAddr() Convert a 4-byte IP address to a dots-and-number string.
IP_ResolveHost() Resolve a host name string to its IP addresse by using a configured DNS server.
IP_SendEtherPacket() Sends a previously allocated Ethernet packet.
IP_SendPacket() Sends a user defined packet on the interface.
IP_SendPing() Sends a single ICMP echo request (“ping”) to the specified host.
IP_SendPingCheckReply() Sends a single ICMP echo request (“ping”) to the specified host using the selected interface and waits for the reply.
IP_SendPingEx() Sends a single ICMP echo request (“ping”) to the specified host using the selected interface.
IP_SetIFaceConnectHook() Sets a hook for an interface that is executed when IP_Connect() is called.
IP_SetIFaceDisconnectHook() Sets a hook for an interface that is executed when IP_Disconnect() is called.
IP_SetOnPacketFreeCallback() This function sets a callback to be executed once the packet has been freed.
IP_SetPacketToS() Sets the value of the ToS/DSCP byte in the IP header of a packet to be sent via the zero-copy API.
IP_SetRxHook() Sets a hook function which will be called if target receives a packet.
IP_SetRandCallback() Sets a callback that can provide random data.

Configuration functions

IP_AddBuffers()

Description

Adds buffers to the TCP/IP stack. This is a configuration function, typically called from IP_X_Config(). It needs to be called 2 times, one per buffer size.

Prototype

void IP_AddBuffers(int NumBuffers,
                   int BytesPerBuffer);

Parameters

Parameter Description
NumBuffers The number of buffers.
BytesPerBuffer Size of buffers in bytes.

Additional information

The stack requires small and large buffers. We recommend to define the size of the big buffers to 1536 to allow a full Ethernet packet to fit. The small buffers are used to store packets which encapsulates no or few application data like protocol management packets (TCP SYNs, TCP ACKs, etc.). We recommend to define the size of the small buffers to 256 bytes.

Example

IP_AddBuffers(20, 256);          // 20 small buffers, each 256 bytes.
IP_AddBuffers(12, 1536);         // 12 big buffers, each 1536 bytes.

IP_AddEtherInterface()

Description

Adds an Ethernet interface to the stack.

Prototype

int IP_AddEtherInterface(const IP_HW_DRIVER* pDriver);

Parameters

Parameter Description
pDriver Pointer to a network interface driver structure.

Return value

Zero-based interface index of the newly created interface.

Additional information

While the order in which interfaces are added to the stack does not matter to the stack itself, it might be important for the driver to add.

Typically drivers for CPU integrated controllers are expected to be added first. Next drivers for external controllers can be added. As external controllers can be used as an extension to internal controllers they do not rely on a specific interface order.

To fill in gaps in the order of interfaces added, a dummy driver IP_Driver_Dummy can be added. A sample of such a configuration would be an application that relies on the following order: - IFace0: Internal controller - IFace1: External WiFi module The same hardware might be produced with a different configuration like only providing WiFi but using a cheaper CPU without internal controller. In this case the dummy driver can be used to keep up the same order: - IFace0: Dummy - IFace1: External WiFi module

For drivers and hardware that supports dual Ethernet the requirement to add drivers for internal controllers remain. For using both internal controllers this means: - IFace0: First internal controller - IFace1: Second internal controller - IFace2: External WiFi module When using only the second internal controller the interface index needs to be pushed by using the dummy driver again: - IFace0: Dummy - IFace1: Second internal controller - IFace2: External WiFi module However for using only the first controller of a driver that supports a dual unit, no dummy needs to be added before adding additional external drivers: - IFace0: First internal controller, second is not used. - IFace1: External WiFi module

Additional information

Refer to Available network interface drivers for a list of available network interface drivers.

Example

IP_AddEtherInterface(&IP_Driver_SAM7X);  // Add Ethernet driver for your hardware

IP_AddVirtEtherInterface()

Description

Adds a virtual interface to the stack that uses a hardware interface for communication.

Prototype

int IP_AddVirtEtherInterface(unsigned HWIFaceId);

Parameters

Parameter Description
HWIFaceId Zero-based interface index of the hardware interface.

Return value

Zero-based interface index of the newly created interface.

Additional information

Virtual interfaces can be added to allow configuration of multiple IP addresses on the same target. One configuration can be assigned per interface.

Example

int IFaceId;

IFaceId = IP_AddEtherInterface(&IP_Driver_SAM7X);  // Add HW Ethernet driver
IP_AddVirtEtherInterface(IFaceId);

IP_AddLoopbackInterface()

Description

Adds a loopback interface to the stack.

Prototype

int IP_AddLoopbackInterface(void);

Return value

Zero-based interface index of the newly created interface.

Additional information

The loopback interface will be added with the pre-configured static IP addresse of 127.0.0.1/8.

Example

IP_AddLoopbackInterface();  // Add an Ethernet loopback interface.

IP_AddMemory()

Description

This function is called from the application to add additional memory to the stack. IP_AssignMemory() needs to be called first.

Prototype

void IP_AddMemory(U32* pMem,
                  U32  NumBytes);

Parameters

Parameter Description
pMem A pointer to the start of the memory region which should be added.
NumBytes Number of bytes which should be added.

Additional information

This function can be used to add additional memory to the stack that can then be requested by application level modules such as Web server or FTP server directly from the stacks memory management.

For further information about the available memory management functions, refer to IP_Alloc and IP_Free.

Example

#define MEM_SIZE  0x8000  // Size of memory to add to the stack in bytes.
U32 _aMem[MEM_SIZE / 4];  // Memory area to add to the stack.

IP_AddMemory(_aMem, sizeof(_aMem));

IP_AllowBackPressure()

Description

Allows back pressure if the driver supports this feature.

Prototype

void IP_AllowBackPressure(char v);

Parameters

Parameter Description
v 0 to disable, 1 to enable back pressure.

IP_AssignMemory()

Description

Assigns memory to the stack.

Prototype

void IP_AssignMemory(U32* pMem,
                     U32  NumBytes);

Parameters

Parameter Description
pMem A pointer to the start of the memory region which should be assigned.
NumBytes Number of bytes which should be assigned.

Additional information

IP_AssignMemory() should be the first function which is called in IP_X_Config(). The amount of RAM required depends on the configuration and the respective application purpose. The assigned memory pool is required for the socket buffers, memory buffers, etc.

Example

#define ALLOC_SIZE      0x8000   // Size of memory dedicated to the stack in bytes
U32 _aPool[ALLOC_SIZE / 4];      // Memory area used by the stack.

IP_AssignMemory(_aPool, sizeof(_aPool));

IP_ARP_ConfigAgeout()

Description

Configures the timeout for cached ARP entries. The ARP timer removes entries which have not been used for a time longer than AgeOut.

Prototype

void IP_ARP_ConfigAgeout(U32 Ageout);

Parameters

Parameter Description
Ageout  in  Timeout in ms after which an entry is deleted from the ARP cache. Default: 30s.

IP_ARP_ConfigAgeoutNoReply()

Description

Configures the timeout for an ARP entry that has been added due to sending an ARP request to the network that has not been answered yet.

Prototype

void IP_ARP_ConfigAgeoutNoReply(U32 Ageout);

Parameters

Parameter Description
Ageout  in  Timeout in ms after which an entry is dele