Skip to contentSkip to conversation

docs/bpf: Add docs for BPF_PROG_TYPE_XDP

PATCH In review Donald Hunter 2 participants 2 messages Dec 12, 2022

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs/bpf: Add docs for BPF_PROG_TYPE_XDP

Document XDP programs (BPF_PROG_TYPE_XDP) and the XDP data path.

---
 Documentation/bpf/prog_xdp.rst | 176 +++++++++++++++++++++++++++++++++
 1 file changed, 176 insertions(+)
 create mode 100644 Documentation/bpf/prog_xdp.rst
Documentation/bpf/prog_xdp.rst new file +176 -0
new file mode 100644
index 000000000000..69b001a6c7d2
@@ -0,0 +1,176 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+.. Copyright (C) 2022 Red Hat, Inc.
+
+================
+XDP BPF Programs
+================
+
+XDP (eXpress Data Path) is a fast path in the kernel network stack. XDP allows
+for packet processing by BPF programs before the packets traverse the L4-L7
+network stack. Programs of type ``BPF_PROG_TYPE_XDP`` are attached to the XDP
+hook of a specific interface in one of three modes:
+
+- ``SKB_MODE`` - The hook point is in the generic net device
+- ``DRV_MODE`` - The hook point is in the driver for the interface
+- ``HW_MODE`` - The BPF program is offloaded to the NIC
+
+The BPF program attached to an interface's XDP hook gets called for each L2
+frame that is received on the interface. The program is passed a ``struct xdp_md
+*ctx`` which gives access to the L2 data frame as well as some essential
+metadata for the frame:
+
+.. code-block:: c
+
+    struct xdp_md {
+            __u32 data;
+            __u32 data_end;
+            __u32 data_meta;
+
+            __u32 ingress_ifindex; /* rxq->dev->ifindex */
+            __u32 rx_queue_index;  /* rxq->queue_index  */
+            __u32 egress_ifindex;  /* txq->dev->ifindex */
+    };
+
+The BPF program can read and modify the frame before deciding what action should
+be taken for the packet. The program returns one of the following action values
+in order to tell the driver or net device how to process the packet (details in
+:ref:`xdp_packet_actions`):
+
+- ``XDP_DROP`` - Drop the packet without any further processing
+- ``XDP_PASS`` - Pass the packet to the kernel network stack for further
+  processing
+- ``XDP_TX`` - Transmit the packet out of the same interface
+- ``XDP_REDIRECT`` - Redirect the packet to a specific destination
+- ``XDP_ABORTED`` - Drop the packet and notify an exception state
+
+There are many BPF helper functions available to XDP programs for accessing and
+modifying packet data, for interacting with the kernel networking stack and for
+using BPF maps. `bpf-helpers(7)`_ describes the helpers available to XDP
+programs.
+
+The `libxdp`_ library provides functions for attaching XDP programs to network
+interfaces and for using ``AF_XDP`` sockets.
+
+XDP Modes
+=========
+
+SKB Mode
+--------
+
+An XDP program attached in SKB mode gets executed by the kernel network stack
+*after* the driver has created a ``struct sk_buff`` (SKB) and passed it to the
+networking stack. SKB mode is also referred to as *generic* mode and is always
+available, whether or not the driver is XDP-enabled. An XDP program in SKB mode
+is run by the netdev before classifiers or ``tc`` BPF programs are run.
+
+Driver Mode
+-----------
+
+An XDP program attached in driver mode gets executed by the network driver for
+an interface *before* the driver creates a ``struct sk_buff`` (SKB) for the
+incoming packet. The XDP program runs immediately after the driver receives the
+packet. This gives the XDP program an opportunity to entirely avoid the cost of
+SKB creation and kernel network stack processing.
+
+Driver mode requires the driver to be XDP-enabled so is not always available.
+
+Hardware Mode
+-------------
+
+Some devices may support hardware offload of BPF programs, which they do in a
+hardware specific way.
+
+.. _xdp_packet_actions:
+
+XDP Packet Actions
+==================
+
+XDP_DROP
+--------
+
+The ``XDP_DROP`` action tells the driver or netdev to drop the XDP frame without
+any further processing.
+
+XDP_PASS
+--------
+
+The ``XDP_PASS`` action tells the driver to convert the XDP frame into an SKB
+and the driver or netdev to pass the SKB on to the kernel network stack for
+normal processing.
+
+XDP_TX
+------
+
+The ``XDP_TX`` action tells the driver or netdev to transmit the XDP frame out
+of the associated interface.
+
+XDP_REDIRECT
+------------
+
+The ``XDP_REDIRECT`` action tells the driver to redirect the packet for further
+processing. There are several types of redirect available to the XDP program:
+
+- Redirect to another device by ifindex
+- Redirect to another device using a devmap
+- Redirect into an ``AF_XDP`` socket using an xskmap
+- Redirect to another CPU using a cpumap, before delivering to the network stack
+
+The ``bpf_redirect()`` and ``bpf_redirect_map()`` helper functions are used
+to set up the desired redirect destination before returning ``XDP_REDIRECT`` to
+the driver.
+
+.. code-block:: c
+
+    long bpf_redirect(u32 ifindex, u64 flags)
+
+The ``bpf_redirect()`` helper function redirects the packet to the net device
+identified by ``ifindex``.
+
+.. code-block:: c
+
+    long bpf_redirect_map(struct bpf_map *map, u32 key, u64 flags)
+
+The ``bpf_redirect_map()`` helper function redirects the packet to the
+destination referenced by ``map`` at index ``key``. The type of destination
+depends on the type ``map`` that is used:
+
+- ``BPF_MAP_TYPE_DEVMAP`` and ``BPF_MAP_TYPE_DEVMAP_HASH`` redirects the packet
+  to another net device
+- ``BPF_MAP_TYPE_CPUMAP`` redirects the packet processing to a specific CPU
+- ``BPF_MAP_TYPE_XSKMAP`` redirects the packet to an ``AF_XDP`` socket. See
+  ../networking/af_xdp.rst for more information.
+
+Detailed behaviour of ``bpf_redirect()`` and ``bpf_redirect_map()`` is described
+in `bpf-helpers(7)`_. ``XDP_REDIRECT`` is described in more detail in
+redirect.rst.
+
+XDP_ABORTED
+-----------
+
+The ``XDP_ABORTED`` action tells the driver that the BPF program exited in an
+exception state. The driver will drop the packet in the same way as if the BPF
+program returned ``XDP_DROP`` but the ``trace_xdp_exception`` trace point is also
+triggered.
+
+Examples
+========
+
+An example XDP program that uses ``XDP_REDIRECT`` can be found in
+`tools/testing/selftests/bpf/progs/xdp_redirect_multi_kern.c`_ and the
+corresponding user space code in
+`tools/testing/selftests/bpf/xdp_redirect_multi.c`_
+
+References
+==========
+
+- https://github.com/xdp-project/xdp-tools
+- https://github.com/xdp-project/xdp-tutorial
+- https://docs.cilium.io/en/latest/bpf/progtypes
+
+.. Links
+.. _bpf-helpers(7): https://man7.org/linux/man-pages/man7/bpf-helpers.7.html
+.. _libxdp: https://github.com/xdp-project/xdp-tools/tree/master/lib/libxdp
+.. _tools/testing/selftests/bpf/progs/xdp_redirect_multi_kern.c:
+   https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/bpf/progs/xdp_redirect_multi_kern.c
+.. _tools/testing/selftests/bpf/xdp_redirect_multi.c:
+   https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/bpf/xdp_redirect_multi.c
Signature · 1 line
2.38.1
#1 lore raw
Quoted 14 lines · Donald Hunter

