1.2.3.2 UDP Module
UDP is a standard transport layer_protocol described in RFC 768. It provides fast but unreliable data-gram based transfers over networks, and forms the foundation SNTP, SNMP, DNS, and many other protocol standards.
Abstraction Model
This module provides software abstraction of the UDP module existent in any TCP/IP Stack implementation. It allows a user to UDP network traffic by opening and using UDP sockets
How the Library Works
Connections over UDP should be thought of as data-gram based transfers. Each packet is a separate entity, the application should expect some packets to arrive out-of-order or even fail to reach the destination node. This is in contrast to TCP, in which the connection is thought of as a stream and network errors are automatically corrected. These tradeoffs in reliability are made for an increase in throughput. In general, UDP transfers operate two to three times faster than those made over TCP.
UDP sockets have their own TX buffers. Once the transmit buffer has valid data it is the socket_user's responsibility to send the data over the network , calling the corresponding TCPIP_UDP_Flush function.
There is no state machine within the UDP module to automatically take care of the data transmission.
On the receive side, a UDP socket_does not have its own RX buffer; however, it will use the RX buffer that was allocated by the corresponding MAC driver for receiving a network packet. What this means is that the user of the UDP socket_will have to consume that pending RX data (or discard it), because eventually, the stack will run out of memory for other incoming traffic.
The following flow diagram provides an overview for the use of the UDP module:
Server/listening sockets are opened using TCPIP_UDP_ServerOpen. Client sockets are opened using TCPIP_UDP_ClientOpen. A client socket_needs to have a remote address specified before it can transmit data.
Once the socket_is opened, you can immediately begin transmitting data. To transmit a segment, call TCPIP_UDP_PutIsReady to determine how many bytes can be written. Then, use any of the TCPIP_UDP_ArrayPut family of functions to write data to the_socket. Once all data has been written, call TCPIP_UDP_Flush to build and transmit the packet. Since each UDP socket_has its own TX buffer, the sequence previously described can be executed in multiple steps. That data that is written in the socket_is persistent and it will be stored until TCPIP_UDP_Flush is called.
Library Interface
Name | Description |
---|---|
Macros | |
TCPIP_UDP_MAX_SOCKETS | Maximum number of UDP sockets that can be opened simultaneously These sockets will be created when the module is initialized. |
TCPIP_UDP_SOCKET_DEFAULT_RX_QUEUE_LIMIT | The maximum number of RX packets that can be queued by an UDP socket at a certain time. Note that UDP sockets do not use their own RX buffers but instead use the network driver supplied packets and a timely processing is critical to avoid packet memory starvation for the whole stack. This symbol sets the maximum number of UDP buffers/packets that can be queued for a UDP socket at a certain time. Once this limit is reached further incoming packets are silently discarded. Adjust depending on the number of RX buffers that are available for the stack and the... more |
TCPIP_UDP_SOCKET_DEFAULT_TX_QUEUE_LIMIT | The maximum number of TX packets that can be queued by an UDP socket at a certain time. For sockets that need to transfer a lot of data (Iperf, for example), especially on slow connections this limit prevents running out of memory because the MAC/PHY transfer cannot keep up with the UDP packet allocation rate imposed by the application. Adjust depending on the TCPIP_UDP_SOCKET_DEFAULT_TX_SIZE, the connection speed and the amount of memory available to the stack. |
TCPIP_UDP_SOCKET_DEFAULT_TX_SIZE | Default socket TX buffer size. Note that this setting affects all UDP sockets that are created and, together with TCPIP_UDP_MAX_SOCKETS, has a great impact on the heap size that's used by the stack (see TCPIP_STACK_DRAM_SIZE setting). When large TX bufferrs are needed, probably a dynamic, per socket approach, is a better choice (see TCPIP_UDP_OptionsSet function). |
TCPIP_UDP_SOCKET_POOL_BUFFER_SIZE | Size of the buffers in the UDP pool. Any UDP socket that is enabled to use the pool and has the TX size <= than this size can use a buffer from the pool. Note that this setting, together with TCPIP_UDP_SOCKET_POOL_BUFFERS, has impact on the heap size that's used by the stack (see TCPIP_STACK_DRAM_SIZE setting). |
TCPIP_UDP_SOCKET_POOL_BUFFERS | Number of buffers in the private UDP pool. These are preallocated buffers that are to be used by UDP sockets only. This improves the UDP socket throughput and is meant only for UDP sockets that have to sustain high TX traffic rate. However, this memory is not returned to the stack heap, it always belongs to UDP. A socket needs to have an option set in order to use the buffers pool (see the UDPSetOptions()). Use 0 to disable the feature. |
TCPIP_UDP_USE_POOL_BUFFERS | enable the build of the pre-allocated pool buffers option |
TCPIP_UDP_USE_RX_CHECKSUM | Check incoming packets to have proper checksum. |
TCPIP_UDP_USE_TX_CHECKSUM | Calculate and transmit a checksum when sending data. Checksum is not mandatory for UDP packets but is highly recommended. This will affect the UDP TX performance. |
TCPIP_UDP_COMMANDS | TCPIP UDP info commands Enables/Disables the UDP command feature. This setting will add a UDP "info" command to the TCP/IP command menu allowing a run time inspection of the UDP sockets Set the value to 1 to enable, 0 to disable the feature. |
TCPIP_UDP_EXTERN_PACKET_PROCESS | This setting enables/disables the processing of the RX packets by an external handler The user of the UDP can register an external function to process the incoming packets If true, the functionality is built in and could be used by the application If false, the functionality does not exist and the generated code is slightly smaller |
Socket Management Functions | |
TCPIP_UDP_ServerOpen | Opens a UDP socket as a server. |
TCPIP_UDP_ClientOpen | Opens a UDP socket as a client. |
TCPIP_UDP_IsOpened | Determines if a socket was opened. |
TCPIP_UDP_IsConnected | Determines if a socket has an established connection. |
TCPIP_UDP_Bind | Bind a socket to an address type, local port and address. This function is meant primarily for client sockets. |
TCPIP_UDP_RemoteBind | Bind a socket to an address type, remote port and address. This function is meant primarily for server sockets. |
TCPIP_UDP_Close | Closes a UDP socket and frees the handle. |
TCPIP_UDP_OptionsGet | Allows getting the options for a socket such as current RX/TX buffer size, etc. |
TCPIP_UDP_OptionsSet | Allows setting options to a socket like adjust RX/TX buffer size, etc |
TCPIP_UDP_SocketInfoGet | Returns information about a selected UDP socket. |
TCPIP_UDP_SocketNetGet | Gets the network interface of an UDP socket |
TCPIP_UDP_SocketNetSet | Sets the network interface for an UDP socket |
TCPIP_UDP_TxOffsetSet | Moves the pointer within the TX buffer. |
TCPIP_UDP_SourceIPAddressSet | Sets the source IP address of a socket |
TCPIP_UDP_BcastIPV4AddressSet | Sets the broadcast IP address of a socket Allows an UDP socket to send broadcasts. |
TCPIP_UDP_DestinationIPAddressSet | Sets the destination IP address of a socket |
TCPIP_UDP_DestinationPortSet | Sets the destination port of a socket |
TCPIP_UDP_Disconnect | Disconnects a UDP socket and re-initializes it. |
TCPIP_UDP_SignalHandlerDeregister | Deregisters a previously registered UDP socket signal handler. |
TCPIP_UDP_SignalHandlerRegister | Registers a UDP socket signal handler. |
TCPIP_UDP_Task | Standard TCP/IP stack module task function. |
TCPIP_UDP_SocketsNumberGet | Returns the number of existent UDP sockets. |
TCPIP_UDP_PacketHandlerDeregister | Deregisters a previously registered packet handler. |
TCPIP_UDP_PacketHandlerRegister | Sets a new packet processing handler. |
Transmit Data Transfer Functions | |
TCPIP_UDP_PutIsReady | Determines how many bytes can be written to the UDP socket. |
TCPIP_UDP_TxPutIsReady | Determines how many bytes can be written to the UDP socket. |
TCPIP_UDP_ArrayPut | Writes an array of bytes to the UDP socket. |
TCPIP_UDP_StringPut | Writes a null-terminated string to the UDP socket. |
TCPIP_UDP_Put | Writes a byte to the UDP socket. |
TCPIP_UDP_TxCountGet | Returns the amount of bytes written into the UDP socket. |
TCPIP_UDP_Flush | Transmits all pending data in a UDP socket. |
Receive Data Transfer Functions | |
TCPIP_UDP_GetIsReady | Determines how many bytes can be read from the UDP socket. |
TCPIP_UDP_ArrayGet | Reads an array of bytes from the UDP socket. |
TCPIP_UDP_Get | Reads a byte from the UDP socket. |
TCPIP_UDP_RxOffsetSet | Moves the read pointer within the socket RX buffer. |
TCPIP_UDP_Discard | Discards any remaining RX data from a UDP socket. |
Data Types and Constants | |
UDP_PORT | Defines a type for a UDP port number |
UDP_SOCKET | Provides a handle to a UDP Socket |
UDP_SOCKET_BCAST_TYPE | UDP broadcast types. |
UDP_SOCKET_INFO | Information about a UDP socket |
UDP_SOCKET_OPTION | UDP socket options |
INVALID_UDP_SOCKET | Indicates a UDP socket that is not valid |
TCPIP_UDP_MODULE_CONFIG | UDP module run time configuration/initialization data. |
TCPIP_UDP_SIGNAL_FUNCTION | UDP Signal Handler. |
TCPIP_UDP_SIGNAL_HANDLE | UDP socket handle. |
TCPIP_UDP_SIGNAL_TYPE | UDP run-time signal types. |
UDP_MULTICAST_FLAGS | UDP multicast options/flags. |
UDP_OPTION_MULTICAST_DATA | Data structure used to set a socket multicast options. |
TCPIP_UDP_PACKET_HANDLER | Pointer to a function(handler) that will get called to process an incoming UDP packet. |
TCPIP_UDP_PROCESS_HANDLE | Defines a UDP packet processing handle. |