NAME
ibv_create_cq, ibv_destroy_cq - Completion Queue (CQ) を作成・破壊する。
SYNOPSIS
#include <infiniband/verbs.h> struct ibv_cq *ibv_create_cq(struct ibv_context *context, int cqe, void *cq_context, struct ibv_comp_channel *channel, int comp_vector); int ibv_destroy_cq(struct ibv_cq *cq);
DESCRIPTION
ibv_create_cq()
は RDMA デバイス context 内に、最小でも cqe 数以上の CQE を持った Completion Channel(CQ) を作成する。
context は ibv_open_device() でオープンした RDMA デバイスを指定する。
cqe は ibv_query_device() で取得できる RDMA デバイス属性のうち max_cqe 以下の値を指定する。 cqe を 0 に指定しても動作するかは仕様に規定されていない。
cq_context にはプログラムが好きなポインタを指定することができる。
これは生成された CQ を示す struct ibv_cq
構造体の cq_context にコピーされており、プログラムが自由にアクセスできる。
channel には ibv_create_comp_channel() で作成した completion channel を指定する。 Completion channel は 「InfiniBand プログラムに必要な基本的な概念」、「まず InfiniBand Verbs プログラムを作成してみよう」 を参照のこと。 channel に NULL を指定した場合には、completion channel を使わないことを意味する。
comp_vector には completion vector 番号を指定する。 Completion vector は 「InfiniBand プログラムに必要な基本的な概念」 を参照のこと。 HCA が利用可能な completion vector の最大数は context->num_comp_vectors で知ることができる。 comp_vector には context->num_comp_vectors 未満の値を指定すること(context->num_comp_vectors は 1 以上であることが保証されているので、comp_vector が 0 にすることは常に許される)。
ibv_destroy_cq()
は cq で示される CQ を破壊する。
RETURN VALUE
ibv_create_cq()
は成功した場合、CQ へのポインタを返す。
失敗した場合は NULL を返す。
ibv_destroy_cq()
は成功した場合、0 を返す。
失敗した場合は、エラーの原因を示す値(errno と同じ)を返す。
NOTES
ibv_create_cq
は cqe で指定された CQE 数以上の CQ を作成するかもしれない。
生成された CQ の cqe には本当の CQE 数が格納されている。
ibv_destroy_cq
は cq に関連付けられたオブジェクトを解放せずに呼び出すと失敗することがある。
また ibv_get_async_event() で取り出した非同期イベントが CQ に関連付けられている場合、その CQ を ibv_destroy_cq
すると、その非同期イベントが ibv_ack_async_event() で承認されるまで待機させられる。
この待機には時間の指定がなく、またシグナルを受信した場合にも復帰しない。
SEE ALSO
InfiniBand Verbs API Reference、ibv_resize_cq(3)、ibv_req_notify_cq(3)、ibv_ack_async_event(3)、ibv_create_qp(3)
AUTHORS
原文 Dotan Barak <dotanba@gmail.com>
原文にない加筆がある。