xlio_types.h

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: NVIDIA CORPORATION & AFFILIATES
 * Copyright (c) 2024-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 * SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause
 */
 
#ifndef XLIO_TYPES_H
#define XLIO_TYPES_H
 
#include <stddef.h>
#include <stdint.h>
#include <netinet/in.h>
#include <sys/socket.h>
#include <sys/time.h>
 
/*
 * Options for setsockopt()/getsockopt()
 */
#define SO_XLIO_GET_API          2800
#define SO_XLIO_RING_ALLOC_LOGIC 2810
#define SO_XLIO_SHUTDOWN_RX      2821
#define SO_XLIO_EXT_VLAN_TAG     2824
 
/*
 * Return values for the receive packet notify callback function
 */
typedef enum {
    XLIO_PACKET_DROP, /* The library will drop the received packet and recycle
                        the buffer if no other socket needs it */
 
    XLIO_PACKET_RECV, /* The library will queue the received packet on this socket ready queue.
                        The application will read it with the usual recv socket APIs */
 
    XLIO_PACKET_HOLD /* Application will handle the queuing of the received packet. The application
                       must return the descriptor to the library using the free packet function
           But not in the context of XLIO's callback itself. */
} xlio_recv_callback_retval_t;
 
/*
 * Structure holding additional information on the packet and socket
 * Note: Check structure size value for future library changes
 */
struct __attribute__((packed)) xlio_info_t {
    size_t
        struct_sz; /* Compare this value with sizeof(xlio_info_t) to check version compatability */
    void *packet_id; /* Handle to received packet buffer to be return if zero copy logic is used */
 
    /* Packet addressing information (in network byte order) */
    const struct sockaddr *src;
    const struct sockaddr *dst;
 
    /* Packet information */
    size_t payload_sz;
 
    /* Socket's information */
    uint32_t socket_ready_queue_pkt_count; /* Current count of packets waiting to be read from the
                                              socket */
    uint32_t socket_ready_queue_byte_count; /* Current count of bytes waiting to be read from the
                                               socket */
 
    /* Packet timestamping information */
    struct timespec hw_timestamp;
    struct timespec sw_timestamp;
};
 
struct xlio_rate_limit_t {
    uint32_t rate; /* rate limit in Kbps */
    uint32_t max_burst_sz; /* maximum burst size in bytes */
    uint16_t typical_pkt_sz; /* typical packet size in bytes */
};
 
typedef enum {
    RING_LOGIC_PER_INTERFACE = 0,
    RING_LOGIC_PER_IP = 1,
    RING_LOGIC_PER_SOCKET = 10,
    RING_LOGIC_PER_USER_ID = 11,
    RING_LOGIC_PER_THREAD = 20,
    RING_LOGIC_PER_CORE = 30,
    RING_LOGIC_PER_CORE_ATTACH_THREADS = 31,
    RING_LOGIC_PER_OBJECT = 32,
    RING_LOGIC_LAST
} ring_logic_t;
 
typedef enum {
    XLIO_RING_ALLOC_MASK_RING_USER_ID = (1 << 0),
    XLIO_RING_ALLOC_MASK_RING_INGRESS = (1 << 1),
    XLIO_RING_ALLOC_MASK_RING_ENGRESS = (1 << 2),
} xlio_ring_alloc_logic_attr_comp_mask;
 
/*
 * @brief pass this struct to process by the library using setsockopt with
 * @ref SO_XLIO_RING_ALLOC_LOGIC
 *  to set the allocation logic of this FD when he requests a ring.
 *  @note ring_alloc_logic is a mandatory
 * @param comp_mask - what fields are read when processing this struct
 *  see @ref xlio_ring_alloc_logic_attr_comp_mask
 * @param ring_alloc_logic- allocation ratio to use
 * @param user_idx - when used RING_LOGIC_PER_USER_ID int @ref ring_alloc_logic
 *  this is the user id to define. This lets you define the same ring for
 *  few FD's regardless the interface\thread\core.
 * @param ingress - RX ring
 * @param engress - TX ring
 */
struct xlio_ring_alloc_logic_attr {
    uint32_t comp_mask;
    ring_logic_t ring_alloc_logic;
    uint32_t user_id;
    uint32_t ingress : 1;
    uint32_t engress : 1;
    uint32_t reserved : 30;
};
 