Document XDP programs (BPF_PROG_TYPE_XDP) and the XDP data path.

---
 Documentation/bpf/prog_xdp.rst | 176 +++++++++++++++++++++++++++++++++
 1 file changed, 176 insertions(+)
 create mode 100644 Documentation/bpf/prog_xdp.rst
Documentation/bpf/prog_xdp.rst new file +0 -0
new file mode 100644
index 000000000000..69b001a6c7d2

Documentation/bpf/prog_xdp.rst line 10

Quoted 10 lines
Documentation/bpf/prog_xdp.rst new file +10 -0
@@ -0,0 +1,176 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+.. Copyright (C) 2022 Red Hat, Inc.
+
+================
+XDP BPF Programs
+================
+
+XDP (eXpress Data Path) is a fast path in the kernel network stack. XDP allows
+for packet processing by BPF programs before the packets traverse the L4-L7
+network stack.

The 'L4-L7' thing is not really accurate, and it's not really relevant here either, so just leave it out? Maybe:

"XDP (eXpress Data Path) is a fast path in the kernel network stack. XDP allows for packet processing by BPF programs in the driver, before the packets traverse the kernel networking stack"?

Documentation/bpf/prog_xdp.rst line 15

Quoted 6 lines

Programs of type ``BPF_PROG_TYPE_XDP`` are attached to the XDP

