libxdp - Man Page

Basic usage of libxdp from an application is quite straight forward. The following example loads, then unloads, an XDP program from the 'lo' interface:

#define IFINDEX 1

struct xdp_program *prog;
int err;

prog = xdp_program__open_file("my-program.o", "section_name", NULL);
err = xdp_program__attach(prog, IFINDEX, XDP_MODE_NATIVE, 0);

if (!err)
    xdp_program__detach(prog, IFINDEX, XDP_MODE_NATIVE, 0);

xdp_program__close(prog);

The xdp_program structure is an opaque structure that represents a single XDP program. libxdp contains functions to create such a struct either from a BPF object file on disk, from a libbpf BPF object, or from an identifier of a program that is already loaded into the kernel:

struct xdp_program *xdp_program__from_bpf_obj(struct bpf_object *obj,
                                              const char *section_name);
struct xdp_program *xdp_program__find_file(const char *filename,
                                           const char *section_name,
                                           struct bpf_object_open_opts *opts);
struct xdp_program *xdp_program__open_file(const char *filename,
                                           const char *section_name,
                                           struct bpf_object_open_opts *opts);
struct xdp_program *xdp_program__from_fd(int fd);
struct xdp_program *xdp_program__from_id(__u32 prog_id);
struct xdp_program *xdp_program__from_pin(const char *pin_path);

The functions that open a BPF object or file need the function name of the XDP program as well as the file name or object, since an ELF file can contain multiple XDP programs. The xdp_program__find_file() function takes a filename without a path, and will look for the object in LIBXDP_OBJECT_PATH which defaults to /usr/lib/bpf (or /usr/lib64/bpf on systems using a split library path). This is convenient for applications shipping pre-compiled eBPF object files.

The xdp_program__attach() function will attach the program to an interface, building a dispatcher program to execute it. Multiple programs can be attached at once with xdp_program__attach_multi(); they will be sorted in order of their run priority, and execution from one program to the next will proceed based on the chain call actions defined for each program (see the Program metadata section below). Because the loading process involves modifying the attach type of the program, the attach functions only work with struct xdp_program objects that have not yet been loaded into the kernel.

When using the attach functions to attach to an interface that already has an XDP program loaded, libxdp will attempt to add the program to the list of loaded programs. However, this may fail, either due to missing kernel support, or because the already-attached program was not loaded using a dispatcher compatible with libxdp. If the kernel support for incremental attach (merged in kernel 5.10) is missing, the only way to actually run multiple programs on a single interface is to attach them all at the same time with xdp_program__attach_multi(). If the existing program is not an XDP dispatcher, that program will have to be detached from the interface before libxdp can attach a new one. This can be done by calling xdp_program__detach() with a reference to the loaded program; but note that this will of course break any application relying on that other XDP program to be present.

This is the priority of the program and is a simple integer used to sort programs when loading multiple programs onto the same interface. Programs that wish to run early (such as a packet filter) should set low values for this, while programs that want to run later (such as a packet forwarder or counter) should set higher values. Note that later programs are only run if the previous programs end with a return code that is part of its chain call actions (see below). If not specified, the default priority value is 50.

These are the program return codes that the program indicate for packets that should continue processing. If the program returns one of these actions, later programs in the call chain will be run, whereas if it returns any other action, processing will be interrupted, and the XDP dispatcher will return the verdict immediately. If not set, this defaults to just XDP_PASS, which is likely the value most programs should use.

The metadata outlined above is specified as BTF information embedded in the ELF file containing the XDP program. The xdp_helpers.h file shipped with libxdp contains helper macros to include this information, which can be used as follows:

#include <bpf/bpf_helpers.h>
#include <xdp/xdp_helpers.h>

struct {
        __uint(priority, 10);
        __uint(XDP_PASS, 1);
        __uint(XDP_DROP, 1);
} XDP_RUN_CONFIG(my_xdp_func);

This example specifies that the XDP program in my_xdp_func should have priority 10 and that its chain call actions are XDP_PASS and XDP_DROP. In a source file with multiple XDP programs in the same file, a definition like the above can be included for each program (main XDP function). Any program that does not specify any config information will use the default values outlined above.

libxdp exposes the following functions that an application can use to inspect and modify the metadata on an XDP program. Modification is only possible before a program is attached on an interface. These functions won't modify the BTF information itself, but the new values will be stored as part of the program attachment.

