ibv_qp_attach_comp_cntr(3) Libibverbs Programmer’s Manual ibv_qp_attach_comp_cntr(3)

ibv_qp_attach_comp_cntr - Attach a completion counter to a QP

#include <infiniband/verbs.h>
int ibv_qp_attach_comp_cntr(struct ibv_qp *qp,
                            struct ibv_comp_cntr *comp_cntr,
                            struct ibv_qp_attach_comp_cntr_attr *attr);

ibv_qp_attach_comp_cntr() attaches the completion counter comp_cntr to the queue pair qp. The attr argument specifies which operation types should update the counter.

The QP must be in IBV_QPS_RESET or IBV_QPS_INIT state when attaching a completion counter. Attempting to attach a counter to a QP in any other state will fail with EINVAL.

The completion counter starts collecting values for the specified QP once attached. Attaching the same completion counter to multiple QPs will accumulate values from all attached QPs into the same counter.

The op_mask field controls which operation completions are counted. Local operations (IBV_QP_ATTACH_COMP_CNTR_OP_SEND, IBV_QP_ATTACH_COMP_CNTR_OP_RECV, IBV_QP_ATTACH_COMP_CNTR_OP_RDMA_READ, IBV_QP_ATTACH_COMP_CNTR_OP_RDMA_WRITE) count completions initiated by the local QP. Remote operations (IBV_QP_ATTACH_COMP_CNTR_OP_REMOTE_RDMA_READ, IBV_QP_ATTACH_COMP_CNTR_OP_REMOTE_RDMA_WRITE) count completions of incoming RDMA operations initiated by the remote side. Supported op_mask values may vary by device and can be queried using ibv_query_comp_cntr_caps(3); unsupported values will result in an ENOTSUP error.

Multiple completion counters can be attached to the same QP, provided their op_mask values do not overlap. Each QP and operation type pair can be associated with at most one completion counter. Attempting to attach a counter with an op_mask that conflicts with an already attached counter will fail.

There is no explicit detach operation. A completion counter is implicitly detached when the QP it is attached to is destroyed. A completion counter cannot be destroyed while it is still attached to any QP; the QP must be destroyed first.

The queue pair to attach the completion counter to.
The completion counter to attach, previously created with ibv_create_comp_cntr().
Attach attributes specifying which operation types update the counter.

enum ibv_qp_attach_comp_cntr_op {
    IBV_QP_ATTACH_COMP_CNTR_OP_SEND                    = 1 << 0,
    IBV_QP_ATTACH_COMP_CNTR_OP_RECV                    = 1 << 1,
    IBV_QP_ATTACH_COMP_CNTR_OP_RDMA_READ               = 1 << 2,
    IBV_QP_ATTACH_COMP_CNTR_OP_REMOTE_RDMA_READ        = 1 << 3,
    IBV_QP_ATTACH_COMP_CNTR_OP_RDMA_WRITE              = 1 << 4,
    IBV_QP_ATTACH_COMP_CNTR_OP_REMOTE_RDMA_WRITE       = 1 << 5,
};
struct ibv_qp_attach_comp_cntr_attr {
    uint32_t comp_mask;
    uint32_t op_mask;
};
Bitmask specifying what fields in the structure are valid. Used for extensibility, should be set to 0.
Bitmask of ibv_qp_attach_comp_cntr_op values specifying which operation types should update the counter.

ibv_qp_attach_comp_cntr() returns 0 on success, or the value of errno on failure (which indicates the failure reason).

Invalid argument(s) passed.
Requested operation is not supported on this device.
The op_mask overlaps with a completion counter already attached to this QP.

ibv_create_comp_cntr(3), ibv_query_comp_cntr_caps(3), ibv_create_qp(3)

Michael Margolin mrgolin@amazon.com

2026-02-09 libibverbs