contrib/ofed/libibverbs/man/ibv_modify_qp.3

   1 .\" -*- nroff -*-
   2 .\"
   3 .TH IBV_MODIFY_QP 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual"
   4 .SH "NAME"
   5 ibv_modify_qp \- modify the attributes of a queue pair (QP)
   6 .SH "SYNOPSIS"
   7 .nf
   8 .B #include <infiniband/verbs.h>
   9 .sp
  10 .BI "int ibv_modify_qp(struct ibv_qp " "*qp" ", struct ibv_qp_attr " "*attr" ,
  11 .BI "                  int " "attr_mask" );
  12 .fi
  13 .SH "DESCRIPTION"
  14 .B ibv_modify_qp()
  15 modifies the attributes of QP
  16 .I qp
  17 with the attributes in
  18 .I attr
  19 according to the mask
  20 .I attr_mask\fR.
  21 The argument \fIattr\fR is an ibv_qp_attr struct, as defined in <infiniband/verbs.h>.
  22 .PP
  23 .nf
  24 struct ibv_qp_attr {
  25 .in +8
  26 enum ibv_qp_state       qp_state;               /* Move the QP to this state */
  27 enum ibv_qp_state       cur_qp_state;           /* Assume this is the current QP state */
  28 enum ibv_mtu            path_mtu;               /* Path MTU (valid only for RC/UC QPs) */
  29 enum ibv_mig_state      path_mig_state;         /* Path migration state (valid if HCA supports APM) */
  30 uint32_t                qkey;                   /* Q_Key for the QP (valid only for UD QPs) */
  31 uint32_t                rq_psn;                 /* PSN for receive queue (valid only for RC/UC QPs) */
  32 uint32_t                sq_psn;                 /* PSN for send queue (valid only for RC/UC QPs) */
  33 uint32_t                dest_qp_num;            /* Destination QP number (valid only for RC/UC QPs) */
  34 int                     qp_access_flags;        /* Mask of enabled remote access operations (valid only for RC/UC QPs) */
  35 struct ibv_qp_cap       cap;                    /* QP capabilities (valid if HCA supports QP resizing) */
  36 struct ibv_ah_attr      ah_attr;                /* Primary path address vector (valid only for RC/UC QPs) */
  37 struct ibv_ah_attr      alt_ah_attr;            /* Alternate path address vector (valid only for RC/UC QPs) */
  38 uint16_t                pkey_index;             /* Primary P_Key index */
  39 uint16_t                alt_pkey_index;         /* Alternate P_Key index */
  40 uint8_t                 en_sqd_async_notify;    /* Enable SQD.drained async notification (Valid only if qp_state is SQD) */
  41 uint8_t                 sq_draining;            /* Is the QP draining? Irrelevant for ibv_modify_qp() */
  42 uint8_t                 max_rd_atomic;          /* Number of outstanding RDMA reads & atomic operations on the destination QP (valid only for RC QPs) */
  43 uint8_t                 max_dest_rd_atomic;     /* Number of responder resources for handling incoming RDMA reads & atomic operations (valid only for RC QPs) */
  44 uint8_t                 min_rnr_timer;          /* Minimum RNR NAK timer (valid only for RC QPs) */
  45 uint8_t                 port_num;               /* Primary port number */
  46 uint8_t                 timeout;                /* Local ack timeout for primary path (valid only for RC QPs) */
  47 uint8_t                 retry_cnt;              /* Retry count (valid only for RC QPs) */
  48 uint8_t                 rnr_retry;              /* RNR retry (valid only for RC QPs) */
  49 uint8_t                 alt_port_num;           /* Alternate port number */
  50 uint8_t                 alt_timeout;            /* Local ack timeout for alternate path (valid only for RC QPs) */
  51 .in -8
  52 };
  53 .fi
  54 .PP
  55 For details on struct ibv_qp_cap see the description of
  56 .B ibv_create_qp()\fR.
  57 For details on struct ibv_ah_attr see the description of
  58 .B ibv_create_ah()\fR.
  59 .PP
  60 The argument
  61 .I attr_mask
  62 specifies the QP attributes to be modified.
  63 The argument is either 0 or the bitwise OR of one or more of the following flags:
  64 .PP
  65 .TP
  66 .B IBV_QP_STATE \fR Modify qp_state
  67 .TP
  68 .B IBV_QP_CUR_STATE \fR Set cur_qp_state
  69 .TP
  70 .B IBV_QP_EN_SQD_ASYNC_NOTIFY \fR Set en_sqd_async_notify
  71 .TP
  72 .B IBV_QP_ACCESS_FLAGS \fR Set qp_access_flags
  73 .TP
  74 .B IBV_QP_PKEY_INDEX \fR Set pkey_index
  75 .TP
  76 .B IBV_QP_PORT \fR Set port_num
  77 .TP
  78 .B IBV_QP_QKEY \fR Set qkey
  79 .TP
  80 .B IBV_QP_AV \fR Set ah_attr
  81 .TP
  82 .B IBV_QP_PATH_MTU \fR Set path_mtu
  83 .TP
  84 .B IBV_QP_TIMEOUT \fR Set timeout
  85 .TP
  86 .B IBV_QP_RETRY_CNT \fR Set retry_cnt
  87 .TP
  88 .B IBV_QP_RNR_RETRY \fR Set rnr_retry
  89 .TP
  90 .B IBV_QP_RQ_PSN \fR Set rq_psn
  91 .TP
  92 .B IBV_QP_MAX_QP_RD_ATOMIC \fR Set max_rd_atomic
  93 .TP
  94 .B IBV_QP_ALT_PATH \fR Set the alternative path via: alt_ah_attr, alt_pkey_index, alt_port_num, alt_timeout
  95 .TP
  96 .B IBV_QP_MIN_RNR_TIMER \fR Set min_rnr_timer
  97 .TP
  98 .B IBV_QP_SQ_PSN \fR Set sq_psn
  99 .TP
 100 .B IBV_QP_MAX_DEST_RD_ATOMIC \fR Set max_dest_rd_atomic
 101 .TP
 102 .B IBV_QP_PATH_MIG_STATE \fR Set path_mig_state
 103 .TP
 104 .B IBV_QP_CAP \fR Set cap
 105 .TP
 106 .B IBV_QP_DEST_QPN \fR Set dest_qp_num
 107 .SH "RETURN VALUE"
 108 .B ibv_modify_qp()
 109 returns 0 on success, or the value of errno on failure (which indicates the failure reason).
 110 .SH "NOTES"
 111 If any of the modify attributes or the modify mask are invalid, none
 112 of the attributes will be modified (including the QP state).
 113 .PP
 114 Not all devices support resizing QPs.  To check if a device supports it, check if the
 115 .B IBV_DEVICE_RESIZE_MAX_WR
 116 bit is set in the device capabilities flags.
 117 .PP
 118 Not all devices support alternate paths.  To check if a device supports it, check if the
 119 .B IBV_DEVICE_AUTO_PATH_MIG
 120 bit is set in the device capabilities flags.
 121 .PP
 122 The following tables indicate for each QP Transport Service Type, the
 123 minimum list of attributes that must be changed upon transitioning QP
 124 state from: Reset \-\-> Init \-\-> RTR \-\-> RTS.
 125 .PP
 126 .nf
 127 For QP Transport Service Type \fB IBV_QPT_UD\fR:
 128 .sp
 129 Next state     Required attributes
 130 \-\-\-\-\-\-\-\-\-\-     \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 131 Init \fB          IBV_QP_STATE, IBV_QP_PKEY_INDEX, IBV_QP_PORT, \fR
 132      \fB          IBV_QP_QKEY \fR
 133 RTR  \fB          IBV_QP_STATE \fR
 134 RTS  \fB          IBV_QP_STATE, IBV_QP_SQ_PSN \fR
 135 .fi
 136 .PP
 137 .nf
 138 For QP Transport Service Type \fB IBV_QPT_UC\fR:
 139 .sp
 140 Next state     Required attributes
 141 \-\-\-\-\-\-\-\-\-\-     \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 142 Init \fB          IBV_QP_STATE, IBV_QP_PKEY_INDEX, IBV_QP_PORT, \fR
 143      \fB          IBV_QP_ACCESS_FLAGS \fR
 144 RTR  \fB          IBV_QP_STATE, IBV_QP_AV, IBV_QP_PATH_MTU, \fR
 145      \fB          IBV_QP_DEST_QPN, IBV_QP_RQ_PSN \fR
 146 RTS  \fB          IBV_QP_STATE, IBV_QP_SQ_PSN \fR
 147 .fi
 148 .PP
 149 .nf
 150 For QP Transport Service Type \fB IBV_QPT_RC\fR:
 151 .sp
 152 Next state     Required attributes
 153 \-\-\-\-\-\-\-\-\-\-     \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 154 Init \fB          IBV_QP_STATE, IBV_QP_PKEY_INDEX, IBV_QP_PORT, \fR
 155      \fB          IBV_QP_ACCESS_FLAGS \fR
 156 RTR  \fB          IBV_QP_STATE, IBV_QP_AV, IBV_QP_PATH_MTU, \fR
 157      \fB          IBV_QP_DEST_QPN, IBV_QP_RQ_PSN, \fR
 158      \fB          IBV_QP_MAX_DEST_RD_ATOMIC, IBV_QP_MIN_RNR_TIMER \fR
 159 RTS  \fB          IBV_QP_STATE, IBV_QP_SQ_PSN, IBV_QP_MAX_QP_RD_ATOMIC, \fR
 160      \fB          IBV_QP_RETRY_CNT, IBV_QP_RNR_RETRY, IBV_QP_TIMEOUT \fR
 161 .fi
 162 .SH "SEE ALSO"
 163 .BR ibv_create_qp (3),
 164 .BR ibv_destroy_qp (3),
 165 .BR ibv_query_qp (3),
 166 .BR ibv_create_ah (3)
 167 .SH "AUTHORS"
 168 .TP
 169 Dotan Barak <dotanb@mellanox.co.il>