129 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3===============4XDP RX Metadata5===============6 7This document describes how an eXpress Data Path (XDP) program can access8hardware metadata related to a packet using a set of helper functions,9and how it can pass that metadata on to other consumers.10 11General Design12==============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 can16implement 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 more20metadata is supported, this set will grow:21 22.. kernel-doc:: net/core/xdp.c23 :identifiers: bpf_xdp_metadata_rx_timestamp24 25.. kernel-doc:: net/core/xdp.c26 :identifiers: bpf_xdp_metadata_rx_hash27 28.. kernel-doc:: net/core/xdp.c29 :identifiers: bpf_xdp_metadata_rx_vlan_tag30 31An XDP program can use these kfuncs to read the metadata into stack32variables for its own consumption. Or, to pass the metadata on to other33consumers, an XDP program can store it into the metadata area carried34ahead of the packet. Not all packets will necessary have the requested35metadata available in which case the driver returns ``-ENODATA``.36 37Not all kfuncs have to be implemented by the device driver; when not38implemented, the default ones that return ``-EOPNOTSUPP`` will be used39to indicate the device driver have not implemented this kfunc.40 41 42Within an XDP frame, the metadata layout (accessed via ``xdp_buff``) is43as follows::44 45 +----------+-----------------+------+46 | headroom | custom metadata | data |47 +----------+-----------------+------+48 ^ ^49 | |50 xdp_buff->data_meta xdp_buff->data51 52An XDP program can store individual metadata items into this ``data_meta``53area in whichever format it chooses. Later consumers of the metadata54will have to agree on the format by some out of band contract (like for55the AF_XDP use case, see below).56 57AF_XDP58======59 60:doc:`af_xdp` use-case implies that there is a contract between the BPF61program that redirects XDP frames into the ``AF_XDP`` socket (``XSK``) and62the final consumer. Thus the BPF program manually allocates a fixed number of63bytes out of metadata via ``bpf_xdp_adjust_meta`` and calls a subset64of kfuncs to populate it. The userspace ``XSK`` consumer computes65``xsk_umem__get_data() - METADATA_SIZE`` to locate that metadata.66Note, ``xsk_umem__get_data`` is defined in ``libxdp`` and67``METADATA_SIZE`` is an application-specific constant (``AF_XDP`` receive68descriptor 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->address78 79XDP_PASS80========81 82This is the path where the packets processed by the XDP program are passed83into the kernel. The kernel creates the ``skb`` out of the ``xdp_buff``84contents. Currently, every driver has custom kernel code to parse85the descriptors and populate ``skb`` metadata when doing this ``xdp_buff->skb``86conversion, and the XDP metadata is not used by the kernel when building87``skbs``. However, TC-BPF programs can access the XDP metadata area using88the ``data_meta`` pointer.89 90In the future, we'd like to support a case where an XDP program91can override some of the metadata used for building ``skbs``.92 93bpf_redirect_map94================95 96``bpf_redirect_map`` can redirect the frame to a different device.97Some devices (like virtual ethernet links) support running a second XDP98program after the redirect. However, the final consumer doesn't have99access to the original hardware descriptor and can't access any of100the original metadata. The same applies to XDP programs installed101into devmaps and cpumaps.102 103This means that for redirected packets only custom metadata is104currently supported, which has to be prepared by the initial XDP program105before redirect. If the frame is eventually passed to the kernel, the106``skb`` created from such a frame won't have any hardware metadata populated107in 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_call111=============112 113Adding programs that access metadata kfuncs to the ``BPF_MAP_TYPE_PROG_ARRAY``114is currently not supported.115 116Supported Devices117=================118 119It is possible to query which kfunc the particular netdev implements via120netlink. See ``xdp-rx-metadata-features`` attribute set in121``Documentation/netlink/specs/netdev.yaml``.122 123Example124=======125 126See ``tools/testing/selftests/bpf/progs/xdp_metadata.c`` and127``tools/testing/selftests/bpf/prog_tests/xdp_metadata.c`` for an example of128BPF program that handles XDP metadata.129