Documentation/bpf/prog_xdp.rst new file +5 -0
+hook of a specific interface in one of three modes:
+
+- ``SKB_MODE`` - The hook point is in the generic net device
+- ``DRV_MODE`` - The hook point is in the driver for the interface
+- ``HW_MODE`` - The BPF program is offloaded to the NIC

How about moving the attach mode stuff a bit later? When it's mentioned this early it seems more important than it really is. Since the "modes" is the next section, we could just leave it out of this intro altogether (and move this paragraph into the beginning of the "XDP modes" section below)?

Quoted 5 lines
Documentation/bpf/prog_xdp.rst new file +5 -0
+The BPF program attached to an interface's XDP hook gets called for each L2
+frame that is received on the interface. The program is passed a ``struct xdp_md
+*ctx`` which gives access to the L2 data frame as well as some essential
+metadata for the frame:
+

Documentation/bpf/prog_xdp.rst line 31

Quoted 10 lines
Documentation/bpf/prog_xdp.rst new file +10 -0
+.. code-block:: c
+
+    struct xdp_md {
+            __u32 data;
+            __u32 data_end;
+            __u32 data_meta;
+
+            __u32 ingress_ifindex; /* rxq->dev->ifindex */
+            __u32 rx_queue_index;  /* rxq->queue_index  */
+            __u32 egress_ifindex;  /* txq->dev->ifindex */

Not sure it's relevant to show which kernel structures the data comes from? Maybe change the comments to be English descriptions (like "ingress ifindex", "ingress RXQ index"). We should also mention that egress_ifindex is only available the program is attached to a devmap. And, erm, the text should mention that XDP programs can be attached to a devmap somewhere? :)

Documentation/bpf/prog_xdp.rst

Quoted 4 lines
Documentation/bpf/prog_xdp.rst new file +4 -0
+    };
+
+The BPF program can read and modify the frame before deciding what action should
+be taken for the packet.

Do we explain how to do that anywhere? I.e., is the "direct data access" thing explained in some other doc?

Quoted 20 lines

The program returns one of the following action values

Documentation/bpf/prog_xdp.rst new file +19 -0
+in order to tell the driver or net device how to process the packet (details in
+:ref:`xdp_packet_actions`):
+
+- ``XDP_DROP`` - Drop the packet without any further processing
+- ``XDP_PASS`` - Pass the packet to the kernel network stack for further
+  processing
+- ``XDP_TX`` - Transmit the packet out of the same interface
+- ``XDP_REDIRECT`` - Redirect the packet to a specific destination
+- ``XDP_ABORTED`` - Drop the packet and notify an exception state
+
+There are many BPF helper functions available to XDP programs for accessing and
+modifying packet data, for interacting with the kernel networking stack and for
+using BPF maps. `bpf-helpers(7)`_ describes the helpers available to XDP
+programs.
+
+The `libxdp`_ library provides functions for attaching XDP programs to network
+interfaces and for using ``AF_XDP`` sockets.
+
+XDP Modes

Documentation/bpf/prog_xdp.rst line 64

Quoted 10 lines
Documentation/bpf/prog_xdp.rst new file +10 -0
+=========
+
+SKB Mode
+--------
+
+An XDP program attached in SKB mode gets executed by the kernel network stack
+*after* the driver has created a ``struct sk_buff`` (SKB) and passed it to the
+networking stack. SKB mode is also referred to as *generic* mode and is always
+available, whether or not the driver is XDP-enabled. An XDP program in SKB mode
+is run by the netdev before classifiers or ``tc`` BPF programs are run.

I think we should add some text saying that the SKB mode has a significant performance overhead compared to driver mode, and that the TC hook in many cases is a better choice than using XDP in SKB mode.

I'd also move SKB mode below driver mode, to highlight that driver mode is really the "main" XDP execution mode.

Documentation/bpf/prog_xdp.rst line 75

