Overview of the XLIO Extra API
The information in this chapter is intended for application developers that want to maximize XLIO performance may use the Extra API and achieve the following:
- To further lower latencies
- To increase throughput
- To gain additional CPU cycles for the application logic
- To better control XLIO offload capabilities
All socket applications are limited to the given Socket API interface functions. The XLIO Extra API enables XLIO to open a new set of functions which allow the application developer to add code which utilizes zero copy receive function calls and low-level packet filtering by inspecting the incoming packet headers or packet payload at a very early stage in the processing.
XLIO is designed as a dynamically linked user-space library. As such, the XLIO Extra API has been designed to allow the user to dynamically load XLIO and to detect at runtime if the additional functionality described here is available or not. The application is still able to run over the general socket library without XLIO loaded as it did previously, or can use an application flag to decide which API to use: Socket API or XLIO Extra API.
The XLIO Extra APIs are provided as a header with the XLIO binary rpm. The application developer needs to include this header file in his application code.
After installing the XLIO rpm on the target host, the XLIO Extra APIs header file is located in the following link:
The xlio_extra.h provides detailed information about the various functions and structures, and instructions on how to use them.
An example using the XLIO Extra API can be seen in the udp_lat source code:
- Follow the ‘--xliorxfiltercb’ flag for the packet filter logic
- Follow the ‘--xliozcopyread’ flag for the zero copy recvfrom logic
A specific example for using the TCP zero copy extra API can be seen under extra_api_tests/tcp_zcopy_cb.
Using XLIO Extra API
During runtime, use the xlio_get_api() function to check if XLIO is loaded in your application and if XLIO Extra API is accessible.
If the function returns with NULL, either XLIO is not loaded with the application, or the XLIO Extra API is not compatible with the header function used for compiling your application. NULL will be the typical return value when running the application on native OS without XLIO loaded. On success the function returns a valid api() pointer and NULL on failure.
Any non-NULL return value is a xlio_api_t type structure pointer that holds pointers to the specific XLIO Extra API function calls which are needed for the application to use. Available functions can be checked using special bit mask field as cap_mask.
It is recommended to call xlio_get_api()once on startup, and to use the returned pointer throughout the life of the process.
There is no need to ‘release’ this pointer in any way.
Control Off-load Capabilities During Run-Time
Adding libxlio.conf Rules During Run-Time
Adds a libxlio.conf rule to the top of the list. This rule will not apply to existing sockets which already considered the conf rules. (around connect/listen/send/recv ..)
- 0 on success
- error code on failure
- Description – new rule to add to the top of the list (highest priority)
- Value – a char buffer with the exact format as defined in libxlio.conf, and should end with '\0'
Creating Sockets as Offloaded or Not-Offloaded
Creates sockets on pthread tid as off-loaded/not-off-loaded. This does not affect existing sockets. Offloaded sockets are still subject to libxlio.conf rules.
Usually combined with the XLIO_OFFLOADED_SOCKETS parameter.
- 0 on success
- error code on failure
- Description – Offload property
- Value – 1 for offloaded, 0 for not-offloaded
- Description – thread ID
- Description – thread ID
The packet filter logic gives the application developer the capability to inspect a received packet. You can then decide, on the fly, to keep or drop the received packet at this stage in processing.
The user’s application packet filtering callback is defined by the prototype:
This callback function should be registered with XLIO by calling the XLIO Extra API function register_recv_callback(). It can be unregistered by setting a NULL function pointer.
XLIO calls the callback to notify of new incoming packets after the internal IP & UDP/TCP header processing, and before they are queued in the socket's receive queue.
The context of the callback is always that of one of the user's application threads that called one of the following socket APIs: select(), poll(), epoll_wait(), recv(), recvfrom(), recvmsg(), read(), or readv().
|Packet Filtering Callback Function Parameter||Description|
File descriptor of the socket to which this packet refers.
iovector structure array pointer holding the packet received, data buffer pointers, and the size of each buffer.
Size of the iov array.
Additional information on the packet and socket.
User-defined value provided during callback registration for each socket.
The application can call all the Socket APIs from within the callback context.
Packet loss might occur depending on the application's behavior in the callback context. A very quick non-blocked callback behavior is not expected to induce packet loss.
Parameters the "iov" and "xlio_info" are only valid until the callback context is returned to XLIO. You should copy these structures for later use if working with zero-copy logic.
Zero Copy recvfrom()
Zero-copy recvfrom implementation. This function attempts to receive a packet without doing data copy.
Socket file descriptor
Buffer to fill with received data or pointers to data (see below).
Pointer to flags (see below).
Usual flags to recvmsg(), and MSG_XLIO_
If not NULL, is set to the source address (same as recvfrom)
If not NULL, is set to the source address size (same as recvfrom).
The flags parameter can contain the usual flags to recvmsg(), and also the MSG_XLIO_ZCOPY_FORCE flag. If the latter is not set, the function reverts to data copy (i.e., zero-copy cannot be performed). If zero-copy is performed, the flag MSG_XLIO_ZCOPY is set upon exit.
If zero copy is performed (MSG_XLIO_ZCOPY flag is returned), the buffer is filled with a xlio_recvfrom_zcopy_packets_t structure holding as much fragments as `len' allows. The total size of all fragments is returned. Otherwise, the buffer is filled with actual data, and its size is returned (same as recvfrom()).
If the return value is positive, data copy has been performed. If the return value is zero, no data has been received.
Freeing Zero Copied Packet Buffers
Frees a packet received by "recvfrom_zcopy()" or held by "receive callback".
- s – socket from which the packet was received
- pkts – array of packet identifiers
- count – number of packets in the array
- 0 on success, -1 on failure
- errno is set to:
- EINVAL – not a offloaded socket
- ENOENT – the packet was not received from 's'.
tx total byte
The number of transmit bytes associated with a TFM rule; has a log counter n.
The above example shows the number of bytes sent from Infiniband to Ethernet (one way) or sent between InfiniBand and Ethernet and matching the two TFM rules with log counter #1.
rx total pack
The number of receive packets associated with a TFM rule; has a log counter n.
rx total byte
The number of receive bytes associated with a TFM rule; has a log counter n.
Dump fd Statistics using XLIO Logger
Dumps statistics for fd number using log_level log level.
fd to dump, 0 for all open fds.
log_level dumping level corresponding vlog_levels_t enum (vlogger.h):
For output example see section Monitoring – the xlio_stats Utility. Return values: 0 on success, -1 on failure
"Dummy Send" to Improve Low Message Rate Latency
The “Dummy Send” feature gives the application developer the capability to send dummy packets in order to warm up the CPU caches on XLIO send path, hence minimizing any cache misses and improving latency. The dummy packets reaches the hardware NIC and then is dropped.
The application developer is responsible for sending the dummy packets by setting the XLIO_SND_FLAGS_DUMMY bit in the flags parameter of send(), sendto(), sendmsg(), and sendmmsg() sockets API.
Indicates a dummy packet
Same as the original APIs for offloaded sockets. Otherwise, -1 is returned and errno is set to EINVAL.Return values:
This sample code consistently sends dummy packets every DummysendCycleDuration using the XLIO extra API while the total time does not exceed waitDuration.
It is recommended not to send more than 50k dummy packets per second.
Verifying “Dummy Send” capability in HW
In order to verify “Dummy Send” capability in the hardware, run XLIO with DEBUG trace level.
Look in the printout for “HW Dummy send support for QP = [0|1]”.
“Dummy Packets” Statistics
Run xlio_stats tool to view the total amount of dummy-packets sent.
The number of dummy messages sent will appear under the relevant fd. For example:
The API introduced for this capability allows an application to remove the overhead of socket API from the receive flow data path, while keeping the well-known socket API for the control interface. Using such functionality the application has almost direct access to XLIO’s HW ring object and it is possible to implement a design which does not call socket APIs such as select(), poll(), epoll_wait(), recv(), recvfrom(), recvmsg(), read(), or readv().
The structures and constants are defined as shown below.
XLIO Specific Events
New packet is available
New connection is auto accepted by server
Next buffer (for last buffer next == NULL)
Point to data
Total data length
List of packet's buffers
Set of events
User provided data
· By default this field has FD of the socket
· User is able to change the content using setsockopt() with level argument SOL_SOCKET and opname as SO_XLIO_USER_DATA
Source address (in network byte order) set for XLIO_SOCKETXTREME_PACKET and XLIO_SOCKETXTREME_NEW_CONNECTION_ACCEPTED events
Connected socket's parent/listen socket fd number.
Polling for XLIO Completions
- fd – file descriptor
- completions – array of completion elements
- ncompletions – number of elements in passed array
- flags – flags to control behavior (set zero)
Return values: Returns the number of ready completions during success. A negative value is returned in case of failure.
Description: This function polls the `fd` for XLIO completions and returns maximum `ncompletions` - ready completions via the `completions` array. The `fd` represents a ring file descriptor. XLIO completions are indicated for incoming packets and/or for other events. If XLIO_SOCKETXTREME_PACKET flag is enabled in the xlio_socketxtreme_completion_t.events field the completion points to the incoming packet descriptor that can be accessed via the xlio_socketxtreme_completion_t.packet field. Packet descriptor points to the XLIO buffers that contain data scattered by HW, so the data is delivered to the application with zero copy. Notice: after the application is finished with the returned packets and their buffers it must free them using socketxtreme_free_packets ()/socketxtreme_free_buff () functions. If XLIO_SOCKETXTREME_PACKET flag is disabled xlio_socketxtreme_packet_desc_t.packet field is reserved. In addition to packet arrival event (indicated by XLIO_SOCKETXTREME_PACKET flag) XLIO also reports XLIO_SOCKETXTREME_NEW_CONNECTION_ACCEPTED event and standard epoll events via the xlio_socketxtreme_packet_desc_t.events field. XLIO_SOCKETXTREME_NEW_CONNECTION_ACCEPTED event is reported when new connection is accepted by the server. When working with socketxtreme_poll() new connections are accepted automatically and accept (listen_socket) must not be called. XLIO_SOCKETXTREME_NEW_CONNECTION_ACCEPTED event is reported for the new connected/child socket (xlio_socketxtreme_packet_desc_t.user_data refers to child socket) and EPOLLIN event is not generated for the listen socket. For events other than packet arrival and new connection acceptance xlio_socketxtreme_packet_desc_t.events bitmask composed using standard epoll API events types. Notice: the same completion can report multiple events, for example XLIO_SOCKETXTREME_PACKET flag can be enabled together with EPOLLOUT event, etc.
Getting Number of Attached Rings
- fd – file descriptor
Return values: Returns the number of rings during success. A negative value is returned in case of failure.
Description: Returns the number of rings that are associated with socket.
Getting Ring FD
- fd – file descriptor
- ring_fds – int array of ring fds
- ring_fds_sz – size of the array
Return values: Returns the number of populated array entries during success. A negative value is returned in case of failure.
Description: Returns FDs of the rings that are associated with the socket.
Free SocketXtreme XLIO Packets
- packets – packets to be freed
- num – number of packets in passed array
Return values: Returns zero value during success. A negative value is returned in case failure.
Description: Frees packets received by socketxtreme_poll().
For each packet in the `packets` array this function updates the receive queue size and the advertised TCP window size, if needed, for the socket that received the packet and frees XLIO buffer list that is associated with the packet. Notice: for each buffer in the buffer list XLIO decreases buffer's ref count and only buffers with ref count zero are deallocated. An application can call socketxtreme_ref_buf() to increase the buffer reference count in order to hold the buffer even after socketxtreme_free_ packets() has been called. Also, the application is responsible to free buffers that could not be deallocated during socketxtreme_free_packets() due to non-zero reference count. This is done by calling the socketxtreme_free_buff() function.
Decrement SocketXtreme XLIO Buffer Reference Counter
Return values: Returns the buffer's reference count after the change (zero value means that the buffer has been deallocated). A negative value is returned in case of failure.
Description: Decrement the reference counter of a buffer received by socketxtreme_poll(). This function decrements the buff reference count. When buff's reference count reaches zero, it is deallocated.
Increment SocketXtreme XLIO Buffer Reference Counter
- buff – buffer to be managed
Return values: Returns buffer's reference count after the change. A negative value is returned in case of failure.
Description: Increment the reference counter of a buffer received by socketxtreme_poll(). This function increments the reference count of the buffer. This function should be used in order to hold the buffer even after a call to socketxtreme_free_packets(). When the buffer is no longer required it should be freed via socketxtreme_free_buff ().
Sockperf benchmark supports socketxtreme mode. Its source code can be used as a reference of socketxtreme API usage.
The following sample implements server side logic based on the API described above.
In this example, the application just waits for connection requests and accepts new connections.
No support for:
User should keep in mind the differences in flow between the standard socket API and that based on the polling completions model.
- SocketXtreme mode is used with non-blocking connect() call only
- Do not use accept() because socketxtreme_poll() provides special event as XLIO_socketxtreme_NEW_CONNECTION_ACCEPTED to track connection request
- Mixed receive methods (recv/recvfrom/recmsg/epoll_wait with socketXtreme) can cause the user to receive out-of-order packets. UDP is an unreliable protocol, hence working with mixed receive methods are allowed yet not recommended. Whereas TCP is a reliable protocol, hence mixed receive methods are not allowed. socketxtreme_poll() is able to notify about any received data using the event XLIO_socketxtreme_PACKET.
Control the library
This function allows to communicate with library using extendable protocol
based on struct cmshdr.
The address of the ancillary data.
The length of the ancillary data is passed in cmsg_hdr. Note that if multiple ancillary data sections are being passed, this length should reflect the total length of ancillary data sections
The cmsg_hdr parameter points to the ancillary data. This cmsg_hdr pointer points to the following structure (C/C++ example shown) that describes the ancillary data.
Ancillary data is a sequence of cmsghdr structures with appended data. The sequence of cmsghdr structures should never be accessed directly. Instead, use only the following macros: CMSG_ALIGN, CMSG_SPACE, CMSG_DATA, CMSG_LEN.
- The cmsg_len should be set to the length of the cmsghdr plus the length of all ancillary data that follows immediately after the cmsghdr. This is represented by the commented out cmsg_data field.
- The cmsg_level should be set to the option level (for example, SOL_SOCKET).
- The cmsg_type should be set to the option name (for example, CMSG_XLIO_IOCTL_USER_ALLOC).
Use user defined function to allocate global pools
pointer to memory allocation function
pointer to memory free function
In this example, the application uses CMSG_XLIO_IOCTL_USER_ALLOC command.