IBV_QUERY_QP(3), IBV_MODIFY

NAME

ibv_query_qp, ibv_modify_qp - Queue Pair(QP) の属性情報を取得・変更する。

SYNOPSIS

#include <infiniband/verbs.h>

int ibv_query_qp(struct ibv_qp *qp, struct ibv_qp_attr *attr,
                 int attr_mask,
                 struct ibv_qp_init_attr *init_attr);

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

DESCRIPTION

ibv_query_qp() は QP qp は属性の情報を取得する。取得する属性は attr_mask で指定する。結果は attr と init_attr で受け取る。

attr_mask は enum ibv_qp_attr_mask 列挙子の論理和で指定する。

init_attr は ibv_create_qp() の引数 qp_init_attr で設定した値がコピーされる(ただし QP ケーパビリティは更新後の値が返ってくる)。

ibv_modify_qp() は QP qp の attr_mask で指定した属性値を attr から読み取り、その値に属性を変更する。

attr_mask は enum ibv_qp_attr_mask 列挙子の論理和で指定する。ただし qp のサービスタイプと現在のステートによって指定できる属性が変わる。「InfiniBand の QP ステートの遷移を理解する」の 3. QP ステートの遷移を参照のこと。

メンバ名型 attr_mask 制限説明

ibv_query_qp ibv_modfiy_qp

qp_state enum ibv_qp_state IBV_QP_STATE 現在の QP ステート。次に遷移する QP ステート。

cur_qp_state enum ibv_qp_state IBV_QP_CUR_STATE *1 無視される。想定遷移元 QP ステート。

port_num uint8_t IBV_QP_PORT *2 Primary port number。QP が接続する物理ポート番号 (1からはじまる)

qkey uint32_t IBV_QP_QKEY UD Q_Key。Q_Key はここを参照のこと。

pkey_index uint16_t IBV_QP_PKEY_INDEX UD Primary P_Key Index。詳細はここを参照のこと。

sq_psn uint32_t IBV_QP_SQ_PSN *3 Send Queue(SQ) の PSN。

rq_psn uint32_t IBV_QP_RQ_PSN RC/UC *3 Receive Queue(RQ) の PSN。

path_mtu enum ibv_mtu IBV_QP_PATH_MTU RC/UC Path MTU。この値はポートに設定された Active MTU 以下である必要がある。

dest_qp_num uint32_t IBV_QP_DEST_QPN RC/UC Destination QP 番号。

qp_access_flags

int

IBV_QP_ACCESS_FLAGS

RC/UC *4

アクセス権限。この QP が受信側として RDMA 系オペレーションを受信する場合に、以下のマクロの論理和で指定する。

意味	マクロ
RDMA WRITE オペレーション(with Immediate を含む)	IBV_ACCESS_REMOTE_WRITE
RDMA READ オペレーション	IBV_ACCESS_REMOTE_READ
Compare and Swap オペレーション、Fetch and Add オペレーション	IBV_ACCESS_REMOTE_ATOMIC

cap struct ibv_qp_cap IBV_QP_CAP RC/UC *5 QP ケーパビリティ。ibv_create_qpで指定した値が取得できる。 HCA が QP Resizing に対応していれば変更できる。

ah_attr struct ibv_ah_attr IBV_QP_AV RC/UC Primary path の送信先を示す Address Vector(AH)。AV は Address Handle(AH) とほぼ同義である。struct ibv_ah_attr 構造体の詳細は ibv_create_ah() を参照のこと。

max_rd_atomic uint8_t IBV_QP_MAX_QP_RD_ATOMIC RC 送信側の RDMA READ と Atomic operations の最大同時発行数。この値はリモートの QP の max_dest_rd_atomic 以下とする必要がある。またibv_query_device() の max_qp_rd_atom 以下の値を指定する必要がある。「InfiniBand の再送制御を理解する」 3.4 RDMA READ と ATOMIC Operations の同時実行数も参照のこと。

max_dest_rd_atomic uint8_t IBV_QP_MAX_DEST_RD_ATOMIC RC 受信側の RDMA READ と Atomic operations の最大同時受信数。ibv_query_device() の max_qp_init_rd_atom 以下の値を指定する必要がある。「InfiniBand の再送制御を理解する」 3.4 RDMA READ と ATOMIC Operations の同時実行数も参照のこと。

min_rnr_timer uint8_t IBV_QP_MIN_RNR_TIMER RC Minimum RNR NAK Timer を 0～31 で指定。min_rnr_timer は受信側に設定するが、この値を使うのはリモートの送信側である。詳細は「InfiniBand の再送制御を理解する」の 2.2 RNR NAK Retryを参照のこと。

