This patch set improves the documentation and selftests for XDP Rx metadata handling. The first patch clarifies the documentation around XDP metadata layout and METADATA_SIZE. The second patch enhances the BPF selftests to make XDP metadata handling more robust across different NICs.
Prior to this patch set, the XDP program might accidentally overwrite the device-reserved metadata.
V3: - update doc and commit msg accordingly.
V2: https://lore.kernel.org/netdev/20250702030349.3275368-1-yoong.siang.song@int... - unconditionally do bpf_xdp_adjust_meta with -XDP_METADATA_SIZE (Stanislav)
V1: https://lore.kernel.org/netdev/20250701042940.3272325-1-yoong.siang.song@int...
Song Yoong Siang (2): doc: enhance explanation of XDP Rx metadata layout and METADATA_SIZE selftests/bpf: Enhance XDP Rx metadata handling
Documentation/networking/xdp-rx-metadata.rst | 36 +++++++++++++++---- .../selftests/bpf/prog_tests/xdp_metadata.c | 2 +- .../selftests/bpf/progs/xdp_hw_metadata.c | 2 +- .../selftests/bpf/progs/xdp_metadata.c | 2 +- tools/testing/selftests/bpf/xdp_hw_metadata.c | 2 +- tools/testing/selftests/bpf/xdp_metadata.h | 7 ++++ 6 files changed, 41 insertions(+), 10 deletions(-)
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 yoong.siang.song@intel.com --- 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/networking/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).
+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 ======
@@ -69,12 +82,23 @@ descriptor does _not_ explicitly carry the size of the metadata).
Here is the ``AF_XDP`` consumer layout (note missing ``data_meta`` pointer)::
- +----------+-----------------+------+ - | 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 and 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 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 ========
On 7/2/25 6:57 PM, Song Yoong Siang wrote: [...]
+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
Imho, this section is misleading to developers. Suppose you're a XDP program writer and you want to implement a generic native BPF program (independent of the underlying NIC). Does this mean, the expectation is to dig into driver code to gather whether or not a driver is prepopulating and how much of it? What are the implications if the data is overwritten? For example, in Cilium today we use the buffer described here as device-reserved metadata and override it. How will users know what breaks?
On Thursday, July 3, 2025 11:58 PM, Daniel Borkmann daniel@iogearbox.net wrote:
On 7/2/25 6:57 PM, Song Yoong Siang wrote: [...]
+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
Imho, this section is misleading to developers. Suppose you're a XDP program writer and you want to implement a generic native BPF program (independent of the underlying NIC). Does this mean, the expectation is to dig into driver code to gather whether or not a driver is prepopulating and how much of it? What are the implications if the data is overwritten? For example, in Cilium today we use the buffer described here as device-reserved metadata and override it. How will users know what breaks?
Thanks for your input.
A generic XDP program can always check the size of device-reserved metadata by "ctx->data - ctx->data_meta" and avoid overwrite it, as shown in code below in my v1 submission [1]. This requires driver to expose the metadata length used [2]. However, I dint have good justification for making the metadata length user-visible. So, I submitted this v3 to keep it simple. Any thoughts?
+ metalen_used = ctx->data - ctx->data_meta; + metalen_to_adjust = XDP_METADATA_SIZE - metalen_used; + if (metalen_to_adjust < (int)sizeof(struct xdp_meta)) + return XDP_DROP; + + ret = bpf_xdp_adjust_meta(ctx, -metalen_to_adjust);
[1] https://lore.kernel.org/netdev/20250701042940.3272325-3-yoong.siang.song@int... [2] https://lore.kernel.org/netdev/20250701080955.3273137-1-yoong.siang.song@int...
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 yoong.siang.song@intel.com --- 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 sent_from_af_xdp)
/* custom metadata */
- meta = data - sizeof(struct xdp_meta); + meta = data - XDP_METADATA_SIZE;
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/testing/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; }
- err = bpf_xdp_adjust_meta(ctx, -(int)sizeof(struct xdp_meta)); + err = 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/testing/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)
/* Reserve enough for all custom metadata. */
- ret = bpf_xdp_adjust_meta(ctx, -(int)sizeof(struct xdp_meta)); + ret = bpf_xdp_adjust_meta(ctx, -(int)XDP_METADATA_SIZE); if (ret != 0) return XDP_DROP;
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 clock_id) { struct xdp_meta *meta;
- meta = data - sizeof(*meta); + meta = data - XDP_METADATA_SIZE;
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/selftests/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 additional + * 32 bytes of padding is included as a conservative measure to accommodate any + * metadata areas reserved by Ethernet devices. If the device-reserved metadata + * exceeds 32 bytes, this value will need adjustment. + */ +#define XDP_METADATA_SIZE (sizeof(struct xdp_meta) + 32)
On 02/07/2025 18.57, Song Yoong Siang wrote:
Introduce the XDP_METADATA_SIZE macro as a conservative measure to accommodate any metadata areas reserved by Ethernet devices.
This seems like a sloppy workaround :-(
To me, the problem arise because AF_XDP is lacking the ability to communicate the size of the data_meta area. If we had this capability, then we could allow the IGC driver to take some of the space, have the BPF-prog expand it futher (bpf_xdp_adjust_meta) and then userspace AF_XDP would simply be able to see the size of the data_meta area, and apply the struct xdp_meta at right offset.
Signed-off-by: Song Yoong Siang yoong.siang.song@intel.com
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 sent_from_af_xdp) /* custom metadata */
- meta = data - sizeof(struct xdp_meta);
- meta = data - XDP_METADATA_SIZE;
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/testing/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; }
- err = bpf_xdp_adjust_meta(ctx, -(int)sizeof(struct xdp_meta));
- err = 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/testing/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) /* Reserve enough for all custom metadata. */
- ret = bpf_xdp_adjust_meta(ctx, -(int)sizeof(struct xdp_meta));
- ret = bpf_xdp_adjust_meta(ctx, -(int)XDP_METADATA_SIZE); if (ret != 0) return XDP_DROP;
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 clock_id) { struct xdp_meta *meta;
- meta = data - sizeof(*meta);
- meta = data - XDP_METADATA_SIZE;
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/selftests/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 additional
- 32 bytes of padding is included as a conservative measure to accommodate any
- metadata areas reserved by Ethernet devices. If the device-reserved metadata
- exceeds 32 bytes, this value will need adjustment.
- */
+#define XDP_METADATA_SIZE (sizeof(struct xdp_meta) + 32)
On Friday, July 4, 2025 1:05 AM, Jesper Dangaard Brouer hawk@kernel.org wrote:
On 02/07/2025 18.57, Song Yoong Siang wrote:
Introduce the XDP_METADATA_SIZE macro as a conservative measure to accommodate any metadata areas reserved by Ethernet devices.
This seems like a sloppy workaround :-(
To me, the problem arise because AF_XDP is lacking the ability to communicate the size of the data_meta area. If we had this capability, then we could allow the IGC driver to take some of the space, have the BPF-prog expand it futher (bpf_xdp_adjust_meta) and then userspace AF_XDP would simply be able to see the size of the data_meta area, and apply the struct xdp_meta at right offset.
Thanks for your input.
I agree with you that the implementation will be simple if user application able to get the size of data_meta area. The intention of this patch set is to let developer aware of such limitations before we have a perfect solution.
Btw, do you got any suggestion on how to expose the metadata length? I not sure whether xdp_desc.options is a simple and good idea or not?
On 04/07/2025 03.17, Song, Yoong Siang wrote:
On Friday, July 4, 2025 1:05 AM, Jesper Dangaard Brouer hawk@kernel.org wrote:
On 02/07/2025 18.57, Song Yoong Siang wrote:
Introduce the XDP_METADATA_SIZE macro as a conservative measure to accommodate any metadata areas reserved by Ethernet devices.
This seems like a sloppy workaround :-(
To me, the problem arise because AF_XDP is lacking the ability to communicate the size of the data_meta area. If we had this capability, then we could allow the IGC driver to take some of the space, have the BPF-prog expand it futher (bpf_xdp_adjust_meta) and then userspace AF_XDP would simply be able to see the size of the data_meta area, and apply the struct xdp_meta at right offset.
Thanks for your input.
I agree with you that the implementation will be simple if user application able to get the size of data_meta area. The intention of this patch set is to let developer aware of such limitations before we have a perfect solution.
Btw, do you got any suggestion on how to expose the metadata length? I not sure whether xdp_desc.options is a simple and good idea or not?
That is a question to the AF_XDP maintainers... added them to this email.
/* Rx/Tx descriptor */ struct xdp_desc { __u64 addr; __u32 len; __u32 options; };
As far as I know, the xdp_desc.options field isn't used, right?
(Please AF_XDP experts, please verify below statements:) Something else we likely want to document: The available headroom in the AF_XDP frame. When accessing the metadata in userspace AF_XDP we do a negative offset from the UMEM packet pointer. IIRC on RX the available headroom will be either 255 or 192 bytes (depending on NIC drivers).
Slightly confusing when AF_XDP transmitting from userspace the UMEM headroom is default zero (XSK_UMEM__DEFAULT_FRAME_HEADROOM is zero). This is configurable via xsk_umem_config.frame_headroom, like I did in this example[1].
Maybe I did something wrong in[1], because I see that the new method is setting xsk_umem_config.tx_metadata_len + flag XDP_UMEM_TX_METADATA_LEN. This is nicely documented in [2]. How does this interact with setting xsk_umem_config.frame_headroom ?
[1] https://github.com/xdp-project/bpf-examples/blob/3f365af4be1fe6a0ef77e751ff9... [2] https://www.kernel.org/doc/html/v6.12/networking/xsk-tx-metadata.html
--Jesper
On 7/4/25 11:58 AM, Jesper Dangaard Brouer wrote:
On 04/07/2025 03.17, Song, Yoong Siang wrote:
On Friday, July 4, 2025 1:05 AM, Jesper Dangaard Brouer hawk@kernel.org wrote:
On 02/07/2025 18.57, Song Yoong Siang wrote:
Introduce the XDP_METADATA_SIZE macro as a conservative measure to accommodate any metadata areas reserved by Ethernet devices.
This seems like a sloppy workaround :-(
To me, the problem arise because AF_XDP is lacking the ability to communicate the size of the data_meta area. If we had this capability, then we could allow the IGC driver to take some of the space, have the BPF-prog expand it futher (bpf_xdp_adjust_meta) and then userspace AF_XDP would simply be able to see the size of the data_meta area, and apply the struct xdp_meta at right offset.
Thanks for your input.
I agree with you that the implementation will be simple if user application able to get the size of data_meta area. The intention of this patch set is to let developer aware of such limitations before we have a perfect solution.
Btw, do you got any suggestion on how to expose the metadata length? I not sure whether xdp_desc.options is a simple and good idea or not?
That is a question to the AF_XDP maintainers... added them to this email.
/* Rx/Tx descriptor */ struct xdp_desc { __u64 addr; __u32 len; __u32 options; };
As far as I know, the xdp_desc.options field isn't used, right?
The options holds flags, see also XDP_PKT_CONTD and XDP_TX_METADATA.
(Please AF_XDP experts, please verify below statements:) Something else we likely want to document: The available headroom in the AF_XDP frame. When accessing the metadata in userspace AF_XDP we do a negative offset from the UMEM packet pointer. IIRC on RX the available headroom will be either 255 or 192 bytes (depending on NIC drivers).
Slightly confusing when AF_XDP transmitting from userspace the UMEM headroom is default zero (XSK_UMEM__DEFAULT_FRAME_HEADROOM is zero). This is configurable via xsk_umem_config.frame_headroom, like I did in this example[1].
Maybe I did something wrong in[1], because I see that the new method is setting xsk_umem_config.tx_metadata_len + flag XDP_UMEM_TX_METADATA_LEN. This is nicely documented in [2]. How does this interact with setting xsk_umem_config.frame_headroom ?
If you request XDP_UMEM_TX_METADATA_LEN then on TX side you can fill struct xsk_tx_metadata before the start of packet data, that is, meta = data - sizeof(struct xsk_tx_metadata). The validity of the latter is indicated via desc->options |= XDP_TX_METADATA and then you fill meta->flags with things like XDP_TXMD_FLAGS_CHECKSUM to tell that the related fields are valid (ex. request.csum_start, request.csum_offset) and that you expect the driver to do the offload with this info. This is also what I mentioned in the other thread some time ago that imho it would make sense to have this also on RX side somewhat similar to virtio_net_hdr..
[1] https://github.com/xdp-project/bpf-examples/blob/3f365af4be1fe6a0ef77e751ff9... [2] https://www.kernel.org/doc/html/v6.12/networking/xsk-tx-metadata.html
--Jesper
On 07/04, Daniel Borkmann wrote:
On 7/4/25 11:58 AM, Jesper Dangaard Brouer wrote:
On 04/07/2025 03.17, Song, Yoong Siang wrote:
On Friday, July 4, 2025 1:05 AM, Jesper Dangaard Brouer hawk@kernel.org wrote:
On 02/07/2025 18.57, Song Yoong Siang wrote:
Introduce the XDP_METADATA_SIZE macro as a conservative measure to accommodate any metadata areas reserved by Ethernet devices.
This seems like a sloppy workaround :-(
To me, the problem arise because AF_XDP is lacking the ability to communicate the size of the data_meta area. If we had this capability, then we could allow the IGC driver to take some of the space, have the BPF-prog expand it futher (bpf_xdp_adjust_meta) and then userspace AF_XDP would simply be able to see the size of the data_meta area, and apply the struct xdp_meta at right offset.
Thanks for your input.
I agree with you that the implementation will be simple if user application able to get the size of data_meta area. The intention of this patch set is to let developer aware of such limitations before we have a perfect solution.
Btw, do you got any suggestion on how to expose the metadata length? I not sure whether xdp_desc.options is a simple and good idea or not?
That is a question to the AF_XDP maintainers... added them to this email.
/* Rx/Tx descriptor */ struct xdp_desc { __u64 addr; __u32 len; __u32 options; };
As far as I know, the xdp_desc.options field isn't used, right?
The options holds flags, see also XDP_PKT_CONTD and XDP_TX_METADATA.
(Please AF_XDP experts, please verify below statements:) Something else we likely want to document: The available headroom in the AF_XDP frame. When accessing the metadata in userspace AF_XDP we do a negative offset from the UMEM packet pointer. IIRC on RX the available headroom will be either 255 or 192 bytes (depending on NIC drivers).
Slightly confusing when AF_XDP transmitting from userspace the UMEM headroom is default zero (XSK_UMEM__DEFAULT_FRAME_HEADROOM is zero). This is configurable via xsk_umem_config.frame_headroom, like I did in this example[1].
Maybe I did something wrong in[1], because I see that the new method is setting xsk_umem_config.tx_metadata_len + flag XDP_UMEM_TX_METADATA_LEN. This is nicely documented in [2]. How does this interact with setting xsk_umem_config.frame_headroom ?
If you request XDP_UMEM_TX_METADATA_LEN then on TX side you can fill struct xsk_tx_metadata before the start of packet data, that is, meta = data - sizeof(struct xsk_tx_metadata). The validity of the latter is indicated via desc->options |= XDP_TX_METADATA and then you fill meta->flags with things like XDP_TXMD_FLAGS_CHECKSUM to tell that the related fields are valid (ex. request.csum_start, request.csum_offset) and that you expect the driver to do the offload with this info. This is also what I mentioned in the other thread some time ago that imho it would make sense to have this also on RX side somewhat similar to virtio_net_hdr..
Let's at least document the current behavior where some (small minority of) drivers can reuse the rx metadata area for some of its state? If we want to improve on that by adding another knob, we can follow up? (but I remember last time it was discussed, about a year ago, people were not enthusiastic about another parameter exported as uapi)
On 7/7/25 5:03 PM, Stanislav Fomichev wrote:
On 07/04, Daniel Borkmann wrote:
On 7/4/25 11:58 AM, Jesper Dangaard Brouer wrote:
On 04/07/2025 03.17, Song, Yoong Siang wrote:
On Friday, July 4, 2025 1:05 AM, Jesper Dangaard Brouer hawk@kernel.org wrote:
On 02/07/2025 18.57, Song Yoong Siang wrote:
Introduce the XDP_METADATA_SIZE macro as a conservative measure to accommodate any metadata areas reserved by Ethernet devices.
This seems like a sloppy workaround :-(
To me, the problem arise because AF_XDP is lacking the ability to communicate the size of the data_meta area. If we had this capability, then we could allow the IGC driver to take some of the space, have the BPF-prog expand it futher (bpf_xdp_adjust_meta) and then userspace AF_XDP would simply be able to see the size of the data_meta area, and apply the struct xdp_meta at right offset.
Thanks for your input.
I agree with you that the implementation will be simple if user application able to get the size of data_meta area. The intention of this patch set is to let developer aware of such limitations before we have a perfect solution.
Btw, do you got any suggestion on how to expose the metadata length? I not sure whether xdp_desc.options is a simple and good idea or not?
That is a question to the AF_XDP maintainers... added them to this email.
/* Rx/Tx descriptor */ struct xdp_desc { __u64 addr; __u32 len; __u32 options; };
As far as I know, the xdp_desc.options field isn't used, right?
The options holds flags, see also XDP_PKT_CONTD and XDP_TX_METADATA.
(Please AF_XDP experts, please verify below statements:) Something else we likely want to document: The available headroom in the AF_XDP frame. When accessing the metadata in userspace AF_XDP we do a negative offset from the UMEM packet pointer. IIRC on RX the available headroom will be either 255 or 192 bytes (depending on NIC drivers).
Slightly confusing when AF_XDP transmitting from userspace the UMEM headroom is default zero (XSK_UMEM__DEFAULT_FRAME_HEADROOM is zero). This is configurable via xsk_umem_config.frame_headroom, like I did in this example[1].
Maybe I did something wrong in[1], because I see that the new method is setting xsk_umem_config.tx_metadata_len + flag XDP_UMEM_TX_METADATA_LEN. This is nicely documented in [2]. How does this interact with setting xsk_umem_config.frame_headroom ?
If you request XDP_UMEM_TX_METADATA_LEN then on TX side you can fill struct xsk_tx_metadata before the start of packet data, that is, meta = data - sizeof(struct xsk_tx_metadata). The validity of the latter is indicated via desc->options |= XDP_TX_METADATA and then you fill meta->flags with things like XDP_TXMD_FLAGS_CHECKSUM to tell that the related fields are valid (ex. request.csum_start, request.csum_offset) and that you expect the driver to do the offload with this info. This is also what I mentioned in the other thread some time ago that imho it would make sense to have this also on RX side somewhat similar to virtio_net_hdr..
Let's at least document the current behavior where some (small minority of) drivers can reuse the rx metadata area for some of its state? If we want to improve on that by adding another knob, we can follow up? (but I remember last time it was discussed, about a year ago, people were not enthusiastic about another parameter exported as uapi)
But its still fundamentally broken no? Unless there is no harm for BPF devs to override that rx metadata area when the pkt later on goes up the stack, but it sounds this is not the case here. Iiuc, Yoong is trying a different approach now to prepend before data_hard_start [0]? Then if BPF prog needs it, igc already implements xmo_rx_timestamp callback which can copy it from there.
[0] https://lore.kernel.org/bpf/20250707191742.662aeffb@kernel.org/
On 07/09, Daniel Borkmann wrote:
On 7/7/25 5:03 PM, Stanislav Fomichev wrote:
On 07/04, Daniel Borkmann wrote:
On 7/4/25 11:58 AM, Jesper Dangaard Brouer wrote:
On 04/07/2025 03.17, Song, Yoong Siang wrote:
On Friday, July 4, 2025 1:05 AM, Jesper Dangaard Brouer hawk@kernel.org wrote:
On 02/07/2025 18.57, Song Yoong Siang wrote: > Introduce the XDP_METADATA_SIZE macro as a conservative measure to > accommodate any metadata areas reserved by Ethernet devices.
This seems like a sloppy workaround :-(
To me, the problem arise because AF_XDP is lacking the ability to communicate the size of the data_meta area. If we had this capability, then we could allow the IGC driver to take some of the space, have the BPF-prog expand it futher (bpf_xdp_adjust_meta) and then userspace AF_XDP would simply be able to see the size of the data_meta area, and apply the struct xdp_meta at right offset.
Thanks for your input.
I agree with you that the implementation will be simple if user application able to get the size of data_meta area. The intention of this patch set is to let developer aware of such limitations before we have a perfect solution.
Btw, do you got any suggestion on how to expose the metadata length? I not sure whether xdp_desc.options is a simple and good idea or not?
That is a question to the AF_XDP maintainers... added them to this email.
/* Rx/Tx descriptor */ struct xdp_desc { __u64 addr; __u32 len; __u32 options; };
As far as I know, the xdp_desc.options field isn't used, right?
The options holds flags, see also XDP_PKT_CONTD and XDP_TX_METADATA.
(Please AF_XDP experts, please verify below statements:) Something else we likely want to document: The available headroom in the AF_XDP frame. When accessing the metadata in userspace AF_XDP we do a negative offset from the UMEM packet pointer. IIRC on RX the available headroom will be either 255 or 192 bytes (depending on NIC drivers).
Slightly confusing when AF_XDP transmitting from userspace the UMEM headroom is default zero (XSK_UMEM__DEFAULT_FRAME_HEADROOM is zero). This is configurable via xsk_umem_config.frame_headroom, like I did in this example[1].
Maybe I did something wrong in[1], because I see that the new method is setting xsk_umem_config.tx_metadata_len + flag XDP_UMEM_TX_METADATA_LEN. This is nicely documented in [2]. How does this interact with setting xsk_umem_config.frame_headroom ?
If you request XDP_UMEM_TX_METADATA_LEN then on TX side you can fill struct xsk_tx_metadata before the start of packet data, that is, meta = data - sizeof(struct xsk_tx_metadata). The validity of the latter is indicated via desc->options |= XDP_TX_METADATA and then you fill meta->flags with things like XDP_TXMD_FLAGS_CHECKSUM to tell that the related fields are valid (ex. request.csum_start, request.csum_offset) and that you expect the driver to do the offload with this info. This is also what I mentioned in the other thread some time ago that imho it would make sense to have this also on RX side somewhat similar to virtio_net_hdr..
Let's at least document the current behavior where some (small minority of) drivers can reuse the rx metadata area for some of its state? If we want to improve on that by adding another knob, we can follow up? (but I remember last time it was discussed, about a year ago, people were not enthusiastic about another parameter exported as uapi)
But its still fundamentally broken no? Unless there is no harm for BPF devs to override that rx metadata area when the pkt later on goes up the stack, but it sounds this is not the case here. Iiuc, Yoong is trying a different approach now to prepend before data_hard_start [0]? Then if BPF prog needs it, igc already implements xmo_rx_timestamp callback which can copy it from there.
[0] https://lore.kernel.org/bpf/20250707191742.662aeffb@kernel.org/
True, Jakub mentioned the same thread to me. This is, indeed, a better idea!
On Thursday, July 10, 2025 12:29 AM, Stanislav Fomichev stfomichev@gmail.com wrote:
On 07/09, Daniel Borkmann wrote:
On 7/7/25 5:03 PM, Stanislav Fomichev wrote:
On 07/04, Daniel Borkmann wrote:
On 7/4/25 11:58 AM, Jesper Dangaard Brouer wrote:
On 04/07/2025 03.17, Song, Yoong Siang wrote:
On Friday, July 4, 2025 1:05 AM, Jesper Dangaard Brouer
hawk@kernel.org wrote:
> On 02/07/2025 18.57, Song Yoong Siang wrote: > > Introduce the XDP_METADATA_SIZE macro as a conservative measure to > > accommodate any metadata areas reserved by Ethernet devices. > > This seems like a sloppy workaround :-( > > To me, the problem arise because AF_XDP is lacking the ability to > communicate the size of the data_meta area. If we had this capability, > then we could allow the IGC driver to take some of the space, have the > BPF-prog expand it futher (bpf_xdp_adjust_meta) and then userspace > AF_XDP would simply be able to see the size of the data_meta area, and > apply the struct xdp_meta at right offset. > Thanks for your input.
I agree with you that the implementation will be simple if user application able to get the size of data_meta area. The intention of this patch set is to let developer aware of such limitations before we have a perfect solution.
Btw, do you got any suggestion on how to expose the metadata length? I not sure whether xdp_desc.options is a simple and good idea or not?
That is a question to the AF_XDP maintainers... added them to this email.
/* Rx/Tx descriptor */ struct xdp_desc { __u64 addr; __u32 len; __u32 options; };
As far as I know, the xdp_desc.options field isn't used, right?
The options holds flags, see also XDP_PKT_CONTD and XDP_TX_METADATA.
(Please AF_XDP experts, please verify below statements:) Something else we likely want to document: The available headroom in the AF_XDP frame. When accessing the metadata in userspace AF_XDP we do a negative offset from the UMEM packet pointer. IIRC on RX the available headroom will be either 255 or 192 bytes (depending on NIC drivers).
Slightly confusing when AF_XDP transmitting from userspace the UMEM headroom is default zero (XSK_UMEM__DEFAULT_FRAME_HEADROOM is
zero).
This is configurable via xsk_umem_config.frame_headroom, like I did in this example[1].
Maybe I did something wrong in[1], because I see that the new method is setting xsk_umem_config.tx_metadata_len + flag XDP_UMEM_TX_METADATA_LEN. This is nicely documented in [2]. How does this interact with setting xsk_umem_config.frame_headroom ?
If you request XDP_UMEM_TX_METADATA_LEN then on TX side you can fill struct xsk_tx_metadata before the start of packet data, that is, meta = data - sizeof(struct xsk_tx_metadata). The validity of the latter is indicated via desc->options |= XDP_TX_METADATA and then you fill meta->flags with things like XDP_TXMD_FLAGS_CHECKSUM to tell that the related fields are valid (ex. request.csum_start, request.csum_offset) and that you expect the driver to do the offload with this info. This is also what I mentioned in the other thread some time ago that imho it would make sense to have this also on RX side somewhat similar to virtio_net_hdr..
Let's at least document the current behavior where some (small minority of) drivers can reuse the rx metadata area for some of its state? If we want to improve on that by adding another knob, we can follow up? (but I remember last time it was discussed, about a year ago, people were not enthusiastic about another parameter exported as uapi)
But its still fundamentally broken no? Unless there is no harm for BPF devs to override that rx metadata area when the pkt later on goes up the stack, but it sounds this is not the case here. Iiuc, Yoong is trying a different approach now to prepend before data_hard_start [0]?
I plan to retrieve the timestamp from metadata area and put it in xdp_buff_xsk.cb area via struct igc_xdp_buff.
Then if BPF prog needs it, igc already implements xmo_rx_timestamp callback which can copy it from there.
[0] https://lore.kernel.org/bpf/20250707191742.662aeffb@kernel.org/
True, Jakub mentioned the same thread to me. This is, indeed, a better idea!
Would it be advisable to update the documentation to indicate that drivers are expected to copy any device-reserved metadata from the metadata area? This would ensure that xdp_buff->data_meta is equal to xdp_buff->data before a BPF program is executed. This approach would allow BPF programs to freely manipulate the metadata area in XDP_REDIRECT scenarios.
Additionally, I am uncertain about the need to overriding metadata in XDP_PASS scenarios. Should BPF programs refrain from overriding the metadata in this case?
On Thu, 10 Jul 2025 15:35:32 +0000 Song, Yoong Siang wrote:
Would it be advisable to update the documentation to indicate that drivers are expected to copy any device-reserved metadata from the metadata area? This would ensure that xdp_buff->data_meta is equal to xdp_buff->data before a BPF program is executed. This approach would allow BPF programs to freely manipulate the metadata area in XDP_REDIRECT scenarios.
Documenting sounds good.
Additionally, I am uncertain about the need to overriding metadata in XDP_PASS scenarios. Should BPF programs refrain from overriding the metadata in this case?
IIRC XDP_PASS was the initial use case for the metadata area. The driver needs to evacuate any HW metadata before handing over to the XDP program.
On 07/03, Song Yoong Siang wrote:
This patch set improves the documentation and selftests for XDP Rx metadata handling. The first patch clarifies the documentation around XDP metadata layout and METADATA_SIZE. The second patch enhances the BPF selftests to make XDP metadata handling more robust across different NICs.
Prior to this patch set, the XDP program might accidentally overwrite the device-reserved metadata.
V3:
- update doc and commit msg accordingly.
V2: https://lore.kernel.org/netdev/20250702030349.3275368-1-yoong.siang.song@int...
- unconditionally do bpf_xdp_adjust_meta with -XDP_METADATA_SIZE (Stanislav)
V1: https://lore.kernel.org/netdev/20250701042940.3272325-1-yoong.siang.song@int...
Acked-by: Stanislav Fomichev sdf@fomichev.me
linux-kselftest-mirror@lists.linaro.org
-
Daniel Borkmann -
Jakub Kicinski -
Jesper Dangaard Brouer -
Song Yoong Siang -
Song, Yoong Siang
-
Stanislav Fomichev