[PATCH] net/mlx5: add RSS TIR registration API

[PATCH] net/mlx5: add RSS TIR registration API

[Shani Peretz]

mlx5 PMD is a bifurcated driver, which uses rdma-core APIs to
communicate with HW instead of UIO or VFIO directly.

It is possible for external libraries built on rdma-core to steer
traffic to DPDK-managed Rx queues using mlx5dv flow API. This
requires access to TIR object handles.

TIR (Transport Interface Receive) is a hardware object that defines
how incoming packets are distributed across Rx queues. It encodes
the complete RSS configuration including the hash function type,
hash key, set of destination queues, and which packet fields
(IP addresses, ports, etc.) participate in the hash calculation.
When a flow rule uses a TIR as its destination, the hardware applies
this RSS configuration to matching packets.

Add the following functions to mlx5 PMD private API:

- rte_pmd_mlx5_rss_tir_register(): Create a TIR DevX object based on
  the provided RSS configuration. The returned TIR handle can be used
  as a destination action in mlx5dv flow steering APIs from rdma-core.

- rte_pmd_mlx5_rss_tir_unregister(): Release the TIR object when no
  longer needed.

Signed-off-by: Shani Peretz <shperetz@nvidia.com>
Acked-by: Dariusz Sosnowski <dsosnowski@nvidia.com>
---
 drivers/net/mlx5/mlx5_flow_hw.c | 82 +++++++++++++++++++++++++++++++++
 drivers/net/mlx5/rte_pmd_mlx5.h | 54 ++++++++++++++++++++++
 2 files changed, 136 insertions(+)

diff --git a/drivers/net/mlx5/mlx5_flow_hw.c b/drivers/net/mlx5/mlx5_flow_hw.c
index c41b99746f..98483abc7f 100644
--- a/drivers/net/mlx5/mlx5_flow_hw.c
+++ b/drivers/net/mlx5/mlx5_flow_hw.c
@@ -2,6 +2,7 @@
  * Copyright (c) 2022 NVIDIA Corporation & Affiliates
  */
 
+#include <eal_export.h>
 #include <rte_flow.h>
 #include <rte_flow_driver.h>
 #include <rte_stdatomic.h>
@@ -574,6 +575,87 @@ flow_hw_hashfields_set(struct mlx5_flow_rss_desc *rss_desc,
 	*hash_fields |= fields;
 }
 
