1
1
.TH "libxdp" "3" "January 14, 2025" "v1.5.2" "libxdp - library for loading XDP programs"
2
-
3
2
.SH "NAME"
4
3
libxdp \- library for attaching XDP programs and using AF_XDP sockets
5
4
.SH "SYNOPSIS"
@@ -22,7 +21,6 @@ well as reading and writing packets from these sockets.
22
21
.PP
23
22
Some of the functionality provided by libxdp depends on particular kernel
24
23
features; see the "Kernel feature compatibility" section below for details.
25
-
26
24
.SS "Using libxdp from an application"
27
25
.PP
28
26
Basic usage of libxdp from an application is quite straight forward. The
@@ -101,12 +99,10 @@ that program will have to be detached from the interface before libxdp can
101
99
attach a new one. This can be done by calling \fI xdp_program__detach() \fP with a
102
100
reference to the loaded program; but note that this will of course break any
103
101
application relying on that other XDP program to be present.
104
-
105
102
.SH "Program metadata"
106
103
.PP
107
104
To support multiple XDP programs on the same interface, libxdp uses two pieces
108
105
of metadata for each XDP program: Run priority and chain call actions.
109
-
110
106
.SS "Run priority"
111
107
.PP
112
108
This is the priority of the program and is a simple integer used
@@ -116,7 +112,6 @@ for this, while programs that want to run later (such as a packet forwarder or
116
112
counter) should set higher values. Note that later programs are only run if the
117
113
previous programs end with a return code that is part of its chain call actions
118
114
(see below). If not specified, the default priority value is 50.
119
-
120
115
.SS "Chain call actions"
121
116
.PP
122
117
These are the program return codes that the program indicate for packets that
@@ -125,7 +120,6 @@ programs in the call chain will be run, whereas if it returns any other action,
125
120
processing will be interrupted, and the XDP dispatcher will return the verdict
126
121
immediately. If not set, this defaults to just XDP_PASS, which is likely the
127
122
value most programs should use.
128
-
129
123
.SS "Specifying metadata"
130
124
.PP
131
125
The metadata outlined above is specified as BTF information embedded in the ELF
@@ -154,7 +148,6 @@ In a source file with multiple XDP programs in the same file, a definition like
154
148
the above can be included for each program (main XDP function). Any program that
155
149
does not specify any config information will use the default values outlined
156
150
above.
157
-
158
151
.SS "Inspecting and modifying metadata"
159
152
.PP
160
153
\fI libxdp \fP exposes the following functions that an application can use to inspect
@@ -179,7 +172,6 @@ int xdp_program__print_chain_call_actions(const struct xdp_program *prog,
179
172
\fP
180
173
.fi
181
174
.RE
182
-
183
175
.SH "The dispatcher program"
184
176
.PP
185
177
To support multiple non-offloaded programs on the same network interface,
@@ -229,7 +221,6 @@ be acquired using \fIxdp_multiprog_hw_prog()\fP. Function
229
221
\fI xdp_multiprog__attach_mode() \fP returns the attach mode of the non-offloaded
230
222
program, whether an offloaded program is attached should be checked through
231
223
\fI xdp_multiprog_hw_prog() \fP .
232
-
233
224
.SS "Pinning in bpffs"
234
225
.PP
235
226
The kernel will automatically detach component programs from the dispatcher once
@@ -258,7 +249,6 @@ libxdp will consult the environment variable \fILIBXDP_BPFFS_AUTOMOUNT\fP. If th
258
249
is set to \fI 1 \fP , libxdp will attempt to automount a bpffs. If not, libxdp will
259
250
fall back to loading a single program without a dispatcher, as if the kernel did
260
251
not support the features needed for multiprog attachment.
261
-
262
252
.SH "Using AF_XDP sockets"
263
253
.PP
264
254
Libxdp implements helper functions for configuring AF_XDP sockets as
@@ -282,7 +272,6 @@ and the documentation in the Linux kernel
282
272
For an example on how to use the interface, take a look at the AF_XDP-example
283
273
and AF_XDP-forwarding programs in the bpf-examples repository:
284
274
\fI https://github.com/xdp-project/bpf-examples \fP .
285
-
286
275
.SS "Control path"
287
276
.PP
288
277
Libxdp provides helper functions for creating and destroying umems and
@@ -377,7 +366,6 @@ beforehand with socket(AF_XDP, SOCK_RAW, 0) and passed to a non-privileged
377
366
process. This socket can be used in xsk_umem__create_opts() and later in
378
367
xsk_socket__create() with created umem. xsk_socket__create_shared() would
379
368
still require privileges for AF_XDP socket creation.
380
-
381
369
.SS "Data path"
382
370
.PP
383
371
For performance reasons, all the data path functions are static inline
@@ -468,7 +456,6 @@ operation than the other two.
468
456
For an example on how to use all these APIs, take a look at the AF_XDP-example
469
457
and AF_XDP-forwarding programs in the bpf-examples repository:
470
458
\fI https://github.com/xdp-project/bpf-examples \fP .
471
-
472
459
.SH "Kernel and BPF program feature compatibility"
473
460
.PP
474
461
The features exposed by libxdp relies on certain kernel versions and BPF
@@ -513,11 +500,9 @@ Finally, XDP programs loaded using the multiprog facility must include type
513
500
information (using the BPF Type Format, BTF). To get this, compile the programs
514
501
with a recent version of Clang/LLVM (version 10+), and enable debug information
515
502
when compiling (using the \fI \- g \fP option).
516
-
517
503
.SH "BUGS"
518
504
.PP
519
505
Please report any bugs on Github: \fI https://github.com/xdp-project/xdp-tools/issues \fP
520
-
521
506
.SH "AUTHORS"
522
507
.PP
523
508
libxdp and this man page were written by Toke
0 commit comments