IBV_QUERY_SRQ(3), IBV_MODIFY_SRQ(3)

NAME

ibv_query_srq, ibv_modify_srq - Shared receive queue (SRQ) の属性を取得・変更する。

SYNOPSIS

#include <infiniband/verbs.h>

int ibv_query_srq(struct ibv_srq *srq, struct ibv_srq_attr *srq_attr);

int ibv_modify_srq(struct ibv_srq *srq,
                   struct ibv_srq_attr *srq_attr,
                   int srq_attr_mask);

DESCRIPTION

ibv_query_srq() は SRQ srq は属性の情報を取得する。 結果は srq_attr で受け取る。

ibv_modify_srq() は SRQ srq の srq_attr_mask で指定した属性値を srq_attr から読み取り、その値に属性を変更する。

srq_attr_mask は IBV_SRQ_MAX_WR と IBV_SRQ_LIMIT の 2 つのマクロを論理和で指定する。

IBV_SRQ_MAX_WR

SRQ の max_wr と max_sge のパラメータを新しい値で変更する。 ただしこれを指定するには HCAが IBV_DEVICE_SRQ_RESIZE の機能をサポートしている必要がある。 サポートの有無は ibv_query_device() の取得できる device_cap_flags に IBV_DEVICE_SRQ_RESIZE のビットによって確認できる。

IBV_SRQ_LIMIT

SRQ Limit は、Receive WR の残量が srq_limit を下回った時に、非同期イベントの IBV_EVENT_SRQ_LIMIT_REACHED を発生させる。 このイベントはワンショットなので、1度発生した場合には IBV_SRQ_LIMIT を指定して再度 ibv_modify_srq を呼び出さないともう一度発生することはない。 また 0 を指定すると、(Receive WR の残量が srq_limit を下回らないので) 非同期イベントの IBV_EVENT_SRQ_LIMIT_REACHED は発生しない。
このような仕様なので、SRQ にはまず ibv_post_srq_recv() で Receive WR を積んでから、ibv_modify_srq を呼ぶ必要がある。
詳細は「InfiniBand の QP ステートの遷移を理解する」の 2.5 Send Queue Drain (SQD)、「まず InfiniBand Verbs プログラムを作成してみよう」の 8.1 Shared Receive Queue (SRQ) を使ってみる。を参照のこと。

RETURN VALUE

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

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

NOTES

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

SRQ は内部のステートがエラーとなることがある。 SRQ のステートを明示的に取得する方法はないが、非同期エラーの SRQ Catastrophic Error (IBV_EVENT_SRQ_ERR) が発生以降はエラーとなる。 エラーの SRQ は ibv_destroy_srq() 以外の API は、ibv_query_srq()、ibv_modify_srq() も含めて失敗する。 詳細は 「InfiniBand のエラーハンドリングのモデルを理解する」 3.1.3 SRQ Catastrophic Error (IBV_EVENT_SRQ_ERR) を参照のこと。

SEE ALSO

InfiniBand Verbs API Reference、ibv_query_device(3)、ibv_create_srq(3)、ibv_destroy_srq(3)

AUTHORS

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

コメント