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