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.