Skip to content


0.00 avg. rating (0% score) - 0 votes
int ibv_query_pkey(struct ibv_context *context, uint8_t port_num,
                   int index, uint16_t *pkey)


ibv_query_pkey() returns the value of an index in The P_Key table of an RDMA device port's.

The content of the P_Key table is valid only when the port_attr.state is either IBV_PORT_ARMED or IBV_PORT_ACTIVE. For other states of the port, the value of the partition table is implementation dependent.

The entity that configures this table is the SM, thus ibv_query_pkey() is relevant only for InfiniBand.


Name Direction Description
context in RDMA device context that was returned from ibv_open_device()
port_num in Port number to query, values can be [1..dev_cap.phys_port_cnt]
index in Requested P_Key index, values can be [0..port_attr.pkey_tbl_len-1]
pkey out P_Key table entry value

Return Values

Value Description
0 On success
-1 On failure, errno indicates the failure reason:

EMFILE Too many files are opened by this process


Query port 1 for the P_Key table entry value in index 2:

uint16_t pkey;
rc = ibv_query_pkey(ctx, 1, 2, &pkey);
if (rc) {
	fprintf(stderr, "Error, failed to query P_Key index %d of port %d in device '%s'\n",
		2, 1, ibv_get_device_name(ctx->device));
	return -1;


Why is P_Key good for anyway?

P_Key allows one to create virtual network over a physical network (just like VLANs in Ethernet).

Every P_Key has 16 bits and its value is combined from two parts:

  • 1 higher bit: define the membership level:
    • 1: full membership
    • 0: limited membership
  • 15 lower bits: define the P_Key key value

The rule for using it is very simple: every QP is associated with a P_Key.

QP X, which is associated with P_Key value PX, can communicate with QP Y, which is associated with P_Key value PY, only if both of the following conditions are met:

  • PX.membership == 1 || PY.membership == 1
  • PX.key == PY.key

This means that if both of PX and PY has limited membership they cannot communicate, even if they key value is equal.

I'm using iWARP/IBoE, will I use this verb?

No. This verb is relevant only for InfiniBand.

Calling every time to ibv_query_pkey() when I need a P_Key index value takes time, can I cache this value?

Actually, yes. The P_Key table is configured by the SM and the SM can change it, but most of the time it isn't. If you cache the value of the P_Key table, in case of the event IBV_EVENT_PKEY_CHANGE you should flush those values.

Share Our Posts

Share this post through social bookmarks.

  • Delicious
  • Digg
  • Newsvine
  • RSS
  • StumbleUpon
  • Technorati


Tell us what do you think.

There are no comments on this entry.

Add a Comment

Fill in the form and submit.

Time limit is exhausted. Please reload CAPTCHA.