timeout uint8_t IBV_QP_TIMEOUT RC Local ack timeout を 0～31 で指定。0 はタイムアウト時間が無限を意味する。詳細は「InfiniBand の再送制御を理解する」の 2.1 Local ACK Timeoutを参照のこと。

retry_cnt uint8_t IBV_QP_RETRY_CNT RC Retry count を 0～7 で指定。詳細は「InfiniBand の再送制御を理解する」の 2.1 Local ACK Timeoutを参照のこと。

rnr_retry uint8_t IBV_QP_RNR_RETRY RC RNR Retry を 0～7 で指定。7 を指定すると無限にリトライする。詳細は「InfiniBand の再送制御を理解する」の 2.2 RNR NAK Retryを参照のこと。

en_sqd_async_notify uint8_t IBV_QP_EN_SQD_ASYNC_NOTIFY RTR → SQD 遷移時に設定し、SQD になった後、送信中の Send WR が全て完了したタイミングで非同期イベント Send Queue Drained (IBV_EVENT_SQ_DRAINED) をあげるかどうか。非 0 なら非同期イベントを送信し、0 なら送信しない。詳細は「InfiniBand の QP ステートの遷移を理解する」の 2.5 Send Queue Drain (SQD)、「まず InfiniBand Verbs プログラムを作成してみよう」の 8.1 Shared Receive Queue (SRQ) を使ってみる。を参照のこと。

sq_draining uint8_t 無指定 (SQD ステートに遷移後)送信中の Send WR を残っている場合は 1、完了した場合は 0。詳細は「InfiniBand の QP ステートの遷移を理解する」の 2.5 Send Queue Drain (SQD)を参照のこと。設定はできない

path_mig_state enum ibv_mig_state IBV_QP_PATH_MIG_STATE *6 Path Migration State (valid if HCA supports APM)。

alt_ah_attr struct ibv_ah_attr IBV_QP_ALT_PATH *6

alt_port_num uint8_t IBV_QP_ALT_PATH *6

alt_pkey_index uint16_t IBV_QP_ALT_PATH *6

alt_timeout uint8_t IBV_QP_ALT_PATH *6

*1: IBV_QP_CUR_STATE は ibv_query_device() の取得できる device_cap_flags に IBV_DEVICE_CURR_QP_STATE_MOD のビットが立っている場合のみ実行できる。
*2: IBV_QP_PORT は ibv_query_device() の取得できる device_cap_flags に IBV_DEVICE_CHANGE_PHY_PORT のビットが立っている場合は、SQD → SQD の遷移でも変更できる。
*3: sq_psn は UD QP でも ibv_modify_qp で設定できるが、意味がない。rq_psn は UD QP でも ibv_query_qp で取得できるが、RQ PSN の値であるとは保証できない。
*4: qp_access_flags には IBV_ACCESS_LOCAL_WRITE を指定しなくてもよい。
*5: IBV_QP_CAP は ibv_query_device() の取得できる device_cap_flags に IBV_DEVICE_RESIZE_MAX_WR のビットが立っている場合のみ実行できる。
*6: IBV_QP_PATH_MIG_STATE は ibv_query_device() の取得できる device_cap_flags に IBV_DEVICE_AUTO_PATH_MIG のビットが立っている場合のみ実行できる。

RETURN VALUE

ibv_query_qp() は成功した場合、0 を返す。失敗した場合は、エラーの原因を示す値(errno と同じ)を返す。

ibv_modify_qp() は成功した場合、0 を返す。失敗した場合は、エラーの原因を示す値(errno と同じ)を返す。

NOTES

ibv_query_qp() で取得する属性は attr_mask で指定するが、HCA によっては attr_mask を無視して全ての属性情報を取得するものもある。 Mellanox ConnectXN はそれにあたる。

ibv_query_qp() を複数回呼び出した場合は、qp_state、sq_psn、rq_psn、path_mig_state、sq_draining、ah_attr は値が変わる可能性がある。その他の属性は ibv_modify_qp() など API で設定した値が取り出す。

ibv_modify_qp() は、無効な attr_mask を指定した場合は、全ての属性を変更しない。

AUTHORS

原文 Dotan Barak <dotanba@gmail.com>
原文にない加筆がある。

コメントを書き込む

TOP

掲示板

戻る

Written by NAKAMURA Minoru, Email: nminoru atmark nminoru dot jp, Twitter:@nminoru_jp

IBV_QUERY_QP(3), IBV_MODIFY_QP(3)