From nobody Wed Oct 8 09:08:32 2025 Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.13]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 858672248BD; Tue, 1 Jul 2025 04:30:28 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=192.198.163.13 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751344230; cv=none; b=lWzE0NFH7qTclVXZrdDnkVGZ01CJGNkt8K0ZyKEypiPGEqSPKhUMA+SHzguqoeQ7poNgllJq7BXnfDCbTQTYT28ZpajCak3itHsCUyIp2wHQg4P6tlz3g32QgwwZNJQyGaanVbSiPnCOfwD/ca1ed7foJEorpFHzUcPB9iOLjIk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751344230; c=relaxed/simple; bh=6VzUIVl7rOqTKTEIjM22aIEwtpdRzAbHjfEmET9YvGU=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=X3wmWFD/g99NDiQ5p2at9lRRFmr4v/dBjCZtgpYM+yZ9955fYGWhCxC8t2iprIplmIl05yxqtr7yqn/PzyGkuB/eCo1lAUg0h3WmbnO0oYZYvlaJ1+CpA+ihP4PbWv2oAB6tPRwo6zbrbqomfhsjA1t/v/Qaq1cpJ+eXflLEPg0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=intel.com; spf=pass smtp.mailfrom=intel.com; dkim=pass (2048-bit key) header.d=intel.com header.i=@intel.com header.b=Qi/5YWO6; arc=none smtp.client-ip=192.198.163.13 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=intel.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=intel.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=intel.com header.i=@intel.com header.b="Qi/5YWO6" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1751344228; x=1782880228; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=6VzUIVl7rOqTKTEIjM22aIEwtpdRzAbHjfEmET9YvGU=; b=Qi/5YWO6jEOV5fNBun4kw98pv4at8s3oX2qizkUuMVtW5KLc+aaf8ChM ZBmIxHl45s1PnmZLpmyt+AW1Q6iTsl6KVYztGXinR8eyzPF5IDvjGvnf9 1x5EOruzHlGTxMsWL4bk/H899Ql0ig5hCf410BaCHGJwFznVoMcmOMTSk kQBO+H0UUQvOktDiOQNt8KRw0p9rKsNaKS0wONXDLplXNvL6iWuAkhi8q 2JW0XgY3Vmc/tm3gy7uroyPJN5KiEgNckA8IosfFmR8n1C4uLu2+NnlEf UhQb/vXGbTjh6J2QawnABZiv5wZs2AvMWDoL4FKyIXAx/OTWQpdlsL8X9 A==; X-CSE-ConnectionGUID: i+vO1p1UTm2zgZaea2UJzg== X-CSE-MsgGUID: GSdUVkgsRnSxwuF62QLJ3A== X-IronPort-AV: E=McAfee;i="6800,10657,11480"; a="56210238" X-IronPort-AV: E=Sophos;i="6.16,279,1744095600"; d="scan'208";a="56210238" Received: from fmviesa002.fm.intel.com ([10.60.135.142]) by fmvoesa107.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 30 Jun 2025 21:30:28 -0700 X-CSE-ConnectionGUID: AwuugabBTd6VG6l3LFT9Qw== X-CSE-MsgGUID: 3V4b/HrqTEG8mADT/u8qlg== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.16,279,1744095600"; d="scan'208";a="177309013" Received: from p12ill20yoongsia.png.intel.com ([10.88.227.38]) by fmviesa002.fm.intel.com with ESMTP; 30 Jun 2025 21:30:23 -0700 From: Song Yoong Siang To: "David S . Miller" , Eric Dumazet , Jakub Kicinski , Paolo Abeni , Simon Horman , Jonathan Corbet , Alexei Starovoitov , Daniel Borkmann , Jesper Dangaard Brouer , John Fastabend , Stanislav Fomichev , Andrii Nakryiko , Martin KaFai Lau , Eduard Zingerman , Song Liu , Yonghong Song , KP Singh , Hao Luo , Jiri Olsa , Mykola Lysenko , Shuah Khan Cc: netdev@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, bpf@vger.kernel.org, linux-kselftest@vger.kernel.org Subject: [PATCH bpf-next 1/2] doc: clarify XDP Rx metadata layout and bpf_xdp_adjust_meta usage Date: Tue, 1 Jul 2025 12:29:39 +0800 Message-Id: <20250701042940.3272325-2-yoong.siang.song@intel.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20250701042940.3272325-1-yoong.siang.song@intel.com> References: <20250701042940.3272325-1-yoong.siang.song@intel.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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 --- Documentation/networking/xdp-rx-metadata.rst | 38 ++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/Documentation/networking/xdp-rx-metadata.rst b/Documentation/n= etworking/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). =20 +It is important to note that some devices may utilize the ``data_meta`` ar= ea for +their own purposes. For example, the IGC device utilizes ``IGC_TS_HDR_LEN`` +bytes of the ``data_meta`` area for receiving hardware timestamps. Therefo= re, +the XDP program should ensure that it does not overwrite any existing meta= data. +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 =3D=3D=3D=3D=3D=3D =20 @@ -76,6 +89,31 @@ Here is the ``AF_XDP`` consumer layout (note missing ``d= ata_meta`` pointer):: | rx_desc->address =20 +It is crucial that the agreed ``METADATA_SIZE`` between the BPF program an= d 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 calculate= d 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 byt= es, +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. I= n this +case, the BPF program should not proceed to populate data into the ``data_= meta`` +area. + XDP_PASS =3D=3D=3D=3D=3D=3D=3D=3D =20 --=20 2.34.1