int ibv_query_pkey(struct ibv_context *context, uint8_t port_num,
                   int index, uint16_t *pkey)

Description

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.

Parameters

Return Values

Examples

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;
}

FAQs

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.

Written by: Dotan Barak on July 27, 2012.on February 17, 2015.