| .\" -*- nroff -*- |
| .\" |
| .TH IBV_POST_RECV 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" |
| .SH "NAME" |
| ibv_post_recv \- post a list of work requests (WRs) to a receive queue |
| .SH "SYNOPSIS" |
| .nf |
| .B #include <infiniband/verbs.h> |
| .sp |
| .BI "int ibv_post_recv(struct ibv_qp " "*qp" ", struct ibv_recv_wr " "*wr" , |
| .BI " struct ibv_recv_wr " "**bad_wr" ); |
| .fi |
| .SH "DESCRIPTION" |
| .B ibv_post_recv() |
| posts the linked list of work requests (WRs) starting with |
| .I wr |
| to the receive queue of the queue pair |
| .I qp\fR. |
| It stops processing WRs from this list at the first failure (that can |
| be detected immediately while requests are being posted), and returns |
| this failing WR through |
| .I bad_wr\fR. |
| .PP |
| The argument |
| .I wr |
| is an ibv_recv_wr struct, as defined in <infiniband/verbs.h>. |
| .PP |
| .nf |
| struct ibv_recv_wr { |
| .in +8 |
| uint64_t wr_id; /* User defined WR ID */ |
| struct ibv_recv_wr *next; /* Pointer to next WR in list, NULL if last WR */ |
| struct ibv_sge *sg_list; /* Pointer to the s/g array */ |
| int num_sge; /* Size of the s/g array */ |
| .in -8 |
| }; |
| .sp |
| .nf |
| struct ibv_sge { |
| .in +8 |
| uint64_t addr; /* Start address of the local memory buffer */ |
| uint32_t length; /* Length of the buffer */ |
| uint32_t lkey; /* Key of the local Memory Region */ |
| .in -8 |
| }; |
| .fi |
| .SH "RETURN VALUE" |
| .B ibv_post_recv() |
| returns 0 on success, or the value of errno on failure (which indicates the failure reason). |
| .SH "NOTES" |
| The buffers used by a WR can only be safely reused after WR the |
| request is fully executed and a work completion has been retrieved |
| from the corresponding completion queue (CQ). |
| .PP |
| If the QP |
| .I qp |
| is associated with a shared receive queue, you must use the function |
| .B ibv_post_srq_recv()\fR, |
| and not |
| .B ibv_post_recv()\fR, |
| since the QP's own receive queue will not be used. |
| .PP |
| If a WR is being posted to a UD QP, the Global Routing Header (GRH) of |
| the incoming message will be placed in the first 40 bytes of the |
| buffer(s) in the scatter list. If no GRH is present in the incoming |
| message, then the first bytes will be undefined. This means that in |
| all cases, the actual data of the incoming message will start at an |
| offset of 40 bytes into the buffer(s) in the scatter list. |
| .SH "SEE ALSO" |
| .BR ibv_create_qp (3), |
| .BR ibv_post_send (3), |
| .BR ibv_post_srq_recv (3), |
| .BR ibv_poll_cq (3) |
| .SH "AUTHORS" |
| .TP |
| Dotan Barak <dotanba@gmail.com> |