The TCP Zero-copy API
7.1About the TCP Zero-copy API
This section documents an optional extension to the Sockets layer, the TCP Zero-copy API. This extension is only present if the stack has been built with the TCP_ZEROCOPY package option defined in ipport.h.
The TCP Zero-copy API is intended to assist the development of higher-performance embedded network applications by allowing the application direct access to the TCP/IP stack packet buffers. This feature can be used to avoid the overhead of having the stack copy data between application-owned buffers and stack-owned buffers in t_send() and t_recv(), but the application has to fit its data into, and accept its data from, the stack buffers.
7.1.1Content of the API
The TCP Zero-copy API comprises:
•two functions for allocating and freeing packet buffers
•a function for sending a packet buffer on an open socket
•an application-supplied callback function for accepting received packets
•an extension to the Sockets t_setsockopt() function for registration of the callback function.
The TCP Zero-copy API is small because it is simply an extension to the existing Sockets API that provides an alternate mechanism for sending and receiving data on a socket. The Sockets API is used for all other operations on the socket.
Allocating and freeing packet buffers
The two functions for allocating and freeing packet buffers are straightforward requests:
tcp_pktalloc() Allocates a packet buffer from the pool of packet buffers on the stack.
tcp_pktfree() Frees a packet buffer.
Applications using the TCP Zero-copy API are responsible for allocating packet buffers for use in sending data, as well as for freeing buffers that have been used to receive data and those that the application has allocated but decided not to use for sending data. As these packet buffers are a limited resource, it is important that applications free them promptly when they are no longer of use.
7-2 |
Copyright © 1998-2001 ARM Limited. All rights reserved. |
ARM DUI 0144B |
The TCP Zero-copy API
Sending data through an open socket
The function for sending data, tcp_xout(), sends a packet buffer of data using a socket.
If successful, it is considered to have consumed the supplied buffer and so the application does not have to free the buffer using tcp_pktfree().
Callback function
Applications that use the TCP Zero-copy API for receiving data must include a callback function for acceptance of received packets, and must register the callback function with the socket using the t_setsockopt() Sockets function with the SO_CALLBACK option name. The callback function, once registered, receives not only received data packets, but also connection events that result in socket errors.
ARM DUI 0144B |
Copyright © 1998-2001 ARM Limited. All rights reserved. |
7-3 |
The TCP Zero-copy API
7.2Sending data with the TCP Zero-copy API
This section describes the procedure for allocating a packet buffer and sending data, in the following sections:
•Allocating a packet buffer on page 7-4
•Filling the allocated buffer with data on page 7-5
•Sending the packet on page 7-5.
7.2.1Allocating a packet buffer
The first step in using the TCP Zero-copy API to send data is to allocate a packet buffer from the stack using the tcp_pktalloc() function. This function takes a single argument (the maximum length of the data you intend to send in the buffer) and returns a PACKET, a pointer to a network buffer structure, as shown in Example 7-1.
Example 7-1 The tcp_pktalloc() function
PACKET pkt; |
/* pointer to netbuf structure for packet |
buffer */ |
|||||
int datalen; |
/* |
amount |
of data to send |
*/ |
|
|
|
datalen |
= 512; |
/* |
should |
indicate amount |
of |
data to send |
*/ |
pkt = tcp_pktalloc(datalen); |
|
|
|
|
|
|
|
if (pkt |
== NULL) |
|
|
|
|
|
|
{
/* error, could not allocate packet buffer */
}
Note
This limits how much data that you can send in one call using the TCP Zero-copy API, as the data sent in one call to tcp_xout() must fit in a single packet buffer, with the TCP, IP, and lower-layer headers that the stack needs to add in order to send the packet.
The actual limit is determined by the big packet buffer size, bigbufsiz, less the HDRSLEN definition in tcpport.h. If you try to request a larger buffer than this, tcp_pktalloc() returns NULL to indicate that it cannot allocate a sufficiently-large buffer.
7-4 |
Copyright © 1998-2001 ARM Limited. All rights reserved. |
ARM DUI 0144B |
The TCP Zero-copy API
7.2.2Filling the allocated buffer with data
Having allocated the packet buffer, you now fill it with the data to send. The function tcp_pktalloc() has initialized the returned PACKET and so pkt->nb_prot points to where you can start depositing data.
When you have filled the buffer, you must set pkt->nb_plen to the number of bytes of data that you have placed in the buffer.
7.2.3Sending the packet
Finally, you send the packet by giving it back to the stack using the function tcp_xout().
e = tcp_xout(s, pkt); if (e < 0)
{
tcp_pktfree(pkt);
}
This function sends the packet over TCP, or returns an error. If its return value is less than zero, it has not accepted the packet and the application must either free the packet or retain it for sending later.
ARM DUI 0144B |
Copyright © 1998-2001 ARM Limited. All rights reserved. |
7-5 |