xdp-rx-metadata.rst

  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
123Driver Implementation
124=====================
125
126Certain devices may prepend metadata to received packets. However, as of now,
127``AF_XDP`` lacks the ability to communicate the size of the ``data_meta`` area
128to the consumer. Therefore, it is the responsibility of the driver to copy any
129device-reserved metadata out from the metadata area and ensure that
130``xdp_buff->data_meta`` is pointing to ``xdp_buff->data`` before presenting the
131frame to the XDP program. This is necessary so that, after the XDP program
132adjusts the metadata area, the consumer can reliably retrieve the metadata
133address using ``METADATA_SIZE`` offset.
134
135The following diagram shows how custom metadata is positioned relative to the
136packet data and how pointers are adjusted for metadata access::
137
138              |<-- bpf_xdp_adjust_meta(xdp_buff, -METADATA_SIZE) --|
139  new xdp_buff->data_meta                              old xdp_buff->data_meta
140              |                                                    |
141              |                                            xdp_buff->data
142              |                                                    |
143   +----------+----------------------------------------------------+------+
144   | headroom |                  custom metadata                   | data |
145   +----------+----------------------------------------------------+------+
146              |                                                    |
147              |                                            xdp_desc->addr
148              |<------ xsk_umem__get_data() - METADATA_SIZE -------|
149
150``bpf_xdp_adjust_meta`` ensures that ``METADATA_SIZE`` is aligned to 4 bytes,
151does not exceed 252 bytes, and leaves sufficient space for building the
152xdp_frame. If these conditions are not met, it returns a negative error. In this
153case, the BPF program should not proceed to populate data into the ``data_meta``
154area.
155
156Example
157=======
158
159See ``tools/testing/selftests/bpf/progs/xdp_metadata.c`` and
160``tools/testing/selftests/bpf/prog_tests/xdp_metadata.c`` for an example of
161BPF program that handles XDP metadata.