IBV_POLL_CQ(3)

作成日:2014.05.10

NAME

ibv_poll_cq - Completion queue (CQ) から work completion を取り出す

SYNOPSIS

#include <infiniband/verbs.h>

int ibv_poll_cq(struct ibv_cq *cq, int num_entries, struct ibv_wc *wc);

DESCRIPTION

ibv_poll_cq()cq で指定された CQ から work completion(WC) の形で取り出し wc の指す領域へ格納する。 取り出した WC は CQ から削除する。 CQ に WC がなければ待機せずにすぐに復帰する。

cqibv_create_cq() で作成した CQ を指定する。

num_entrieswc の配列の要素数を指定する。 これが取り出し可能な最大 WC 数となる。

wc は CQ から取り出した WC を格納する領域を配列で指定する。

Table 1: struct ibv_wc 構造体
メンバ名名前説明
wr_iduint64_tID of the completed Work Request(WR) この WC の元になった Send Work Request または Receive Work Request の wr_id に設定された値をコピー。
statusenum ibv_wc_statusStatus of operation WC のステータス。IBV_WC_SUCCESS は成功で、それ以外には何らかの問題が生じている。 詳細は 「InfiniBand のエラーハンドリングのモデルを理解する」を参照のこと。
opcodeenum ibv_wc_opcodeOperation type WC を生み出す元になった Work Request のオペコードを格納する。
マクロWR を投入する操作オペコード
IBV_WC_SENDibv_post_sendIBV_WR_SEND、IBV_WR_SEND_WITH_IMM
IBV_WC_RDMA_WRITEibv_post_sendIBV_WR_RDMA_WRITE、IBV_WR_RDMA_WRITE_WITH_IMM
IBV_WC_RDMA_READibv_post_sendIBV_WR_READ
IBV_WC_COMP_SWAPibv_post_sendIBV_WR_ATOMIC_CMP_AND_SWP
IBV_WC_FETCH_ADDibv_post_sendIBV_WR_ATOMIC_FETCH_AND_ADD
IBV_WC_BIND_MW  
IBV_WC_RECVibv_post_recv、ibv_post_srq_recv 
IBV_WC_RECV_RDMA_WITH_IMMibv_post_recv、ibv_post_srq_recv 

ただし statusIBV_WC_SUCCESS の場合のみ有効。
vendor_erruint32_tVendor error syndrome HCA のベンダー固有情報
byte_lenuint32_tNumber of bytes transferred Receive Work Request に対する完了の場合、メッセージの転送サイズがバイト数で格納される。 つまり SEND オペレーション(with Immediate を含む) と RDMA WRITE with Immediate オペレーションを受信した場合、受信データのバイト数が格納される。 opcodeIBV_WC_RECVIBV_WC_RECV_RDMA_WITH_IMM になる。

上記の条件を満たしても、statusIBV_WC_SUCCESS 以外では無効である。
また Send Work Request に対する完了の場合も、無効となりどのような値が入っているか保証できない(0 を設定する HCA が多い)。
imm_datauint32_tImmediate data SEND with Immediate オペレーションまたは RDMA WRITE with Immediate オペレーションを受信した場合、imm_data には転送された Immediate Data が格納される。格納された値はネットワークバイトオーダーになっている。

このメンバ変数は statusIBV_WC_SUCCESS が有効で、wc_flagsIBV_WC_WITH_IMM のビットが立っている場合に飲み有効である。 opcodeIBV_WC_RECVIBV_WC_RECV_RDMA_WITH_IMM になる。
qp_numuint32_tLocal QP Number 操作対象となった QP 番号。 CQ は複数の QP と関連付けることができるので、この WC がどの QP で生成されたものかを判別するのに利用可能。 「InfiniBand プログラムに必要な基本的な概念」も参照のこと。
src_qpuint32_tSource QP Number UD QP の IBV_WC_RECV の場合、この属性に送信元 QP 番号が入る。 UD QP 以外では無効。

また statusIBV_WC_SUCCESS の場合のみ有効。
wc_flagsintFlags IBV_WC_RECV の場合、wc_flags は以下のマクロの論理和が入っている。
IBV_WC_GRH
UD QP において受信バッファの先頭 40 バイトに Global Routing Header(GRH) が存在することを示す。 これは送信側の QP において ibv_create_ah()struct ibv_ah_attris_global を 0 以外に指定して作成した AH を使って送信を行うと、受信側で GRH が付くことになる。
なおこのフラグが立っていない場合でも受信バッファのは先頭 40 バイトに未使用領域が存在する。
IBV_WC_WITH_IMM
imm_data が有効なことを示す。
これは送信側の QP において SEND with Immediate オペレーションまたは RDMA WRITE with Immediate オペレーションを使ったことを意味する。
ただし statusIBV_WC_SUCCESS の場合のみ有効。
pkey_indexuint16_tP_Key index QP1 を使う MAD 通信は Parition Key Table のいずれかのエントリに合致すれば受信可能となる。 pkey_index は受信に使われた Parition Key Table のインデックス番号を返す。

ただし statusIBV_WC_SUCCESS の場合のみ有効。
sliduint16_tSource LID IBV_WC_RECV の場合、送信元の LID が入っている。 src_qp は UD QP でのみ有効であったが、slid は全てのサービスタイプで有効。
ただし statusIBV_WC_SUCCESS の場合のみ有効。
sluint8_tService Level  
dlid_path_bitsuint8_tDLID path bits  

statusIBV_WC_SUCCESS 以外の場合、wr_idstatusqp_numvendor_err のみが有効である。 struct ibv_wc のそれ以外のメンバ変数は不正な値が指定されているかもしれない。

RETURN VALUE

ibv_poll_cq() が 0 以上の値を返す場合、取り出しに成功し wc に格納できた WC 数を返す。 0 の場合は WC を取り出せなかったことを返す。 負数の場合は失敗したことを示す。

NOTES

取り出した完了は CQ からは削除され、元に戻すことはできない。

設定された CQE 数以上の完了を CQに積もうとした場合、CQ Overflow が発生する。 CQ は外からは観測できないが内部的にエラーとなり、保持していた完了は ibv_poll_cq() で取り出せなくなり、ibv_destroy_cq() 以外の操作もできなくなる。

CQ Overflow が生じると非同期イベントの IBV_EVENT_CQ_ERR が発生する。 また連鎖的に CQ に関連付けられている全ての QP もエラーとなり非同期イベントの IBV_EVENT_QP_ERR が発生する。

SEE ALSO

InfiniBand Verbs API Referenceibv_post_send(3)ibv_post_recv(3)

AUTHORS

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

コメント

トラックバック   [Trackback URL: http://www.nminoru.jp/cgi-bin/tb.cgi/network__infiniband__ibv_poll_cq]
コメントを書き込む

TOP    掲示板    戻る
Written by NAKAMURA Minoru, Email: nminoru atmark nminoru dot jp, Twitter:@nminoru_jp