ibv_modify_qp

Modifies the attributes of a queue pair (QP).

Syntax

#include <rdma/verbs.h>

int ibv_modify_qp(struct ibv_qp *qp, struct ibv_qp_attr *attr, int ibv_qp_attr_mask attr_mask)

Queue pairs (QP) must be taken through an incremental sequence of states before using QP for communication.

The following table indicates the QP states:

Item	Descriptor
RESET	Newly created queues that are empty.
INIT	The basic information required for the queue is set and the queue is ready for posting to receive queue.
RTR	The queue is ready to receive. The remote address information is set for the connected QPs, and the QP can receive packets.
RTS	The queue is ready to send. The timeout and retry parameters are set. The QP can send packets.

The state transitions are used with ibv_modify_qp function.

Description

The ibv_modify_qp() function modifies the attributes of a QP qp with the attributes in attr parameter according to the attr_mask mask . The attr parameter is an ibv_qp_attr struct, as defined in the<rdma/verbs.h> file.

struct ibv_qp_attr {
enum ibv_qp_state       qp_state;               /* Move the QP to this state */
enum ibv_qp_state       cur_qp_state;           /* Assume this is the current QP state */
enum ibv_mtu            path_mtu;               /* Path MTU (valid only for RC/UC QPs) */
enum ibv_mig_state      path_mig_state;         /* Path migration state (valid if HCA supports APM) */
uint32_t                qkey;                   /* Q_Key for the QP (valid only for UD QPs) */
uint32_t                rq_psn;                 /* PSN for receive queue (valid only for RC/UC QPs) */
uint32_t                sq_psn;                 /* PSN for send queue (valid only for RC/UC QPs) */
uint32_t                dest_qp_num;            /* Destination QP number (valid only for RC/UC QPs) */
int                     qp_access_flags;        /* Mask of enabled remote access operations (valid only 
                                                   for RC/UC QPs) */
struct ibv_qp_cap       cap;                    /* QP capabilities (valid if HCA supports QP resizing) */
struct ibv_ah_attr      ah_attr;                /* Primary path address vector (valid only 
                                                   for RC/UC QPs) */
struct ibv_ah_attr      alt_ah_attr;            /* Alternate path address vector (valid only 
                                                   for RC/UC QPs) */
uint16_t                pkey_index;             /* Primary P_Key index */
uint16_t                alt_pkey_index;         /* Alternate P_Key index */
uint8_t                 en_sqd_async_notify;    /* Enable SQD.drained async notification (Valid only 
                                                   if qp_state is SQD) */
uint8_t                 sq_draining;            /* Is the QP draining? Irrelevant for ibv_modify_qp() */
uint8_t                 max_rd_atomic;          /* Number of outstanding RDMA reads & atomic operations 
                                                   on the destination QP (valid only for RC QPs) */
uint8_t                 max_dest_rd_atomic;     /* Number of responder resources for handling incoming 
                                                   RDMA reads & atomic operations (valid only 
                                                   for RC QPs)*/
uint8_t                 min_rnr_timer;          /* Minimum RNR NAK timer (valid only for RC QPs) */
uint8_t                 port_num;               /* Primary port number */
uint8_t                 timeout;                /* Local ack timeout for primary path (valid only 
                                                   for RC QPs) */
uint8_t                 retry_cnt;              /* Retry count (valid only for RC QPs) */
uint8_t                 rnr_retry;              /* RNR retry (valid only for RC QPs) */
uint8_t                 alt_port_num;           /* Alternate port number */
uint8_t                 alt_timeout;            /* Local ack timeout for alternate path (valid only 
                                                   for RC QPs) */
};

The attr_mask parameter specifies the QP attributes to be modified. The argument is either 0 or bitwise OR of one or more of the following flags:

IBV_QP_STATE: Modify qp_state
IBV_QP_CUR_STATE: Set cur_qp_state
IBV_QP_EN_SQD_ASYNC_NOTIFY: Set en_sqd_async_notify
IBV_QP_ACCESS_FLAGS: Set qp_access_flags
IBV_QP_PKEY_INDEX: Set pkey_index
IBV_QP_PORT: Set port_num
IBV_QP_QKEY: Set qkey
IBV_QP_AV: Set ah_attr
IBV_QP_PATH_MTU: Set path_mtu
IBV_QP_TIMEOUT: Set timeout
IBV_QP_RETRY_CNT: Set retry_cnt
IBV_QP_RNR_RETRY: Set rnr_retry
IBV_QP_RQ_PSN: Set rq_psn
IBV_QP_MAX_QP_RD_ATOMIC: Set max_rd_atomic
IBV_QP_ALT_PATH: Set the alternative path through alt_ah_attr, alt_pkey_index, alt_port_num, alt_timeout
IBV_QP_MIN_RNR_TIMER: Set min_rnr_timer
IBV_QP_SQ_PSN: Set sq_psn
IBV_QP_MAX_DEST_RD_ATOMIC: Set max_dest_rd_atomic
IBV_QP_PATH_MIG_STATE: Set path_mig_state
IBV_QP_CAP: Set cap
IBV_QP_DEST_QPN: Set dest_qp_num

