linux-kernel - [PATCH bpf-next,v2 1/2] doc: clarify XDP Rx metadata layout and bpf_xdp_adjust

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20250702030349.3275368-2-yoong.siang.song@intel.com>
Date: Wed,  2 Jul 2025 11:03:48 +0800
From: Song Yoong Siang <yoong.siang.song@...el.com>
To: "David S . Miller" <davem@...emloft.net>,
	Eric Dumazet <edumazet@...gle.com>,
	Jakub Kicinski <kuba@...nel.org>,
	Paolo Abeni <pabeni@...hat.com>,
	Simon Horman <horms@...nel.org>,
	Jonathan Corbet <corbet@....net>,
	Alexei Starovoitov <ast@...nel.org>,
	Daniel Borkmann <daniel@...earbox.net>,
	Jesper Dangaard Brouer <hawk@...nel.org>,
	John Fastabend <john.fastabend@...il.com>,
	Stanislav Fomichev <sdf@...ichev.me>,
	Andrii Nakryiko <andrii@...nel.org>,
	Martin KaFai Lau <martin.lau@...ux.dev>,
	Eduard Zingerman <eddyz87@...il.com>,
	Song Liu <song@...nel.org>,
	Yonghong Song <yonghong.song@...ux.dev>,
	KP Singh <kpsingh@...nel.org>,
	Hao Luo <haoluo@...gle.com>,
	Jiri Olsa <jolsa@...nel.org>,
	Mykola Lysenko <mykolal@...com>,
	Shuah Khan <shuah@...nel.org>
Cc: netdev@...r.kernel.org,
	linux-doc@...r.kernel.org,
	linux-kernel@...r.kernel.org,
	bpf@...r.kernel.org,
	linux-kselftest@...r.kernel.org
Subject: [PATCH bpf-next,v2 1/2] doc: clarify XDP Rx metadata layout and bpf_xdp_adjust_meta usage

Expand the explanation of how METADATA_SIZE should be chosen to accommodate
both device-reserved and custom metadata. Additionally, add a diagram to
illustrate the calculation of the delta parameter for bpf_xdp_adjust_meta,
including alignment and size constraints.

These changes help users correctly allocate and access metadata in AF_XDP
use cases.

Signed-off-by: Song Yoong Siang <yoong.siang.song@...el.com>
---
 Documentation/networking/xdp-rx-metadata.rst | 38 ++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/Documentation/networking/xdp-rx-metadata.rst b/Documentation/networking/xdp-rx-metadata.rst
index a6e0ece18be5..61418f533e0e 100644
--- a/Documentation/networking/xdp-rx-metadata.rst
+++ b/Documentation/networking/xdp-rx-metadata.rst
@@ -54,6 +54,19 @@ area in whichever format it chooses. Later consumers of the metadata
 will have to agree on the format by some out of band contract (like for
 the AF_XDP use case, see below).
 
+It is important to note that some devices may utilize the ``data_meta`` area for
+their own purposes. For example, the IGC device utilizes ``IGC_TS_HDR_LEN``
+bytes of the ``data_meta`` area for receiving hardware timestamps. Therefore,
+the XDP program should ensure that it does not overwrite any existing metadata.
+The metadata layout of such device is depicted below::
+
+  +----------+-----------------+--------------------------+------+
+  | headroom | custom metadata | device-reserved metadata | data |
+  +----------+-----------------+--------------------------+------+
+             ^                                            ^
+             |                                            |
+   xdp_buff->data_meta                              xdp_buff->data
+
 AF_XDP
 ======
 
@@ -76,6 +89,31 @@ Here is the ``AF_XDP`` consumer layout (note missing ``data_meta`` pointer)::
                                |
                         rx_desc->address
 
+It is crucial that the agreed ``METADATA_SIZE`` between the BPF program and the
+final consumer is sufficient to accommodate both device-reserved metadata and
+the data the BPF program needs to populate. When calling
+``bpf_xdp_adjust_meta``, the input parameter ``delta`` should be calculated as
+``METADATA_SIZE - (xdp_buff->data - xdp_buff->data_meta)``.
+
+The diagram below provides a visual representation of the calculation of
+``delta`` and the overall metadata layout::
+
+             |<-------------------METADATA_SIZE------------------->|
+  +----------+--------------------------+--------------------------+------+
+  | headroom |      custom metadata     | device-reserved metadata | data |
+  +----------+--------------------------+--------------------------+------+
+             ^                          ^                          ^
+             |                          |                          |
+  new xdp_buff->data_meta    old xdp_buff->data_meta        xdp_buff->data
+             |                          |
+             |<----------delta--------->|
+
+``bpf_xdp_adjust_meta`` ensures that ``METADATA_SIZE`` is aligned to 4 bytes,
+does not exceed 252 bytes, and leaves sufficient space for building the
+xdp_frame. If these conditions are not met, it returns a negative error. In this
+case, the BPF program should not proceed to populate data into the ``data_meta``
+area.
+
 XDP_PASS
 ========
 
-- 
2.34.1