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