Notes:

If any of the modify attributes or the modify mask is invalid, none of the attributes are modified (including the QP state).
Not all devices support resizing QPs. To determine whether a device supports resizing of the QP, check whether the IBV_DEVICE_RESIZE_MAX_WR bit is set in the device capabilities flags.
Not all devices support alternate paths. To determine whether a device supports alternate paths, check whether the IBV_DEVICE_AUTO_PATH_MIG bit is set in the device capabilities flags.

The following tables indicate the type of the QP transport service, the minimum list of attributes that must be changed after changing the QP state from Reset to Init to RTR to RTS state.

The types of QP transport service for the IBV_QPT_UD type, follow:

Next state     Required attributes
----------     ----------------------------------------
Init           IBV_QP_STATE, IBV_QP_PKEY_INDEX, IBV_QP_PORT, 
               IBV_QP_QKEY 
RTR            IBV_QP_STATE 
RTS            IBV_QP_STATE, IBV_QP_SQ_PSN 

The types of QP transport service for the IBV_QPT_UC type, follow:

Next state     Required attributes
----------     ----------------------------------------
Init           IBV_QP_STATE, IBV_QP_PKEY_INDEX, IBV_QP_PORT, 
               IBV_QP_ACCESS_FLAGS 
RTR            IBV_QP_STATE, IBV_QP_AV, IBV_QP_PATH_MTU, 
               IBV_QP_DEST_QPN, IBV_QP_RQ_PSN 
RTS            IBV_QP_STATE, IBV_QP_SQ_PSN 

The types of QP transport service for the IBV_QPT_RC type, follow:

Next state     Required attributes
----------     ----------------------------------------
Init           IBV_QP_STATE, IBV_QP_PKEY_INDEX, IBV_QP_PORT, 
               IBV_QP_ACCESS_FLAGS 
RTR            IBV_QP_STATE, IBV_QP_AV, IBV_QP_PATH_MTU, 
               IBV_QP_DEST_QPN, IBV_QP_RQ_PSN, 
               IBV_QP_MAX_DEST_RD_ATOMIC, IBV_QP_MIN_RNR_TIMER 
RTS            IBV_QP_STATE, IBV_QP_SQ_PSN, IBV_QP_MAX_QP_RD_ATOMIC, 
               IBV_QP_RETRY_CNT, IBV_QP_RNR_RETRY, IBV_QP_TIMEOUT 

The types of QP transport service for the  IBV_QPT_RAW_PACKET type, follow:

Next state     Required attributes
----------     ----------------------------------------
Init           IBV_QP_STATE, IBV_QP_PORT
RTR            IBV_QP_STATE
RTS            IBV_QP_STATE

Indicates the QP transport service types:

Next state	Required attributes
Init	IBV_QP_STATE, IBV_QP_PKEY_INDEX, IBV_QP_PORT, IBV_QP_ACCESS_FLAGS
RTR	IBV_QP_STATE, IBV_QP_AV, IBV_QP_PATH_MTU, IBV_QP_DEST_QPN, IBV_QP_RQ_PSN, IBV_QP_MAX_DEST_RD_ATOMIC, IBV_QP_MIN_RNR_TIMER
RTS	IBV_QP_STATE, IBV_QP_SQ_PSN, IBV_QP_MAX_QP_RD_ATOMIC, IBV_QP_RETRY_CNT, IBV_QP_RNR_RETRY, IBV_QP_TIMEOUT

Input Parameters

Item	Descriptor
qp	Specifies the `ibv_qp` struct for the ibv_create_qp function.
attr	Specifies the QP attributes.
attr_mask	Specifies the bit mask. The bit mask defines the attributes within the attr parameter that is set for a call.

Return Values

Item	Descriptor
0	On success.
errno	On failure.