From nobody Wed Oct 8 03:53:54 2025 Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.10]) (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 0202E1DACB1; Wed, 2 Jul 2025 16:58:47 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=192.198.163.10 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751475529; cv=none; b=bxFrL6a2QeHQHB3Qly4Ojx41MX5TYWFcFwUsSMkZ9ycjHmtptVWbckPNdmMmSC88UwUfP3GIiwwrOQEfCnTsqYk7DNV7e7QgVbx2DiM52g2kqBaZi/AkO1/3apeAOTmfimDEBn+TsiePTIVdPr2cOCBhnUO8otJHVeWqnk+ykPM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751475529; c=relaxed/simple; bh=0Y0rAgKbRmjp0aExcFCmCupQOJxS3kfg7p4YDyQlK4M=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=bXZ5kKchM1KVXmAb3IMkVRadwRvg0lMu0LDw+S7LlB4JbE3T4xhXc13kg22NPt5VTE7H7R+tmI9fo/vBECpVbpp+F1k1wpEI+OuJTEpVoAiRKonMRZHdYX8QW8XCpmS5pUWVA0jQHNt2OggYW3wpvj63Clw2s7XdKYLnQaOjPeE= 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=A1+lHhsR; arc=none smtp.client-ip=192.198.163.10 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="A1+lHhsR" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1751475528; x=1783011528; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=0Y0rAgKbRmjp0aExcFCmCupQOJxS3kfg7p4YDyQlK4M=; b=A1+lHhsR3mGXJHdsr912UjRlTG2cYpaH9E+BVxwuf5KLiUQA7wHtZxk1 OLyevugtlnQ1I41vpl96Hm4aquxrHSajv0fHlROx4RBaZX9nJrsNegwrn tH3+bOvxnLhNmRtpCbVrJcaO56mh1nRj6ZX3cIwOc0vT4/F1I6MlzxPN8 wAhln/2FCNcreHTNVrTY1+iOJB0k8vIpGOH4LYvCbaBSQ8U7LOViOgEhl x/cz64UTENurKJ1ALSxY1Go6gDvAyoTZZSFcYL6N6q2b0mjtjwCHasKzi 2b7qGvPYShREF+1bhZPdEfK0bRpI9GeE6s5pQRiruFv5WcGOMUGpb/sm0 w==; X-CSE-ConnectionGUID: 29zAYVn5RY+8IBYlVJkoNA== X-CSE-MsgGUID: GuMIIhLRSsewbhYCcGBLKQ== X-IronPort-AV: E=McAfee;i="6800,10657,11482"; a="65132640" X-IronPort-AV: E=Sophos;i="6.16,281,1744095600"; d="scan'208";a="65132640" Received: from orviesa010.jf.intel.com ([10.64.159.150]) by fmvoesa104.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Jul 2025 09:58:48 -0700 X-CSE-ConnectionGUID: +TCAcKOZRJifDTqrOd9KYA== X-CSE-MsgGUID: UMM4RcscRGuzeBLPs575eg== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.16,281,1744095600"; d="scan'208";a="153538539" Received: from p12ill20yoongsia.png.intel.com ([10.88.227.38]) by orviesa010.jf.intel.com with ESMTP; 02 Jul 2025 09:58:41 -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,v3 1/2] doc: enhance explanation of XDP Rx metadata layout and METADATA_SIZE Date: Thu, 3 Jul 2025 00:57:56 +0800 Message-Id: <20250702165757.3278625-2-yoong.siang.song@intel.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20250702165757.3278625-1-yoong.siang.song@intel.com> References: <20250702165757.3278625-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" Add diagram to show metadata layout of devices that utilize the data_meta area for their own purposes. Besides, enhance the documentation on selecting an appropriate METADATA_SIZE for XDP Rx metadata, ensuring it accommodates both device-reserved and custom metadata. It includes considerations for alignment and size constraints. The updated guidance helps users correctly allocate and access metadata in AF_XDP scenarios. Signed-off-by: Song Yoong Siang Acked-by: Stanislav Fomichev --- Documentation/networking/xdp-rx-metadata.rst | 36 ++++++++++++++++---- 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/Documentation/networking/xdp-rx-metadata.rst b/Documentation/n= etworking/xdp-rx-metadata.rst index a6e0ece18be5..65a1a6e0f7a2 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 @@ -69,12 +82,23 @@ descriptor does _not_ explicitly carry the size of the = metadata). =20 Here is the ``AF_XDP`` consumer layout (note missing ``data_meta`` pointer= ):: =20 - +----------+-----------------+------+ - | headroom | custom metadata | data | - +----------+-----------------+------+ - ^ - | - rx_desc->address + |<--------------METADATA_SIZE--------------->| + +----------+-----------------+--------------------------+------+ + | headroom | custom metadata | device-reserved metadata | data | + +----------+-----------------+--------------------------+------+ + ^ + | + rx_desc->address + +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. + +``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. =20 XDP_PASS =3D=3D=3D=3D=3D=3D=3D=3D --=20 2.34.1 From nobody Wed Oct 8 03:53:54 2025 Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.10]) (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 3486B2F3C36; Wed, 2 Jul 2025 16:58:54 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=192.198.163.10 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751475535; cv=none; b=b39cmHt72u4N/Eqyg6305RYC0Qpy2qASnegX3mHyLV+JeojC2WFMsAGZcUEEU4wLO2HmqE3071fxuF/fvaqx+SbXXPPav/CkhzajFMq68HTSk9CuZK/ZgTddPn5K8ottYHrwhyphhIfGNve1J3CvKckw8gi4oY1hVi4CtKHBCio= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751475535; c=relaxed/simple; bh=NRCwcBa+605nVVuq9je4xdUTbE9ogB25Tw0Q/57qzjo=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=fS/5xfHmCtBq2huTmZyUS9rfudB5MBVXXFZYHBgktV41BaQwpeJl/K8OMpqeG+UyzO+8Qefh6N1pLQz06DDDN5FKU52RTqU/uuJ4OP/ldLnIfmU5eGUr58AidIfP8fIsrzK56FXw+LDmNCbg0TvyZLOxOhsxU2vFq1PrI5lGru0= 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=Va46DDik; arc=none smtp.client-ip=192.198.163.10 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="Va46DDik" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1751475534; x=1783011534; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=NRCwcBa+605nVVuq9je4xdUTbE9ogB25Tw0Q/57qzjo=; b=Va46DDikOrXIvfSbOucqM1atsEf6wuQZFPMhiuFjsRBgPxieIWJEuhq2 K5MKInUEWn3IXCwkCKmr5mYJsoJ07xB3pLVzxnNkhWhfajsSUwCy3CBzn MYktuT7gUC/mb5bMkva+LGmvo7ZSEoXSaFfmAYdjYg506HMUaLFnNhWRI 9oEsKozvvr+ZWiSCe2W2wW0Ny2ie9oXPnl9i+rYz4+FfiPO0K71MMohRh 8SlaEtcOSxGzgFWBZ7itxzgLPcyHdKmZIt+PJpTqIKkxvtz6b9Xfmw4ID IbDBUoMKlPEMnjY+u29znO3SkEZafnlSHiQD2rkviifZJiC16Mw6HNv74 g==; X-CSE-ConnectionGUID: 12lNxwf/S0OsXOrdB8qR6A== X-CSE-MsgGUID: QC5ondRCQEm5NZ4A3IbjCQ== X-IronPort-AV: E=McAfee;i="6800,10657,11482"; a="65132676" X-IronPort-AV: E=Sophos;i="6.16,281,1744095600"; d="scan'208";a="65132676" Received: from orviesa010.jf.intel.com ([10.64.159.150]) by fmvoesa104.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Jul 2025 09:58:54 -0700 X-CSE-ConnectionGUID: 1sbzCVlVTSCIMJVzDvo/3g== X-CSE-MsgGUID: 5LYgvkbZQkqdQZuay9eh1A== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.16,281,1744095600"; d="scan'208";a="153538594" Received: from p12ill20yoongsia.png.intel.com ([10.88.227.38]) by orviesa010.jf.intel.com with ESMTP; 02 Jul 2025 09:58:47 -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,v3 2/2] selftests/bpf: Enhance XDP Rx metadata handling Date: Thu, 3 Jul 2025 00:57:57 +0800 Message-Id: <20250702165757.3278625-3-yoong.siang.song@intel.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20250702165757.3278625-1-yoong.siang.song@intel.com> References: <20250702165757.3278625-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" Introduce the XDP_METADATA_SIZE macro as a conservative measure to accommodate any metadata areas reserved by Ethernet devices. Signed-off-by: Song Yoong Siang Acked-by: Stanislav Fomichev --- tools/testing/selftests/bpf/prog_tests/xdp_metadata.c | 2 +- tools/testing/selftests/bpf/progs/xdp_hw_metadata.c | 2 +- tools/testing/selftests/bpf/progs/xdp_metadata.c | 2 +- tools/testing/selftests/bpf/xdp_hw_metadata.c | 2 +- tools/testing/selftests/bpf/xdp_metadata.h | 7 +++++++ 5 files changed, 11 insertions(+), 4 deletions(-) diff --git a/tools/testing/selftests/bpf/prog_tests/xdp_metadata.c b/tools/= testing/selftests/bpf/prog_tests/xdp_metadata.c index 19f92affc2da..8d6c2633698b 100644 --- a/tools/testing/selftests/bpf/prog_tests/xdp_metadata.c +++ b/tools/testing/selftests/bpf/prog_tests/xdp_metadata.c @@ -302,7 +302,7 @@ static int verify_xsk_metadata(struct xsk *xsk, bool se= nt_from_af_xdp) =20 /* custom metadata */ =20 - meta =3D data - sizeof(struct xdp_meta); + meta =3D data - XDP_METADATA_SIZE; =20 if (!ASSERT_NEQ(meta->rx_timestamp, 0, "rx_timestamp")) return -1; diff --git a/tools/testing/selftests/bpf/progs/xdp_hw_metadata.c b/tools/te= sting/selftests/bpf/progs/xdp_hw_metadata.c index 330ece2eabdb..3766f58d3486 100644 --- a/tools/testing/selftests/bpf/progs/xdp_hw_metadata.c +++ b/tools/testing/selftests/bpf/progs/xdp_hw_metadata.c @@ -72,7 +72,7 @@ int rx(struct xdp_md *ctx) return XDP_PASS; } =20 - err =3D bpf_xdp_adjust_meta(ctx, -(int)sizeof(struct xdp_meta)); + err =3D bpf_xdp_adjust_meta(ctx, -(int)XDP_METADATA_SIZE); if (err) { __sync_add_and_fetch(&pkts_fail, 1); return XDP_PASS; diff --git a/tools/testing/selftests/bpf/progs/xdp_metadata.c b/tools/testi= ng/selftests/bpf/progs/xdp_metadata.c index 09bb8a038d52..5cada85fe0f4 100644 --- a/tools/testing/selftests/bpf/progs/xdp_metadata.c +++ b/tools/testing/selftests/bpf/progs/xdp_metadata.c @@ -73,7 +73,7 @@ int rx(struct xdp_md *ctx) =20 /* Reserve enough for all custom metadata. */ =20 - ret =3D bpf_xdp_adjust_meta(ctx, -(int)sizeof(struct xdp_meta)); + ret =3D bpf_xdp_adjust_meta(ctx, -(int)XDP_METADATA_SIZE); if (ret !=3D 0) return XDP_DROP; =20 diff --git a/tools/testing/selftests/bpf/xdp_hw_metadata.c b/tools/testing/= selftests/bpf/xdp_hw_metadata.c index 3d8de0d4c96a..a529d55d4ff4 100644 --- a/tools/testing/selftests/bpf/xdp_hw_metadata.c +++ b/tools/testing/selftests/bpf/xdp_hw_metadata.c @@ -223,7 +223,7 @@ static void verify_xdp_metadata(void *data, clockid_t c= lock_id) { struct xdp_meta *meta; =20 - meta =3D data - sizeof(*meta); + meta =3D data - XDP_METADATA_SIZE; =20 if (meta->hint_valid & XDP_META_FIELD_RSS) printf("rx_hash: 0x%X with RSS type:0x%X\n", diff --git a/tools/testing/selftests/bpf/xdp_metadata.h b/tools/testing/sel= ftests/bpf/xdp_metadata.h index 87318ad1117a..2dfd3bf5e7bb 100644 --- a/tools/testing/selftests/bpf/xdp_metadata.h +++ b/tools/testing/selftests/bpf/xdp_metadata.h @@ -50,3 +50,10 @@ struct xdp_meta { }; enum xdp_meta_field hint_valid; }; + +/* XDP_METADATA_SIZE must be at least the size of struct xdp_meta. An addi= tional + * 32 bytes of padding is included as a conservative measure to accommodat= e any + * metadata areas reserved by Ethernet devices. If the device-reserved met= adata + * exceeds 32 bytes, this value will need adjustment. + */ +#define XDP_METADATA_SIZE (sizeof(struct xdp_meta) + 32) --=20 2.34.1