IBV_POLL_CQ(3)

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 がなければ待機せずにすぐに復帰する。

cq は ibv_create_cq() で作成した CQ を指定する。

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

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

メンバ名型名前説明

wr_id uint64_t ID of the completed Work Request(WR) この WC の元になった Send Work Request または Receive Work Request の wr_id に設定された値をコピー。

status enum ibv_wc_status Status of operation WC のステータス。IBV_WC_SUCCESS は成功で、それ以外には何らかの問題が生じている。詳細は「InfiniBand のエラーハンドリングのモデルを理解する」を参照のこと。

opcode

enum ibv_wc_opcode

Operation type

WC を生み出す元になった Work Request のオペコードを格納する。

マクロ	WR を投入する操作	オペコード
IBV_WC_SEND	ibv_post_send	IBV_WR_SEND、IBV_WR_SEND_WITH_IMM
IBV_WC_RDMA_WRITE	ibv_post_send	IBV_WR_RDMA_WRITE、IBV_WR_RDMA_WRITE_WITH_IMM
IBV_WC_RDMA_READ	ibv_post_send	IBV_WR_READ
IBV_WC_COMP_SWAP	ibv_post_send	IBV_WR_ATOMIC_CMP_AND_SWP
IBV_WC_FETCH_ADD	ibv_post_send	IBV_WR_ATOMIC_FETCH_AND_ADD
IBV_WC_BIND_MW
IBV_WC_RECV	ibv_post_recv、ibv_post_srq_recv
IBV_WC_RECV_RDMA_WITH_IMM	ibv_post_recv、ibv_post_srq_recv

ただし status が IBV_WC_SUCCESS の場合のみ有効。

vendor_err uint32_t Vendor error syndrome HCA のベンダー固有情報

byte_len uint32_t Number of bytes transferred Receive Work Request に対する完了の場合、メッセージの転送サイズがバイト数で格納される。つまり SEND オペレーション(with Immediate を含む) と RDMA WRITE with Immediate オペレーションを受信した場合、受信データのバイト数が格納される。 opcode は IBV_WC_RECV か IBV_WC_RECV_RDMA_WITH_IMM になる。

上記の条件を満たしても、status が IBV_WC_SUCCESS 以外では無効である。
また Send Work Request に対する完了の場合も、無効となりどのような値が入っているか保証できない(0 を設定する HCA が多い)。

imm_data uint32_t Immediate data SEND with Immediate オペレーションまたは RDMA WRITE with Immediate オペレーションを受信した場合、imm_data には転送された Immediate Data が格納される。格納された値はネットワークバイトオーダーになっている。

このメンバ変数は status が IBV_WC_SUCCESS が有効で、wc_flags に IBV_WC_WITH_IMM のビットが立っている場合に飲み有効である。 opcode は IBV_WC_RECV か IBV_WC_RECV_RDMA_WITH_IMM になる。

qp_num uint32_t Local QP Number 操作対象となった QP 番号。 CQ は複数の QP と関連付けることができるので、この WC がどの QP で生成されたものかを判別するのに利用可能。「InfiniBand プログラムに必要な基本的な概念」も参照のこと。

src_qp uint32_t Source QP Number UD QP の IBV_WC_RECV の場合、この属性に送信元 QP 番号が入る。 UD QP 以外では無効。

また status が IBV_WC_SUCCESS の場合のみ有効。

wc_flags

int

Flags

IBV_WC_RECV の場合、wc_flags は以下のマクロの論理和が入っている。

IBV_WC_GRH: UD QP において受信バッファの先頭 40 バイトに Global Routing Header(GRH) が存在することを示す。これは送信側の QP において ibv_create_ah() で struct ibv_ah_attr の is_global を 0 以外に指定して作成した AH を使って送信を行うと、受信側で GRH が付くことになる。
なおこのフラグが立っていない場合でも受信バッファのは先頭 40 バイトに未使用領域が存在する。
IBV_WC_WITH_IMM: imm_data が有効なことを示す。
これは送信側の QP において SEND with Immediate オペレーションまたは RDMA WRITE with Immediate オペレーションを使ったことを意味する。

ただし status が IBV_WC_SUCCESS の場合のみ有効。

pkey_index uint16_t P_Key index QP1 を使う MAD 通信は Parition Key Table のいずれかのエントリに合致すれば受信可能となる。 pkey_index は受信に使われた Parition Key Table のインデックス番号を返す。

ただし status が IBV_WC_SUCCESS の場合のみ有効。

slid uint16_t Source LID IBV_WC_RECV の場合、送信元の LID が入っている。 src_qp は UD QP でのみ有効であったが、slid は全てのサービスタイプで有効。
ただし status が IBV_WC_SUCCESS の場合のみ有効。

sl uint8_t Service Level

dlid_path_bits uint8_t DLID path bits

status が IBV_WC_SUCCESS 以外の場合、wr_id、status、qp_num、vendor_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 が発生する。

AUTHORS

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

コメントを書き込む