--- name: "mlx5dv_create_qp" section: "3" platform: "linux" package: "rdma-core" version: "65.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/mlx5dv_create_qp" --- # mlx5dv\_create\_qp(3) creates a queue pair (QP) ## NAME mlx5dv\_create\_qp - creates a queue pair (QP) ## SYNOPSIS - ``` #include struct ibv_qp *mlx5dv_create_qp(struct ibv_context *context, struct ibv_qp_init_attr_ex *qp_attr, struct mlx5dv_qp_init_attr *mlx5_qp_attr) ``` ## DESCRIPTION **mlx5dv\_create\_qp()** creates a queue pair (QP) with specific driver properties. ## ARGUMENTS Please see *[ibv\_create\_qp\_ex(3)](/ibv_create_qp_ex/3.md)* man page for *context* and *qp\_attr*. ### mlx5\_qp\_attr - ``` struct mlx5dv_qp_init_attr { uint64_t comp_mask; uint32_t create_flags; struct mlx5dv_dc_init_attr dc_init_attr; uint64_t send_ops_flags; }; ``` - *comp\_mask* Bitmask specifying what fields in the structure are valid: MLX5DV\_QP\_INIT\_ATTR\_MASK\_QP\_CREATE\_FLAGS: valid values in *create\_flags* MLX5DV\_QP\_INIT\_ATTR\_MASK\_DC: valid values in *dc\_init\_attr* MLX5DV\_QP\_INIT\_ATTR\_MASK\_SEND\_OPS\_FLAGS: valid values in *send\_ops\_flags* - *create\_flags* A bitwise OR of the various values described below. MLX5DV\_QP\_CREATE\_TUNNEL\_OFFLOADS: Enable offloading such as checksum and LRO for incoming tunneling traffic. MLX5DV\_QP\_CREATE\_TIR\_ALLOW\_SELF\_LOOPBACK\_UC: Allow receiving loopback unicast traffic. MLX5DV\_QP\_CREATE\_TIR\_ALLOW\_SELF\_LOOPBACK\_MC: Allow receiving loopback multicast traffic. MLX5DV\_QP\_CREATE\_DISABLE\_SCATTER\_TO\_CQE: Disable scatter to CQE feature which is enabled by default. MLX5DV\_QP\_CREATE\_ALLOW\_SCATTER\_TO\_CQE: Allow scatter to CQE for requester even if the qp was not configured to signal all WRs. MLX5DV\_QP\_CREATE\_PACKET\_BASED\_CREDIT\_MODE: Set QP to work in end-to-end packet-based credit, instead of the default message-based credits (IB spec. section 9.7.7.2). It is the applications responsibility to make sure that the peer QP is configured with same mode. MLX5DV\_QP\_CREATE\_SIG\_PIPELINING: If the flag is set, the QP is moved to SQD state upon encountering a signature error, and IBV\_EVENT\_SQ\_DRAINED is generated to inform about the new state. The signature pipelining feature is a performance optimization, which reduces latency for read operations in the storage protocols. The feature is optional. Creating the QP fails if the kernel or device does not support the feature. In this case, an application should fallback to backward compatibility mode and handle read operations without the pipelining. See details about the signature pipelining in [**mlx5dv\_qp\_cancel\_posted\_send\_wrs**(3)](/mlx5dv_qp_cancel_posted_send_wrs/3.md). MLX5DV\_QP\_CREATE\_OOO\_DP: If the flag is set, Receive WRs on the receiver side of the QP are allowed to be consumed out-of-order and sender side of the QP is allowed to transmit messages without guaranteeing any arrival ordering on the receiver side. - ``` The flag, when set, must be set both on the sender and receiver side of a QP (e.g., DCT and DCI). Setting the flag is optional and the availability of this feature should be queried by the application (See details in **mlx5dv_query_device**(3)) and there is no automatic fallback: If the flag is set while kernel or device does not support the feature, then creating the QP fails. Thus, before creating a QP with this flag set, application must query the maximal outstanding Receive WRs possible on a QP with this flag set, according to the QP type (see details in **mlx5dv_query_device**(3)) and make sure the capability is supported. > **Note** > > All the following describe the behavior and semantics of a QP > with this flag set. Completions' delivery ordering: A Receive WR posted on this QP may be consumed by any arriving message to this QP that requires Receive WR consumption. Nonetheless, the ordering in which work completions are delivered for the posted WRs, both on sender side and receiver side, remains unchanged when this flag is set (and is independent of the ordering in which the Receive WRs are consumed). The ID delivered in every work completion (wr_id) will specify which WR was completed by the delivered work completion. Data placing and operations' execution ordering: RDMA Read and RDMA Atomic operations are executed on the responder side in order, i.e., these operations are executed after all previous messages are done executing. However, the ordering of RDMA Read response packets being scattered to memory on the requestor side is not guaranteed. This means that, although the data is read after executing all previous messages, it may be scattered out-of-order on the requestor side. Ordering of write requests towards the memory on the responder side, initiated by RDMA Send, RDMA Send with Immediate, RDMA Write or RDMA Write with Immediate is not guaranteed. Good and bad practice: Since it cannot be guaranteed which RDMA Send (and/or RDMA Send with Immediate) will consume a Receive WR (and will scatter its data to the memory buffers specified in the WR) it's not recommended to post different sizes of Receive WRs. Polling on any memory that is used by the device to scatter data, is not recommended since ordering of data placement of RDMA Send, RDMA Write and RDMA Write with Immediate is not guaranteed. Receiver, upon getting a completion for an RDMA Write with Immediate, should not rely on wr_id alone to determine to which memory data was scattered by the operation. ``` - *dc\_init\_attr* DC init attributes. ### *dc\_init\_attr* - ``` struct mlx5dv_dci_streams { uint8_t log_num_concurent; uint8_t log_num_errored; }; struct mlx5dv_dc_init_attr { enum mlx5dv_dc_type dc_type; union { uint64_t dct_access_key; struct mlx5dv_dci_streams dci_streams; }; }; ``` - *dc\_type* MLX5DV\_DCTYPE\_DCT QP type: Target DC. MLX5DV\_DCTYPE\_DCI QP type: Initiator DC. - *dct\_access\_key* used to create a DCT QP. - *dci\_streams* dci\_streams used to define DCI QP with multiple concurrent streams. Valid when comp\_mask includes MLX5DV\_QP\_INIT\_ATTR\_MASK\_DCI\_STREAMS. log\_num\_concurent Defines the number of parallel different streams that could be handled by HW. All work request of a specific stream\_id are handled in order. log\_num\_errored Defines the number of dci error stream channels before moving DCI to an error state. - *send\_ops\_flags* A bitwise OR of the various values described below. MLX5DV\_QP\_EX\_WITH\_MR\_INTERLEAVED: Enables the mlx5dv\_wr\_mr\_interleaved() work requset on this QP. MLX5DV\_QP\_EX\_WITH\_MR\_LIST: Enables the mlx5dv\_wr\_mr\_list() work requset on this QP. MLX5DV\_QP\_EX\_WITH\_MKEY\_CONFIGURE: Enables the mlx5dv\_wr\_mkey\_configure() work request and the related setters on this QP. ## NOTES **mlx5dv\_qp\_ex\_from\_ibv\_qp\_ex()** is used to get *struct* *mlx5dv\_qp\_ex* for accessing the send ops interfaces when IBV\_QP\_INIT\_ATTR\_SEND\_OPS\_FLAGS is used. The MLX5DV\_QP\_CREATE\_DISABLE\_SCATTER\_TO\_CQE flag should be set in cases that IOVA doesn’t match the process’ VA and the message payload size is small enough to trigger the scatter to CQE feature. When device memory is used IBV\_SEND\_INLINE and scatter to CQE should not be used, as the memcpy is not possible. ## RETURN VALUE **mlx5dv\_create\_qp()** returns a pointer to the created QP, on error NULL will be returned and errno will be set. ## SEE ALSO [**ibv\_query\_device\_ex**(3)](/ibv_query_device_ex/3.md), [**ibv\_create\_qp\_ex**(3)](/ibv_create_qp_ex/3.md), [**mlx5dv\_query\_device**(3)](/mlx5dv_query_device/3.md) ## AUTHOR Yonatan Cohen ⟨yonatanc@mellanox.com⟩\\c