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.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.