unsigned int xdp_program__run_prio(const struct xdp_program *xdp_prog);
int xdp_program__set_run_prio(struct xdp_program *xdp_prog,
                              unsigned int run_prio);
bool xdp_program__chain_call_enabled(const struct xdp_program *xdp_prog,
                                     enum xdp_action action);
int xdp_program__set_chain_call_enabled(struct xdp_program *prog,
                                        unsigned int action,
                                        bool enabled);
int xdp_program__print_chain_call_actions(const struct xdp_program *prog,
                                          char *buf,
                                          size_t buf_len);

The kernel will automatically detach component programs from the dispatcher once the last reference to them disappears. To prevent this from happening, libxdp will pin the component program references in bpffs before attaching the dispatcher to the network interface. The pathnames generated for pinning is as follows:

—

/sys/fs/bpf/xdp/dispatch-IFINDEX-DID - dispatcher program for IFINDEX with BPF program ID DID

—

/sys/fs/bpf/xdp/dispatch-IFINDEX-DID/prog0-prog - component program 0, program reference

—

/sys/fs/bpf/xdp/dispatch-IFINDEX-DID/prog0-link - component program 0, bpf_link reference

—

/sys/fs/bpf/xdp/dispatch-IFINDEX-DID/prog1-prog - component program 1, program reference

—

/sys/fs/bpf/xdp/dispatch-IFINDEX-DID/prog1-link - component program 1, bpf_link reference

—

etc, up to ten component programs

If set, the LIBXDP_BPFFS environment variable will override the location of bpffs, but the xdp subdirectory is always used. If no bpffs is mounted, libxdp will consult the environment variable LIBXDP_BPFFS_AUTOMOUNT. If this is set to 1, libxdp will attempt to automount a bpffs. If not, libxdp will fall back to loading a single program without a dispatcher, as if the kernel did not support the features needed for multiprog attachment.

Libxdp provides helper functions for creating and destroying umems and sockets as shown below. The first thing that a user generally wants to do is to create a umem area. This is the area that will contain all packets received and the ones that are going to be sent. After that, AF_XDP sockets can be created tied to this umem. These can either be sockets that have exclusive ownership of that umem through xsk_socket__create() or shared with other sockets using xsk_socket__create_shared. There is one option called XSK_LIBBPF_FLAGS__INHIBIT_PROG_LOAD that can be set in the libxdp_flags field (also called libbpf_flags for compatibility reasons). This will make libxdp not load any XDP program or set and BPF maps which is a must if users want to add their own XDP program.

If there is already a socket created with socket(AF_XDP, SOCK_RAW, 0) not bound and not tied to any umem, file descriptor of this socket can be used in an xsk_umem__create_with_fd() variant of the umem creation function.

int xsk_umem__create(struct xsk_umem **umem,
                     void *umem_area, __u64 size,
                     struct xsk_ring_prod *fill,
                     struct xsk_ring_cons *comp,
                     const struct xsk_umem_config *config);
int xsk_umem__create_with_fd(struct xsk_umem **umem,
                             int fd, void *umem_area, __u64 size,
                             struct xsk_ring_prod *fill,
                             struct xsk_ring_cons *comp,
                             const struct xsk_umem_config *config);
int xsk_socket__create(struct xsk_socket **xsk,
                       const char *ifname, __u32 queue_id,
                       struct xsk_umem *umem,
                       struct xsk_ring_cons *rx,
                       struct xsk_ring_prod *tx,
                       const struct xsk_socket_config *config);
int xsk_socket__create_shared(struct xsk_socket **xsk_ptr,
                              const char *ifname,
                              __u32 queue_id, struct xsk_umem *umem,
                              struct xsk_ring_cons *rx,
                              struct xsk_ring_prod *tx,
                              struct xsk_ring_prod *fill,
                              struct xsk_ring_cons *comp,
                              const struct xsk_socket_config *config);
int xsk_umem__delete(struct xsk_umem *umem);
void xsk_socket__delete(struct xsk_socket *xsk);

There are also two helper function to get the file descriptor of a umem or a socket. These are needed when using standard Linux syscalls such as poll(), recvmsg(), sendto(), etc.

int xsk_umem__fd(const struct xsk_umem *umem);
int xsk_socket__fd(const struct xsk_socket *xsk);

