1.. SPDX-License-Identifier: GPL-2.0
2
3===============
4XDP RX Metadata
5===============
6
7This document describes how an eXpress Data Path (XDP) program can access
8hardware metadata related to a packet using a set of helper functions,
9and how it can pass that metadata on to other consumers.
10
11General Design
12==============
13
14XDP has access to a set of kfuncs to manipulate the metadata in an XDP frame.
15Every device driver that wishes to expose additional packet metadata can
16implement these kfuncs. The set of kfuncs is declared in ``include/net/xdp.h``
17via ``XDP_METADATA_KFUNC_xxx``.
18
19Currently, the following kfuncs are supported. In the future, as more
20metadata is supported, this set will grow:
21
22.. kernel-doc:: net/core/xdp.c
23   :identifiers: bpf_xdp_metadata_rx_timestamp
24
25.. kernel-doc:: net/core/xdp.c
26   :identifiers: bpf_xdp_metadata_rx_hash
27
28.. kernel-doc:: net/core/xdp.c
29   :identifiers: bpf_xdp_metadata_rx_vlan_tag
30
31An XDP program can use these kfuncs to read the metadata into stack
32variables for its own consumption. Or, to pass the metadata on to other
33consumers, an XDP program can store it into the metadata area carried
34ahead of the packet. Not all packets will necessary have the requested
35metadata available in which case the driver returns ``-ENODATA``.
36
37Not all kfuncs have to be implemented by the device driver; when not
38implemented, the default ones that return ``-EOPNOTSUPP`` will be used
39to indicate the device driver have not implemented this kfunc.
40
41
42Within an XDP frame, the metadata layout (accessed via ``xdp_buff``) is
43as follows::
44
45  +----------+-----------------+------+
46  | headroom | custom metadata | data |
47  +----------+-----------------+------+
48             ^                 ^
49             |                 |
50   xdp_buff->data_meta   xdp_buff->data
51
52An XDP program can store individual metadata items into this ``data_meta``
53area in whichever format it chooses. Later consumers of the metadata
54will have to agree on the format by some out of band contract (like for
55the AF_XDP use case, see below).
56
57AF_XDP
58======
59
60:doc:`af_xdp` use-case implies that there is a contract between the BPF
61program that redirects XDP frames into the ``AF_XDP`` socket (``XSK``) and
62the final consumer. Thus the BPF program manually allocates a fixed number of
63bytes out of metadata via ``bpf_xdp_adjust_meta`` and calls a subset
64of kfuncs to populate it. The userspace ``XSK`` consumer computes
65``xsk_umem__get_data() - METADATA_SIZE`` to locate that metadata.
66Note, ``xsk_umem__get_data`` is defined in ``libxdp`` and
67``METADATA_SIZE`` is an application-specific constant (``AF_XDP`` receive
68descriptor does _not_ explicitly carry the size of the metadata).
69
70Here is the ``AF_XDP`` consumer layout (note missing ``data_meta`` pointer)::
71
72  +----------+-----------------+------+
73  | headroom | custom metadata | data |
74  +----------+-----------------+------+
75                               ^
76                               |
77                        rx_desc->address
78
79XDP_PASS
80========
81
82This is the path where the packets processed by the XDP program are passed
83into the kernel. The kernel creates the ``skb`` out of the ``xdp_buff``
84contents. Currently, every driver has custom kernel code to parse
85the descriptors and populate ``skb`` metadata when doing this ``xdp_buff->skb``
86conversion, and the XDP metadata is not used by the kernel when building
87``skbs``. However, TC-BPF programs can access the XDP metadata area using
88the ``data_meta`` pointer.
89
90In the future, we'd like to support a case where an XDP program
91can override some of the metadata used for building ``skbs``.
92
93bpf_redirect_map
94================
95
96``bpf_redirect_map`` can redirect the frame to a different device.
97Some devices (like virtual ethernet links) support running a second XDP
98program after the redirect. However, the final consumer doesn't have
99access to the original hardware descriptor and can't access any of
100the original metadata. The same applies to XDP programs installed
101into devmaps and cpumaps.
102
103This means that for redirected packets only custom metadata is
104currently supported, which has to be prepared by the initial XDP program
105before redirect. If the frame is eventually passed to the kernel, the
106``skb`` created from such a frame won't have any hardware metadata populated
107in its ``skb``. If such a packet is later redirected into an ``XSK``,
108that will also only have access to the custom metadata.
109
110bpf_tail_call
111=============
112
113Adding programs that access metadata kfuncs to the ``BPF_MAP_TYPE_PROG_ARRAY``
114is currently not supported.
115
116Supported Devices
117=================
118
119It is possible to query which kfunc the particular netdev implements via
120netlink. See ``xdp-rx-metadata-features`` attribute set in
121``Documentation/netlink/specs/netdev.yaml``.
122
123Example
124=======
125
126See ``tools/testing/selftests/bpf/progs/xdp_metadata.c`` and
127``tools/testing/selftests/bpf/prog_tests/xdp_metadata.c`` for an example of
128BPF program that handles XDP metadata.
129