contrib/ofed/libibverbs/man/verbs.7

   1 .\" -*- nroff -*-
   2 .\"
   3 .TH VERBS 7 2008-02-25 libibverbs "Libibverbs Programmer's Manual"
   4 .SH "NAME"
   5 verbs \- Infiniband verbs library
   6 .SH "SYNOPSIS"
   7 .nf
   8 .B #include <infiniband/verbs.h>
   9 .fi
  10 .SH "DESCRIPTION"
  11 This library is an implementation of the verbs based on the Infiniband specification volume 1.2 chapter 11. It handles the control path of creating, modifying, querying and destroying resources such as Protection Domains (PD), Completion Queues (CQ), Queue-Pairs (QP), Shared Receive Queues (SRQ), Address Handles (AH), Memory Regions (MR). It also handles sending and receiving data posted to QPs and SRQs, getting completions from CQs using polling and completions events.
  12
  13 The control path is implemented through system calls to the uverbs kernel module which further calls the low level HW driver. The data path is implemented through calls made to low level HW library which in most cases interacts directly with the HW providing kernel and network stack bypass (saving context/mode switches) along with zero copy and an asynchronous I/O model.
  14
  15
  16 Typically, under network and RDMA programming, there are operations which involve interaction with remote peers (such as address resolution and connection establishment) and remote entities (such as route resolution and joining a multicast group under IB), where a resource managed through IB verbs such as QP or AH would be eventually created or effected from this interaction. In such cases, applications whose addressing semantics is based on IP can use librdmacm (see rdma_cm(7)) which works in conjunction with libibverbs.
  17
  18 This library is thread safe library and verbs can be called from every thread in the process (the same resource can even be handled from different threads, for example: ibv_poll_cq can be called from more than one thread).
  19
  20 However, it is up to the user to stop working with a resource after it was destroyed (by the same thread or by any other thread), this may result a segmentation fault.
  21
  22 If fork (or any other system call that perform fork directly or indirectly) is being used, please see ibv_fork_init(3).
  23
  24 .LP
  25 The following shall be declared as functions and may also be defined
  26 as macros. Function prototypes shall be provided.
  27 .RS
  28 .nf
  29
  30 \fB
  31 .B Library functions
  32
  33 int ibv_fork_init(void);
  34
  35 .B Device functions
  36
  37 struct ibv_device **ibv_get_device_list(int *num_devices);
  38 void ibv_free_device_list(struct ibv_device **list);
  39 const char *ibv_get_device_name(struct ibv_device *device);
  40 uint64_t ibv_get_device_guid(struct ibv_device *device);
  41
  42 .B Context functions
  43
  44 struct ibv_context *ibv_open_device(struct ibv_device *device);
  45 int ibv_close_device(struct ibv_context *context);
  46
  47 .B Queries
  48
  49 int ibv_query_device(struct ibv_context *context,
  50                      struct ibv_device_attr *device_attr);
  51 int ibv_query_port(struct ibv_context *context, uint8_t port_num,
  52                    struct ibv_port_attr *port_attr);
  53 int ibv_query_pkey(struct ibv_context *context, uint8_t port_num,
  54                    int index, uint16_t *pkey);
  55 int ibv_query_gid(struct ibv_context *context, uint8_t port_num,
  56                   int index, union ibv_gid *gid);
  57
  58 .B Asynchronous events
  59
  60 int ibv_get_async_event(struct ibv_context *context,
  61                         struct ibv_async_event *event);
  62 void ibv_ack_async_event(struct ibv_async_event *event);
  63
  64 .B Protection Domains
  65
  66 struct ibv_pd *ibv_alloc_pd(struct ibv_context *context);
  67 int ibv_dealloc_pd(struct ibv_pd *pd);
  68
  69 .B Memory Regions
  70
  71 struct ibv_mr *ibv_reg_mr(struct ibv_pd *pd, void *addr,
  72                           size_t length, enum ibv_access_flags access);
  73 int ibv_dereg_mr(struct ibv_mr *mr);
  74
  75 .B Address Handles
  76
  77 struct ibv_ah *ibv_create_ah(struct ibv_pd *pd, struct ibv_ah_attr *attr);
  78 int ibv_init_ah_from_wc(struct ibv_context *context, uint8_t port_num,
  79                         struct ibv_wc *wc, struct ibv_grh *grh,
  80                         struct ibv_ah_attr *ah_attr);
  81 struct ibv_ah *ibv_create_ah_from_wc(struct ibv_pd *pd, struct ibv_wc *wc,
  82                                      struct ibv_grh *grh, uint8_t port_num);
  83 int ibv_destroy_ah(struct ibv_ah *ah);
  84
  85 .B Completion event channels
  86
  87 struct ibv_comp_channel *ibv_create_comp_channel(struct ibv_context *context);
  88 int ibv_destroy_comp_channel(struct ibv_comp_channel *channel);
  89
  90 .B Completion Queues Control
  91
  92 struct ibv_cq *ibv_create_cq(struct ibv_context *context, int cqe,
  93                              void *cq_context,
  94                              struct ibv_comp_channel *channel,
  95                              int comp_vector);
  96 int ibv_destroy_cq(struct ibv_cq *cq);
  97 int ibv_resize_cq(struct ibv_cq *cq, int cqe);
  98
  99 .B Reading Completions from CQ
 100
 101 int ibv_poll_cq(struct ibv_cq *cq, int num_entries, struct ibv_wc *wc);
 102
 103 .B Requesting / Managing CQ events
 104
 105 int ibv_req_notify_cq(struct ibv_cq *cq, int solicited_only);
 106 int ibv_get_cq_event(struct ibv_comp_channel *channel,
 107                      struct ibv_cq **cq, void **cq_context);
 108 void ibv_ack_cq_events(struct ibv_cq *cq, unsigned int nevents);
 109
 110 .B Shared Receive Queue control
 111
 112 struct ibv_srq *ibv_create_srq(struct ibv_pd *pd,
 113                                struct ibv_srq_init_attr *srq_init_attr);
 114 int ibv_destroy_srq(struct ibv_srq *srq);
 115 int ibv_modify_srq(struct ibv_srq *srq,
 116                    struct ibv_srq_attr *srq_attr,
 117                    enum ibv_srq_attr_mask srq_attr_mask);
 118 int ibv_query_srq(struct ibv_srq *srq, struct ibv_srq_attr *srq_attr);
 119
 120 .B eXtended Reliable Connection control
 121
 122 struct ibv_xrc_domain *ibv_open_xrc_domain(struct ibv_context *context,
 123                                            int fd, int oflag);
 124 int ibv_close_xrc_domain(struct ibv_xrc_domain *d);
 125 struct ibv_srq *ibv_create_xrc_srq(struct ibv_pd *pd,
 126                                    struct ibv_xrc_domain *xrc_domain,
 127                                    struct ibv_cq *xrc_cq,
 128                                    struct ibv_srq_init_attr *srq_init_attr);
 129 int ibv_create_xrc_rcv_qp(struct ibv_qp_init_attr *init_attr,
 130                           uint32_t *xrc_rcv_qpn);
 131 int ibv_modify_xrc_rcv_qp(struct ibv_xrc_domain *xrc_domain, uint32_t xrc_qp_num,
 132                           struct ibv_qp_attr *attr, int attr_mask);
 133 int ibv_query_xrc_rcv_qp(struct ibv_xrc_domain *xrc_domain, uint32_t xrc_qp_num,
 134                          struct ibv_qp_attr *attr, int attr_mask,
 135                          struct ibv_qp_init_attr *init_attr);
 136 int ibv_reg_xrc_rcv_qp(struct ibv_xrc_domain *xrc_domain, uint32_t xrc_qp_num);
 137 int ibv_unreg_xrc_rcv_qp(struct ibv_xrc_domain *xrc_domain, uint32_t xrc_qp_num);
 138
 139 .B Queue Pair control
 140
 141 struct ibv_qp *ibv_create_qp(struct ibv_pd *pd,
 142                              struct ibv_qp_init_attr *qp_init_attr);
 143 int ibv_destroy_qp(struct ibv_qp *qp);
 144 int ibv_modify_qp(struct ibv_qp *qp, struct ibv_qp_attr *attr,
 145                   enum ibv_qp_attr_mask attr_mask);
 146 int ibv_query_qp(struct ibv_qp *qp, struct ibv_qp_attr *attr,
 147                  enum ibv_qp_attr_mask attr_mask,
 148                  struct ibv_qp_init_attr *init_attr);
 149
 150 .B posting Work Requests to QPs/SRQs
 151 int ibv_post_send(struct ibv_qp *qp, struct ibv_send_wr *wr,
 152                   struct ibv_send_wr **bad_wr);
 153 int ibv_post_recv(struct ibv_qp *qp, struct ibv_recv_wr *wr,
 154                   struct ibv_recv_wr **bad_wr);
 155 int ibv_post_srq_recv(struct ibv_srq *srq,
 156                       struct ibv_recv_wr *recv_wr,
 157                       struct ibv_recv_wr **bad_recv_wr);
 158
 159 .B Multicast group
 160
 161 int ibv_attach_mcast(struct ibv_qp *qp, union ibv_gid *gid, uint16_t lid);
 162 int ibv_detach_mcast(struct ibv_qp *qp, union ibv_gid *gid, uint16_t lid);
 163
 164 .B General functions
 165
 166 int ibv_rate_to_mult(enum ibv_rate rate);
 167 enum ibv_rate mult_to_ibv_rate(int mult);
 168 \fP
 169 .SH "SEE ALSO"
 170 .LP
 171 \fIibv_fork_init\fP(),
 172 \fIibv_get_device_list\fP(),
 173 \fIibv_free_device_list\fP(),
 174 \fIibv_get_device_name\fP(),
 175 \fIibv_get_device_guid\fP(),
 176 \fIibv_open_device\fP(),
 177 \fIibv_close_device\fP(),
 178 \fIibv_query_device\fP(),
 179 \fIibv_query_port\fP(),
 180 \fIibv_query_pkey\fP(),
 181 \fIibv_query_gid\fP(),
 182 \fIibv_get_async_event\fP(),
 183 \fIibv_ack_async_event\fP(),
 184 \fIibv_alloc_pd\fP(),
 185 \fIibv_dealloc_pd\fP(),
 186 \fIibv_reg_mr\fP(),
 187 \fIibv_dereg_mr\fP(),
 188 \fIibv_create_ah\fP(),
 189 \fIibv_init_ah_from_wc\fP(),
 190 \fIibv_create_ah_from_wc\fP(),
 191 \fIibv_destroy_ah\fP(),
 192 \fIibv_create_comp_channel\fP(),
 193 \fIibv_destroy_comp_channel\fP(),
 194 \fIibv_create_cq\fP(),
 195 \fIibv_destroy_cq\fP(),
 196 \fIibv_resize_cq\fP(),
 197 \fIibv_poll_cq\fP(),
 198 \fIibv_req_notify_cq\fP(),
 199 \fIibv_get_cq_event\fP(),
 200 \fIibv_ack_cq_events\fP(),
 201 \fIibv_create_srq\fP(),
 202 \fIibv_destroy_srq\fP(),
 203 \fIibv_modify_srq\fP(),
 204 \fIibv_query_srq\fP(),
 205 \fIibv_open_xrc_domain\fP(),
 206 \fIibv_close_xrc_domain\fP(),
 207 \fIibv_create_xrc_srq\fP(),
 208 \fIibv_create_xrc_rcv_qp\fP(),
 209 \fIibv_modify_xrc_rcv_qp\fP(),
 210 \fIibv_query_xrc_rcv_qp\fP(),
 211 \fIibv_reg_xrc_rcv_qp\fP(),
 212 \fIibv_unreg_xrc_rcv_qp\fP(),
 213 \fIibv_post_srq_recv\fP(),
 214 \fIibv_create_qp\fP(),
 215 \fIibv_destroy_qp\fP(),
 216 \fIibv_modify_qp\fP(),
 217 \fIibv_query_qp\fP(),
 218 \fIibv_post_send\fP(),
 219 \fIibv_post_recv\fP(),
 220 \fIibv_attach_mcast\fP(),
 221 \fIibv_detach_mcast\fP(),
 222 \fIibv_rate_to_mult\fP(),
 223 \fImult_to_ibv_rate\fP()
 224 .SH "AUTHORS"
 225 .TP
 226 Dotan Barak <dotanb@mellanox.co.il>
 227 .TP
 228 Or Gerlitz <ogerlitz@voltaire.com>