Documentation/networking/xdp-rx-metadata.rst

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