Quoted 10 lines
Documentation/bpf/prog_xdp.rst new file +10 -0
+Driver Mode
+-----------
+
+An XDP program attached in driver mode gets executed by the network driver for
+an interface *before* the driver creates a ``struct sk_buff`` (SKB) for the
+incoming packet. The XDP program runs immediately after the driver receives the
+packet. This gives the XDP program an opportunity to entirely avoid the cost of
+SKB creation and kernel network stack processing.
+
+Driver mode requires the driver to be XDP-enabled so is not always available.

Since this is supposed to be the authoritative documentation on XDP, should we list which drivers support XDP here?

Documentation/bpf/prog_xdp.rst line 81

Quoted 5 lines
Documentation/bpf/prog_xdp.rst new file +5 -0
+Hardware Mode
+-------------
+
+Some devices may support hardware offload of BPF programs, which they do in a
+hardware specific way.

"...which they do in a hardware-specific way, meaning that some features and helpers are not available to offloaded programs." ?

Also, as above, should we mention that only the nfp driver supports this?

Quoted 76 lines

+.. _xdp_packet_actions:

Documentation/bpf/prog_xdp.rst new file +75 -0
+
+XDP Packet Actions
+==================
+
+XDP_DROP
+--------
+
+The ``XDP_DROP`` action tells the driver or netdev to drop the XDP frame without
+any further processing.
+
+XDP_PASS
+--------
+
+The ``XDP_PASS`` action tells the driver to convert the XDP frame into an SKB
+and the driver or netdev to pass the SKB on to the kernel network stack for
+normal processing.
+
+XDP_TX
+------
+
+The ``XDP_TX`` action tells the driver or netdev to transmit the XDP frame out
+of the associated interface.
+
+XDP_REDIRECT
+------------
+
+The ``XDP_REDIRECT`` action tells the driver to redirect the packet for further
+processing. There are several types of redirect available to the XDP program:
+
+- Redirect to another device by ifindex
+- Redirect to another device using a devmap
+- Redirect into an ``AF_XDP`` socket using an xskmap
+- Redirect to another CPU using a cpumap, before delivering to the network stack
+
+The ``bpf_redirect()`` and ``bpf_redirect_map()`` helper functions are used
+to set up the desired redirect destination before returning ``XDP_REDIRECT`` to
+the driver.
+
+.. code-block:: c
+
+    long bpf_redirect(u32 ifindex, u64 flags)
+
+The ``bpf_redirect()`` helper function redirects the packet to the net device
+identified by ``ifindex``.
+
+.. code-block:: c
+
+    long bpf_redirect_map(struct bpf_map *map, u32 key, u64 flags)
+
+The ``bpf_redirect_map()`` helper function redirects the packet to the
+destination referenced by ``map`` at index ``key``. The type of destination
+depends on the type ``map`` that is used:
+
+- ``BPF_MAP_TYPE_DEVMAP`` and ``BPF_MAP_TYPE_DEVMAP_HASH`` redirects the packet
+  to another net device
+- ``BPF_MAP_TYPE_CPUMAP`` redirects the packet processing to a specific CPU
+- ``BPF_MAP_TYPE_XSKMAP`` redirects the packet to an ``AF_XDP`` socket. See
+  ../networking/af_xdp.rst for more information.
+
+Detailed behaviour of ``bpf_redirect()`` and ``bpf_redirect_map()`` is described
+in `bpf-helpers(7)`_. ``XDP_REDIRECT`` is described in more detail in
+redirect.rst.
+
+XDP_ABORTED
+-----------
+
+The ``XDP_ABORTED`` action tells the driver that the BPF program exited in an
+exception state. The driver will drop the packet in the same way as if the BPF
+program returned ``XDP_DROP`` but the ``trace_xdp_exception`` trace point is also
+triggered.
+
+Examples
+========
+
+An example XDP program that uses ``XDP_REDIRECT`` can be found in

Documentation/bpf/prog_xdp.rst line 168

Quoted 10 lines
Documentation/bpf/prog_xdp.rst new file +10 -0
+`tools/testing/selftests/bpf/progs/xdp_redirect_multi_kern.c`_ and the
+corresponding user space code in
+`tools/testing/selftests/bpf/xdp_redirect_multi.c`_
+
+References
+==========
+
+- https://github.com/xdp-project/xdp-tools
+- https://github.com/xdp-project/xdp-tutorial
+- https://docs.cilium.io/en/latest/bpf/progtypes

Should we incorporate (some of) the text from the Cilium doc instead of linking to it (assuming the license is compatible, of course)?

-Toke