Add the the capability to load HW RX checsum in eBPF programs

Introduce XDP RX checksum capability to XDP metadata specs. XDP RX checksum will be use by devices capable of exposing receive checksum result via bpf_xdp_metadata_rx_checksum().
Moreover, introduce xmo_rx_checksum netdev callback in order to allow the eBPF program bound to the device to retrieve the RX checksum result computed by the hw NIC.

Signed-off-by Lorenzo Bianconi <[email protected]>

---
 Documentation/netlink/specs/netdev.yaml |  5 +++++
 include/net/xdp.h                       | 13 +++++++++++++
 include/uapi/linux/netdev.h             |  3 +++
 net/core/xdp.c                          | 28 ++++++++++++++++++++++++++++
 tools/include/uapi/linux/netdev.h       |  3 +++
 5 files changed, 52 insertions(+)

Documentation/netlink/specs/netdev.yaml +5 -0

index 596c306ce52b8303b20680ff0cd34d4fd9db0e48..58eda634668a07860447a65d9fc2284839af6244 100644
@@ -61,6 +61,11 @@ definitions:
         doc: |
           Device is capable of exposing receive packet VLAN tag via
           bpf_xdp_metadata_rx_vlan_tag().
+      -
+        name: checksum
+        doc: |
+          Device is capable of exposing receive checksum result via
+          bpf_xdp_metadata_rx_checksum().
   -
     type: flags
     name: xsk-flags

include/net/xdp.h +13 -0

index aa742f413c358575396530879af4570dc3fc18de..00abb2e1e85514b4080d0e4e6e3b8f5f67f73b61 100644
@@ -586,6 +586,10 @@ void xdp_attachment_setup(struct xdp_attachment_info *info,
 			   NETDEV_XDP_RX_METADATA_VLAN_TAG, \
 			   bpf_xdp_metadata_rx_vlan_tag, \
 			   xmo_rx_vlan_tag) \
