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