.\" -*- nroff -*- .\" Licensed under the OpenIB.org BSD license (FreeBSD Variant) - See COPYING.md .\" .TH IBV_REG_MR 3 2006-10-31 libibverbs "Libibverbs Programmer's Manual" .SH "NAME" ibv_reg_mr, ibv_reg_mr_iova, ibv_reg_dmabuf_mr, ibv_dereg_mr \- register or deregister a memory region (MR) .SH "SYNOPSIS" .nf .B #include .sp .BI "struct ibv_mr *ibv_reg_mr(struct ibv_pd " "*pd" ", void " "*addr" , .BI " size_t " "length" ", int " "access" ); .sp .BI "struct ibv_mr *ibv_reg_mr_iova(struct ibv_pd " "*pd" ", void " "*addr" , .BI " size_t " "length" ", uint64_t " "hca_va" , .BI " int " "access" ); .sp .BI "struct ibv_mr *ibv_reg_dmabuf_mr(struct ibv_pd " "*pd" ", uint64_t " "offset" , .BI " size_t " "length" ", uint64_t " "iova" , .BI " int " "fd" ", int " "access" ); .sp .BI "int ibv_dereg_mr(struct ibv_mr " "*mr" ); .fi .SH "DESCRIPTION" .B ibv_reg_mr() registers a memory region (MR) associated with the protection domain .I pd\fR. The MR's starting address is .I addr and its size is .I length\fR. The argument .I access describes the desired memory protection attributes; it is either 0 or the bitwise OR of one or more of the following flags: .PP .TP .B IBV_ACCESS_LOCAL_WRITE \fR Enable Local Write Access .TP .B IBV_ACCESS_REMOTE_WRITE \fR Enable Remote Write Access .TP .B IBV_ACCESS_REMOTE_READ\fR Enable Remote Read Access .TP .B IBV_ACCESS_REMOTE_ATOMIC\fR Enable Remote Atomic Operation Access (if supported) .TP .B IBV_ACCESS_FLUSH_GLOBAL\fR Enable Remote Flush Operation with global visibility placement type (if supported) .TP .B IBV_ACCESS_FLUSH_PERSISTENT\fR Enable Remote Flush Operation with persistence placement type (if supported) .TP .B IBV_ACCESS_MW_BIND\fR Enable Memory Window Binding .TP .B IBV_ACCESS_ZERO_BASED\fR Use byte offset from beginning of MR to access this MR, instead of a pointer address .TP .B IBV_ACCESS_ON_DEMAND\fR Create an on-demand paging MR .TP .B IBV_ACCESS_HUGETLB\fR Huge pages are guaranteed to be used for this MR, applicable with IBV_ACCESS_ON_DEMAND in explicit mode only .TP .B IBV_ACCESS_RELAXED_ORDERING\fR Allow system to reorder accesses to the MR to improve performance .PP If .B IBV_ACCESS_REMOTE_WRITE or .B IBV_ACCESS_REMOTE_ATOMIC is set, then .B IBV_ACCESS_LOCAL_WRITE must be set too. .PP Local read access is always enabled for the MR. .PP To create an implicit ODP MR, IBV_ACCESS_ON_DEMAND should be set, addr should be 0 and length should be SIZE_MAX. .PP If .B IBV_ACCESS_HUGETLB is set, then application awares that for this MR all pages are huge and must promise it will never do anything to break huge pages. .PP .B ibv_reg_mr_iova() ibv_reg_mr_iova is the same as the normal reg_mr, except that the user is allowed to specify the virtual base address of the MR when accessed through a lkey or rkey. The offset in the memory region is computed as 'addr + (iova - hca_va)'. Specifying 0 for hca_va has the same effect as IBV_ACCESS_ZERO_BASED. .PP .B ibv_reg_dmabuf_mr() registers a dma-buf based memory region (MR) associated with the protection domain .I pd\fR. The MR starts at .I offset of the dma-buf and its size is .I length\fR. The dma-buf is identified by the file descriptor .I fd\fR. The argument .I iova specifies the virtual base address of the MR when accessed through a lkey or rkey. It must have the same page offset as .I offset\fR. The argument .I access describes the desired memory protection attributes; it is similar to the ibv_reg_mr case except that only the following flags are supported: .B IBV_ACCESS_LOCAL_WRITE, IBV_ACCESS_REMOTE_WRITE, IBV_ACCESS_REMOTE_READ, IBV_ACCESS_REMOTE_ATOMIC, IBV_ACCESS_RELAXED_ORDERING. .PP .B ibv_dereg_mr() deregisters the MR .I mr\fR. .SH "RETURN VALUE" .B ibv_reg_mr() / ibv_reg_mr_iova() / ibv_reg_dmabuf_mr() returns a pointer to the registered MR, or NULL if the request fails. The local key (\fBL_Key\fR) field .B lkey is used as the lkey field of struct ibv_sge when posting buffers with ibv_post_* verbs, and the the remote key (\fBR_Key\fR) field .B rkey is used by remote processes to perform Atomic and RDMA operations. The remote process places this .B rkey as the rkey field of struct ibv_send_wr passed to the ibv_post_send function. .PP .B ibv_dereg_mr() returns 0 on success, or the value of errno on failure (which indicates the failure reason). .SH "NOTES" .B ibv_dereg_mr() fails if any memory window is still bound to this MR. .SH "SEE ALSO" .BR ibv_alloc_pd (3), .BR ibv_post_send (3), .BR ibv_post_recv (3), .BR ibv_post_srq_recv (3) .SH "AUTHORS" .TP Dotan Barak