mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-09-27 04:47:05 +00:00
bpf: Document XDP RX metadata
Document all current use-cases and assumptions. Cc: John Fastabend <john.fastabend@gmail.com> Cc: David Ahern <dsahern@gmail.com> Cc: Martin KaFai Lau <martin.lau@linux.dev> Cc: Jakub Kicinski <kuba@kernel.org> Cc: Willem de Bruijn <willemb@google.com> Cc: Jesper Dangaard Brouer <brouer@redhat.com> Cc: Anatoly Burakov <anatoly.burakov@intel.com> Cc: Alexander Lobakin <alexandr.lobakin@intel.com> Cc: Magnus Karlsson <magnus.karlsson@gmail.com> Cc: Maryam Tahhan <mtahhan@redhat.com> Cc: xdp-hints@xdp-project.net Cc: netdev@vger.kernel.org Acked-by: David Vernet <void@manifault.com> Signed-off-by: Stanislav Fomichev <sdf@google.com> Link: https://lore.kernel.org/r/20230119221536.3349901-2-sdf@google.com Signed-off-by: Martin KaFai Lau <martin.lau@kernel.org>
This commit is contained in:
parent
84150795a4
commit
a4aeb9d656
2 changed files with 111 additions and 0 deletions
|
@ -120,6 +120,7 @@ Contents:
|
|||
xfrm_proc
|
||||
xfrm_sync
|
||||
xfrm_sysctl
|
||||
xdp-rx-metadata
|
||||
|
||||
.. only:: subproject and html
|
||||
|
||||
|
|
110
Documentation/networking/xdp-rx-metadata.rst
Normal file
110
Documentation/networking/xdp-rx-metadata.rst
Normal file
|
@ -0,0 +1,110 @@
|
|||
===============
|
||||
XDP RX Metadata
|
||||
===============
|
||||
|
||||
This document describes how an eXpress Data Path (XDP) program can access
|
||||
hardware metadata related to a packet using a set of helper functions,
|
||||
and how it can pass that metadata on to other consumers.
|
||||
|
||||
General Design
|
||||
==============
|
||||
|
||||
XDP has access to a set of kfuncs to manipulate the metadata in an XDP frame.
|
||||
Every device driver that wishes to expose additional packet metadata can
|
||||
implement these kfuncs. The set of kfuncs is declared in ``include/net/xdp.h``
|
||||
via ``XDP_METADATA_KFUNC_xxx``.
|
||||
|
||||
Currently, the following kfuncs are supported. In the future, as more
|
||||
metadata is supported, this set will grow:
|
||||
|
||||
.. kernel-doc:: net/core/xdp.c
|
||||
:identifiers: bpf_xdp_metadata_rx_timestamp bpf_xdp_metadata_rx_hash
|
||||
|
||||
An XDP program can use these kfuncs to read the metadata into stack
|
||||
variables for its own consumption. Or, to pass the metadata on to other
|
||||
consumers, an XDP program can store it into the metadata area carried
|
||||
ahead of the packet.
|
||||
|
||||
Not all kfuncs have to be implemented by the device driver; when not
|
||||
implemented, the default ones that return ``-EOPNOTSUPP`` will be used.
|
||||
|
||||
Within an XDP frame, the metadata layout (accessed via ``xdp_buff``) is
|
||||
as follows::
|
||||
|
||||
+----------+-----------------+------+
|
||||
| headroom | custom metadata | data |
|
||||
+----------+-----------------+------+
|
||||
^ ^
|
||||
| |
|
||||
xdp_buff->data_meta xdp_buff->data
|
||||
|
||||
An XDP program can store individual metadata items into this ``data_meta``
|
||||
area in whichever format it chooses. Later consumers of the metadata
|
||||
will have to agree on the format by some out of band contract (like for
|
||||
the AF_XDP use case, see below).
|
||||
|
||||
AF_XDP
|
||||
======
|
||||
|
||||
:doc:`af_xdp` use-case implies that there is a contract between the BPF
|
||||
program that redirects XDP frames into the ``AF_XDP`` socket (``XSK``) and
|
||||
the final consumer. Thus the BPF program manually allocates a fixed number of
|
||||
bytes out of metadata via ``bpf_xdp_adjust_meta`` and calls a subset
|
||||
of kfuncs to populate it. The userspace ``XSK`` consumer computes
|
||||
``xsk_umem__get_data() - METADATA_SIZE`` to locate that metadata.
|
||||
Note, ``xsk_umem__get_data`` is defined in ``libxdp`` and
|
||||
``METADATA_SIZE`` is an application-specific constant (``AF_XDP`` receive
|
||||
descriptor does _not_ explicitly carry the size of the metadata).
|
||||
|
||||
Here is the ``AF_XDP`` consumer layout (note missing ``data_meta`` pointer)::
|
||||
|
||||
+----------+-----------------+------+
|
||||
| headroom | custom metadata | data |
|
||||
+----------+-----------------+------+
|
||||
^
|
||||
|
|
||||
rx_desc->address
|
||||
|
||||
XDP_PASS
|
||||
========
|
||||
|
||||
This is the path where the packets processed by the XDP program are passed
|
||||
into the kernel. The kernel creates the ``skb`` out of the ``xdp_buff``
|
||||
contents. Currently, every driver has custom kernel code to parse
|
||||
the descriptors and populate ``skb`` metadata when doing this ``xdp_buff->skb``
|
||||
conversion, and the XDP metadata is not used by the kernel when building
|
||||
``skbs``. However, TC-BPF programs can access the XDP metadata area using
|
||||
the ``data_meta`` pointer.
|
||||
|
||||
In the future, we'd like to support a case where an XDP program
|
||||
can override some of the metadata used for building ``skbs``.
|
||||
|
||||
bpf_redirect_map
|
||||
================
|
||||
|
||||
``bpf_redirect_map`` can redirect the frame to a different device.
|
||||
Some devices (like virtual ethernet links) support running a second XDP
|
||||
program after the redirect. However, the final consumer doesn't have
|
||||
access to the original hardware descriptor and can't access any of
|
||||
the original metadata. The same applies to XDP programs installed
|
||||
into devmaps and cpumaps.
|
||||
|
||||
This means that for redirected packets only custom metadata is
|
||||
currently supported, which has to be prepared by the initial XDP program
|
||||
before redirect. If the frame is eventually passed to the kernel, the
|
||||
``skb`` created from such a frame won't have any hardware metadata populated
|
||||
in its ``skb``. If such a packet is later redirected into an ``XSK``,
|
||||
that will also only have access to the custom metadata.
|
||||
|
||||
bpf_tail_call
|
||||
=============
|
||||
|
||||
Adding programs that access metadata kfuncs to the ``BPF_MAP_TYPE_PROG_ARRAY``
|
||||
is currently not supported.
|
||||
|
||||
Example
|
||||
=======
|
||||
|
||||
See ``tools/testing/selftests/bpf/progs/xdp_metadata.c`` and
|
||||
``tools/testing/selftests/bpf/prog_tests/xdp_metadata.c`` for an example of
|
||||
BPF program that handles XDP metadata.
|
Loading…
Reference in a new issue