+RTE_EXPORT_EXPERIMENTAL_SYMBOL(rte_pmd_mlx5_rss_tir_register, 26.03)
+int
+rte_pmd_mlx5_rss_tir_register(uint16_t port_id,
+			      const struct rte_flow_action_rss *rss,
+			      struct rte_pmd_mlx5_rss_devx *devx)
+{
+	struct rte_eth_dev *dev;
+	struct mlx5_hrxq *hrxq;
+	struct mlx5_flow_rss_desc rss_desc = {
+		.hws_flags = MLX5DR_ACTION_FLAG_ROOT_RX,
+	};
+
+	if (rte_eth_dev_is_valid_port(port_id) < 0) {
+		DRV_LOG(ERR, "port %u: no Ethernet device", port_id);
+		rte_errno = ENODEV;
+		return -rte_errno;
+	}
+	if (!rss->queue_num || !rss->queue) {
+		DRV_LOG(ERR, "port %u: invalid RSS queues configuration", port_id);
+		rte_errno = EINVAL;
+		return -rte_errno;
+	}
+	if (rss->key && rss->key_len != MLX5_RSS_HASH_KEY_LEN) {
+		DRV_LOG(ERR, "port %u: RSS key length must be %d",
+			port_id, MLX5_RSS_HASH_KEY_LEN);
+		rte_errno = EINVAL;
+		return -rte_errno;
+	}
+	dev = &rte_eth_devices[port_id];
+	if (!mlx5_hws_active(dev)) {
+		DRV_LOG(ERR, "port %u: HWS not active", port_id);
+		rte_errno = EINVAL;
+		return -rte_errno;
+	}
+	rss_desc.queue_num = rss->queue_num;
+	rss_desc.const_q = rss->queue;
+	if (rss->queue_num > 1) {
+		memcpy(rss_desc.key,
+		       rss->key ? rss->key : rss_hash_default_key,
+		       MLX5_RSS_HASH_KEY_LEN);
+		rss_desc.key_len = MLX5_RSS_HASH_KEY_LEN;
+		rss_desc.types = !rss->types ? RTE_ETH_RSS_IP : rss->types;
+		rss_desc.symmetric_hash_function = MLX5_RSS_IS_SYMM(rss->func);
+		flow_hw_hashfields_set(&rss_desc, &rss_desc.hash_fields);
+		flow_dv_action_rss_l34_hash_adjust(rss->types,
+						   &rss_desc.hash_fields);
+		if (rss->level > 1) {
+			rss_desc.hash_fields |= IBV_RX_HASH_INNER;
+			rss_desc.tunnel = 1;
+		}
+	}
+
+	hrxq = mlx5_hrxq_get(dev, &rss_desc);
+	if (!hrxq) {
+		DRV_LOG(ERR, "port %u: failed to allocate DevX", port_id);
+		return -rte_errno;
+	}
+	devx->destroy_handle = hrxq;
+	devx->obj = hrxq->tir->obj;
+	devx->id = hrxq->tir->id;
+
+	return 0;
+}
+
+RTE_EXPORT_EXPERIMENTAL_SYMBOL(rte_pmd_mlx5_rss_tir_unregister, 26.03)
+int
+rte_pmd_mlx5_rss_tir_unregister(uint16_t port_id, void *handle)
+{
+	struct rte_eth_dev *dev;
+	struct mlx5_hrxq *hrxq = handle;
+
+	if (rte_eth_dev_is_valid_port(port_id) < 0) {
+		DRV_LOG(ERR, "port %u: no Ethernet device", port_id);
+		rte_errno = ENODEV;
+		return -rte_errno;
+	}
+	dev = &rte_eth_devices[port_id];
+	mlx5_hrxq_obj_release(dev, hrxq);
+	return 0;
+}
+
 uint64_t
 mlx5_flow_hw_action_flags_get(const struct rte_flow_action actions[],
 			 const struct rte_flow_action **qrss,
diff --git a/drivers/net/mlx5/rte_pmd_mlx5.h b/drivers/net/mlx5/rte_pmd_mlx5.h
index 31f99e7a78..7acfdae97d 100644
--- a/drivers/net/mlx5/rte_pmd_mlx5.h
+++ b/drivers/net/mlx5/rte_pmd_mlx5.h
@@ -9,6 +9,7 @@
 
 #include <rte_byteorder.h>
 #include <rte_compat.h>
+#include <rte_flow.h>
 #include <rte_per_lcore.h>
 
 /**
@@ -626,6 +627,59 @@ __rte_experimental
 int
 rte_pmd_mlx5_enable_steering(void);
 
+struct rte_pmd_mlx5_rss_devx {
+	void *obj; /**< DevX object pointer. */
+	void *destroy_handle; /**< Destroy handle passed to #rte_pmd_mlx5_rss_tir_unregister. */
+	uint32_t id; /**< DevX object ID. */
+};
+
+/**
+ * Register TIR DevX object for RSS flow action.
+ *
+ * TIR (Transport Interface Receive) is a hardware object that encodes
+ * RSS configuration (hash function, key, destination queues) and serves
+ * as the destination for steering rules directing traffic to Rx queues.
+ *
+ * This function creates a TIR object based on the provided RSS configuration.
+ * The returned DevX handle can be used as a destination action in mlx5dv
+ * flow steering API from rdma-core, enabling external libraries to direct
+ * traffic to DPDK-managed Rx queues.
+ *
+ * @param[in] port_id
+ *   The port identifier of the Ethernet device.
+ * @param[in] rss
+ *  RSS flow action configuration.
+ * @param[out] devx
+ *   A pointer to an object that will store returned data.
+ *
+ * @return
+ *   - (0) if successful. *devx* will hold DevX object.
+ *   - (-ENODEV) if *port_id* invalid.
+ *   - (-EINVAL) if *rss* data was incorrect or port HWS was not activated.
+ *   - (-ENOMEM) memory allocation error.
+ */
+__rte_experimental
+int
+rte_pmd_mlx5_rss_tir_register(uint16_t port_id,
+				   const struct rte_flow_action_rss *rss,
+				   struct rte_pmd_mlx5_rss_devx *devx);
+
+/**
+ * Unregister RSS action DevX object.
+ *
+ * @param[in] port_id
+ *   The port identifier of the Ethernet device.
+ * @param[in] handle
+ *   DevX object handle (destroy_handle from rte_pmd_mlx5_rss_devx).
+ * @return
+ *   - (0) if successful.
+ *   - (-ENODEV) if *port_id* invalid.
+ */
+__rte_experimental
+int
+rte_pmd_mlx5_rss_tir_unregister(uint16_t port_id, void *handle);
+
+
 #ifdef __cplusplus
 }
 #endif
-- 
2.43.0

Re: [PATCH] net/mlx5: add RSS TIR registration API

[Raslan Darawsheh]

Hi,


On 08/01/2026 10:12 AM, Shani Peretz wrote:
> mlx5 PMD is a bifurcated driver, which uses rdma-core APIs to
> communicate with HW instead of UIO or VFIO directly.
> 
> It is possible for external libraries built on rdma-core to steer
> traffic to DPDK-managed Rx queues using mlx5dv flow API. This
> requires access to TIR object handles.
> 
> TIR (Transport Interface Receive) is a hardware object that defines
> how incoming packets are distributed across Rx queues. It encodes
> the complete RSS configuration including the hash function type,
> hash key, set of destination queues, and which packet fields
> (IP addresses, ports, etc.) participate in the hash calculation.
> When a flow rule uses a TIR as its destination, the hardware applies
> this RSS configuration to matching packets.
> 
> Add the following functions to mlx5 PMD private API:
> 
> - rte_pmd_mlx5_rss_tir_register(): Create a TIR DevX object based on
>    the provided RSS configuration. The returned TIR handle can be used
>    as a destination action in mlx5dv flow steering APIs from rdma-core.
> 
> - rte_pmd_mlx5_rss_tir_unregister(): Release the TIR object when no
>    longer needed.
> 
> Signed-off-by: Shani Peretz <shperetz@nvidia.com>
> Acked-by: Dariusz Sosnowski <dsosnowski@nvidia.com>

Patch applied to next-net-mlx,

Kindest regards
Raslan Darawsheh