1219820Sjeffcommit ebc306b0ad2a8a873a195b26ebafe704da001981 2219820SjeffAuthor: Dotan Barak <dotanb@dev.mellanox.co.il> 3219820SjeffDate: Sun Feb 3 17:58:53 2008 +0200 4219820Sjeff 5219820Sjeff libibverbs: Added the man page verbs.7 6219820Sjeff 7219820Sjeff Added the man page verbs.7 which is an introduction to libibverbs man pages. 8219820Sjeff 9219820Sjeff Signed-off-by: Dotan Barak <dotanb@dev.mellanox.co.il> 10219820Sjeff Signed-off-by: Or Gerlitz <ogerlitz@voltaire.com> 11219820Sjeff 12219820SjeffIndex: libibverbs/Makefile.am 13219820Sjeff=================================================================== 14219820Sjeff--- libibverbs.orig/Makefile.am 2010-06-07 18:38:19.088451000 +0300 15219820Sjeff+++ libibverbs/Makefile.am 2010-06-08 10:58:10.061113000 +0300 16219820Sjeff@@ -53,7 +53,7 @@ man_MANS = man/ibv_asyncwatch.1 man/ibv_ 17219820Sjeff man/ibv_post_srq_recv.3 man/ibv_query_device.3 man/ibv_query_gid.3 \ 18219820Sjeff man/ibv_query_pkey.3 man/ibv_query_port.3 man/ibv_query_qp.3 \ 19219820Sjeff man/ibv_query_srq.3 man/ibv_rate_to_mult.3 man/ibv_reg_mr.3 \ 20219820Sjeff- man/ibv_req_notify_cq.3 man/ibv_resize_cq.3 21219820Sjeff+ man/ibv_req_notify_cq.3 man/ibv_resize_cq.3 man/verbs.7 22219820Sjeff 23219820Sjeff DEBIAN = debian/changelog debian/compat debian/control debian/copyright \ 24219820Sjeff debian/ibverbs-utils.install debian/libibverbs1.install \ 25219820SjeffIndex: libibverbs/libibverbs.spec.in 26219820Sjeff=================================================================== 27219820Sjeff--- libibverbs.orig/libibverbs.spec.in 2010-06-08 10:47:13.106792000 +0300 28219820Sjeff+++ libibverbs/libibverbs.spec.in 2010-06-08 10:58:10.160119000 +0300 29219820Sjeff@@ -74,6 +74,7 @@ rm -rf $RPM_BUILD_ROOT 30219820Sjeff %{_libdir}/lib*.so 31219820Sjeff %{_includedir}/* 32219820Sjeff %{_mandir}/man3/* 33219820Sjeff+%{_mandir}/man7/* 34219820Sjeff 35219820Sjeff %files devel-static 36219820Sjeff %defattr(-,root,root,-) 37219820SjeffIndex: libibverbs/man/verbs.7 38219820Sjeff=================================================================== 39219820Sjeff--- /dev/null 1970-01-01 00:00:00.000000000 +0000 40219820Sjeff+++ libibverbs/man/verbs.7 2010-06-08 10:58:10.360115000 +0300 41219820Sjeff@@ -0,0 +1,201 @@ 42219820Sjeff+.\" -*- nroff -*- 43219820Sjeff+.\" 44219820Sjeff+.TH VERBS 7 2008-01-17 libibverbs "Libibverbs Programmer's Manual" 45219820Sjeff+.SH "NAME" 46219820Sjeff+verbs \- Infiniband verbs library 47219820Sjeff+.SH "SYNOPSIS" 48219820Sjeff+.nf 49219820Sjeff+.B #include <infiniband/verbs.h> 50219820Sjeff+.fi 51219820Sjeff+.SH "DESCRIPTION" 52219820Sjeff+This library is an implementation of the verbs according to the Infiniband specification volume 1.2. 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. 53219820Sjeff+ 54219820Sjeff+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. 55219820Sjeff+ 56219820Sjeff+ 57219820Sjeff+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. 58219820Sjeff+ 59219820Sjeff+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). 60219820Sjeff+ 61219820Sjeff+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. 62219820Sjeff+ 63219820Sjeff+If fork (or any other system call that perform fork directly or indirectly) is being used, please see ibv_fork_init(3). 64219820Sjeff+ 65219820Sjeff+.LP 66219820Sjeff+The following shall be declared as functions and may also be defined 67219820Sjeff+as macros. Function prototypes shall be provided. 68219820Sjeff+.RS 69219820Sjeff+.nf 70219820Sjeff+ 71219820Sjeff+\fB 72219820Sjeff+.B Library functions 73219820Sjeff+ 74219820Sjeff+int ibv_fork_init(void); 75219820Sjeff+ 76219820Sjeff+.B Device functions 77219820Sjeff+ 78219820Sjeff+struct ibv_device **ibv_get_device_list(int *num_devices); 79219820Sjeff+void ibv_free_device_list(struct ibv_device **list); 80219820Sjeff+const char *ibv_get_device_name(struct ibv_device *device); 81219820Sjeff+uint64_t ibv_get_device_guid(struct ibv_device *device); 82219820Sjeff+ 83219820Sjeff+.B Context functions 84219820Sjeff+ 85219820Sjeff+struct ibv_context *ibv_open_device(struct ibv_device *device); 86219820Sjeff+int ibv_close_device(struct ibv_context *context); 87219820Sjeff+ 88219820Sjeff+.B Queries 89219820Sjeff+ 90219820Sjeff+int ibv_query_device(struct ibv_context *context, 91219820Sjeff+ struct ibv_device_attr *device_attr); 92219820Sjeff+int ibv_query_port(struct ibv_context *context, uint8_t port_num, 93219820Sjeff+ struct ibv_port_attr *port_attr); 94219820Sjeff+int ibv_query_pkey(struct ibv_context *context, uint8_t port_num, 95219820Sjeff+ int index, uint16_t *pkey); 96219820Sjeff+int ibv_query_gid(struct ibv_context *context, uint8_t port_num, 97219820Sjeff+ int index, union ibv_gid *gid); 98219820Sjeff+ 99219820Sjeff+.B Asynchronous events 100219820Sjeff+ 101219820Sjeff+int ibv_get_async_event(struct ibv_context *context, 102219820Sjeff+ struct ibv_async_event *event); 103219820Sjeff+void ibv_ack_async_event(struct ibv_async_event *event); 104219820Sjeff+ 105219820Sjeff+.B Protection Domains 106219820Sjeff+ 107219820Sjeff+struct ibv_pd *ibv_alloc_pd(struct ibv_context *context); 108219820Sjeff+int ibv_dealloc_pd(struct ibv_pd *pd); 109219820Sjeff+ 110219820Sjeff+.B Memory Regions 111219820Sjeff+ 112219820Sjeff+struct ibv_mr *ibv_reg_mr(struct ibv_pd *pd, void *addr, 113219820Sjeff+ size_t length, enum ibv_access_flags access); 114219820Sjeff+int ibv_dereg_mr(struct ibv_mr *mr); 115219820Sjeff+ 116219820Sjeff+.B Address Handles 117219820Sjeff+ 118219820Sjeff+struct ibv_ah *ibv_create_ah(struct ibv_pd *pd, struct ibv_ah_attr *attr); 119219820Sjeff+int ibv_init_ah_from_wc(struct ibv_context *context, uint8_t port_num, 120219820Sjeff+ struct ibv_wc *wc, struct ibv_grh *grh, 121219820Sjeff+ struct ibv_ah_attr *ah_attr); 122219820Sjeff+struct ibv_ah *ibv_create_ah_from_wc(struct ibv_pd *pd, struct ibv_wc *wc, 123219820Sjeff+ struct ibv_grh *grh, uint8_t port_num); 124219820Sjeff+int ibv_destroy_ah(struct ibv_ah *ah); 125219820Sjeff+ 126219820Sjeff+.B Completion event channels 127219820Sjeff+ 128219820Sjeff+struct ibv_comp_channel *ibv_create_comp_channel(struct ibv_context *context); 129219820Sjeff+int ibv_destroy_comp_channel(struct ibv_comp_channel *channel); 130219820Sjeff+ 131219820Sjeff+.B Completion Queues Control 132219820Sjeff+ 133219820Sjeff+struct ibv_cq *ibv_create_cq(struct ibv_context *context, int cqe, 134219820Sjeff+ void *cq_context, 135219820Sjeff+ struct ibv_comp_channel *channel, 136219820Sjeff+ int comp_vector); 137219820Sjeff+int ibv_destroy_cq(struct ibv_cq *cq); 138219820Sjeff+int ibv_resize_cq(struct ibv_cq *cq, int cqe); 139219820Sjeff+ 140219820Sjeff+.B Reading Completions from CQ 141219820Sjeff+ 142219820Sjeff+int ibv_poll_cq(struct ibv_cq *cq, int num_entries, struct ibv_wc *wc); 143219820Sjeff+ 144219820Sjeff+.B Requesting / Managing CQ events 145219820Sjeff+ 146219820Sjeff+int ibv_req_notify_cq(struct ibv_cq *cq, int solicited_only); 147219820Sjeff+int ibv_get_cq_event(struct ibv_comp_channel *channel, 148219820Sjeff+ struct ibv_cq **cq, void **cq_context); 149219820Sjeff+void ibv_ack_cq_events(struct ibv_cq *cq, unsigned int nevents); 150219820Sjeff+ 151219820Sjeff+.B Shared Receive Queue control 152219820Sjeff+ 153219820Sjeff+struct ibv_srq *ibv_create_srq(struct ibv_pd *pd, 154219820Sjeff+ struct ibv_srq_init_attr *srq_init_attr); 155219820Sjeff+int ibv_destroy_srq(struct ibv_srq *srq); 156219820Sjeff+int ibv_modify_srq(struct ibv_srq *srq, 157219820Sjeff+ struct ibv_srq_attr *srq_attr, 158219820Sjeff+ enum ibv_srq_attr_mask srq_attr_mask); 159219820Sjeff+int ibv_query_srq(struct ibv_srq *srq, struct ibv_srq_attr *srq_attr); 160219820Sjeff+ 161219820Sjeff+.B Queue Pair control 162219820Sjeff+ 163219820Sjeff+struct ibv_qp *ibv_create_qp(struct ibv_pd *pd, 164219820Sjeff+ struct ibv_qp_init_attr *qp_init_attr); 165219820Sjeff+int ibv_destroy_qp(struct ibv_qp *qp); 166219820Sjeff+int ibv_modify_qp(struct ibv_qp *qp, struct ibv_qp_attr *attr, 167219820Sjeff+ enum ibv_qp_attr_mask attr_mask); 168219820Sjeff+int ibv_query_qp(struct ibv_qp *qp, struct ibv_qp_attr *attr, 169219820Sjeff+ enum ibv_qp_attr_mask attr_mask, 170219820Sjeff+ struct ibv_qp_init_attr *init_attr); 171219820Sjeff+ 172219820Sjeff+.B posting Work Requests to QPs/SRQs 173219820Sjeff+int ibv_post_send(struct ibv_qp *qp, struct ibv_send_wr *wr, 174219820Sjeff+ struct ibv_send_wr **bad_wr); 175219820Sjeff+int ibv_post_recv(struct ibv_qp *qp, struct ibv_recv_wr *wr, 176219820Sjeff+ struct ibv_recv_wr **bad_wr); 177219820Sjeff+int ibv_post_srq_recv(struct ibv_srq *srq, 178219820Sjeff+ struct ibv_recv_wr *recv_wr, 179219820Sjeff+ struct ibv_recv_wr **bad_recv_wr); 180219820Sjeff+ 181219820Sjeff+.B Multicast group 182219820Sjeff+ 183219820Sjeff+int ibv_attach_mcast(struct ibv_qp *qp, union ibv_gid *gid, uint16_t lid); 184219820Sjeff+int ibv_detach_mcast(struct ibv_qp *qp, union ibv_gid *gid, uint16_t lid); 185219820Sjeff+ 186219820Sjeff+.B General functions 187219820Sjeff+ 188219820Sjeff+int ibv_rate_to_mult(enum ibv_rate rate); 189219820Sjeff+enum ibv_rate mult_to_ibv_rate(int mult); 190219820Sjeff+\fP 191219820Sjeff+.SH "SEE ALSO" 192219820Sjeff+.LP 193219820Sjeff+\fIibv_fork_init\fP(), 194219820Sjeff+\fIibv_get_device_list\fP(), 195219820Sjeff+\fIibv_free_device_list\fP(), 196219820Sjeff+\fIibv_get_device_name\fP(), 197219820Sjeff+\fIibv_get_device_guid\fP(), 198219820Sjeff+\fIibv_open_device\fP(), 199219820Sjeff+\fIibv_close_device\fP(), 200219820Sjeff+\fIibv_query_device\fP(), 201219820Sjeff+\fIibv_query_port\fP(), 202219820Sjeff+\fIibv_query_pkey\fP(), 203219820Sjeff+\fIibv_query_gid\fP(), 204219820Sjeff+\fIibv_get_async_event\fP(), 205219820Sjeff+\fIibv_ack_async_event\fP(), 206219820Sjeff+\fIibv_alloc_pd\fP(), 207219820Sjeff+\fIibv_dealloc_pd\fP(), 208219820Sjeff+\fIibv_reg_mr\fP(), 209219820Sjeff+\fIibv_dereg_mr\fP(), 210219820Sjeff+\fIibv_create_ah\fP(), 211219820Sjeff+\fIibv_init_ah_from_wc\fP(), 212219820Sjeff+\fIibv_create_ah_from_wc\fP(), 213219820Sjeff+\fIibv_destroy_ah\fP(), 214219820Sjeff+\fIibv_create_comp_channel\fP(), 215219820Sjeff+\fIibv_destroy_comp_channel\fP(), 216219820Sjeff+\fIibv_create_cq\fP(), 217219820Sjeff+\fIibv_destroy_cq\fP(), 218219820Sjeff+\fIibv_resize_cq\fP(), 219219820Sjeff+\fIibv_poll_cq\fP(), 220219820Sjeff+\fIibv_req_notify_cq\fP(), 221219820Sjeff+\fIibv_get_cq_event\fP(), 222219820Sjeff+\fIibv_ack_cq_events\fP(), 223219820Sjeff+\fIibv_create_srq\fP(), 224219820Sjeff+\fIibv_destroy_srq\fP(), 225219820Sjeff+\fIibv_modify_srq\fP(), 226219820Sjeff+\fIibv_query_srq\fP(), 227219820Sjeff+\fIibv_post_srq_recv\fP(), 228219820Sjeff+\fIibv_create_qp\fP(), 229219820Sjeff+\fIibv_destroy_qp\fP(), 230219820Sjeff+\fIibv_modify_qp\fP(), 231219820Sjeff+\fIibv_query_qp\fP(), 232219820Sjeff+\fIibv_post_send\fP(), 233219820Sjeff+\fIibv_post_recv\fP(), 234219820Sjeff+\fIibv_attach_mcast\fP(), 235219820Sjeff+\fIibv_detach_mcast\fP(), 236219820Sjeff+\fIibv_rate_to_mult\fP(), 237219820Sjeff+\fImult_to_ibv_rate\fP() 238219820Sjeff+.SH "AUTHORS" 239219820Sjeff+.TP 240219820Sjeff+Dotan Barak <dotanb@mellanox.co.il> 241219820Sjeff+.TP 242219820Sjeff+Or Gerlitz <ogerlitz@voltaire.com> 243