/*
 * Notification callback for incoming packet on socket
 * @param fd Socket's file descriptor which this packet refers to
 * @param iov iovector structure array point holding the packet
 *            received data buffer pointers and size of each buffer
 * @param iov_sz Size of iov array
 * @param xlio_info Additional information on the packet and socket
 * @param context User-defined value provided during callback
 *                registration for each socket
 *
 *   This callback function should be registered by the library calling
 * register_recv_callback() in the extended API. It can be unregistered by
 * setting a NULL function pointer. The library will call the callback to notify
 * of new incoming packets after the IP & UDP header processing and before
 * they are queued in the socket's receive queue.
 *   Context of the callback will always be from one of the user's application
 * threads when calling the following socket APIs: select, poll, epoll, recv,
 * recvfrom, recvmsg, read, readv.
 *
 * Notes:
 * - The application can call all of the Socket APIs control and send from
 *   within the callback context.
 * - Packet loss might occur depending on the applications behavior in the
 *   callback context.
 * - Parameters `iov' and `xlio_info' are only valid until callback context
 *   is returned to the library. User should copy these structures for later use
 *   if working with zero copy logic.
 */
typedef xlio_recv_callback_retval_t (*xlio_recv_callback_t)(int fd, size_t sz_iov,
                                                            struct iovec iov[],
                                                            struct xlio_info_t *xlio_info,
                                                            void *context);
 
typedef uintptr_t xlio_poll_group_t;
 
typedef uintptr_t xlio_socket_t;
 
struct xlio_buf {
    uint64_t userdata;
};
 // end of xlio_rx group
 
typedef void (*xlio_memory_cb_t)(void *addr, size_t len, size_t hugepage_size);
 
enum {
    XLIO_SOCKET_EVENT_ESTABLISHED = 1,
    XLIO_SOCKET_EVENT_TERMINATED,
    XLIO_SOCKET_EVENT_CLOSED,
    XLIO_SOCKET_EVENT_ERROR,
};
 
typedef void (*xlio_socket_event_cb_t)(xlio_socket_t sock, uintptr_t userdata_sq, int event,
                                       int value);
 
typedef void (*xlio_socket_comp_cb_t)(xlio_socket_t sock, uintptr_t userdata_sq,
                                      uintptr_t userdata_op);
 
typedef void (*xlio_socket_rx_cb_t)(xlio_socket_t sock, uintptr_t userdata_sq, void *data,
                                    size_t len, struct xlio_buf *buf);
 
typedef void (*xlio_socket_accept_cb_t)(xlio_socket_t sock, xlio_socket_t parent,
                                        uintptr_t parent_userdata_sq);
 // end of xlio_callbacks group
 
struct xlio_init_attr {
    unsigned flags;
    xlio_memory_cb_t memory_cb;
 
    /* Optional external user allocator for XLIO buffers. */
    void *(*memory_alloc)(size_t);
    void (*memory_free)(void *);
};
 // end of xlio_init group
 
#define XLIO_GROUP_FLAG_SAFE 0x1
#define XLIO_GROUP_FLAG_DIRTY 0x2
 
struct xlio_poll_group_attr {
    unsigned flags;
 
    xlio_socket_event_cb_t socket_event_cb;
    xlio_socket_comp_cb_t socket_comp_cb;
    xlio_socket_rx_cb_t socket_rx_cb;
    xlio_socket_accept_cb_t socket_accept_cb;
};
 // end of xlio_poll_group group
 
struct xlio_socket_attr {
    unsigned flags;
    int domain; /* AF_INET or AF_INET6 */
    xlio_poll_group_t group;
    uintptr_t userdata_sq;
};
 // end of xlio_socket group
 
#define XLIO_SOCKET_SEND_FLAG_FLUSH 0x1
#define XLIO_SOCKET_SEND_FLAG_INLINE 0x2
 
struct xlio_socket_send_attr {
    unsigned flags;
    uint32_t mkey;
    uintptr_t userdata_op;
};
 // end of xlio_tx group
 // end of xlio_ultra_api group
 
#endif /* XLIO_TYPES_H */