IBV_MODIFY_QP(3)

💅 ibv_modify_qp(3) — straight outta the Libibverbs Programmer's Manual 🦋

okay bestie, sit down, hydrate, because we're about to give your queue pair the glow-up it deserves 💖

---

🌸 NAME 🌸

ibv_modify_qp — modify the attributes of a queue pair (QP) ✨

---

✨ SYNOPSIS ✨

#include <infiniband/verbs.h>

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

---

💖 DESCRIPTION 💖

so ibv_modify_qp() modifies the attributes of QP qp with the attributes sitting in attr, and it does that according to the mask attr_mask. the argument attr is an ibv_qp_attr struct, as defined in <infiniband/verbs.h>. no cap.

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 */
        uint32_t                dest_qp_num;            /* Destination QP number (valid only for RC/UC QPs) */
        unsigned 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) */
        uint32_t                rate_limit;             /* Rate limit in kbps for packet pacing */
};

want the tea on struct ibv_qp_cap? 🫖 go read the description of ibv_create_qp(). and for struct ibv_ah_attr, check out the description of ibv_create_ah(). iykyk.

the argument attr_mask tells you which QP attributes are getting modified. it's either 0, or the bitwise OR of one or more of these flags, bestie:

• 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 via: 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
• IBV_QP_RATE_LIMIT — set rate_limit

---

💫 RETURN VALUE 💫

ibv_modify_qp() returns 0 on success 🎉, or the value of errno on failure (which is literally the whole reason why it failed).

---

🚨 NOTES 🚨

⚠️ if any of the modify attributes or the modify mask are invalid, then none of the attributes will be modified — including the QP state. it's all or nothing, periodt. 💀

• not all devices support resizing QPs 😭 want to check? see if the IBV_DEVICE_RESIZE_MAX_WR bit is set in the device capabilities flags.
• not all devices support alternate paths either 🙈 to check, see if the IBV_DEVICE_AUTO_PATH_MIG bit is set in the device capabilities flags.

okay so here's the chart of minimum required attributes for each QP Transport Service Type when you're transitioning the QP state through: Reset --> Init --> RTR --> RTS. this is the main character energy of this whole page ngl 👑

For QP Transport Service Type IBV_QPT_UD:

• Init — required attributes: IBV_QP_STATE, IBV_QP_PKEY_INDEX, IBV_QP_PORT, IBV_QP_QKEY
• RTR — required attributes: IBV_QP_STATE
• RTS — required attributes: IBV_QP_STATE, IBV_QP_SQ_PSN

For QP Transport Service Type IBV_QPT_UC:

• Init — required attributes: IBV_QP_STATE, IBV_QP_PKEY_INDEX, IBV_QP_PORT, IBV_QP_ACCESS_FLAGS
• RTR — required attributes: IBV_QP_STATE, IBV_QP_AV, IBV_QP_PATH_MTU, IBV_QP_DEST_QPN, IBV_QP_RQ_PSN
• RTS — required attributes: IBV_QP_STATE, IBV_QP_SQ_PSN

For QP Transport Service Type IBV_QPT_RC:

• Init — required attributes: IBV_QP_STATE, IBV_QP_PKEY_INDEX, IBV_QP_PORT, IBV_QP_ACCESS_FLAGS
• RTR — required attributes: 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 — required attributes: IBV_QP_STATE, IBV_QP_SQ_PSN, IBV_QP_MAX_QP_RD_ATOMIC, IBV_QP_RETRY_CNT, IBV_QP_RNR_RETRY, IBV_QP_TIMEOUT

For QP Transport Service Type IBV_QPT_RAW_PACKET:

• Init — required attributes: IBV_QP_STATE, IBV_QP_PORT
• RTR — required attributes: IBV_QP_STATE
• RTS — required attributes: IBV_QP_STATE

and one more thing bestie, don't forget it 💅 — if port flag IBV_QPF_GRH_REQUIRED is set then ah_attr and alt_ah_attr must be passed with definition of 'struct ibv_ah_attr { .is_global = 1; .grh = {...}; }'.

---

👀 SEE ALSO 👀

• ibv_create_qp(3)
• ibv_destroy_qp(3)
• ibv_query_qp(3)
• ibv_create_ah(3)

---

👑 AUTHORS 👑

Dotan Barak <dotanba@gmail.com>

---

and that's the whole page, bestie 🫶 this came to you from libibverbs, dated 2006-10-31, and it lives under the name IBV_MODIFY_QP(3). go forth and modify those queue pairs responsibly, mwah 💖✨🎀