The control path also provides two APIs for setting up AF_XDP sockets when the process that is going to use the AF_XDP socket is non-privileged. These two functions perform the operations that require privileges and can be executed from some form of control process that has the necessary privileges. The xsk_socket__create executed on the non-privileged process will then skip these two steps. For an example on how to use these, please take a look at the AF_XDP-example program in the bpf-examples repository: https://github.com/xdp-project/bpf-examples/tree/master/AF_XDP-example.

int xsk_setup_xdp_prog(int ifindex, int *xsks_map_fd);
int xsk_socket__update_xskmap(struct xsk_socket *xsk, int xsks_map_fd);

To further reduce required level of privileges, an AF_XDP socket can be created beforehand with socket(AF_XDP, SOCK_RAW, 0) and passed to a non-privileged process.  This socket can be used in xsk_umem__create_with_fd() and later in xsk_socket__create() with created umem.  xsk_socket__create_shared() would still require privileges for AF_XDP socket creation.

For performance reasons, all the data path functions are static inline functions found in the xsk.h header file so they can be optimized into the target application binary for best possible performance. There are four FIFO rings of two main types: producer rings (fill and Tx) and consumer rings (Rx and completion). The producer rings use xsk_ring_prod functions and consumer rings use xsk_ring_cons functions. For producer rings, you start with reserving one or more slots in a producer ring and then when they have been filled out, you submit them so that the kernel will act on them. For a consumer ring, you peek if there are any new packets in the ring and if so you can read them from the ring. Once you are done reading them, you release them back to the kernel so it can use them for new packets. There is also a cancel operation for consumer rings if the application does not want to consume all packets received with the peek operation.

__u32 xsk_ring_prod__reserve(struct xsk_ring_prod *prod, __u32 nb, __u32 *idx);
void xsk_ring_prod__submit(struct xsk_ring_prod *prod, __u32 nb);
__u32 xsk_ring_cons__peek(struct xsk_ring_cons *cons, __u32 nb, __u32 *idx);
void xsk_ring_cons__cancel(struct xsk_ring_cons *cons, __u32 nb);
void xsk_ring_cons__release(struct xsk_ring_cons *cons, __u32 nb);

The functions below are used for reading and writing the descriptors of the rings. xsk_ring_prod__fill_addr() and xsk_ring_prod__tx_desc() writes entries in the fill and Tx rings respectively, while xsk_ring_cons__comp_addr and xsk_ring_cons__rx_desc reads entries from the completion and Rx rings respectively. The idx is the parameter returned in the xsk_ring_prod__reserve or xsk_ring_cons__peek calls. To advance to the next entry, simply do idx++.

__u64 *xsk_ring_prod__fill_addr(struct xsk_ring_prod *fill, __u32 idx);
struct xdp_desc *xsk_ring_prod__tx_desc(struct xsk_ring_prod *tx, __u32 idx);
const __u64 *xsk_ring_cons__comp_addr(const struct xsk_ring_cons *comp, __u32 idx);
const struct xdp_desc *xsk_ring_cons__rx_desc(const struct xsk_ring_cons *rx, __u32 idx);

The xsk_umem functions are used to get a pointer to the packet data itself, always located inside the umem. In the default aligned mode, you can get the addr variable straight from the Rx descriptor. But in unaligned mode, you need to use the three last function below as the offset used is carried in the upper 16 bits of the addr. Therefore, you cannot use the addr straight from the descriptor in the unaligned case.

void *xsk_umem__get_data(void *umem_area, __u64 addr);
__u64 xsk_umem__extract_addr(__u64 addr);
__u64 xsk_umem__extract_offset(__u64 addr);
__u64 xsk_umem__add_offset_to_addr(__u64 addr);

There is one more function in the data path and that checks if the need_wakeup flag is set. Use of this flag is highly encouraged and should be enabled by setting XDP_USE_NEED_WAKEUP bit in the xdp_bind_flags field that is provided to the xsk_socket_create_[shared]() calls. If this function returns true, then you need to call recvmsg(), sendto(), or poll() depending on the situation. recvmsg() if you are receiving, or sendto() if you are sending. poll() can be used for both cases and provide the ability to sleep too, as with any other socket. But note that poll is a slower operation than the other two.

int xsk_ring_prod__needs_wakeup(const struct xsk_ring_prod *r);

For an example on how to use all these APIs, take a look at the AF_XDP-example and AF_XDP-forwarding programs in the bpf-examples repository: https://github.com/xdp-project/bpf-examples.