XLIO Ultra API

The XLIO Ultra API is a high-performance, event-driven networking interface designed for applications that require maximum throughput and minimum latency. The Ultra API enables:

• Increased throughput – Higher sustained data transfer rates

• More available CPU cycles – Less networking overhead, more cycles for application logic

• Zero-copy operations – Avoid unnecessary buffer copies

• Fine-grained control of offload features – Direct control over hardware-accelerated functionality

• Lower latency – Further reduction of communication delays

The Ultra API exposes a set of advanced functions that allow applications to use zero-copy data paths and highly efficient event-delivery mechanisms.

Ultra API headers are installed with the XLIO binary packages.

XLIO provides two integration models:

1. Dynamic loading – Detect and use the Ultra API at runtime

2. Static linkage – Link directly against XLIO at compile time

Dynamic Loading

XLIO is primarily a dynamically linked user-space library. Applications may load it at runtime and detect whether Ultra API support is available.

There are two approaches:

1. Manual loading using dlopen() / dlsym()

   You may manually load the XLIO library and resolve each Ultra API function:

   Copy

   Copied!

               
   
               
   void *handle = dlopen("libxlio.so", RTLD_LAZY);
   if (handle) {
       // Use dlsym() to load each function pointer
       my_xlio_function = dlsym(handle, "xlio_function_name");
           

   This method gives full control over which symbols are loaded.

2. LD_PRELOAD with `xlio_get_api()`

   When XLIO is preloaded:

   Copy

   Copied!

               
   
               
   LD_PRELOAD=libxlio.so ./your_application
           

   you can call xlio_get_api() (declared in <xlio_extra.h>) to retrieve a structure containing all Ultra API function pointers.

Return values

• NULL – XLIO was not loaded, or the XLIO Ultra API version is incompatible with the headers used during at build time.

• Valid pointer – Returns an xlio_api_t* containing function pointers and the cap_mask field, which indicates which Ultra API capabilities are available.

Socket interception

With LD_PRELOAD, XLIO intercepts standard socket API calls (socket(), bind(), send(), recv(), etc.).

This enables:

• acceleration of existing socket-based applications with no code changes, and

• optional access to Ultra API functions when available.

Best Practices

• Call xlio_get_api() once during application initialization.

• Reuse the returned pointer throughout the lifetime of the process.

• No cleanup or teardown of the pointer is required.

Static linkage

The XLIO static library allows applications to link directly and invoke Ultra API functions without dynamic loading.

The API is declared in <mellanox/xlio.h> (typically located at /usr/include/mellanox/xlio.h).

XLIO Ultra API Documentation

The XLIO Ultra API is documented in Doxygen format. For detailed function descriptions, parameter specifications, and usage guidelines, refer to the official Doxygen documentation.

API Argument Validity and Safety

To maintain high performance and minimal overhead, the Ultra API performs very limited runtime validation.

Developer Responsibilities

• All socket handles passed to Ultra API functions must be valid XLIO socket objects

• Pointer arguments must be valid unless a NULL pointer is explicitly permitted

• Objects must not be used after invalidation (e.g., after socket closure)

XLIO Ultra API Examples

Ultra API examples are provided in the examples/ directory of the XLIO source tree.

The latest stable examples are also available in the official git repository.

These examples demonstrate:

• Typical usage patterns

• Zero-copy data-path techniques

• Event-driven programming with Ultra API

• Best practices for production-grade integration