+	XDP_METADATA_KFUNC(XDP_METADATA_KFUNC_RX_CHECKSUM, \
+			   NETDEV_XDP_RX_METADATA_CHECKSUM, \
+			   bpf_xdp_metadata_rx_checksum, \
+			   xmo_rx_checksum)
 
 enum xdp_rx_metadata {
 #define XDP_METADATA_KFUNC(name, _, __, ___) name,

@@ -643,12 +647,21 @@ enum xdp_rss_hash_type {
 	XDP_RSS_TYPE_L4_IPV6_SCTP_EX = XDP_RSS_TYPE_L4_IPV6_SCTP | XDP_RSS_L3_DYNHDR,
 };
 
+enum xdp_checksum {
+	XDP_CHECKSUM_NONE		= CHECKSUM_NONE,
+	XDP_CHECKSUM_UNNECESSARY	= CHECKSUM_UNNECESSARY,
+	XDP_CHECKSUM_COMPLETE		= CHECKSUM_COMPLETE,
+};
+
 struct xdp_metadata_ops {
 	int	(*xmo_rx_timestamp)(const struct xdp_md *ctx, u64 *timestamp);
 	int	(*xmo_rx_hash)(const struct xdp_md *ctx, u32 *hash,
 			       enum xdp_rss_hash_type *rss_type);
 	int	(*xmo_rx_vlan_tag)(const struct xdp_md *ctx, __be16 *vlan_proto,
 				   u16 *vlan_tci);
+	int	(*xmo_rx_checksum)(const struct xdp_md *ctx,
+				   enum xdp_checksum *ip_summed,
+				   u32 *cksum_meta);
 };
 
 #ifdef CONFIG_NET

include/uapi/linux/netdev.h +3 -0

index e0b579a1df4f2126acec6c44c299e97bbbefe640..d20da430cfd57bc26b5ea2f406c27b48d8a81693 100644
@@ -47,11 +47,14 @@ enum netdev_xdp_act {
  *   hash via bpf_xdp_metadata_rx_hash().
  * @NETDEV_XDP_RX_METADATA_VLAN_TAG: Device is capable of exposing receive
  *   packet VLAN tag via bpf_xdp_metadata_rx_vlan_tag().
+ * @NETDEV_XDP_RX_METADATA_CHECKSUM: Device is capable of exposing receive
+ *   checksum result via bpf_xdp_metadata_rx_checksum().
  */
 enum netdev_xdp_rx_metadata {
 	NETDEV_XDP_RX_METADATA_TIMESTAMP = 1,
 	NETDEV_XDP_RX_METADATA_HASH = 2,
 	NETDEV_XDP_RX_METADATA_VLAN_TAG = 4,
+	NETDEV_XDP_RX_METADATA_CHECKSUM = 8,
 };
 
 /**

net/core/xdp.c +5 -0

index fee6d080ee85fc2d278bfdddfd1365633058ec06..7d1e08d8ab4151ab42c91203def2afafc66d3149 100644
@@ -961,6 +961,34 @@ __bpf_kfunc int bpf_xdp_metadata_rx_vlan_tag(const struct xdp_md *ctx,
 	return -EOPNOTSUPP;
 }
 
+/**
+ * bpf_xdp_metadata_rx_checksum - Read XDP frame RX checksum.
+ * @ctx: XDP context pointer.
+ * @ip_summed: Return value pointer indicating checksum result.
+ * @cksum_meta: Return value pointer indicating checksum result metadata.

Quoted 101 lines · Lorenzo Bianconi

Introduce XDP RX checksum capability to XDP metadata specs. XDP RX checksum will be use by devices capable of exposing receive checksum result via bpf_xdp_metadata_rx_checksum().
Moreover, introduce xmo_rx_checksum netdev callback in order to allow the eBPF program bound to the device to retrieve the RX checksum result computed by the hw NIC.

Signed-off-by Lorenzo Bianconi <[email protected]>

---
  Documentation/netlink/specs/netdev.yaml |  5 +++++
  include/net/xdp.h                       | 13 +++++++++++++
  include/uapi/linux/netdev.h             |  3 +++
  net/core/xdp.c                          | 28 ++++++++++++++++++++++++++++
  tools/include/uapi/linux/netdev.h       |  3 +++
  5 files changed, 52 insertions(+)

Documentation/netlink/specs/netdev.yaml +5 -0

index 596c306ce52b8303b20680ff0cd34d4fd9db0e48..58eda634668a07860447a65d9fc2284839af6244 100644
@@ -61,6 +61,11 @@ definitions:
          doc: |
            Device is capable of exposing receive packet VLAN tag via
            bpf_xdp_metadata_rx_vlan_tag().
+      -
+        name: checksum
+        doc: |
+          Device is capable of exposing receive checksum result via
+          bpf_xdp_metadata_rx_checksum().
    -
      type: flags
      name: xsk-flags

include/net/xdp.h +13 -0

index aa742f413c358575396530879af4570dc3fc18de..00abb2e1e85514b4080d0e4e6e3b8f5f67f73b61 100644
@@ -586,6 +586,10 @@ void xdp_attachment_setup(struct xdp_attachment_info *info,
  			   NETDEV_XDP_RX_METADATA_VLAN_TAG, \
  			   bpf_xdp_metadata_rx_vlan_tag, \
  			   xmo_rx_vlan_tag) \
+	XDP_METADATA_KFUNC(XDP_METADATA_KFUNC_RX_CHECKSUM, \
+			   NETDEV_XDP_RX_METADATA_CHECKSUM, \
+			   bpf_xdp_metadata_rx_checksum, \
+			   xmo_rx_checksum)
 
  enum xdp_rx_metadata {
  #define XDP_METADATA_KFUNC(name, _, __, ___) name,

@@ -643,12 +647,21 @@ enum xdp_rss_hash_type {
  	XDP_RSS_TYPE_L4_IPV6_SCTP_EX = XDP_RSS_TYPE_L4_IPV6_SCTP | XDP_RSS_L3_DYNHDR,
  };
 
+enum xdp_checksum {
+	XDP_CHECKSUM_NONE		= CHECKSUM_NONE,
+	XDP_CHECKSUM_UNNECESSARY	= CHECKSUM_UNNECESSARY,
+	XDP_CHECKSUM_COMPLETE		= CHECKSUM_COMPLETE,
+};
+
  struct xdp_metadata_ops {
  	int	(*xmo_rx_timestamp)(const struct xdp_md *ctx, u64 *timestamp);
  	int	(*xmo_rx_hash)(const struct xdp_md *ctx, u32 *hash,
  			       enum xdp_rss_hash_type *rss_type);
  	int	(*xmo_rx_vlan_tag)(const struct xdp_md *ctx, __be16 *vlan_proto,
  				   u16 *vlan_tci);
+	int	(*xmo_rx_checksum)(const struct xdp_md *ctx,
+				   enum xdp_checksum *ip_summed,
+				   u32 *cksum_meta);
  };
 
  #ifdef CONFIG_NET

include/uapi/linux/netdev.h +3 -0

index e0b579a1df4f2126acec6c44c299e97bbbefe640..d20da430cfd57bc26b5ea2f406c27b48d8a81693 100644
@@ -47,11 +47,14 @@ enum netdev_xdp_act {
   *   hash via bpf_xdp_metadata_rx_hash().
   * @NETDEV_XDP_RX_METADATA_VLAN_TAG: Device is capable of exposing receive
   *   packet VLAN tag via bpf_xdp_metadata_rx_vlan_tag().
+ * @NETDEV_XDP_RX_METADATA_CHECKSUM: Device is capable of exposing receive
+ *   checksum result via bpf_xdp_metadata_rx_checksum().
   */
  enum netdev_xdp_rx_metadata {
  	NETDEV_XDP_RX_METADATA_TIMESTAMP = 1,
  	NETDEV_XDP_RX_METADATA_HASH = 2,
  	NETDEV_XDP_RX_METADATA_VLAN_TAG = 4,
+	NETDEV_XDP_RX_METADATA_CHECKSUM = 8,
  };
 
  /**

net/core/xdp.c +5 -0

index fee6d080ee85fc2d278bfdddfd1365633058ec06..7d1e08d8ab4151ab42c91203def2afafc66d3149 100644
@@ -961,6 +961,34 @@ __bpf_kfunc int bpf_xdp_metadata_rx_vlan_tag(const struct xdp_md *ctx,
  	return -EOPNOTSUPP;
  }
 
+/**
+ * bpf_xdp_metadata_rx_checksum - Read XDP frame RX checksum.
+ * @ctx: XDP context pointer.
+ * @ip_summed: Return value pointer indicating checksum result.
+ * @cksum_meta: Return value pointer indicating checksum result metadata.

net/core/xdp.c __bpf_kfunc int bpf_xdp_metadata_rx_vlan_tag(const struct xdp_md *ctx, · line 978

Quoted 10 lines

net/core/xdp.c +10 -0

+ *
+ * In case of success, ``ip_summed`` is set to the RX checksum result. Possible
+ * values are:
+ * ``XDP_CHECKSUM_NONE``
+ * ``XDP_CHECKSUM_UNNECESSARY``
+ * ``XDP_CHECKSUM_COMPLETE``
+ *
+ * In case of success, ``cksum_meta`` contains the hw computed checksum value
+ * for ``XDP_CHECKSUM_COMPLETE`` or the ``csum_level`` for
+ * ``XDP_CHECKSUM_UNNECESSARY``. It is set to 0 for ``XDP_CHECKSUM_NONE``

The only thing I'm still not sure about is the csum_level and whether we need to export it or just start with csum_level=0 and extend later when needed. The rest looks good.

Jesper, Lorenzo mentioned that you might need it? Can you clarify?

+ * In case of success, ``ip_summed`` is set to the RX checksum result. Possible
+ * values are:
+ * ``XDP_CHECKSUM_NONE``
+ * ``XDP_CHECKSUM_UNNECESSARY``
+ * ``XDP_CHECKSUM_COMPLETE``
+ *
+ * In case of success, ``cksum_meta`` contains the hw computed checksum value
+ * for ``XDP_CHECKSUM_COMPLETE`` or the ``csum_level`` for
+ * ``XDP_CHECKSUM_UNNECESSARY``. It is set to 0 for ``XDP_CHECKSUM_NONE``

Quoted 9 lines

+ * In case of success, ``ip_summed`` is set to the RX checksum result. Possible
+ * values are:
+ * ``XDP_CHECKSUM_NONE``
+ * ``XDP_CHECKSUM_UNNECESSARY``
+ * ``XDP_CHECKSUM_COMPLETE``
+ *
+ * In case of success, ``cksum_meta`` contains the hw computed checksum value
+ * for ``XDP_CHECKSUM_COMPLETE`` or the ``csum_level`` for
+ * ``XDP_CHECKSUM_UNNECESSARY``. It is set to 0 for ``XDP_CHECKSUM_NONE``

It's fairly common for NICs to report both csum complete and unnecessary. Which one should the driver return in that case?

What if the user prefers the other one?..

Quoted 11 lines · On Tue, 17 Feb 2026 09:33:56 +0100 Lorenzo Bianconi wrote:

Quoted 9 lines

+ * In case of success, ``ip_summed`` is set to the RX checksum result. Possible
+ * values are:
+ * ``XDP_CHECKSUM_NONE``
+ * ``XDP_CHECKSUM_UNNECESSARY``
+ * ``XDP_CHECKSUM_COMPLETE``
+ *
+ * In case of success, ``cksum_meta`` contains the hw computed checksum value
+ * for ``XDP_CHECKSUM_COMPLETE`` or the ``csum_level`` for
+ * ``XDP_CHECKSUM_UNNECESSARY``. It is set to 0 for ``XDP_CHECKSUM_NONE``

Quoted 2 lines

It's fairly common for NICs to report both csum complete and unnecessary. Which one should the driver return in that case?

Do you mean what is value for cksum_meta if we do not report csum_level for XDP_CHECKSUM_UNNECESSARY/CHECKSUM_UNNECESSARY use-case? (as suggested by Stanislav).

My original idea is:
- if the hw reports CHECKSUM_COMPLETE:
- ip_summed = XDP_CHECKSUM_COMPLETE
- cksum_meta contains the checksum computed by the hw
- if the hw reports CHECKSUM_UNNECESSARY
- ip_summed = XDP_CHECKSUM_UNNECESSARY
- cksum_meta = csum_level <-- Stanislav suggests to drop this one
- if the hw reports CHECKSUM_NONE
- ip_summed = XDP_CHECKSUM_NONE
- cksum_meta = 0

Quoted 11 lines

Quoted 11 lines · On Tue, 17 Feb 2026 09:33:56 +0100 Lorenzo Bianconi wrote:

Quoted 9 lines

+ * In case of success, ``ip_summed`` is set to the RX checksum result. Possible
+ * values are:
+ * ``XDP_CHECKSUM_NONE``
+ * ``XDP_CHECKSUM_UNNECESSARY``
+ * ``XDP_CHECKSUM_COMPLETE``
+ *
+ * In case of success, ``cksum_meta`` contains the hw computed checksum value
+ * for ``XDP_CHECKSUM_COMPLETE`` or the ``csum_level`` for
+ * ``XDP_CHECKSUM_UNNECESSARY``. It is set to 0 for ``XDP_CHECKSUM_NONE``

Quoted 6 lines

Quoted 2 lines

It's fairly common for NICs to report both csum complete and unnecessary. Which one should the driver return in that case?

Do you mean what is value for cksum_meta if we do not report csum_level for XDP_CHECKSUM_UNNECESSARY/CHECKSUM_UNNECESSARY use-case? (as suggested by Stanislav).

More fundamentally whether the API is right.

Quoted 10 lines

My original idea is:
- if the hw reports CHECKSUM_COMPLETE:
- ip_summed = XDP_CHECKSUM_COMPLETE
- cksum_meta contains the checksum computed by the hw
- if the hw reports CHECKSUM_UNNECESSARY
- ip_summed = XDP_CHECKSUM_UNNECESSARY
- cksum_meta = csum_level <-- Stanislav suggests to drop this one
- if the hw reports CHECKSUM_NONE
- ip_summed = XDP_CHECKSUM_NONE
- cksum_meta = 0

Off the top of my head drivers prefer reporting UNNECESSARY when they have both, and reserve COMPLETE for cases where L4 could not be found or is incorrect. Why don't we report both? We're using 3 args, we still have 3 to go. We could turn ip_summed into a bitmap and have explicit output args for both level and csum complete value?

One more thing I'd like us to at least have a plan for at this stage is how to deal with COMPLETE + modified packet + XDP_PASS. Right now some drivers discard COMPLETE when XDP is attached since they can't be sure if XDP modifies the packet. Other drivers don't and we end up with bad csum splat. Do we have a recommendation on the correct behavior? If not - should we have a kfunc to adjust / discard csum complete explicitly?

Quoted 5 lines

Off the top of my head drivers prefer reporting UNNECESSARY when they have both, and reserve COMPLETE for cases where L4 could not be found or is incorrect. Why don't we report both? We're using 3 args, we still have 3 to go. We could turn ip_summed into a bitmap and have explicit output args for both level and csum complete value?

Ack, thx for the explanation. Just for sake of understanding, is there any NIC capable of reporting both csum_value and csum for the same packet in the DMA descriptor? Or is this change needed to be future-proof?

Quoted 7 lines

One more thing I'd like us to at least have a plan for at this stage is how to deal with COMPLETE + modified packet + XDP_PASS. Right now some drivers discard COMPLETE when XDP is attached since they can't be sure if XDP modifies the packet. Other drivers don't and we end up with bad csum splat. Do we have a recommendation on the correct behavior? If not - should we have a kfunc to adjust / discard csum complete explicitly?

At the moment there is no way to store the csum value we got running bpf_xdp_metadata_rx_checksum() in order to be consumed during xdp_buff/xdp_frame to skb conversion (this info can just be consumed in the ebpf program bound to the NIC) but

I guess the issue you pointed out can be solved in the verifier during program load time. What do you think?

Quoted 6 lines

Quoted 5 lines

Off the top of my head drivers prefer reporting UNNECESSARY when they have both, and reserve COMPLETE for cases where L4 could not be found or is incorrect. Why don't we report both? We're using 3 args, we still have 3 to go. We could turn ip_summed into a bitmap and have explicit output args for both level and csum complete value?

Quoted 3 lines

Ack, thx for the explanation. Just for sake of understanding, is there any NIC capable of reporting both csum_value and csum for the same packet in the DMA descriptor? Or is this change needed to be future-proof?

Both nfp and fbnic definitely can. Off the top of my head - mlx5 also can, but I haven't double checked.

Quoted 9 lines

Quoted 8 lines

One more thing I'd like us to at least have a plan for at this stage is how to deal with COMPLETE + modified packet + XDP_PASS. Right now some drivers discard COMPLETE when XDP is attached since they can't be sure if XDP modifies the packet. Other drivers don't and we end up with bad csum splat. Do we have a recommendation on the correct behavior? If not - should we have a kfunc to adjust / discard csum complete explicitly?

Quoted 4 lines

At the moment there is no way to store the csum value we got running bpf_xdp_metadata_rx_checksum() in order to be consumed during xdp_buff/xdp_frame to skb conversion (this info can just be consumed in the ebpf program bound to the NIC) but

I think the scope here is much narrower than the xdp_buf to xdp_frame to skb conversion. We are just pass information between the program and driver which owns xdp_buff. Very similar to your new xmo.

We could either tell the driver to discard the csum complete or even add a helper to "adjust" the the csum value. Similar to the helper we have to adjust the csum in TC / skb context.

Quoted 3 lines

I guess the issue you pointed out can be solved in the verifier during program load time. What do you think?

It could, but at the verifier level we'd probably have to be fairly coarse-grained. Any write to the packet data would mean csum complete cannot be trusted, that's not too hard. But also any tail call / fentry? I'm not really up to date on the latest in program chaining in BPF but I think a lot of real-life deployments would use either chaining or fentry. So in practice it may be a lot of complexity for having csum complete always disabled w/ XDP, in practice.

Up to you. I'm totally okay to just say** that drivers should never report csum complete with XDP (until appropriate API is built). Perhaps this will force those who care about XDP+csum_complete to tell us what their requirements are?

[**] "just say" == document and add driver kselftest that validates it

Quoted 5 lines

Quoted 4 lines

At the moment there is no way to store the csum value we got running bpf_xdp_metadata_rx_checksum() in order to be consumed during xdp_buff/xdp_frame to skb conversion (this info can just be consumed in the ebpf program bound to the NIC) but

Quoted 7 lines

I think the scope here is much narrower than the xdp_buf to xdp_frame to skb conversion. We are just pass information between the program and driver which owns xdp_buff. Very similar to your new xmo.

We could either tell the driver to discard the csum complete or even add a helper to "adjust" the the csum value. Similar to the helper we have to adjust the csum in TC / skb context.

IIUC, for the CSUM_COMPLETE case, we want to add a kfunc used to update (or invalidate) the checksum value (if the packet has been modified by the eBPF program bounded to the NIC) and report the updated checksum to the driver if the XDP verdict is XDP_PASS. Correct?

I guess we could have two approaches here:
- Write the new checksum value into the xdp_metadata area (if available) where the driver can load it and update the checksum value before allocating the skb.
The main downside of this approach is we need modify each driver.
- Add a new xmo callback used to set the checksum value and report it from the eBPF program into a specific memory area provided by the driver (e.g. DMA descriptor) that is used to build the skb.

What do you think?

Moreover, since we already have this issue upstream, do you think this new feature must be part this series or can we do it with a follow-up patch/series?

Quoted 27 lines

Quoted 5 lines

Quoted 4 lines

At the moment there is no way to store the csum value we got running bpf_xdp_metadata_rx_checksum() in order to be consumed during xdp_buff/xdp_frame to skb conversion (this info can just be consumed in the ebpf program bound to the NIC) but

Quoted 7 lines

I think the scope here is much narrower than the xdp_buf to xdp_frame to skb conversion. We are just pass information between the program and driver which owns xdp_buff. Very similar to your new xmo.

We could either tell the driver to discard the csum complete or even add a helper to "adjust" the the csum value. Similar to the helper we have to adjust the csum in TC / skb context.

IIUC, for the CSUM_COMPLETE case, we want to add a kfunc used to update (or invalidate) the checksum value (if the packet has been modified by the eBPF program bounded to the NIC) and report the updated checksum to the driver if the XDP verdict is XDP_PASS. Correct?

I guess we could have two approaches here:
- Write the new checksum value into the xdp_metadata area (if available) where the driver can load it and update the checksum value before allocating the skb.
The main downside of this approach is we need modify each driver.
- Add a new xmo callback used to set the checksum value and report it from the eBPF program into a specific memory area provided by the driver (e.g. DMA descriptor) that is used to build the skb.

Quoted 1 line

What do you think?

Exactly. The invalidation is easier 'cause using a single bit in the flags should be uncontroversial. If we want to be able to repair / provide the csum complete then we have to pick one of the two options you outlined. As you may suspect from previous discussions I favor the latter. But we'd probably have to have a PoC with either one and see where the consensus falls.

Actually, thinking about it more, I guess this is not just a CSUM_COMPLETE issue. XDP_PASS will also risk reporting invalid UNNECESSARY to the stack (e.g. when XDP stripped a UDP tunnel which which the NIC compute the UNNECESSARY but the packet inside the tunnel has an invalid csum).

Quoted 3 lines

Moreover, since we already have this issue upstream, do you think this new feature must be part this series or can we do it with a follow-up patch/series?

We don't have to add the kfunc to adjust / invalidate the csum. But we should document how the drivers are expected to behave until such kfunc exists and we should add a selftest that checks the documented expectation.