915efd8a44
When driver doesn't implement a bpf_xdp_metadata kfunc the fallback implementation returns EOPNOTSUPP, which indicate device driver doesn't implement this kfunc. Currently many drivers also return EOPNOTSUPP when the hint isn't available, which is ambiguous from an API point of view. Instead change drivers to return ENODATA in these cases. There can be natural cases why a driver doesn't provide any hardware info for a specific hint, even on a frame to frame basis (e.g. PTP). Lets keep these cases as separate return codes. When describing the return values, adjust the function kernel-doc layout to get proper rendering for the return values. Fixes:ab46182d0d("net/mlx4_en: Support RX XDP metadata") Fixes:bc8d405b1b("net/mlx5e: Support RX XDP metadata") Fixes:306531f024("veth: Support RX XDP metadata") Fixes:3d76a4d3d4("bpf: XDP metadata RX kfuncs") Signed-off-by: Jesper Dangaard Brouer <brouer@redhat.com> Acked-by: Stanislav Fomichev <sdf@google.com> Acked-by: Toke Høiland-Jørgensen <toke@redhat.com> Acked-by: Tariq Toukan <tariqt@nvidia.com> Link: https://lore.kernel.org/r/167940675120.2718408.8176058626864184420.stgit@firesoul Signed-off-by: Alexei Starovoitov <ast@kernel.org>
114 lines
4.5 KiB
ReStructuredText
114 lines
4.5 KiB
ReStructuredText
===============
|
|
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 packets will necessary have the requested
|
|
metadata available in which case the driver returns ``-ENODATA``.
|
|
|
|
Not all kfuncs have to be implemented by the device driver; when not
|
|
implemented, the default ones that return ``-EOPNOTSUPP`` will be used
|
|
to indicate the device driver have not implemented this kfunc.
|
|
|
|
|
|
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.
|